Guida

Analizza la tua live su Whatnot o Fanatics Live

cardstream non accede mai a Whatnot, a Fanatics Live né a nessun altro marketplace. Guarda, sul tuo computer, lo stesso video che stai già mandando a loro, e dà un nome a ogni carta che finisce sul tavolo. Ecco tutto il percorso, da zero a un overlay in diretta: circa un quarto d’ora, una volta sola.

Un computer vicino alla videocamera

macOS, Linux o Windows. Se ci gira già OBS, quel computer è quello giusto: l’analisi avviene in locale, quindi niente deve viaggiare.

Il video che mandi già

Una scena di OBS, una webcam, una scheda di acquisizione o un encoder. cardstream si aggancia a quello che hai; non ti chiede di rifare l’allestimento dello show.

Una chiave API Ximilar

L’unica credenziale di tutto il sistema, e resta sul tuo computer. Nessun account del marketplace, nessuna password, nessun bot nella tua chat.

Prima

Fallo funzionare da solo

Prima che tutto questo tocchi il tuo show, dimostra che funziona con la webcam del portatile. Tre comandi.

Installalo

Lo script crea un venv in ~/.cardstream, verifica il wheel della release con i suoi checksum, scarica i pesi dei modelli e mette i comandi nel tuo PATH. Le installazioni da wheel, con Docker e dai sorgenti sono nella pagina di download.

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

Aggiungi la tua chiave

Di default l’identificazione passa da Ximilar collectibles/v2, oppure dal tuo sistema al suo posto. XIMILAR_API_KEY è l’unica variabile d’ambiente che viene letta: mettila nel profilo della shell, così sopravvive a un riavvio la sera dello show.

$ export XIMILAR_API_KEY=your-key

Mostra una carta al portatile

Questo comando apre l’interfaccia nel browser con la webcam integrata. Tieni ferma una carta per un attimo: l’overlay mostra la macchina a stati che decide, poi nome, set e confidenza, con accanto alla corrispondenza il tempo impiegato dalla chiamata di identificazione. Il prodotto è tutto qui: il resto della pagina riguarda solo da dove arrivano i pixel.

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

Poi

Puntalo sul tuo show

Scegli una riga. Quale, dipende da una sola domanda: trasmetti da un computer o da un telefono?

Che cosa non puoi fare

Puntare cardstream sulla pagina pubblica di riproduzione della tua live su Whatnot o Fanatics. Non esiste un URL del flusso in uscita per il tuo show, e fare scraping del player aggiungerebbe secondi di latenza, oltre a violare i termini della piattaforma. Tutti i metodi qui sotto agganciano il tuo video a monte del marketplace, ed è proprio per questo che a cardstream non servono né un account, né una password, né una chiave API da parte loro.

Trasmetti da OBS su un computer

La fotocamera virtuale di OBS

Parti da qui

OBS può presentare al sistema operativo la tua scena composta come una normale webcam. A quel punto cardstream la apre come qualsiasi altra videocamera: nessuna seconda codifica, nessun carico in più sul tuo encoder e nessun ffmpeg da installare.

In OBS, fai clic su Avvia la fotocamera virtuale nel pannello Controlli.
Avvia cardstream indicandola come indice di webcam. L’indice 0 di solito è la videocamera integrata, quindi quella virtuale in genere è la 1: prova 0, 1, 2 finché non vedi la tua scena.

$ cardstream-web --source 1

Provalo una volta prima di uno show, non durante: su macOS il terminale ha bisogno del permesso di accesso alla fotocamera, e se OpenCV non riesce ad aprire il dispositivo virtuale sul tuo computer, il metodo B funziona ovunque.

Trasmetti da OBS e vuoi esattamente i pixel che vanno in onda

Una seconda uscita da OBS

cardstream resta in ascolto sul tuo computer e OBS gli invia una copia. Whatnot o Fanatics continuano a ricevere esattamente quello che ricevevano prima: è una destinazione in più, mai un reindirizzamento.

Avvia prima l’ascolto; aspetta il push e si riconnette da solo.
OBS ha una sola uscita Dirette, quindi manda la copia da una seconda: con il plugin obs-multi-rtmp, oppure da Impostazioni → Uscita → Registrazione → Uscita personalizzata (FFmpeg), tipo Uscita verso un URL, URL rtmp://127.0.0.1:1935/live, contenitore flv, e poi premi Avvia la registrazione.
Questo metodo richiama il binario ffmpeg di sistema: prima esegui brew install ffmpeg.

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

Vai in diretta da un telefono, come la maggior parte dei venditori

Una videocamera tutta sua sul tavolo

Un telefono che trasmette direttamente verso l’app non ti lascia nessun flusso da sdoppiare. Quindi smetti di inseguire il flusso in uscita e dai a cardstream una sua vista sullo stesso tavolo: una seconda webcam dall’alto, oppure l’uscita HDMI della videocamera in una scheda di acquisizione.

Punta una webcam o una scheda di acquisizione sul punto in cui mostri le carte.
Avvialo sul computer accanto a quella videocamera.

$ cardstream-web --source 0

Non deve essere per forza l’inquadratura che vedono i tuoi acquirenti. Una ripresa dall’alto, stretta e ben illuminata, si identifica meglio di quanto farà mai un flusso compresso del marketplace.

Usi un encoder, un mixer video o una videocamera IP

Qualsiasi cosa abbia un URL

I flussi rtsp://, rtmp:// e srt:// vengono prelevati direttamente, così come i feed JPEG ws:// quando il setup è fatto in casa. Le riconnessioni avvengono a intervalli crescenti ma limitati, quindi un collegamento con lo studio che cade a metà break torna su senza che tu debba toccarlo.

Dagli l’URL che il tuo encoder pubblica già.
La pagina nel browser diventa un semplice monitor: l’analisi gira anche senza nessun browser aperto.

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

Prima di andare in diretta

Regolalo per lo show che stai facendo

Le impostazioni predefinite sono oneste, ma un break non è un flusso video qualunque: di solito sai che cosa stai per aprire prima di aprirlo.

Digli che cosa stai aprendo

Preimpostare il gioco o il set restringe la ricerca: chiamate più rapide, corrispondenze migliori. Una sola regola: passa sempre --alphabet quando passi --game, perché preimpostare il gioco spegne il rilevamento dell’alfabeto dell’endpoint, che a quel punto presume l’alfabeto latino, e una carta giapponese verrebbe abbinata alla sua stampa inglese.

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

Cambia idea a diretta in corso

Quando il lotto successivo è di un altro gioco non devi riavviare niente: categoria, gioco, codice di set, alfabeto e le soglie di risultato e di nitidezza si modificano tutti nella finestra delle impostazioni del browser mentre la diretta va avanti. Tutto il resto (rilevatore, filtro, risoluzione) viene letto una sola volta all’avvio, quindi sceglilo adesso.

Tieni il registro, tieni chiusa la porta

--split-results dà a ogni apparizione una riga tutta sua invece di unire le ripetizioni: un elenco di quello che hai mostrato, nell’ordine in cui l’hai mostrato, pronto da confrontare con gli ordini a show finito. Lascia --host sul valore predefinito 127.0.0.1: quel processo custodisce la tua chiave e l’interfaccia locale non ha autenticazione, quindi non deve mai essere raggiungibile dalla tua rete locale.

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

Salva lo show per la mattina dopo

Aggiungi --ximilar-stream NEW e ogni riga di quello storico (la carta, il suo prezzo, quanto è rimasta in diretta e il ritaglio da cui è stata identificata) viene salvata in una sessione del tuo account Ximilar mentre trasmetti. Dopo, la sezione Cardstream dell’app Ximilar mostra tutto lo show (il suo valore, le carte di maggior valore e ogni carta con la sua immagine), ed è lì che segni cosa hai venduto e correggi una corrispondenza sbagliata. Se il client si riavvia a metà show, fallo ripartire con l’id della sessione stampato al posto di NEW e lo stesso show prosegue. Per salvare in un workspace di team serve --ximilar-workspace.

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

Poi fai il tuo show. Rilevamento, movimento e filtro di identità girano tutti in locale sul tuo computer; la chiamata di identificazione parte una volta per ogni carta che metti sul tavolo, circa un centinaio in un’ora, contro i 54.000 fotogrammi che quell’ora contiene. I conti sono qui.

Se qualcosa non va

Le sei cose che vanno storte davvero

La fotocamera virtuale non è nell’elenco

Prova --source 0, 1, 2 uno dopo l’altro: gli indici sono quelli che assegna il sistema operativo. Su macOS, dai al terminale l’accesso alla fotocamera in Impostazioni di Sistema → Privacy e sicurezza. Se OpenCV continua a non aprirla, passa al metodo B.

“ffmpeg not found”

Solo --listen e --ffmpeg richiamano il binario di sistema. Installalo (brew install ffmpeg) e rilancia; i metodi con fotocamera virtuale, webcam e semplice pull non richiedono nient’altro.

OBS non mi lascia aggiungere una seconda diretta

È un limite di OBS, non di cardstream: ha una sola uscita Dirette. Il plugin obs-multi-rtmp aggiunge vere destinazioni in più; la registrazione con Uscita personalizzata (FFmpeg) del metodo B funziona con OBS così com’è.

Le carte vengono trovate ma mai riconosciute

Quasi sempre è questione di risoluzione o di movimento. Il numero della carta deve essere leggibile nel fotogramma che invii: tieni OBS a 1080p, tieni ferma la carta per un attimo quando la mostri, e solo dopo allenta --result-threshold (0.9 di default; più è alto, più tiene corrispondenze deboli, e 1.0 tiene tutto).

La stessa carta viene identificata due volte

Il filtro di identità ha dato alle due viste un punteggio inferiore a --similarity-threshold (0.85 di default) e l’ha considerata una carta nuova. Abbassalo un po’. Se appoggi una carta e poi la riprendi in mano, alza invece --forget-after: dopo 2 secondi di assenza una carta viene trattata come nuova, per scelta.

Non viene rilevato proprio niente

Avvialo con --show-detection per disegnare il riquadro: il rilevamento gira sempre, solo che di default non viene disegnato. Nessun riquadro significa che la carta è troppo piccola o troppo veloce nell’inquadratura; un riquadro senza corrispondenza ti rimanda alla riga precedente.

Ancora in difficoltà? Il README documenta ogni flag, e la documentazione li raggruppa in base a quello che vuoi fare.