Preguntas frecuentes

¿Qué necesito para ejecutarlo?

Una máquina con Python 3.11 o más reciente, y poco más. macOS arm64, Linux amd64 y Windows amd64 quedan cubiertos por la misma versión en Python puro, sin necesidad de GPU. El binario ffmpeg del sistema solo hace falta para las fuentes por pull y en modo escucha (RTSP, RTMP, SRT); una webcam, un archivo o la interfaz del navegador no lo necesitan.

¿Dónde deja las cosas el script de instalación?

En dos sitios. ~/.cardstream es la raíz de la instalación: un entorno virtual en venv/ y los pesos de los modelos en models/. Los dos comandos, cardstream-web y cardstream-client, son pequeños shims (scripts envoltorio) escritos en ~/.local/bin; ejecutan los binarios del entorno virtual con las rutas de los modelos ya rellenadas, así que cualquier flag que pases tiene prioridad. Ambas ubicaciones se cambian con CARDSTREAM_HOME e INSTALL_DIR. No se toca nada más en la máquina; en particular, el script nunca edita el perfil de tu shell: si ~/.local/bin no está en tu PATH, muestra un aviso y te deja el cambio a ti.

¿Cómo actualizo a una versión nueva?

Vuelve a ejecutar la misma línea. Instala la versión actual en el entorno virtual existente y reescribe los shims. Los pesos que ya están en ~/.cardstream/models no se tocan (solo se descargan cuando faltan), así que una actualización es una descarga pequeña, no otro cuarto de gigabyte. Para quedarte en una versión concreta en lugar de la última, define CARDSTREAM_VERSION.

# la misma línea; /install.sh redirige al script en la rama main
$ curl -fsSL https://cardstream.ai/install.sh | sh
$ curl -fsSL https://cardstream.ai/install.sh | CARDSTREAM_VERSION=v0.5.0 sh
$ cardstream-web --version

¿Cómo lo desinstalo?

Dos comandos. El primero elimina el entorno virtual y los pesos de los modelos; el segundo, los dos shims. No hay nada más que limpiar: ni demonios, ni elementos de inicio de sesión, ni paquetes del sistema.

$ rm -rf ~/.cardstream # venv/ + models/
$ rm -f ~/.local/bin/cardstream-web ~/.local/bin/cardstream-client

Si instalaste con CARDSTREAM_HOME o INSTALL_DIR definidos, elimina esas rutas en su lugar, y usa sudo si pusiste los shims en un directorio del sistema. Lo que añadiste a mano sigue siendo cosa tuya: una línea de PATH en el perfil de tu shell, el export de XIMILAR_API_KEY y cualquier carpeta que pasaras a --store-images. La aplicación no escribe nada más en tu directorio personal. Comprueba que ha desaparecido con command -v cardstream-web en una shell nueva; la antigua guarda la ruta en caché hasta que ejecutes hash -r.

¿Necesito una GPU?

No. Los pesos incluidos son exportaciones ONNX dimensionadas para CPU, y todo lo que hace el motor local (la compuerta de movimiento, el limitador de detección, el embedding que responde «¿misma carta o carta nueva?») corre en el procesador que ya tienes. Una GPU es una opción para tus propios pesos de mayor precisión, nunca un requisito para la configuración por defecto.

¿Funciona con Whatnot o Fanatics Live?

Sí, aunque no conectándose al marketplace: aprovecha el vídeo que ya estás produciendo. Una cámara virtual de OBS, una segunda salida RTMP o SRT junto a la que alimenta la plataforma, un pull RTSP desde un codificador, o simplemente su propia cámara apuntando a la misma mesa. La guía de venta en directo recorre las cuatro vías de principio a fin.

¿Qué sale realmente de mi máquina?

En modo cliente, un recorte JPEG por carta distinta: ni el stream, ni los fotogramas de alrededor, ni el resto de la mesa. Toda decisión sobre si enviar algo se toma primero en local, así que una hora de vídeo en la que muestras cien cartas son cien peticiones pequeñas. La única excepción la activas tú: con --ximilar-stream, el historial del show (una fila de texto por carta más el recorte a partir del cual se identificó) se guarda además en una sesión de tu propia cuenta de Ximilar. Está desactivado por defecto, y --no-ximilar-stream-images lo deja solo en texto.

¿Puedo revisar un show después?

Sí, si lo guardas. Arranca con --ximilar-stream NEW y cada carta que aparece en el historial (con su precio, su tiempo en pantalla y el recorte a partir del cual se identificó) va a una sesión de tu cuenta de Ximilar mientras el show avanza. Después, abre la sección Cardstream de la app de Ximilar: el valor del show, sus productos más valiosos y sus sets principales, cada carta con su imagen; marca lo que se vendió y corrige una coincidencia equivocada. ¿Se reinició a mitad del show? Pasa el id de la sesión en lugar de NEW y continúa, aunque se hubiera cerrado. Para guardar en un espacio de trabajo de equipo, usa --ximilar-workspace. Los detalles.

$ cardstream-web --price-stats --ximilar-stream NEW

¿Puedo ejecutarlo en mi red local para abrir la interfaz desde otra máquina?

No lo hagas. La interfaz web no tiene autenticación y guarda tu clave de API, así que su sitio es 127.0.0.1 y ningún otro. El contenedor escucha en 0.0.0.0 internamente, y por eso el docker run documentado publica el puerto solo en 127.0.0.1. Si de verdad lo necesitas desde otro equipo, pon delante tu propio túnel autenticado en lugar de abrir el puerto.

$ docker run --rm -e XIMILAR_API_KEY -p 127.0.0.1:8001:8001 \
    -v cardstream-models:/models cardstream