Frequently asked questions
The questions that come up most — installing and removing it, what it costs, what leaves your machine, and what it can name. Everything longer lives in the docs hub.
Installing, updating, uninstalling
The install script touches exactly two places on your machine, and both are yours to delete.
What do I need to run it?
A machine with Python 3.11 or newer, and that is close to it. macOS arm64, Linux amd64 and Windows amd64 are all covered by the same pure-Python release, no GPU required. The system ffmpeg binary is needed only for the pull and listen sources (RTSP, RTMP, SRT) — a webcam, a file or the browser UI does not need it.
Where does the install script put things?
Two places. ~/.cardstream is the install root — a virtualenv in venv/ and the model weights in models/. The two commands, cardstream-web and cardstream-client, are small shims written into ~/.local/bin; they exec the venv binaries with the model paths already filled in, so any flag you pass wins. Both locations move with CARDSTREAM_HOME and INSTALL_DIR. Nothing else on the machine is touched — in particular the script never edits your shell profile: if ~/.local/bin is not on your PATH it prints a note and leaves the change to you.
How do I update to a new version?
Re-run the same one-liner. It installs the current release into the existing virtualenv and rewrites the shims. Weights already sitting in ~/.cardstream/models are left alone — they are fetched only when they are missing — so an update is a small download, not another quarter of a gigabyte. To land on a specific release instead of the latest, set CARDSTREAM_VERSION.
# the same one-liner; /install.sh redirects to the script on main $ curl -fsSL https://cardstream.ai/install.sh | sh $ curl -fsSL https://cardstream.ai/install.sh | CARDSTREAM_VERSION=v0.3.0 sh $ cardstream-web --version
How do I uninstall it?
Two commands. The first removes the virtualenv and the model weights, the second removes the two shims. There is nothing else to clean up — no daemon, no login item, no system package.
$ rm -rf ~/.cardstream # venv/ + models/ $ rm -f ~/.local/bin/cardstream-web ~/.local/bin/cardstream-client
If you installed with CARDSTREAM_HOME or INSTALL_DIR set, remove those paths instead — and use sudo if you pointed the shims at a system directory. Anything you added by hand is still yours to undo: a PATH line in your shell profile, the XIMILAR_API_KEY export, and any folder you passed to --store-images. The app writes nothing else under your home directory. Check it is gone with command -v cardstream-web in a fresh shell — the old one caches the lookup until you run hash -r.
What it costs and what it needs
No platform in the middle: your hardware, your key, and an engine whose job is to call out as rarely as possible.
Do I need a Ximilar API key?
For the default identification path, yes — and it is the only credential the whole system needs. Get one at ximilar.com and export it as XIMILAR_API_KEY before you start. If you connect your own recogniser instead, you need whatever that endpoint needs and nothing from Ximilar.
$ export XIMILAR_API_KEY=your-key
What does cardstream itself cost?
Nothing. There is no subscription, no per-seat licence and no platform fee — one permissively licensed Python package you run on your own hardware, with detection weights published Apache-2.0 alongside the releases. What you pay for is identification calls to whichever endpoint you connect, and keeping that number down is the entire point of the local engine: roughly one call per distinct card you show, about a hundred in an hour where a naive per-frame pipeline at 15 fps would fire 54,000.
Can I use my own models, or my own identification system?
Both. The card locator and the identity gate are backend-routed — the shipped RF-DETR .onnx export, an RT-DETRv2 one, or a transformers directory or hub id while you are still iterating on a finetune. The identification step behind it is just an endpoint, so pointing it at your own recogniser keeps every gate, throttle and cooldown in front of it unchanged. See the model backends and the model zoo.
Hardware, streams and staying safe
It runs beside your show on the machine you already stream from.
Do I need a GPU?
No. The shipped weights are ONNX exports sized for CPU, and everything the local engine does — the motion gate, the detection throttle, the embedding that answers "same card or new card?" — runs on the processor you already have. A GPU is an option for your own higher-accuracy weights, never a requirement for the defaults.
Does it work with Whatnot or Fanatics Live?
Yes, though not by plugging into the marketplace — it taps the video you are already producing. An OBS virtual camera, a second RTMP or SRT output next to the one feeding the platform, an RTSP pull from an encoder, or simply its own camera pointed at the same mat. The live-selling guide walks all four routes end to end.
What actually leaves my machine?
In client-side mode, one JPEG crop per distinct card — not the stream, not the frames around it, not the rest of the mat. Every decision about whether to send anything is made locally first, so an hour of video where you show a hundred cards is a hundred small requests.
Can I run it on my LAN so another machine can open the UI?
Do not. The web UI is unauthenticated and holds your API key, so it belongs on 127.0.0.1 and nowhere else. The container binds 0.0.0.0 internally, which is why the documented docker run publishes the port to 127.0.0.1 only. If you genuinely need it from another box, put your own authenticated tunnel in front of it rather than opening the port.
$ docker run --rm -e XIMILAR_API_KEY -p 127.0.0.1:8001:8001 \ -v cardstream-models:/models cardstream
What it names, and how sure it is
Every match arrives with its distance, its tier and the cards it could have been instead.
Which cards can it identify?
Four categories, one switch. Trading card games — Pokémon, Magic: The Gathering, Yu-Gi-Oh!, One Piece, Lorcana and around twenty more, modern and vintage singles read straight off the stream. Sports cards across every major sport, down to the parallel and the year. Graded slabs, read off the label without cracking the case. And comics, by title, issue and year. One flag picks the category, or the settings dialog switches it mid-stream. See the full list.
What happens when it names the wrong card?
You see it coming. Every match carries the raw distance and a High / Medium / Low tier — the cutoffs sit at 0.18 and 0.30 — plus up to four alternative cards it could have been, and the right one is usually in that short list. Set a result threshold and anything below it never reaches the overlay at all. If a whole show is one game or one set, the prefills narrow the search before it starts: tell it the game, the set code or the writing system and the endpoint stops guessing them.
Open source. Self-hosted. Your stream, your stack.
No platform in the middle, no seat licence: connect the Ximilar API or your own identification system, and cardstream calls it once per distinct card instead of once per frame. Whether you're breaking on Whatnot, running a Fanatics Live-style show, or streaming your own live commerce setup, run cardstream tonight on the hardware you already have.