Guía

Analiza tu directo de Whatnot o Fanatics Live

cardstream nunca inicia sesión en Whatnot, Fanatics Live ni ningún otro marketplace. Mira el mismo vídeo que ya les estás enviando, en tu propia máquina, y nombra cada carta que cae sobre la mesa. Este es el camino completo, de cero a un overlay en directo: unos quince minutos, una sola vez.

Un ordenador cerca de la cámara

macOS, Linux o Windows. Si ya tienes OBS en él, esa es la máquina indicada: el análisis ocurre en local, así que nada tiene que viajar.

El vídeo que ya envías

Una escena de OBS, una webcam, una capturadora o un codificador. cardstream aprovecha lo que ya tienes; no te pide que montes el show de nuevo.

Una clave de API de Ximilar

La única credencial de todo el sistema, y se queda en tu máquina. Sin cuenta del marketplace, sin contraseña, sin bots en tu chat.

Primero

Ponlo en marcha por su cuenta

Antes de que nada de esto toque tu show, comprueba que funciona con la webcam de tu portátil. Tres comandos.

Instálalo

El script crea un entorno virtual en ~/.cardstream, verifica el wheel publicado con sus checksums, descarga los pesos de los modelos y pone los comandos en tu PATH. Las instalaciones con wheel, Docker y código fuente están en la página de descarga.

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

Añade tu clave

La identificación pasa por Ximilar collectibles/v2 por defecto, o por tu propio sistema en su lugar. XIMILAR_API_KEY es la única variable de entorno que lee algo: ponla en el perfil de tu shell para que sobreviva a un reinicio la noche del show.

$ export XIMILAR_API_KEY=your-key

Muestra una carta a tu portátil

Esto abre la interfaz en el navegador con tu webcam integrada. Mantén una carta quieta un instante: el overlay muestra a la máquina de estados decidiendo, luego el nombre, el set y la confianza, con el tiempo real de la llamada de identificación junto a la coincidencia. Eso es todo el producto; el resto de esta página trata solo de dónde salen los píxeles.

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

Después

Apúntalo a tu show

Elige una fila. Cuál depende de una sola pregunta: ¿transmites desde un ordenador o desde un móvil?

Lo que no puedes hacer

Apuntar cardstream a tu página pública de reproducción de Whatnot o Fanatics. No existe una URL de stream saliente de tu propio show, y raspar el reproductor añadiría segundos de latencia, además de chocar con las condiciones de la plataforma. Todas las vías de abajo toman tu vídeo antes de que llegue al marketplace, y precisamente por eso cardstream no necesita cuenta, contraseña ni clave de API de ninguna de ellas.

Transmites desde OBS en un ordenador

La cámara virtual de OBS

Empieza aquí

OBS puede presentar tu escena compuesta al sistema operativo como una webcam normal. cardstream la abre entonces exactamente igual que cualquier otra cámara: sin segunda codificación, sin carga extra para tu codificador y sin ffmpeg que instalar.

En OBS, pulsa Iniciar cámara virtual en el panel de controles.
Ejecuta cardstream contra ella como índice de webcam. El índice 0 suele ser tu cámara integrada, así que la virtual normalmente es 1: prueba 0, 1, 2 hasta que veas tu escena.

$ cardstream-web --source 1

Pruébalo una vez antes de un show y no durante uno: en macOS la terminal necesita permiso de cámara, y si OpenCV no consigue abrir el dispositivo virtual en tu máquina, la vía B funciona en todas partes.

Transmites desde OBS y quieres exactamente los píxeles que emites

Una segunda salida desde OBS

cardstream escucha en tu propia máquina y OBS le envía una copia. Whatnot o Fanatics siguen recibiendo exactamente lo que recibían antes: es un destino adicional, nunca una redirección.

Arranca primero el modo escucha; espera el envío y se reconecta por sí solo.
OBS solo tiene una salida de Transmisión, así que envía la copia desde una segunda: bien el plugin obs-multi-rtmp, bien Ajustes → Salida → Grabación → Salida personalizada (FFmpeg), tipo Salida a URL, URL rtmp://127.0.0.1:1935/live, contenedor flv, y después pulsa Iniciar grabación.
Esta vía invoca el binario ffmpeg del sistema: antes, brew install ffmpeg.

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

Sales en directo desde un móvil, como la mayoría de vendedores

Su propia cámara sobre la mesa

Un móvil que envía directamente a la app no te deja nada que duplicar. Así que deja de perseguir el stream saliente y dale a cardstream su propia vista de la misma mesa: una segunda webcam en cenital, o la salida HDMI de la cámara a una capturadora.

Apunta una webcam o una capturadora al sitio donde abres las cartas.
Ejecútalo en la máquina que está junto a esa cámara.

$ cardstream-web --source 0

No tiene por qué ser el ángulo de tus compradores. Un plano cenital cerrado y bien iluminado identifica mejor de lo que jamás lo hará la señal comprimida de un marketplace.

Usas un codificador, un mezclador o una cámara IP

Cualquier cosa con una URL

rtsp://, rtmp:// y srt:// se reciben directamente, además de feeds JPEG por ws:// cuando el montaje es casero. La reconexión usa backoff limitado, así que un enlace de estudio que se cae en mitad de un break vuelve sin que toques nada.

Dale la URL que tu codificador ya publica.
La página del navegador se convierte en un visor pasivo: el análisis corre aunque no haya ningún navegador abierto.

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

Antes de salir en directo

Ajústalo al show que vas a hacer

Los valores por defecto son honestos, pero un break no es una señal de cámara cualquiera: normalmente sabes lo que vas a abrir antes de abrirlo.

Dile qué estás abriendo

Un preajuste de juego o de set acota la búsqueda: llamadas más rápidas, mejores coincidencias. Una sola regla: pasa siempre --alphabet cuando pases --game, porque preajustar el juego desactiva la detección de alfabeto del propio endpoint, que entonces asume latino, y una carta japonesa coincidiría con su edición inglesa.

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

Cambia de idea en pleno directo

Cuando el siguiente lote es de otro juego no reinicias nada: categoría, juego, código de set, alfabeto y los umbrales de resultado y de nitidez se editan en el diálogo de ajustes del navegador mientras el stream sigue. Todo lo demás (detector, compuerta, resolución) se lee una sola vez al arrancar, así que decídelo ahora.

Guarda el registro, mantén el puerto cerrado

--split-results da a cada aparición su propia fila en lugar de fusionar las repeticiones: una lista continua de lo que mostraste, en el orden en que lo mostraste, lista para cotejarla después con los pedidos. Deja --host en su valor por defecto 127.0.0.1: ese proceso guarda tu clave y la interfaz local no tiene autenticación, así que nunca debería ser accesible desde tu red local.

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

Guarda el show para la mañana siguiente

Añade --ximilar-stream NEW y cada fila de ese historial (la carta, su precio, cuánto tiempo estuvo en pantalla y el recorte a partir del cual se identificó) se guarda en una sesión de tu cuenta de Ximilar mientras transmites. Después, la sección Cardstream de la app de Ximilar muestra el show completo (su valor, sus cartas más valiosas y cada carta con su imagen), y es ahí donde marcas lo que se vendió y corriges una coincidencia equivocada. Si el cliente se reinicia a mitad del show, vuelve a arrancarlo con el id de sesión que imprimió en lugar de NEW y el mismo show continúa. Para guardar en un espacio de trabajo de equipo, usa --ximilar-workspace.

$ cardstream-web --source 1 --price-stats --ximilar-stream NEW
# tras un reinicio:
$ cardstream-web --source 1 --price-stats --ximilar-stream <session-id>

Y ahora haz tu show. La detección, el movimiento y la compuerta de identidad corren en local, en tu máquina; la llamada de identificación se dispara una vez por cada carta que pones sobre la mesa: alrededor de cien en una hora, frente a los 54.000 fotogramas que contiene esa hora. Las cuentas están aquí.

Si algo no va bien

Las seis cosas que fallan de verdad

La cámara virtual no aparece en la lista

Prueba --source 0, 1, 2 por orden: los índices son los que reparte el sistema operativo. En macOS, da acceso a la cámara a tu terminal en Ajustes del Sistema → Privacidad y seguridad. Si OpenCV sigue sin poder abrirla, pásate a la vía B.

«ffmpeg not found»

Solo --listen y --ffmpeg invocan el binario del sistema. Instálalo (brew install ffmpeg) y vuelve a ejecutar; las vías de cámara virtual, webcam y pull simple no necesitan nada más.

OBS no me deja añadir una segunda transmisión

Es un límite de OBS, no de cardstream: tiene una única salida de Transmisión. El plugin obs-multi-rtmp añade destinos adicionales de verdad; la vía de grabación con Salida personalizada (FFmpeg) de la vía B funciona con OBS tal cual viene.

Encuentra las cartas pero nunca las identifica

Casi siempre es resolución o movimiento. El número de carta tiene que ser legible en el fotograma que envías: mantén OBS a 1080p, sostén la carta quieta un instante al mostrarla y solo entonces relaja --result-threshold (por defecto 0.9; más alto conserva coincidencias más débiles, 1.0 lo conserva todo).

La misma carta se identifica dos veces

La compuerta de identidad puntuó las dos vistas por debajo de --similarity-threshold (por defecto 0.85) y la consideró una carta nueva. Bájalo un poco. Si dejas una carta y la vuelves a coger, sube --forget-after en su lugar: tras 2 segundos fuera, una carta se trata como nueva por diseño.

No se detecta nada en absoluto

Ejecuta con --show-detection para dibujar la caja: la detección siempre corre, solo que por defecto no se dibuja. Si no hay caja, la carta es demasiado pequeña o va demasiado rápido en el encuadre; una caja sin coincidencia te manda a la fila de arriba.

¿Sigues atascado? El README documenta todos los flags, y el centro de documentación los agrupa según lo que quieras hacer.