cardstream
GitHub 开始使用
语言: 简体中文
English Español 日本語 한국어 简体中文 ไทย Português Français Italiano Deutsch हिन्दी বাংলা پنجابی Dansk Svenska Polski Русский اردو العربية Tiếng Việt Türkçe Nederlands Bahasa Indonesia
开源 由 Ximilar 提供技术支持 测试版

为直播而生的卡牌识别。 专为拆盒、开包和直播秀打造。

cardstream 盯着你的拆盒、开包或直播秀，卡牌一进入画面就立刻识别：名称、系列、置信度，实时呈现。用卡牌追踪系统分析你的直播带货，让想更了解自己直播的主播心里有数。

三步开始 在 GitHub 上查看
能识别什么

从宝可梦到万智牌

每场直播切换一次类别，整套引擎都会跟着走：检测、闸门和识别调用全部指向正确的端点。每条匹配结果都带有名称、系列、系列代码、卡号、子系列和年份。

🃏

集换式卡牌游戏

collectibles/v2/tcg_id
Ximilar 已可用

从现行到复古的 TCG 单卡，直接从直播画面识别。端点会读取插画、边框和文字，所以用观众看到的同一幅画面就能认出这张卡：不用找系列符号，也不用眯着眼看收藏编号。

  • 宝可梦
  • 万智牌
  • 游戏王
  • 航海王卡牌
  • Lorcana
  • 数码宝贝
  • 龙珠超
  • Flesh and Blood
  • Star Wars Unlimited
  • Star Wars Destiny
  • MetaZoo
  • Riftbound
  • Weiss Schwarz
  • Union Arena
  • Force of Will
  • Grand Archive
  • Vanguard
  • Marvel Champions
  • Sorcery
  • 最终幻想
  • 高达
  • Duel Masters
  • Naruto Mythos
  • Hololive
  • Garbage Pail Kids
🏅

球星卡 sport_id

新秀卡、平行卡、特卡和签字卡，覆盖棒球、篮球、美式足球、足球、冰球等各大运动：精确到具体是哪张卡、哪个系列、哪一年。

即将推出
🧊

评级卡砖 slab_id

读取评级盒上的标签：PSA、BGS 或 CGC 卡砖里的那张卡，不用拆盒就能识别。

即将推出
📚

漫画 comics_id

封面识别方式和卡牌一样：从一帧静止画面里读出书名、期号和年份。

即将推出
不绑定单一供应商

接入专有识别器，或者你自己的

所有决定要不要调用的逻辑都发生在识别之前：检测、运动闸门和同卡闸门都在本地运行，与供应商无关。调用本身只是一个可替换的步骤：默认是 Ximilar，也可以是某个专有的卡牌识别服务，或者你自己训练、在自己硬件上托管的模型。

接口很小：进去一张卡的裁切图，出来一条匹配。实现 IdentifyTarget，前面所有的闸门、节流和阈值都照常工作：无论由谁来回答，仍然是每张不同的卡只发一张裁切图。

# 你自己的识别器，同一套引擎
class HouseIdentifier(IdentifyTarget):
    def identify(self, crop_bgr):
        return my_service.match(crop_bgr)

# 无论哪种方式，每张不同的卡只发一张裁切图
$ cardstream-web --detector rfdetr
为什么选 cardstream.ai？

每张卡调用一次，而不是每帧一次

目标很简单：把直播分析的调用压缩到那些真正带来新信息的次数。这是对封闭式卡牌识别 SaaS 的开源替代：没有中间平台，没有席位许可。你的硬件、你的 API 密钥，再加一台只在画面里出现真正新卡时才向外请求的状态机。

54,000 → ~100
每小时 API 调用次数

一条逐帧处理的朴素流水线在 15 fps 下每小时会触发 54,000 次识别。cardstream 对你展示的每张不同卡只触发一次：同样一小时，大约一百次。

540×
识别调用次数减少

同样的一小时、同样的视频、同样的卡：54,000 次对比约 100 次。运动闸门和身份闸门都在你自己的硬件上本地运行，只有一张真正新的卡在画面里静止下来时，才会发出调用。

$0
平台费用

没有 SaaS 订阅，没有按席位定价，没有锁定。连识别在内的整套系统都可以自托管，也可以直接接入 Ximilar API。

功能

卡牌直播秀需要的一切

一位从不漏看任何一张卡的搭档：适用于 Whatnot、Fanatics Live 这类平台上的直播带货、拆盒、卡店直播，以及收藏整理编目。凡是摄像头对着卡牌的地方，都用得上。

⚡

进入画面的瞬间就认出来

没有扫描按钮，不用等待。把卡亮出来就行：名称、系列、置信度，从纸板到卡名大约半秒，直播中实时显示。

🎯

每张卡只调用一次

运动闸门和基于嵌入向量的身份闸门都在你自己的 CPU 上本地运行。卡拿稳不动，零次重复调用；换一张卡，正好一次新调用。

📡

任意视频源

网络摄像头、视频文件、RTSP、RTMP 和 SRT，既可以拉流，也可以用 --listen 直接接收 OBS 的推流。自制设备还可以用 WebSocket JPEG 流。

🔌

任意识别后端

Ximilar collectibles/v2 开箱即用，也可以把同一套引擎指向某个专有的卡牌识别器，或者你自己训练并托管的模型。

🧠

自带模型

定位器的权重是我们自己的：一个微调过的 RF-DETR 分割模型，Apache-2.0 许可，由安装器自动下载。如果你更想用自己导出的模型，也支持边界框检测器（RF-DETR、RT-DETRv2）。

🔓

开源，自托管

一个 Python 包，宽松许可。读它、fork 它、在自己的硬件上跑它。你的密钥、你的数据、你的基础设施。

工作原理

聪明到知道什么时候不该调用 API

你的视频流和 API 之间站着一台状态机。每一帧都流经 DecisionCore，一台在本地运行的状态机，由三道本地闸门决定唯一的那一步 API 调用什么时候真的有必要。

1

检测

本地 · 不调用 API

找到卡牌的四边形，校正透视，裁出一张干净的图。由本地运动闸门分三档节流：移动中、静止有卡、空桌面。

2

运动闸门

本地 · 不调用 API

一次开销极小的帧间平均差分。只有画面连续 N 帧静止，这张卡才值得细看。还在动？那就等。

3

身份闸门

本地 · 不调用 API

一次嵌入向量比对，只回答一个问题：这和刚才是同一张卡吗？是同一张，就重新发出缓存的结果。

4

识别

ximilar · 1 次调用

只有一张真正新的、已经静止的卡才会触发 Ximilar 识别：异步、带防抖、在帧循环之外执行。结果实时推回直播。

面向主播、拆盒玩家和卡店

你是一个人在做直播吗？

一个人、一台摄像头、一整夜的拆盒。要知道屏幕上是哪张卡，不该需要一支工程团队。把你正在进行的直播接进来，让 cardstream 实时分析，不管你是在交易平台上卖，还是直接在自己的频道里卖。

  • Whatnot
  • Fanatics Live
  • eBay Live
  • TikTok Shop
  • Twitch
  • YouTube Live
  • 你自己的网站

不需要账号权限，不需要平台的 API 密钥，不往你的聊天室里放机器人，也和这些平台没有任何关联。cardstream 只读你的视频，别的什么都不碰。

01

你已经在用 OBS 直播

在推给直播间的那路输出旁边再加一路。买家看到的和以前一模一样，只是同一画面的一份拷贝进了 cardstream，每张放到桌上的卡经过时都会被识别出来。下面这个监听模式需要系统里装有 ffmpeg；也可以完全跳过第二路输出，让 cardstream 把 OBS 虚拟摄像头当成普通网络摄像头来读。

$ cardstream-web --listen \
      --source rtmp://0.0.0.0:1935/live
# 把 OBS 的第二个推流目标指到这里
02

或者桌上已有的那台摄像头

俯拍摄像头、采集卡、当网络摄像头用的手机，你开包展示时用的是什么都行。分析在摄像头旁边的那台机器上进行，所以默认情况下，离开这间屋子的只有每张卡的一张裁切图。

$ cardstream-web --source 0
# 网络摄像头 · 浏览器界面在 localhost
03

或者任何有 URL 的东西

编码器、切换台、转推服务、城市另一头的第二间演播室。RTSP、RTMP 和 SRT 拉流，自制设备还能用 WebSocket JPEG 流。

$ cardstream-web \
      --source rtsp://studio/stream1

实时叠加层

卡一静止，名称、系列和置信度就出现，可以直接念出来，也可以合成回你的场景里。

每张卡都有记录

一份持续更新的历史记录，列出你展示过的每一张卡：每张卡的缩略图，以及它在直播中停留了多久。把它保存到你的 Ximilar 账号，第二天早上回看这场直播：卖出了什么，值多少钱。

一个人也用得起

没有平台费，没有席位许可。三小时的直播只是寥寥几次识别调用，而不是每帧一次。

分步教程：接入 Whatnot 或 Fanatics Live 直播 →

Cardstream Cloud

把直播保存下来，随时回看

cardstream 在你自己的机器上运行，默认不保存任何东西。加上一个参数，你展示的每张卡（连同价格、在画面中停留的时长和据以识别它的裁切图）也会保存到你 Ximilar 账号里的一个会话。直播结束后打开 Ximilar 应用，看看这场直播值多少。

$ cardstream-web --price-stats \
    --ximilar-stream NEW
# 打印会话 id，并在直播进行时保存
打开 Ximilar 应用 保存是如何工作的
Ximilar 应用中一个已保存的会话：展示的商品数、付费 API 调用、市场价值、平均停留时长、最有价值的商品和出现最多的系列。

用数字看直播

每个会话都有展示的商品数、付费 API 调用、市场价值和平均停留时长，旁边列出最有价值的商品和出现最多的系列。

每张卡都带图片

每一行都保留卡牌、系列、编号、价格和据以识别它的裁切图。可以按商品或系列搜索列表，并按状态、平台和日期筛选会话。

变成你自己的记录

标记已售出的卡、添加备注、更正认错的匹配或它的价格、删除误识别的条目。给会话命名，并附上你自己的元数据：批次号、成本、买家。

从中断的地方继续

直播中途重启了？把 NEW 换成会话 id，直播就会在同一个会话里继续，即使会话已经关闭也一样。用 --ximilar-workspace 可以保存到团队工作区。

默认关闭：不加 --ximilar-stream 时，离开你机器的只有识别调用。保存需要你的 Ximilar 账号开通 Cardstream 服务；只有开始一个会话会计费，--no-ximilar-stream-images 则只保存文字。

快速上手

三步从零到实时识别

1

安装

一个虚拟环境、发行版 wheel（校验和已验证）、模型权重，以及加到 PATH 里的两个命令。可以用脚本，可以用 pip 从 PyPI 安装同一个 wheel（权重需另行下载），也可以克隆仓库自己构建。Docker 和 Windows 的说明见下载页。

$ curl -fsSL https://raw.githubusercontent.com/Ximilar-com/cardstream/main/scripts/install.sh | sh
# 其他安装方式 → cardstream.ai/download
$ pip install 'cardstream[client,onnx]'   # 或者：uv tool install 'cardstream[client,onnx]'
# wheel 里不含权重：从 cardstream.ai/models 解压两个 tarball，
# 再用参数指向它们：
$ cardstream-web --segmentor-model segmentation_model/onnx/model.onnx \
    --embed-model similarity_model/onnx/model.onnx
$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream
$ ./scripts/build-from-source.sh --models
$ source .venv/bin/activate
2

接入识别系统

Ximilar collectibles/v2 开箱即用：整个系统只需要一个从 ximilar.com 获取的密钥。也可以把这一步指向你自己的识别器。

$ export XIMILAR_API_KEY=your-key
3

把摄像头对准卡牌

用网络摄像头打开浏览器界面，或者把你的直播喂给它：RTSP 拉流，或让 OBS 直接推 RTMP 进来。整晚只拆一个系列？预先指定好，端点就不用再猜：CRI 的英文版宝可梦卡，少了三样可能出错的东西。指定 --game 时务必同时指定 --alphabet，因为预设游戏会关闭端点自己的文字系统检测。加上 --price-stats，每条匹配还会附带美元市场价：中位数、区间和最近成交价，卡片上和历史记录里都有。加上 --ximilar-stream NEW，就能把直播保存到你的 Ximilar 账号，事后回看。

$ cardstream-web
# → http://127.0.0.1:8001 — 把卡举到镜头前

# 英文版宝可梦卡，单一系列（CRI - Chaos Rising），附美元市场价：
$ cardstream-web --game Pokemon --set-code CRI --alphabet latin --price-stats

开源。自托管。你的直播，你的技术栈。

没有中间平台，没有按席位收费的许可：接入 Ximilar API 或你自己的识别系统，cardstream 对每张不同的卡只调用一次，而不是每帧一次。无论你是在 Whatnot 上拆盒、做 Fanatics Live 式的直播秀，还是在自己的直播电商环境里开播，今晚就能用手头现有的硬件跑起 cardstream。

在 GitHub 上点个 Star 获取 Ximilar API 密钥