ダウンロード

cardstream を動かす

macOS と Linux ならコマンド1つ。より細かく制御したいときは、リリースの wheel、Dockerfile、ソースからのビルドが使えます。macOS arm64、Linux amd64、Windows amd64 のいずれも、同じピュア Python のリリースでカバーされます。

インストールスクリプト

コマンド1つでインストール

~/.cardstream に仮想環境（venv）を作成し、リリースの wheel をチェックサムと照合してから、モデルの重みを取得し、cardstream-web と cardstream-client を PATH に配置します。uv が入っていればそれを使います。

$ 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 — カードをかざしてください

必要に応じて使える設定

CARDSTREAM_VERSION — 最新版の代わりにリリースタグを固定します（例: v0.5.0）
CARDSTREAM_HOME — venv とモデルを置くインストール先のルート（デフォルト ~/.cardstream）
INSTALL_DIR — cardstream-web / cardstream-client のシム（ラッパースクリプト）を置く場所（デフォルト ~/.local/bin）
CARDSTREAM_MODELS_BASE_URL — モデルごとの重み tarball を取得する代替ホスト
CARDSTREAM_MODEL_ARCHIVES — そこから取得する tarball の指定（スペース区切り）
CARDSTREAM_EXTRAS — インストールする pip の extras（デフォルト client,onnx）
CARDSTREAM_TRACKER_URL — オプトインの vitTracker の .onnx（デフォルト: OpenCV zoo）

動作確認

インストールを確認する

スクリプトは、何かをインストールする前に wheel をリリースの SHA256SUMS と照合します。インストール後は、フラグ1つでマシンに入っているものを確認できます:

$ cardstream-web --version
cardstream 0.5.0

成果物を自分でダウンロードした場合は、スクリプトと同じ方法で確認できます: shasum -a 256 -c SHA256SUMS。

手動ダウンロード

リリースから直接

パッケージは PyPI にあり、各 GitHub リリースにも同じ wheel と sdist が SHA256SUMS と並んで置かれています。ピュア Python の wheel 1つで、すべてのプラットフォームをカバーします:

$ pip install 'cardstream[client,onnx]'

Windows

インストールスクリプトは POSIX 専用です。Windows では PyPI からインストールし、モデルのリリースからモデルごとの重み tarball を展開して、フラグでその場所を指定します:

> 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

比較

方法を選ぶ

方法	向いているケース	最初の動作確認
インストールスクリプト	localhost で最速にセットアップしたいとき。venv、モデルの重み、PATH のシムをすべて任せられます。	`cardstream-web --version`
Docker	クリーンなホストで動かしたいとき、またはエンコーダーの近くのマシンで OBS からのプッシュを受け取りたいとき。	`curl -s http://127.0.0.1:8001/mode`
ソースからビルド	コードに手を入れるとき。	`pytest -q tests/core/test_engine.py`

Docker

コンテナで動かす

イメージは初回起動時にモデルの重みをボリュームへ取得し、Web クライアントを起動します。リポジトリの 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

コンテナ内部では 0.0.0.0 にバインドされるため、ポートの公開は上記のとおり 127.0.0.1 のみにしてください。このアプリには認証がなく、Ximilar の APIキーを保持しています。LAN やインターネットに公開しないでください。

ソース

ソースからビルド

チェックアウトしてスクリプトを1つ実行し、最初の動作確認としてオフラインのテストスイートを走らせます。--models を付けると重みも取得します。

$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream
$ ./scripts/build-from-source.sh --models
$ source .venv/bin/activate
$ cardstream-web --version

cardstream を動かす

コマンド1つでインストール

必要に応じて使える設定

インストールを確認する

リリースから直接

Windows

方法を選ぶ

コンテナで動かす

ソースからビルド

次のステップ

インストールと実行 →

配信映像を入力する →

安心して運用する →

更新とアンインストール →