Documentation
Everything runs on your machine: install it, point a camera at it, and tune when it is allowed to call out. Grouped by what you are trying to do.
From nothing to a card on screen
One command installs the client, the model weights and the shims. The only credential in the whole system is your Ximilar key.
The install script
Creates a venv in ~/.cardstream, verifies the release wheel against its checksums, fetches the model weights and puts both commands on your PATH. Other paths — wheel, Docker, source — live on the download page.
$ curl -fsSL https://raw.githubusercontent.com/Ximilar-com/cardstream/main/scripts/install.sh | sh All install paths → Manual install
A checkout and pip work too. Extras are independent: [client] is the UI and sources, [onnx] or [torch] provide the detector and embedder backends.
$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream $ pip install -e '.[client,onnx]'
Your Ximilar key
Identification is powered by Ximilar collectibles/v2. XIMILAR_API_KEY is the one environment variable anything reads — everything else is a flag.
$ export XIMILAR_API_KEY=your-key
First run
Opens the browser UI on your webcam. Hold up a card; the overlay shows the state machine thinking and the match when it lands.
$ cardstream-web # → http://127.0.0.1:8001
Verify what you have
Both commands print their version and exit — no model files needed, so it works the moment the install finishes.
$ cardstream-web --version
cardstream 0.3.0 Headless, for rigs
The same pipeline without a browser: results print to the terminal. Same flags as cardstream-web, one process next to the camera.
$ cardstream-client --source 0 Feed it your show
Sources are pluggable and the analysis is identical whichever one you pick. Everything is a flag; the settings dialog retunes the important ones live.
Webcams and files
The browser webcam is the default for cardstream-web; an index, a video file or a still image work everywhere. Good for testing before the show.
$ cardstream-web # browser webcam $ cardstream-client --source clip.mp4
Pull a stream
Point it at an IP camera, an encoder or a restreamer — rtsp://, rtmp://, srt:// and ws:// JPEG feeds, with capped-backoff reconnects.
$ cardstream-web --source rtsp://cam/stream1 Let OBS push
Run it as a listener and add one extra RTMP or SRT output in OBS. Needs the system ffmpeg binary (brew install ffmpeg).
$ cardstream-web --source rtmp://0.0.0.0:1935/live --listen Prefills narrow the search
Game, set code and writing system are validated locally before they are sent. Always pass --alphabet when you pass --game — a game prefill stops the endpoint detecting the alphabet itself.
$ cardstream-web --game "Pokémon" --alphabet japanese --set-code M4
The settings dialog
Category, game, set code, alphabet and thresholds are retunable from the browser mid-stream — no restart, and the controls carry the same validation as the process.
Three resolution knobs
What the camera captures, what gets sent, and what gets analysed are separate numbers. Analysis runs small; the identify crop is re-cut from the full frame.
$ cardstream-web --camera-width 3840 --width 1280 One identification call per distinct card
Local signals — motion, detection, the identity gate — decide when an identification call is actually warranted. These are the knobs that keep it honest.
Thresholds
A result threshold keeps weak matches off the overlay; the similarity threshold decides same-card vs new-card; forget-after clears the memory once a card has been gone long enough.
$ cardstream-web --result-threshold 0.35 The recommended run
RF-DETR segmentation with an ONNX embedding gate — the shipped defaults. A bare cardstream-web runs exactly this once the weights are in place; spelling it out is the same pipeline.
$ cardstream-web \ --segmentor-model model/segmentation/onnx/model.onnx \ --embed-model model/similarity/onnx/model.onnx
Keep it on localhost
The local app is unauthenticated and holds your API key. --host defaults to 127.0.0.1 — leave it there and never expose the port to a LAN.
“Model not found” at startup
The model weights are a separate download, not part of the repo. The install script and Docker image fetch them; a bare checkout needs them dropped into model/segmentation/ and model/similarity/ — scripts/build-from-source.sh --models does it for you.
Specify the game you are showing
A one-game show does not need the endpoint guessing the game every call. Name it and the search narrows to that game — faster answers, fewer wrong prints. Pass --alphabet with it, because a game prefill stops the endpoint detecting the writing system itself.
$ cardstream-web --game "Pokémon" --alphabet japanese
ffmpeg, when you need it
--listen and --ffmpeg shell out to the system ffmpeg binary. Plain pulls work with a pip-only install; the push-from-OBS setup does not.
Beyond the defaults
Swap the models or read the code — the whole pipeline is one installable package.
Bring your own weights
Detection and the identity gate are backend-routed: the family picks the class, the file extension picks the runtime. RF-DETR or RT-DETRv2, .onnx or a transformers directory.
Model backends →The model zoo
Every weight cardstream can load, trained by Ximilar and published Apache-2.0 with the releases: what each one does, what it runs at, and the licence on it.
Model zoo →Short answers
What it costs, what leaves the machine, which cards it names, and the two commands that remove it again.
Read the FAQ →README and issues
The README covers every flag; issues are the place for bugs and questions.
Read the README →Releases and artifacts
Wheels, checksums and the install script, one set per release — plus Docker and source builds.
Download page →