Domande frequenti

Che cosa mi serve per farlo girare?

Un computer con Python 3.11 o successivo, e poco altro. macOS arm64, Linux amd64 e Windows amd64 sono tutti coperti dalla stessa release in puro Python, senza bisogno di GPU. Il binario ffmpeg di sistema serve solo per le sorgenti in pull e in ascolto (RTSP, RTMP, SRT): una webcam, un file o l’interfaccia nel browser ne fanno a meno.

Dove mette le cose lo script di installazione?

In due posti. ~/.cardstream è la radice dell’installazione: un virtualenv in venv/ e i pesi dei modelli in models/. I due comandi, cardstream-web e cardstream-client, sono piccoli shim scritti in ~/.local/bin; lanciano i binari del venv con i percorsi dei modelli già compilati, e qualsiasi flag passi tu ha la precedenza. Entrambe le posizioni si spostano con CARDSTREAM_HOME e INSTALL_DIR. Sul computer non viene toccato nient’altro. In particolare lo script non modifica mai il profilo della tua shell: se ~/.local/bin non è nel tuo PATH, stampa un avviso e lascia a te la modifica.

Come aggiorno a una nuova versione?

Rilancia lo stesso comando. Installa la release corrente nel virtualenv esistente e riscrive gli shim. I pesi già presenti in ~/.cardstream/models non vengono toccati (si scaricano solo se mancano), quindi un aggiornamento è un download piccolo, non un altro quarto di gigabyte. Per passare a una release precisa invece dell’ultima, imposta CARDSTREAM_VERSION.

# lo stesso comando; /install.sh reindirizza allo script sul ramo 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

Come lo disinstallo?

Con due comandi. Il primo rimuove il virtualenv e i pesi dei modelli, il secondo rimuove i due shim. Non c’è altro da ripulire: nessun demone, nessun elemento di login, nessun pacchetto di sistema.

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

Se hai installato con CARDSTREAM_HOME o INSTALL_DIR impostati, rimuovi invece quei percorsi, usando sudo se avevi puntato gli shim su una directory di sistema. Quello che hai aggiunto a mano resta da annullare a te: una riga PATH nel profilo della shell, l’export di XIMILAR_API_KEY e qualsiasi cartella tu abbia passato a --store-images. L’app non scrive nient’altro nella tua home. Controlla che sia sparito con command -v cardstream-web in una shell nuova: quella vecchia tiene in cache la ricerca finché non esegui hash -r.

Mi serve una GPU?

No. I pesi inclusi sono export ONNX dimensionati per la CPU, e tutto ciò che fa il motore locale (il filtro di movimento, la frequenza del rilevamento, l’embedding che risponde a “stessa carta o carta nuova?”) gira sul processore che hai già. Una GPU è un’opzione per i tuoi pesi più accurati, mai un requisito per le impostazioni predefinite.

Funziona con Whatnot o Fanatics Live?

Sì, ma non collegandosi al marketplace: sfrutta il video che stai già producendo. La fotocamera virtuale di OBS, una seconda uscita RTMP o SRT accanto a quella che alimenta la piattaforma, un flusso RTSP prelevato da un encoder, o semplicemente una videocamera tutta sua puntata sullo stesso tappetino. La guida alla vendita in diretta percorre tutti e quattro i metodi dall’inizio alla fine.

Che cosa esce davvero dal mio computer?

In modalità client, un ritaglio JPEG per carta distinta: non la diretta, non i fotogrammi intorno, non il resto del tappetino. Ogni decisione sul se inviare qualcosa viene presa prima in locale, quindi un’ora di video in cui mostri cento carte sono cento piccole richieste. L’unica eccezione la attivi tu: con --ximilar-stream anche lo storico dello show (una riga di testo per carta più il ritaglio da cui è stata identificata) viene salvato in una sessione del tuo account Ximilar. È disattivato di default, e con --no-ximilar-stream-images si salva solo il testo.

Posso rivedere uno show a posteriori?

Sì, se lo salvi. Parti con --ximilar-stream NEW e ogni carta elencata nello storico, con il suo prezzo, il tempo in diretta e il ritaglio da cui è stata identificata, finisce in una sessione del tuo account Ximilar mentre lo show va avanti. Dopo, apri la sezione Cardstream dell’app Ximilar: il valore dello show, i prodotti di maggior valore e i set più frequenti, ogni carta con la sua immagine; lì segni cosa hai venduto e correggi una corrispondenza sbagliata. Hai riavviato a metà show? Passa l’id della sessione al posto di NEW e lo show riprende, anche se la sessione era stata chiusa. Per salvare in un workspace di team serve --ximilar-workspace. Tutti i dettagli.

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

Posso metterlo in rete locale per aprire l’interfaccia da un altro computer?

No, non farlo. L’interfaccia web non ha autenticazione e custodisce la tua chiave API, quindi il suo posto è 127.0.0.1 e nessun altro. Al suo interno il container ascolta su 0.0.0.0, ed è per questo che il docker run documentato pubblica la porta solo su 127.0.0.1. Se ti serve davvero da un altro computer, mettigli davanti un tuo tunnel autenticato invece di aprire la porta.

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