ドキュメント — cardstream

ドキュメント

すべてがお使いのマシン上で動きます。インストールしてカメラを向け、外部への呼び出しを許可するタイミングを調整するだけです。やりたいことごとにまとめました。

インストールと実行

ゼロから画面にカードが映るまで

コマンド1つでクライアント、モデルの重み、シムがインストールされます。システム全体で必要な認証情報は Ximilar のAPIキーだけです。

インストールスクリプト

~/.cardstream に仮想環境（venv）を作成し、リリース版の wheel をチェックサムで検証し、モデルの重みを取得して、2つのコマンドを PATH に登録します。wheel、Docker、ソースからのインストール方法はダウンロードページにまとめています。

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

すべてのインストール方法 →

手動インストール

チェックアウトして pip でも入れられます。extras は互いに独立しています。[client] がUIとソース（入力）、[onnx] または [torch] が検出モデルと埋め込みモデルのバックエンドです。

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

Ximilar のAPIキー

識別は Ximilar collectibles/v2 が担います。どこかで読み取られる環境変数は XIMILAR_API_KEY の1つだけで、それ以外の設定はすべてフラグです。

$ export XIMILAR_API_KEY=your-key

初回の実行

ウェブカメラを映したブラウザUIが開きます。カードをかざすと、オーバーレイにステートマシンの判断の様子が表示され、確定した時点で一致したカードが出ます。

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

インストール内容の確認

どちらのコマンドもバージョンを表示して終了します。モデルファイルは不要なので、インストール直後から動きます。

$ cardstream-web --version
cardstream 0.5.0

ヘッドレス実行（配信リグ向け）

ブラウザなしで同じパイプラインを動かし、結果をターミナルに出力します。フラグは cardstream-web と同じで、カメラの隣で1プロセス動かすだけです。

$ cardstream-client --source 0

使う

配信映像を取り込む

ソース（入力）は差し替え可能で、どれを選んでも解析は同じです。設定はすべてフラグで指定でき、重要なものは設定ダイアログから配信中にそのまま調整できます。

ウェブカメラとファイル

cardstream-web の既定はブラウザのウェブカメラです。デバイス番号、動画ファイル、静止画はどちらのコマンドでも使えます。配信前のテストに便利です。

$ cardstream-web # ブラウザのウェブカメラ
$ cardstream-client --source clip.mp4

ストリームを受信する

IPカメラ、エンコーダー、リストリーマーを指定できます。rtsp://、rtmp://、srt://、および ws:// のJPEGフィードに対応し、上限付きバックオフで自動再接続します。

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

OBS から送る

待ち受けモードで起動し、OBS 側に RTMP または SRT の出力を1つ追加するだけです。システムの ffmpeg バイナリが必要です（brew install ffmpeg）。

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

事前指定で検索を絞る

ゲーム、セットコード、文字体系は送信前にローカルで検証されます。--game を渡すときは必ず --alphabet も渡してください。ゲームを事前指定すると、エンドポイント側での文字体系の自動判定が行われなくなるためです。

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

設定ダイアログ

カテゴリー、ゲーム、セットコード、文字体系、しきい値は配信中にブラウザから変更できます。再起動は不要で、プロセス側と同じ検証がそのまま効きます。

3つの解像度設定

カメラが取り込む解像度、送信する解像度、解析する解像度はそれぞれ別の値です。解析は小さい解像度で行い、識別用の切り出しはフル解像度のフレームから改めて取り直します。

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

配信を振り返る

配信を保存して、あとから振り返る

既定ではオフです。フラグを1つ付けるだけで、ページに溜まっていく履歴（見せたすべてのカードとその切り抜き）が、あなた自身の Ximilar アカウント内のセッションに保存されます。翌朝になっても、配信の記録はそのまま残っています。

サムネイル付きの履歴

ブラウザUIには、見せたすべてのカードが新しい順に並びます。識別に使われた切り抜きのサムネイル、--price-stats を付けた場合はその価格、そして配信に映っていた時間。このリストはお使いのマシンの中にあります。

配信を保存する

--ximilar-stream NEW を付けるとセッションが始まり、その ID が表示されます。以降は配信の進行に合わせて、履歴の各行が保存されていきます。アップロードはバックグラウンドでまとめて行われ、ネットワークエラーのときは再試行され、配信を止めることはありません。正常に終了すると、残りをアップロードしてセッションを閉じます。

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

配信の保存について詳しく →

アップロードされるもの

テキストとしての各行（カード、セット、価格、配信に映っていた時間、その裏で発生した有料の呼び出し）と、各行の識別に使われた最大 1024 px の切り抜きです。この切り抜きは、識別呼び出しがすでに受け取っている画像そのものです。--no-ximilar-stream-images を付ければテキストだけになります。Ximilar アカウントで Cardstream サービスを利用できる必要があります。

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

Ximilar アプリで振り返る

すべてのセッションは Ximilar アプリの Cardstream セクションに届きます。いつ何を見せたか、配信の総額、最も高額な商品と上位のセット、そして切り抜き付きの各カード。売れたカードに印を付けたり、誤ったマッチを修正したり、メモを残したりできます。

Ximilar アプリを開く →

再起動後に再開する

NEW の代わりにセッション ID を渡せば、同じセッションのまま配信を続けられます。正常終了でセッションが閉じていても、そのまま開き直されます。課金されるのはセッションの開始だけなので、再開に費用はかかりません。

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

チームのワークスペース

セッションは、APIキーの既定のワークスペースに保存されます。別のワークスペースは --ximilar-workspace で指定できます。そこに保存したセッションを再開するときは、同じ ID をもう一度渡してください。

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

安心して運用する

カード1枚につき識別呼び出しは1回

モーション、検出、同一性ゲートといったローカルの信号が、識別呼び出しが本当に必要かどうかを判断します。それを正しく保つための設定項目がこちらです。

しきい値

結果しきい値は弱い一致をオーバーレイに出さないためのもの、類似度しきい値は同じカードか新しいカードかを判定するもの、forget-after はカードが十分長く画面から消えたあとに記憶をクリアするものです。

$ cardstream-web --result-threshold 0.35

推奨構成

RF-DETR のセグメンテーションと ONNX の埋め込みゲートの組み合わせが、同梱の既定値です。重みが揃っていれば、引数なしの cardstream-web がまさにこの構成で動きます。明示的に書いても同じパイプラインです。

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

localhost から出さない

ローカルアプリには認証がなく、APIキーを保持しています。--host の既定値は 127.0.0.1 です。そのままにして、ポートを LAN に公開しないでください。

起動時の「Model not found」

モデルの重みはリポジトリに含まれておらず、別途ダウンロードが必要です。インストールスクリプトと Docker イメージは自動で取得します。素のチェックアウトの場合は model/segmentation/ と model/similarity/ に配置する必要があり、scripts/build-from-source.sh --models を実行すれば自動で行われます。

扱うゲームを指定する

1つのゲームだけを扱う配信なら、呼び出しのたびにエンドポイントにゲームを推測させる必要はありません。ゲーム名を指定すると検索がそのゲームに絞られ、応答が速くなり、誤った版の判定も減ります。あわせて --alphabet も渡してください。ゲームを事前指定すると、エンドポイント側での文字体系の自動判定が行われなくなるためです。

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

ffmpeg が必要になる場面

--listen と --ffmpeg はシステムの ffmpeg バイナリを呼び出します。通常のストリーム受信は pip だけのインストールで動きますが、OBS から送る構成には ffmpeg が必要です。

さらに詳しく

既定値のその先へ

モデルを差し替えるのもコードを読むのも自由です。パイプライン全体が1つのインストール可能なパッケージになっています。

独自の重みを使う

検出と同一性ゲートはバックエンド振り分け方式です。モデルファミリーでクラスが決まり、ファイルの拡張子でランタイムが決まります。RF-DETR または RT-DETRv2、.onnx または transformers ディレクトリに対応しています。

モデルバックエンド →

モデル一覧

cardstream が読み込めるすべての重みは Ximilar が学習させ、Apache-2.0 ライセンスでリリースと一緒に公開しています。それぞれの役割、動作速度、ライセンスをまとめています。

モデル一覧 →

手短な答え

費用はいくらか、マシンの外に何が出ていくのか、どのカードを識別できるのか、そしてアンインストールするための2つのコマンド。

FAQ を読む →

README と Issue

README にはすべてのフラグの説明があります。バグ報告や質問は Issue へどうぞ。

README を読む →

リリースと成果物

wheel、チェックサム、インストールスクリプトをリリースごとに1セットずつ公開しています。Docker とソースからのビルドもあります。

ダウンロードページ →