Get cardstream running
One command on macOS and Linux; a release wheel, a Dockerfile and a source build when you want more control. macOS arm64, Linux amd64 and Windows amd64 are all covered by the same pure-Python release.
Install in one command
Creates a virtualenv in ~/.cardstream, verifies the
release wheel against its checksums, fetches the model weights and
puts cardstream-web and cardstream-client
on your PATH. Uses uv when
you have it.
$ curl -fsSL https://raw.githubusercontent.com/Ximilar-com/cardstream/main/scripts/install.sh | sh $ export XIMILAR_API_KEY=your-key $ cardstream-web # → http://127.0.0.1:8001 — hold up a card
Knobs, if you need them
-
CARDSTREAM_VERSION— pin a release tag instead of latest, e.g. v0.3.0 -
CARDSTREAM_HOME— install root holding the venv and models (default ~/.cardstream) -
INSTALL_DIR— where the cardstream-web / cardstream-client shims go (default ~/.local/bin) -
CARDSTREAM_MODELS_BASE_URL— alternate host for the per-model weight tarballs -
CARDSTREAM_MODEL_ARCHIVES— which tarballs to fetch from there (space-separated) -
CARDSTREAM_EXTRAS— pip extras to install (default client,onnx) -
CARDSTREAM_TRACKER_URL— the opt-in vitTracker .onnx (default: the OpenCV zoo)
Verify the install
The script verifies the wheel against the release's
SHA256SUMS before installing anything. Afterwards, one
flag confirms what is on your machine:
$ cardstream-web --version
cardstream 0.3.0
Downloaded the artifacts yourself? Check them the same way the script
does: shasum -a 256 -c SHA256SUMS.
Straight from the release
The package is on PyPI, and every GitHub release carries the same wheel and sdist beside a
SHA256SUMS. One pure-Python wheel covers every
platform:
$ pip install 'cardstream[client,onnx]' Windows
The install script is POSIX-only; on Windows install from PyPI, unpack the per-model weight tarballs from the models release, and point the flags at them:
> py -3.11 -m venv cardstream-env > cardstream-env\Scripts\activate > pip install 'cardstream[client,onnx]' > set XIMILAR_API_KEY=your-key > cardstream-web --segmentor-model models\segmentation_model\onnx\model.onnx ^ --embed-model models\similarity_model\onnx\model.onnx
Pick your path
| Path | Best when | First verification |
|---|---|---|
| Install script | You want the fastest localhost setup — venv, model weights and PATH shims handled for you. | cardstream-web --version |
| Docker | A clean host, or ingesting an OBS push on a box near the encoder. | curl -s http://127.0.0.1:8001/mode |
| Build from source | You are changing the code. | pytest -q tests/core/test_engine.py |
Run it in a container
The image fetches model weights into a volume on first run and
starts the web client. Build it from the repo's
Dockerfile:
$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream $ docker build -t cardstream . $ docker run --rm -e XIMILAR_API_KEY -p 127.0.0.1:8001:8001 \ -v cardstream-models:/models cardstream
The container binds 0.0.0.0 internally — publish the port to 127.0.0.1 only, as above. The app is unauthenticated and holds your Ximilar API key; never expose it to a LAN or the internet.
Build from source
A checkout, one script, and the offline test suite as your first
verification. --models also fetches the weights.
$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream $ ./scripts/build-from-source.sh --models $ source .venv/bin/activate $ cardstream-web --version
Next steps
Install and run →
Your key, your first run, and what to check.
Feed it your show →
Webcams, RTSP pulls, OBS pushing straight in.
Operate with confidence →
Thresholds, the recommended run, and staying on localhost.
Update or uninstall →
Where the script puts things, and the two commands that undo it.