English 
Español 
日本語 
한국어 
ไทย 
Português 
Français 
Italiano 
Deutsch 
हिन्दी 
বাংলা 
پنجابی 
Dansk 
Svenska 
Polski 
Русский 
العربية 
Tiếng Việt 
Türkçe 
Nederlands 
Bahasa Indonesia 文档
一切都在你的机器上运行：安装它，把摄像头对准它，再调好它什么时候允许向外调用。按你想做的事分组。
从零到屏幕上出现一张卡
一条命令装好客户端、模型权重和启动脚本。整个系统唯一的凭据就是你的 Ximilar 密钥。
安装脚本
在 ~/.cardstream 里创建虚拟环境，用校验和验证发行版 wheel，下载模型权重，并把两个命令加到 PATH。其他方式（wheel、Docker、源码）见下载页。
$ curl -fsSL https://raw.githubusercontent.com/Ximilar-com/cardstream/main/scripts/install.sh | sh 全部安装方式 → 手动安装
检出仓库再 pip 安装也行。extras 相互独立：[client] 是界面和视频源，[onnx] 或 [torch] 提供检测器和嵌入模型的后端。
$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream $ pip install -e '.[client,onnx]'
你的 Ximilar 密钥
识别由 Ximilar collectibles/v2 提供。XIMILAR_API_KEY 是唯一会被读取的环境变量，其他一切都是命令行参数。
$ export XIMILAR_API_KEY=your-key
首次运行
用你的网络摄像头打开浏览器界面。举起一张卡，叠加层会显示状态机的判断过程，以及最终落定的匹配结果。
$ cardstream-web # → http://127.0.0.1:8001
确认装了什么
两个命令都会打印版本号后退出，不需要模型文件，所以安装一结束就能用。
$ cardstream-web --version
cardstream 0.5.0 无界面模式，适合固定设备
同一条流水线，不带浏览器：结果直接打印到终端。参数和 cardstream-web 完全一样，在摄像头旁边跑一个进程即可。
$ 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 输出即可。需要系统里装有 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
设置对话框
类别、游戏、系列代码、字母表和阈值都可以在直播中从浏览器里重新调整：无需重启，而且这些控件带有和进程端完全一致的验证。
三个分辨率参数
摄像头采集的分辨率、发送的分辨率和分析的分辨率是三个独立的数值。分析用小图跑，识别用的裁切图则从完整帧重新裁出。
$ cardstream-web --camera-width 3840 --width 1280 保存直播，日后回看
默认关闭。一个参数就能把页面生成的历史记录（你展示过的每张卡，连同它的裁切图）保存到你自己 Ximilar 账号里的一个会话中，第二天早上这场直播依然都在。
带缩略图的历史记录
浏览器界面按从新到旧列出你展示过的每张卡：被识别的那张裁切图的缩略图、加上 --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>
每张不同的卡只调用一次识别
本地信号（运动、检测、身份闸门）决定一次识别调用是否真的有必要。下面这些参数让它保持诚实。
阈值
结果阈值把弱匹配挡在叠加层之外；相似度阈值判断是同一张卡还是新卡；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，保持不变，绝不要把端口暴露到局域网。
启动时提示 "Model not found"
模型权重需要单独下载，不在仓库里。安装脚本和 Docker 镜像会自动获取；直接检出的仓库需要把它们放进 model/segmentation/ 和 model/similarity/，运行 scripts/build-from-source.sh --models 会帮你完成。
指定你正在展示的游戏
只有一个游戏的直播，没必要让端点每次调用都去猜是哪个游戏。指定名称后搜索范围就收窄到该游戏：回答更快，认错版本更少。同时传上 --alphabet，因为预设游戏会让端点不再自行检测文字系统。
$ cardstream-web --game "Pokémon" --alphabet japanese
什么时候需要 ffmpeg
--listen 和 --ffmpeg 会调用系统里的 ffmpeg。普通拉流只靠 pip 安装就能工作；OBS 推流的方案则不行。
默认值之外
换掉模型或者读读代码：整条流水线就是一个可安装的包。