Doku

Dokumentation

Alles läuft auf deinem Rechner: installieren, eine Kamera anschließen und einstellen, wann es einen Aufruf absetzen darf. Sortiert nach dem, was du gerade vorhast.

Installieren und starten

Von null zur Karte auf dem Bildschirm

Ein Befehl installiert den Client, die Modellgewichte und die Shims. Dein Ximilar-Schlüssel ist alles an Zugangsdaten, was das ganze System braucht.

Das Installationsskript

Legt ein venv in ~/.cardstream an, prüft das Release-Wheel gegen seine Prüfsummen, lädt die Modellgewichte und legt beide Befehle in deinen PATH. Die anderen Wege (Wheel, Docker, Quellcode) stehen auf der Download-Seite.

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

Alle Installationswege →

Manuelle Installation

Ein Checkout und pip funktionieren auch. Die Extras sind unabhängig voneinander: [client] bringt Oberfläche und Quellen mit, [onnx] oder [torch] die Backends für Detektor und Embedder.

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

Dein Ximilar-Schlüssel

Die Identifikation läuft über Ximilar collectibles/v2. XIMILAR_API_KEY ist die einzige Umgebungsvariable, die überhaupt gelesen wird. Alles andere ist ein Flag.

$ export XIMILAR_API_KEY=your-key

Erster Start

Öffnet die Browser-Oberfläche mit deiner Webcam. Halte eine Karte hoch: Das Overlay zeigt, wie der Zustandsautomat überlegt, und dann den Treffer, sobald er da ist.

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

Prüfen, was installiert ist

Beide Befehle geben ihre Version aus und beenden sich. Modelldateien braucht es dafür nicht, es klappt also, sobald die Installation fertig ist.

$ cardstream-web --version
cardstream 0.5.0

Headless, für feste Setups

Dieselbe Pipeline ohne Browser: Die Ergebnisse erscheinen im Terminal. Dieselben Flags wie cardstream-web, ein Prozess neben der Kamera.

$ cardstream-client --source 0

Benutzen

Gib ihm deine Show

Die Quellen sind austauschbar, und die Analyse ist dieselbe, egal welche du nimmst. Alles ist ein Flag; die wichtigsten stellst du im Einstellungsdialog live nach.

Webcams und Dateien

Die Webcam im Browser ist der Standard für cardstream-web; ein Kamera-Index, eine Videodatei oder ein Standbild funktionieren überall. Gut zum Testen vor der Show.

$ cardstream-web # Webcam im Browser
$ cardstream-client --source clip.mp4

Einen Stream abholen (Pull)

Richte es auf eine IP-Kamera, einen Encoder oder einen Restreamer: rtsp://, rtmp://, srt:// und JPEG-Feeds über ws://. Bricht die Verbindung ab, verbindet es sich mit gedeckeltem Backoff neu.

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

OBS senden lassen (Push)

Starte es als Listener und füge in OBS eine zusätzliche RTMP- oder SRT-Ausgabe hinzu. Braucht ein systemweit installiertes ffmpeg (brew install ffmpeg).

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

Vorgaben grenzen die Suche ein

Spiel, Set-Code und Schriftsystem werden lokal geprüft, bevor sie gesendet werden. Gib immer --alphabet an, wenn du --game angibst, denn mit vorgegebenem Spiel erkennt der Endpunkt das Alphabet nicht mehr selbst.

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

Der Einstellungsdialog

Kategorie, Spiel, Set-Code, Alphabet und Schwellenwerte lassen sich mitten im Stream im Browser nachstellen, ohne Neustart, und die Felder prüfen genauso streng wie der Prozess.

Drei Stellschrauben für die Auflösung

Was die Kamera aufnimmt, was gesendet wird und was analysiert wird, sind drei getrennte Zahlen. Analysiert wird in kleiner Auflösung; der Ausschnitt für die Identifikation wird aus dem vollen Frame neu geschnitten.

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

Show auswerten

Die Show speichern und später auswerten

Standardmäßig aus. Ein Flag speichert den Verlauf, den die Seite aufbaut (jede Karte, die du gezeigt hast, mit ihrem Ausschnitt), in einer Session in deinem eigenen Ximilar-Konto. So ist die Show am nächsten Morgen noch da.

Der Verlauf, mit Vorschaubildern

Die Browser-Oberfläche listet jede Karte auf, die du gezeigt hast, die neueste zuerst: ein Vorschaubild des erkannten Ausschnitts, mit --price-stats ihr Preis, und wie lange sie im Stream war. Diese Liste liegt auf deinem Rechner.

Eine Show speichern

--ximilar-stream NEW startet eine Session und gibt ihre ID aus. Von da an wird jede Zeile des Verlaufs gespeichert, während die Show läuft: Die Uploads laufen gebündelt im Hintergrund, werden bei Netzwerkfehlern wiederholt und halten die Show nie auf. Beim sauberen Beenden wird der Rest hochgeladen und die Session geschlossen.

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

Eine Show speichern, im Detail →

Was hochgeladen wird

Die Zeilen als Text (Karte, Set, Preis, Zeit im Stream, die bezahlten Aufrufe dahinter) und zu jeder Zeile der Ausschnitt, an dem die Karte erkannt wurde, höchstens 1024 px groß: das Bild, das der Identifikationsaufruf ohnehin bekommen hat. Mit --no-ximilar-stream-images bleibt es bei Text. Dein Ximilar-Konto braucht den Dienst Cardstream.

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

In der Ximilar-App auswerten

Jede Session landet im Bereich Cardstream der Ximilar-App: was du wann gezeigt hast, der Wert der Show, ihre wertvollsten Produkte und häufigsten Sets, und jede Karte mit ihrem Ausschnitt. Markiere, was verkauft wurde, korrigiere einen falschen Treffer, füge Notizen hinzu.

Ximilar-App öffnen →

Nach einem Neustart weitermachen

Gib statt NEW die Session-ID an, und die Show läuft in derselben Session weiter. Auch wenn ein sauberes Beenden sie geschlossen hat, wird sie einfach wieder geöffnet. Berechnet wird nur der Start einer Session, das Fortsetzen kostet also nichts.

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

Team-Workspaces

Eine Session wird im Standard-Workspace deines API-Schlüssels gespeichert. Einen anderen gibst du mit --ximilar-workspace an, und dieselbe ID brauchst du auch, wenn du eine dort gespeicherte Session fortsetzt.

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

Sicher betreiben

Ein Identifikationsaufruf pro neuer Karte

Lokale Signale (Bewegung, Detektion, der Identitätsfilter) entscheiden, wann ein Identifikationsaufruf wirklich nötig ist. Mit diesen Stellschrauben bleibt es dabei.

Schwellenwerte

Ein Ergebnis-Schwellenwert hält schwache Treffer vom Overlay fern; der Ähnlichkeits-Schwellenwert entscheidet zwischen derselben und einer neuen Karte; forget-after leert das Gedächtnis, sobald eine Karte lange genug weg war.

$ cardstream-web --result-threshold 0.35

Der empfohlene Start

RF-DETR-Segmentierung mit einem ONNX-Embedding als Identitätsfilter: die ausgelieferten Standardwerte. Ein bloßes cardstream-web läuft genau so, sobald die Gewichte an ihrem Platz sind; ausgeschrieben ist es dieselbe Pipeline.

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

Bleib auf localhost

Die lokale App hat keine Authentifizierung und hält deinen API-Schlüssel. --host steht standardmäßig auf 127.0.0.1. Lass es dabei und gib den Port nie in einem LAN frei.

„Model not found“ beim Start

Die Modellgewichte sind ein separater Download und nicht Teil des Repositorys. Installationsskript und Docker-Image laden sie; bei einem bloßen Checkout müssen sie nach model/segmentation/ und model/similarity/ gelegt werden. scripts/build-from-source.sh --models erledigt das für dich.

Gib an, welches Spiel du zeigst

In einer Show mit nur einem Spiel muss der Endpunkt nicht bei jedem Aufruf das Spiel raten. Nenne es, und die Suche beschränkt sich auf dieses Spiel: schnellere Antworten, weniger falsche Versionen. Gib --alphabet dazu an, denn mit vorgegebenem Spiel erkennt der Endpunkt das Schriftsystem nicht mehr selbst.

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

ffmpeg, wenn du es brauchst

--listen und --ffmpeg rufen das systemweit installierte ffmpeg auf. Einfache Pulls funktionieren mit einer reinen pip-Installation, der Push aus OBS nicht.

Tiefer einsteigen

Jenseits der Standardwerte

Tausch die Modelle aus oder lies den Code: Die ganze Pipeline ist ein einziges installierbares Paket.

Eigene Gewichte mitbringen

Detektion und Identitätsfilter wählen ihr Backend selbst: Die Modellfamilie bestimmt die Klasse, die Dateiendung die Laufzeit. RF-DETR oder RT-DETRv2, .onnx oder ein transformers-Verzeichnis.

Modell-Backends →

Der Modellkatalog

Alle Gewichte, die cardstream laden kann, von Ximilar trainiert und mit den Releases unter Apache-2.0 veröffentlicht: was jedes Modell tut, wie schnell es läuft und unter welcher Lizenz es steht.

Modellkatalog →

Kurz beantwortet

Was es kostet, was den Rechner verlässt, welche Karten es erkennt und die zwei Befehle, mit denen du es wieder loswirst.

Zur FAQ →

README und Issues

Das README beschreibt jedes Flag; für Bugs und Fragen sind die Issues da.

README lesen →

Releases und Artefakte

Wheels, Prüfsummen und das Installationsskript, ein Satz pro Release. Dazu Docker und der Build aus dem Quellcode.

Download-Seite →