よくある質問

実行に必要なものは何ですか？

Python 3.11 以降が動くマシン、ほぼそれだけです。macOS arm64、Linux amd64、Windows amd64 のいずれも同じ pure-Python のリリースで対応しており、GPU は不要です。システムの ffmpeg バイナリが必要になるのは pull ソースと listen ソース（RTSP、RTMP、SRT）を使う場合だけで、ウェブカメラ、ファイル、ブラウザ UI では必要ありません。

インストールスクリプトはファイルをどこに置きますか？

2か所です。~/.cardstream がインストールルートで、venv/ に仮想環境（venv）、models/ にモデルの重みが入ります。cardstream-web と cardstream-client の2つのコマンドは ~/.local/bin に書き込まれる小さなシム（ラッパースクリプト）で、モデルのパスをあらかじめ埋めた状態で venv 内のバイナリを exec するため、あなたが渡したフラグが常に優先されます。どちらの場所も CARDSTREAM_HOME と INSTALL_DIR で変更できます。マシン上のそれ以外の場所には一切触れません。特にシェルのプロファイルは決して編集しません。~/.local/bin が PATH に含まれていない場合は注意メッセージを表示し、変更はあなたに委ねます。

新しいバージョンに更新するにはどうすればいいですか？

同じワンライナーをもう一度実行してください。既存の仮想環境（venv）に最新リリースをインストールし、シムを書き直します。~/.cardstream/models にすでにある重みはそのまま残されます（重みは存在しないときにだけ取得されます）。そのため更新は小さなダウンロードで済み、ギガバイトの4分の1ほどをまるごとダウンロードし直すことにはなりません。最新版ではなく特定のリリースを入れたい場合は CARDSTREAM_VERSION を設定してください。

# 同じワンライナー。/install.sh は main ブランチ上のスクリプトにリダイレクトされます
$ curl -fsSL https://cardstream.ai/install.sh | sh
$ curl -fsSL https://cardstream.ai/install.sh | CARDSTREAM_VERSION=v0.5.0 sh
$ cardstream-web --version

アンインストールするにはどうすればいいですか？

コマンド2つです。1つ目で仮想環境（venv）とモデルの重みを削除し、2つ目で2つのシムを削除します。ほかに片付けるものはありません。デーモンも、ログイン項目も、システムパッケージもありません。

$ rm -rf ~/.cardstream # venv/ + models/
$ rm -f ~/.local/bin/cardstream-web ~/.local/bin/cardstream-client

CARDSTREAM_HOME や INSTALL_DIR を設定してインストールした場合は、代わりにそれらのパスを削除してください。シムをシステムディレクトリに置いた場合は sudo を使います。手動で追加したものは、自分で元に戻す必要があります。シェルのプロファイルに書いた PATH の行、XIMILAR_API_KEY の export、--store-images に渡したフォルダなどです。アプリがホームディレクトリ以下に書き込むものはほかにありません。新しいシェルで command -v cardstream-web を実行して消えたことを確認してください。古いシェルは hash -r を実行するまで以前の検索結果をキャッシュしています。

GPU は必要ですか？

不要です。同梱の重みは CPU 向けにサイズを抑えた ONNX エクスポートで、ローカルエンジンが行うすべての処理（モーションゲート、検出のスロットル、「同じカードか、新しいカードか」を判定する埋め込み）は、いま手元にあるプロセッサで動きます。GPU は独自の高精度な重みを使うときの選択肢であって、デフォルト構成で必須になることはありません。

Whatnot や Fanatics Live でも使えますか？

使えます。ただしマーケットプレイスに直接つなぐのではなく、すでに配信している映像を取り込む形です。OBS の仮想カメラ、プラットフォームに送っている出力とは別の2本目の RTMP または SRT 出力、エンコーダーからの RTSP プル、あるいは同じマットに向けた専用カメラ。ライブ販売ガイドでは、この4つの経路すべてを最初から最後まで解説しています。

実際にマシンの外に出ていくものは何ですか？

クライアントサイドモードでは、異なるカード1枚につき JPEG の切り抜き1枚だけです。ストリームも、前後のフレームも、マットの残りの部分も送られません。何かを送るかどうかの判断はすべて先にローカルで下されるため、100枚のカードを見せた1時間の映像は、100件の小さなリクエストになります。例外は1つだけで、それをオンにするかどうかはあなたが決めます。--ximilar-stream を付けると、配信の履歴（カードごとのテキスト1行と、その識別に使われた切り抜き）が、あなた自身の Ximilar アカウントのセッションにも保存されます。デフォルトではオフで、--no-ximilar-stream-images を付ければテキストだけになります。

配信をあとから振り返ることはできますか？

保存しておけばできます。--ximilar-stream NEW を付けて起動すると、履歴に並ぶすべてのカードが、価格、配信に映っていた時間、識別に使われた切り抜きとともに、配信の進行に合わせて Ximilar アカウントのセッションに送られます。配信後にXimilar アプリの Cardstream セクションを開けば、配信の総額、最も高額な商品と上位のセット、画像付きのすべてのカードを確認でき、売れたカードに印を付けたり、誤ったマッチを修正したりできます。配信の途中で再起動した場合は、NEW の代わりにセッション ID を渡せば、セッションが閉じていても続きから記録されます。チームのワークスペースに保存するには --ximilar-workspace を使います。詳しくはこちら。

$ cardstream-web --price-stats --ximilar-stream NEW

LAN 上で動かして別のマシンから UI を開くことはできますか？

やめてください。Web UI は認証がなく APIキーを保持しているため、置くべき場所は 127.0.0.1 だけです。コンテナは内部で 0.0.0.0 にバインドしており、ドキュメントの docker run がポートを 127.0.0.1 にだけ公開しているのはそのためです。どうしても別のマシンから使う必要がある場合は、ポートを開放するのではなく、認証付きのトンネルを自分で手前に置いてください。

$ docker run --rm -e XIMILAR_API_KEY -p 127.0.0.1:8001:8001 \
    -v cardstream-models:/models cardstream