Docs

Documentation

Tout tourne sur votre machine : installez-le, pointez une caméra dessus et réglez le moment où il a le droit d’appeler l’extérieur. Classé selon ce que vous cherchez à faire.

Installer et lancer

De rien du tout à une carte à l’écran

Une seule commande installe le client, les poids des modèles et les shims. Le seul identifiant de tout le système est votre clé Ximilar.

Le script d’installation

Crée un venv dans ~/.cardstream, vérifie le wheel de la release avec ses sommes de contrôle, télécharge les poids des modèles et place les deux commandes dans votre PATH. Les autres méthodes (wheel, Docker, sources) sont sur la page de téléchargement.

$ curl -fsSL https://raw.githubusercontent.com/Ximilar-com/cardstream/main/scripts/install.sh | sh

Toutes les méthodes d’installation →

Installation manuelle

Un clone du dépôt et pip font aussi l’affaire. Les extras sont indépendants : [client] apporte l’interface et les sources, [onnx] ou [torch] fournissent les backends du détecteur et de l’embedding.

$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream
$ pip install -e '.[client,onnx]'

Votre clé Ximilar

L’identification repose sur Ximilar collectibles/v2. XIMILAR_API_KEY est la seule variable d’environnement lue ; tout le reste passe par des options.

$ export XIMILAR_API_KEY=your-key

Premier lancement

Ouvre l’interface navigateur sur votre webcam. Montrez une carte : l’overlay affiche la machine à états en train de réfléchir, puis la correspondance dès qu’elle arrive.

$ cardstream-web
# → http://127.0.0.1:8001

Vérifier ce que vous avez

Les deux commandes affichent leur version et s’arrêtent. Aucun fichier de modèle n’est nécessaire : cela fonctionne dès la fin de l’installation.

$ cardstream-web --version
cardstream 0.5.0

Sans interface, pour les installations fixes

Le même pipeline sans navigateur : les résultats s’affichent dans le terminal. Les mêmes options que cardstream-web, un seul processus à côté de la caméra.

$ cardstream-client --source 0

L’utiliser

Donnez-lui votre show

Les sources sont interchangeables et l’analyse est la même, quelle que soit celle que vous choisissez. Tout passe par des options ; la fenêtre de réglages ajuste les plus importantes en direct.

Webcams et fichiers

La webcam du navigateur est la source par défaut de cardstream-web ; un index, un fichier vidéo ou une image fixe fonctionnent partout. Pratique pour tester avant le show.

$ cardstream-web # webcam du navigateur
$ cardstream-client --source clip.mp4

Récupérer un flux

Pointez-le sur une caméra IP, un encodeur ou un restreamer : flux rtsp://, rtmp://, srt:// et flux JPEG ws://, avec des reconnexions à intervalles croissants, mais plafonnés.

$ cardstream-web --source rtsp://cam/stream1

Laisser OBS pousser

Lancez-le en mode écoute et ajoutez une sortie RTMP ou SRT supplémentaire dans OBS. Nécessite le binaire ffmpeg du système (brew install ffmpeg).

$ cardstream-web --source rtmp://0.0.0.0:1935/live --listen

Des préréglages qui resserrent la recherche

Le jeu, le code d’extension et le système d’écriture sont validés en local avant d’être envoyés. Passez toujours --alphabet quand vous passez --game : un préréglage de jeu empêche l’endpoint de détecter lui-même l’alphabet.

$ cardstream-web --game "Pokémon" --alphabet japanese --set-code M4

La fenêtre de réglages

Catégorie, jeu, code d’extension, alphabet et seuils se modifient depuis le navigateur en plein stream : aucun redémarrage, et les contrôles appliquent la même validation que le processus.

Trois réglages de résolution

Ce que la caméra capture, ce qui est envoyé et ce qui est analysé sont trois valeurs distinctes. L’analyse tourne en petit ; le recadrage à identifier est redécoupé dans l’image entière.

$ cardstream-web --camera-width 3840 --width 1280

Revoir le show

Enregistrez le show, revoyez-le plus tard

Désactivé par défaut. Une option enregistre l’historique que construit la page (chaque carte montrée, avec son recadrage) dans une session de votre propre compte Ximilar : le show est toujours là le lendemain matin.

L’historique, avec ses vignettes

L’interface navigateur liste toutes les cartes montrées, de la plus récente à la plus ancienne : une vignette du recadrage identifié, son prix avec --price-stats et son temps de présence sur le stream. Cette liste reste sur votre machine.

Enregistrer un show

--ximilar-stream NEW démarre une session et affiche son id. À partir de là, chaque ligne de l’historique est enregistrée au fil du show : les envois sont groupés en arrière-plan, retentés en cas d’erreur réseau et ne retardent jamais le show. Une sortie propre envoie ce qui reste et ferme la session.

$ cardstream-web --game "Pokémon" --alphabet latin \
    --price-stats --ximilar-stream NEW

L’enregistrement d’un show, en détail →

Ce qui est envoyé

Les lignes sous forme de texte (carte, extension, prix, temps sur le stream, appels payants correspondants) et le recadrage qui a servi à identifier chacune, de 1024 px au plus : l’image que l’appel d’identification a déjà reçue. --no-ximilar-stream-images s’en tient au texte. Votre compte Ximilar doit disposer du service Cardstream.

$ cardstream-web --ximilar-stream NEW --no-ximilar-stream-images

Le revoir dans l’application Ximilar

Chaque session arrive dans la section Cardstream de l’application Ximilar : ce que vous avez montré et quand, la valeur du show, ses produits les plus chers et ses extensions les plus fréquentes, et chaque carte avec son recadrage. Marquez ce qui s’est vendu, corrigez une mauvaise correspondance, ajoutez des notes.

Ouvrir l’application Ximilar →

Reprendre après un redémarrage

Passez l’id de session à la place de NEW et le show continue dans la même session ; même si une sortie propre l’avait fermée, elle se rouvre simplement. Seul le démarrage d’une session est facturé : reprendre ne coûte rien.

$ cardstream-web --ximilar-stream <session-id>

Espaces de travail d’équipe

Une session est enregistrée dans l’espace de travail par défaut de votre clé API. Désignez-en un autre avec --ximilar-workspace, et passez le même id quand vous reprenez une session qui y est enregistrée.

$ cardstream-web --ximilar-stream NEW \
    --ximilar-workspace <workspace-id>

L’exploiter en confiance

Un appel d’identification par carte distincte

Des signaux locaux (le mouvement, la détection, le filtre d’identité) décident du moment où un appel d’identification se justifie vraiment. Voici les réglages qui le gardent honnête.

Les seuils

Un seuil de résultat écarte de l’overlay les correspondances faibles ; le seuil de similarité tranche entre même carte et nouvelle carte ; forget-after vide la mémoire une fois qu’une carte est partie depuis assez longtemps.

$ cardstream-web --result-threshold 0.35

La configuration recommandée

La segmentation RF-DETR avec un filtre par embedding ONNX : ce sont les réglages par défaut. Un simple cardstream-web lance exactement cela une fois les poids en place ; l’écrire en toutes lettres donne le même pipeline.

$ cardstream-web \
    --segmentor-model model/segmentation/onnx/model.onnx \
    --embed-model model/similarity/onnx/model.onnx

Restez en localhost

L’application locale n’a pas d’authentification et détient votre clé API. --host vaut 127.0.0.1 par défaut : n’y touchez pas et n’exposez jamais le port sur un réseau local.

« Model not found » au démarrage

Les poids des modèles se téléchargent à part, ils ne font pas partie du dépôt. Le script d’installation et l’image Docker les récupèrent ; avec un simple clone, il faut les déposer dans model/segmentation/ et model/similarity/. scripts/build-from-source.sh --models le fait pour vous.

Précisez le jeu que vous montrez

Un show consacré à un seul jeu n’a pas besoin que l’endpoint devine le jeu à chaque appel. Nommez-le et la recherche se limite à ce jeu : des réponses plus rapides, moins de mauvaises versions. Passez --alphabet en même temps, car un préréglage de jeu empêche l’endpoint de détecter lui-même le système d’écriture.

$ cardstream-web --game "Pokémon" --alphabet japanese

ffmpeg, quand il le faut

--listen et --ffmpeg font appel au binaire ffmpeg du système. Les flux en pull simples fonctionnent avec une installation pip seule ; la configuration où OBS pousse le flux, non.

Aller plus loin

Au-delà des réglages par défaut

Changez les modèles ou lisez le code : tout le pipeline tient dans un seul paquet installable.

Apportez vos propres poids

La détection et le filtre d’identité passent par des backends : la famille choisit la classe, l’extension du fichier choisit le runtime. RF-DETR ou RT-DETRv2, un .onnx ou un dossier transformers.

Les backends de modèles →

Le catalogue de modèles

Tous les poids que cardstream peut charger, entraînés par Ximilar et publiés sous Apache-2.0 avec les releases : ce que fait chacun, sur quoi il tourne et sous quelle licence.

Catalogue de modèles →

Des réponses en bref

Ce que ça coûte, ce qui quitte la machine, quelles cartes il reconnaît, et les deux commandes qui le désinstallent.

Lire la FAQ →

README et issues

Le README couvre toutes les options ; les issues sont l’endroit où signaler un bug ou poser une question.

Lire le README →

Releases et artefacts

Wheels, sommes de contrôle et script d’installation, un jeu par release, sans oublier Docker et la compilation depuis les sources.

Page de téléchargement →