Гайд

Анализируйте свой стрим на Whatnot или Fanatics Live

cardstream никогда не входит в аккаунт Whatnot, Fanatics Live или любого другого маркетплейса. Он на вашем же компьютере смотрит то видео, которое вы и так им отправляете, и называет каждую карту, которая ложится на стол. Вот весь путь с нуля до оверлея в эфире: около пятнадцати минут, один раз.

Компьютер рядом с камерой

macOS, Linux или Windows. Если на нём уже работает OBS, это тот самый компьютер: анализ идёт локально, и никуда ничего передавать не нужно.

Видео, которое вы уже отправляете

Сцена OBS, веб-камера, устройство захвата или энкодер. cardstream берёт то, что есть, и не требует перестраивать эфир.

API-ключ Ximilar

Единственные учётные данные во всей системе, и они остаются на вашем компьютере. Ни аккаунта маркетплейса, ни пароля, ни бота в чате.

Сначала

Запустите его отдельно от эфира

Прежде чем что-то из этого коснётся вашего эфира, убедитесь, что всё работает с веб-камерой ноутбука. Три команды.

Установите

Скрипт создаёт venv в ~/.cardstream, сверяет релизный wheel с контрольными суммами, скачивает веса моделей и добавляет команды в PATH. Установка из wheel, через Docker и из исходников описана на странице загрузки.

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

Добавьте ключ

По умолчанию распознавание идёт через Ximilar collectibles/v2, но на его место можно поставить собственную систему. XIMILAR_API_KEY — единственная переменная окружения, которую читает программа. Пропишите её в профиле оболочки, чтобы она пережила перезагрузку в вечер эфира.

$ export XIMILAR_API_KEY=your-key

Покажите карту ноутбуку

Эта команда открывает веб-интерфейс со встроенной веб-камерой. Подержите карту неподвижно секунду: оверлей покажет, как конечный автомат принимает решение, а затем название, сет и уверенность; рядом с совпадением видно, сколько времени занял запрос на распознавание. Это и есть весь продукт. Остальная часть страницы только о том, откуда берутся пиксели.

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

Затем

Направьте его на свой эфир

Выберите один вариант. Какой именно, зависит от одного вопроса: вы стримите с компьютера или с телефона?

Чего сделать нельзя

Направить cardstream на публичную страницу вашего эфира на Whatnot или Fanatics. У вашего эфира нет исходящего URL потока, а захват видео из плеера добавил бы секунды задержки, не говоря уже об условиях платформы. Все способы ниже берут видео до маркетплейса, и именно поэтому cardstream не нужны ни аккаунт, ни пароль, ни API-ключ этих платформ.

Вы стримите из OBS на компьютере

Виртуальная камера OBS

Начните отсюда

OBS умеет показывать собранную сцену операционной системе как обычную веб-камеру. cardstream открывает её так же, как любую другую камеру: без второго кодирования, без лишней нагрузки на кодировщик и без установки ffmpeg.

В OBS нажмите Запуск виртуальной камеры на панели «Управление».
Запустите cardstream, указав её как индекс веб-камеры. Индекс 0 обычно у встроенной камеры, так что у виртуальной чаще всего 1. Пробуйте 0, 1, 2, пока не увидите свою сцену.

$ cardstream-web --source 1

Попробуйте это заранее, а не во время эфира: в macOS терминалу нужно разрешение на доступ к камере, а если OpenCV не сможет открыть виртуальное устройство на вашем компьютере, способ B работает везде.

Вы стримите из OBS и хотите получить именно ту картинку, что уходит в эфир

Второй вывод из OBS

cardstream ждёт поток на вашем же компьютере, а OBS отправляет ему копию. Whatnot или Fanatics по-прежнему получают ровно то же, что и раньше: это дополнительный получатель, а не перенаправление.

Сначала запустите cardstream в режиме ожидания: он ждёт поток и сам переподключается.
В OBS только один вывод Трансляция, поэтому копию нужно отправить со второго: либо плагином obs-multi-rtmp, либо через Настройки → Вывод → Запись → Пользовательский вывод (FFmpeg), тип вывода Вывод по ссылке, ссылка rtmp://127.0.0.1:1935/live, формат контейнера flv. Затем нажмите «Начать запись».
Этот способ запускает системный ffmpeg, так что сначала выполните brew install ffmpeg.

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

Вы выходите в эфир с телефона, как большинство продавцов

Отдельная камера над столом

Когда телефон отправляет видео прямо в приложение, ответвлять нечего. Поэтому не гонитесь за исходящим потоком, а дайте cardstream собственный вид на тот же стол: вторую веб-камеру сверху или HDMI-выход камеры, подключённый к устройству захвата.

Направьте веб-камеру (или камеру, подключённую через устройство захвата) на то место, где вы показываете карты.
Запустите cardstream на компьютере рядом с этой камерой.

$ cardstream-web --source 0

Ракурс не обязан совпадать с тем, что видят покупатели. Крупный, хорошо освещённый план сверху всегда распознаётся лучше, чем сжатый поток маркетплейса.

У вас энкодер, видеомикшер или IP-камера

Всё, у чего есть URL

Потоки rtsp://, rtmp:// и srt:// cardstream забирает напрямую, а для самодельных сетапов принимает JPEG-кадры по ws://. Переподключение идёт с растущей, но ограниченной паузой, так что связь со студией, оборвавшаяся посреди брейка, восстановится без вашего участия.

Укажите URL, который ваш энкодер уже публикует.
Страница в браузере становится пассивным зрителем: анализ идёт, даже когда браузер закрыт.

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

Перед выходом в эфир

Настройте его под свой эфир

Настройки по умолчанию разумны, но брейк — это не абстрактное видео с камеры: обычно вы знаете, что вскрываете, ещё до того, как вскроете.

Сообщите, что вы вскрываете

Подсказка с игрой или сетом сужает поиск: запросы быстрее, совпадения точнее. Одно правило: вместе с --game всегда передавайте --alphabet, потому что подсказка с игрой отключает у эндпоинта собственное определение алфавита, тот по умолчанию берёт latin, и японская карта совпала бы со своим английским изданием.

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

Передумали посреди стрима?

Если следующий лот из другой игры, ничего перезапускать не нужно: категорию, игру, код сета, алфавит, а также пороги результата и резкости можно менять в окне настроек в браузере, пока идёт стрим. Всё остальное (детектор, фильтр, разрешение) читается один раз при запуске, так что определитесь с этим сейчас.

Ведите журнал, держите порт закрытым

С флагом --split-results каждое появление карты получает отдельную строку, а повторы не объединяются: получается список всего показанного в порядке показа, который потом удобно сверять с заказами. Оставьте у --host значение по умолчанию 127.0.0.1: этот процесс хранит ваш ключ, а локальный интерфейс работает без авторизации, поэтому он не должен быть доступен из локальной сети.

$ cardstream-web --source 1 --split-results

Сохраните эфир, чтобы разобрать его утром

Добавьте --ximilar-stream NEW, и каждая строка этой истории (карта, её цена, время на стриме и кроп, по которому её распознали) будет сохраняться в сеанс в вашем аккаунте Ximilar, пока вы стримите. После эфира раздел Cardstream в приложении Ximilar покажет его целиком: стоимость, самые дорогие карты и каждую карту с картинкой. Там же можно отметить проданное и исправить неверное совпадение. Если клиент перезапустился посреди эфира, запустите его снова с выведенным идентификатором сеанса вместо NEW, и тот же эфир продолжится. Для сохранения в командное рабочее пространство нужен флаг --ximilar-workspace.

$ cardstream-web --source 1 --price-stats --ximilar-stream NEW
# после перезапуска:
$ cardstream-web --source 1 --price-stats --ximilar-stream <session-id>

А теперь ведите эфир. Детекция, фильтр движения и фильтр повторов работают локально, на вашем компьютере, а запрос на распознавание уходит один раз на каждую карту, которую вы кладёте на стол: около сотни в час против 54 000 кадров, из которых этот час состоит. Вся арифметика здесь.

Если что-то не так

Шесть проблем, которые случаются на самом деле

Виртуальной камеры нет в списке

Переберите по очереди --source 0, 1, 2: индексы раздаёт операционная система. В macOS разрешите терминалу доступ к камере в разделе Системные настройки → Конфиденциальность и безопасность. Если OpenCV всё равно не открывает её, переходите к способу B.

«ffmpeg not found»

Системный ffmpeg запускают только --listen и --ffmpeg. Установите его (brew install ffmpeg) и запустите команду снова. Способам с виртуальной камерой, веб-камерой и обычным получением потока ничего дополнительного не нужно.

OBS не даёт добавить вторую трансляцию

Это ограничение OBS, а не cardstream: вывод «Трансляция» у него один. Плагин obs-multi-rtmp добавляет настоящих дополнительных получателей, а запись с типом «Пользовательский вывод (FFmpeg)» из способа B работает и в обычном OBS без плагинов.

Карты находятся, но совпадений нет

Почти всегда дело в разрешении или в движении. Номер карты должен читаться в кадре, который вы отправляете: оставьте в OBS 1080p, при показе подержите карту секунду неподвижно и только после этого ослабляйте --result-threshold (по умолчанию 0.9: чем выше значение, тем более слабые совпадения проходят, а 1.0 пропускает всё).

Одна и та же карта распознаётся дважды

Фильтр повторов оценил сходство двух ракурсов карты ниже --similarity-threshold (по умолчанию 0.85) и счёл её новой. Немного понизьте порог. А если вы кладёте карту и берёте её снова, лучше увеличьте --forget-after: так задумано, что карта, которой не было в кадре 2 секунды, считается новой.

Вообще ничего не обнаруживается

Запустите с флагом --show-detection, чтобы видеть прямоугольник детекции: детекция работает всегда, просто по умолчанию он не рисуется. Нет прямоугольника — значит, карта в кадре слишком мелкая или движется слишком быстро. Прямоугольник есть, а совпадения нет — смотрите пункт «Карты находятся, но совпадений нет».

Всё ещё не получается? В README описан каждый флаг, а в документации они сгруппированы по задачам.