Документация

Всё работает на вашем компьютере: установите cardstream, подключите камеру и настройте, когда ему разрешено обращаться к API. Разделы сгруппированы по задачам.

Установка и запуск

С нуля до карты на экране

Одна команда устанавливает клиент, веса моделей и скрипты-обёртки. Единственные учётные данные во всей системе — ваш ключ Ximilar.

Скрипт установки

Создаёт venv в ~/.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:// и JPEG-кадры по ws://, а при обрыве связь восстанавливается с растущей, но ограниченной паузой.

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

Пусть OBS отправляет сам

Запустите cardstream в режиме ожидания и добавьте в 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 создаёт сеанс и выводит его идентификатор. С этого момента каждая строка истории сохраняется по ходу эфира: данные отправляются пакетами в фоне, при сетевых ошибках отправка повторяется, и эфир это никогда не задерживает. При штатном завершении отправляется остаток, и сеанс закрывается.

$ 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

Каждый сеанс попадает в раздел Cardstream приложения Ximilar: что и когда вы показали, стоимость эфира, самые дорогие товары и самые частые сеты, а также каждая карта со своим кропом. Отмечайте проданное, исправляйте неверные совпадения, добавляйте заметки.

Открыть приложение Ximilar →

Продолжение после перезапуска

Передайте идентификатор сеанса вместо NEW, и эфир продолжится в том же сеансе. Даже если сеанс закрылся при штатном завершении, он просто откроется снова. Оплачивается только создание сеанса, так что продолжение ничего не стоит.

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

Командные рабочие пространства

Сеанс сохраняется в рабочее пространство, которое задано по умолчанию для вашего API-ключа. Другое можно указать флагом --ximilar-workspace; тот же идентификатор передавайте, когда продолжаете сохранённый там сеанс.

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

Работа без сюрпризов

Каждой новой карте — один запрос на распознавание

Локальные сигналы (движение, детекция, фильтр повторов) решают, когда запрос на распознавание действительно оправдан. Вот настройки, которые держат это под контролем.

Пороги

Порог результата не пускает слабые совпадения в оверлей; порог сходства отделяет ту же карту от новой; forget-after очищает память, когда карты нет достаточно долго.

$ cardstream-web --result-threshold 0.35

Оставайтесь на 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 — нет.

Глубже

За пределами настроек по умолчанию

Замените модели или почитайте код: весь пайплайн — это один устанавливаемый пакет.

Свои веса

Детекция и фильтр повторов выбирают бэкенд сами: семейство модели определяет класс, а расширение файла — среду выполнения. RF-DETR или RT-DETRv2, .onnx или каталог transformers.

Бэкенды моделей →

Каталог моделей

Все веса, которые умеет загружать cardstream: они обучены в Ximilar и публикуются вместе с релизами под лицензией Apache-2.0. Что делает каждая модель, с какой скоростью работает и какая у неё лицензия.

Каталог моделей →

Коротко о главном

Сколько это стоит, что покидает компьютер, какие карты распознаются и какие две команды всё удаляют.

Вопросы и ответы →

README и issues

В README описан каждый флаг, а issues — место для сообщений об ошибках и вопросов.

Читать README →

Релизы и файлы

Wheel-пакеты, контрольные суммы и скрипт установки, по одному комплекту на релиз, а также Docker и сборка из исходников.

Страница загрузки →