Docs

Documentación

Todo corre en tu máquina: instálalo, apúntale una cámara y ajusta cuándo puede llamar fuera. Agrupado según lo que quieras hacer.

Instalar y ejecutar

De nada a una carta en pantalla

Un solo comando instala el cliente, los pesos de los modelos y los shims. La única credencial de todo el sistema es tu clave de Ximilar.

El script de instalación

Crea un entorno virtual en ~/.cardstream, verifica el wheel publicado con sus checksums, descarga los pesos de los modelos y pone los dos comandos en tu PATH. Las otras vías (wheel, Docker, 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

Todas las formas de instalar →

Instalación manual

Un checkout y pip también sirven. Los extras son independientes: [client] es la interfaz y las fuentes de vídeo; [onnx] o [torch] aportan los backends del detector y del embedding.

$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream
$ pip install -e '.[client,onnx]'

Tu clave de Ximilar

La identificación la hace Ximilar collectibles/v2. XIMILAR_API_KEY es la única variable de entorno que lee algo; todo lo demás es un flag.

$ export XIMILAR_API_KEY=your-key

Primera ejecución

Abre la interfaz en el navegador con tu webcam. Muestra una carta; el overlay enseña a la máquina de estados pensando y la coincidencia cuando llega.

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

Comprueba lo que tienes

Ambos comandos imprimen su versión y salen, sin necesitar archivos de modelo, así que funciona en cuanto termina la instalación.

$ cardstream-web --version
cardstream 0.5.0

Sin interfaz, para montajes

El mismo pipeline sin navegador: los resultados se imprimen en la terminal. Los mismos flags que cardstream-web, un proceso junto a la cámara.

$ cardstream-client --source 0

Úsalo

Pásale tu show

Las fuentes son intercambiables y el análisis es idéntico elijas la que elijas. Todo es un flag; el diálogo de ajustes permite retocar los importantes en directo.

Webcams y archivos

La webcam del navegador es la opción por defecto de cardstream-web; un índice de dispositivo, un archivo de vídeo o una imagen fija funcionan en ambos comandos. Útil para probar antes del show.

$ cardstream-web # webcam del navegador
$ cardstream-client --source clip.mp4

Recibir un stream (pull)

Apúntalo a una cámara IP, un codificador o un restreamer: rtsp://, rtmp://, srt:// y feeds JPEG por ws://, con reconexión automática y backoff limitado.

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

Deja que OBS envíe (push)

Ejecútalo en modo escucha y añade una salida RTMP o SRT más en OBS. Necesita el binario ffmpeg del sistema (brew install ffmpeg).

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

Los preajustes acotan la búsqueda

Juego, código de set y sistema de escritura se validan en local antes de enviarse. Indica siempre --alphabet cuando indiques --game: preajustar el juego impide que el endpoint detecte el alfabeto por sí mismo.

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

El diálogo de ajustes

Categoría, juego, código de set, alfabeto y umbrales se pueden retocar desde el navegador en pleno directo, sin reiniciar y con la misma validación que aplica el proceso.

Tres ajustes de resolución

Lo que captura la cámara, lo que se envía y lo que se analiza son tres números distintos. El análisis corre en pequeño; el recorte para identificar se vuelve a cortar del fotograma completo.

$ cardstream-web --camera-width 3840 --width 1280

Revisa el show

Guarda el show y revísalo después

Desactivado por defecto. Un solo flag guarda el historial que construye la página (cada carta que mostraste, con su recorte) en una sesión de tu propia cuenta de Ximilar, así que el show sigue ahí a la mañana siguiente.

El historial, con miniaturas

La interfaz del navegador lista cada carta que mostraste, de la más reciente a la más antigua: una miniatura del recorte que se identificó, su precio con --price-stats y cuánto tiempo estuvo en pantalla. Esa lista vive en tu máquina.

Guarda un show

--ximilar-stream NEW crea una sesión e imprime su id. A partir de ahí, cada fila del historial se guarda mientras el show avanza: las subidas se agrupan en segundo plano, se reintentan si hay errores de red y nunca frenan el show. Al salir limpiamente se sube lo que falte y se cierra la sesión.

$ cardstream-web --game "Pokémon" --alphabet latin \
    --price-stats --ximilar-stream NEW

Guardar un show, en detalle →

Qué se sube

Las filas como texto (carta, set, precio, tiempo en pantalla, las llamadas de pago que hay detrás) y el recorte a partir del cual se identificó cada fila, de 1024 px como máximo: la imagen que ya recibió la llamada de identificación. --no-ximilar-stream-images lo deja solo en texto. Tu cuenta de Ximilar necesita el servicio Cardstream.

$ cardstream-web --ximilar-stream NEW --no-ximilar-stream-images

Revísalo en la app de Ximilar

Cada sesión llega a la sección Cardstream de la app de Ximilar: qué mostraste y cuándo, el valor del show, sus productos más valiosos y sus sets principales, y cada carta con su recorte. Marca lo que se vendió, corrige una coincidencia equivocada, añade notas.

Abrir la app de Ximilar →

Retómalo tras un reinicio

Pasa el id de la sesión en lugar de NEW y el show continúa en la misma sesión; aunque una salida limpia la haya cerrado, simplemente se vuelve a abrir. Solo se cobra crear una sesión, así que retomarla no cuesta nada.

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

Espacios de trabajo de equipo

Una sesión se guarda en el espacio de trabajo por defecto de tu clave de API. Indica otro con --ximilar-workspace y pasa el mismo id cuando retomes una sesión guardada allí.

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

Opera con confianza

Una llamada de identificación por carta distinta

Señales locales (movimiento, detección, la compuerta de identidad) deciden cuándo está justificada de verdad una llamada de identificación. Estos son los ajustes que lo mantienen a raya.

Umbrales

El umbral de resultado mantiene las coincidencias débiles fuera del overlay; el umbral de similitud decide entre misma carta y carta nueva; forget-after borra la memoria cuando una carta lleva suficiente tiempo fuera.

$ cardstream-web --result-threshold 0.35

La configuración recomendada

Segmentación RF-DETR con una compuerta de embedding ONNX: los valores por defecto incluidos. Un cardstream-web sin argumentos ejecuta exactamente esto una vez que los pesos están en su sitio; escribirlo explícitamente es el mismo pipeline.

$ cardstream-web \
    --segmentor-model model/segmentation/onnx/model.onnx \
    --embed-model model/similarity/onnx/model.onnx

Mantenlo en localhost

La aplicación local no tiene autenticación y guarda tu clave de API. --host vale 127.0.0.1 por defecto: déjalo así y nunca expongas el puerto a la red local.

«Model not found» al arrancar

Los pesos de los modelos se descargan aparte; no forman parte del repositorio. El script de instalación y la imagen de Docker los descargan; un checkout limpio necesita que los coloques en model/segmentation/ y model/similarity/, y scripts/build-from-source.sh --models lo hace por ti.

Indica el juego que estás mostrando

Un show de un solo juego no necesita que el endpoint adivine el juego en cada llamada. Nómbralo y la búsqueda se acota a ese juego: respuestas más rápidas y menos ediciones equivocadas. Pasa --alphabet junto a él, porque preajustar el juego impide que el endpoint detecte el sistema de escritura por sí mismo.

$ cardstream-web --game "Pokémon" --alphabet japanese

ffmpeg, cuando hace falta

--listen y --ffmpeg invocan el binario ffmpeg del sistema. La recepción normal por pull funciona con una instalación solo con pip; el montaje con envío desde OBS, no.

Ve más allá

Más allá de los valores por defecto

Cambia los modelos o lee el código: todo el pipeline es un único paquete instalable.

Trae tus propios pesos

La detección y la compuerta de identidad se enrutan por backend: la familia elige la clase y la extensión del archivo elige el runtime. RF-DETR o RT-DETRv2, .onnx o un directorio de transformers.

Backends de modelos →

El catálogo de modelos

Todos los pesos que cardstream puede cargar, entrenados por Ximilar y publicados con licencia Apache-2.0 junto a cada versión: qué hace cada uno, a qué velocidad va y con qué licencia.

Catálogo de modelos →

Respuestas breves

Cuánto cuesta, qué sale de la máquina, qué cartas nombra y los dos comandos que lo desinstalan.

Leer las preguntas frecuentes →

README e issues

El README cubre todos los flags; los issues son el sitio para errores y preguntas.

Leer el README →

Versiones y artefactos

Wheels, checksums y el script de instalación, un conjunto por versión, además de las compilaciones con Docker y desde el código fuente.

Página de descarga →