Docs

Documentação

Tudo roda na sua máquina: instale, aponte uma câmera e ajuste quando ele pode chamar pra fora. Agrupado pelo que você quer fazer.

Instalar e rodar

Do zero a uma carta na tela

Um único comando instala o cliente, os pesos dos modelos e os shims. A única credencial de todo o sistema é a sua chave da Ximilar.

O script de instalação

Cria um virtualenv em ~/.cardstream, confere o wheel da versão publicada com seus checksums, baixa os pesos dos modelos e coloca os dois comandos no seu PATH. Os outros caminhos (wheel, Docker, código-fonte) estão na página de download.

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

Todas as formas de instalar →

Instalação manual

Um checkout e pip também funcionam. Os extras são independentes: [client] é a interface e as fontes de vídeo; [onnx] ou [torch] fornecem os backends do detector e do embedding.

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

Sua chave da Ximilar

A identificação roda na Ximilar collectibles/v2. XIMILAR_API_KEY é a única variável de ambiente que alguma coisa lê; todo o resto é flag.

$ export XIMILAR_API_KEY=your-key

Primeira execução

Abre a interface no navegador usando a sua webcam. Mostre uma carta: o overlay exibe a máquina de estados pensando e a correspondência assim que ela chega.

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

Confira o que você tem

Os dois comandos imprimem a versão e encerram. Não precisam dos arquivos de modelo, então funcionam assim que a instalação termina.

$ cardstream-web --version
cardstream 0.5.0

Headless, para rigs

O mesmo pipeline sem navegador: os resultados saem no terminal. Mesmas flags do cardstream-web, um processo ao lado da câmera.

$ cardstream-client --source 0

Usar

Mande o seu show pra ele

As fontes são plugáveis e a análise é idêntica, seja qual for a escolhida. Tudo é flag; o painel de configurações reajusta as mais importantes ao vivo.

Webcams e arquivos

A webcam do navegador é o padrão do cardstream-web; um índice, um arquivo de vídeo ou uma imagem parada funcionam em qualquer lugar. Ótimo para testar antes do show.

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

Puxar um stream

Aponte para uma câmera IP, um encoder ou um restreamer: feeds rtsp://, rtmp://, srt:// e ws:// JPEG, com reconexão automática e backoff limitado.

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

Deixe o OBS enviar

Rode em modo de escuta e adicione uma saída extra RTMP ou SRT no OBS. Precisa do binário ffmpeg do sistema (brew install ffmpeg).

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

Pré-ajustes estreitam a busca

Jogo, código da coleção e sistema de escrita são validados localmente antes de serem enviados. Sempre passe --alphabet junto com --game: pré-ajustar o jogo faz o endpoint parar de detectar o alfabeto sozinho.

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

O painel de configurações

Categoria, jogo, código da coleção, alfabeto e limiares podem ser reajustados pelo navegador no meio da live. Sem reiniciar, e os controles têm a mesma validação do processo.

Três ajustes de resolução

O que a câmera captura, o que é enviado e o que é analisado são números separados. A análise roda em tamanho pequeno; o recorte para identificação é cortado de novo a partir do quadro inteiro.

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

Reveja o show

Salve o show e reveja depois

Desligado por padrão. Uma flag salva o histórico que a página monta (cada carta que você mostrou, com o recorte dela) em uma sessão na sua própria conta da Ximilar, e o show continua lá na manhã seguinte.

O histórico, com miniaturas

A interface no navegador lista cada carta que você mostrou, da mais recente para a mais antiga: uma miniatura do recorte que foi identificado, o preço dela com --price-stats e quanto tempo ela ficou no ar. Essa lista fica na sua máquina.

Salve um show

--ximilar-stream NEW inicia uma sessão e imprime o id dela. A partir daí, cada linha do histórico é salva enquanto o show acontece: os envios são agrupados em lotes em segundo plano, repetidos quando a rede falha e nunca seguram o show. Um encerramento limpo envia o que faltou e fecha a sessão.

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

Como salvar um show, em detalhes →

O que é enviado

As linhas como texto (carta, coleção, preço, tempo no ar, as chamadas pagas por trás de cada uma) e o recorte a partir do qual cada linha foi identificada, com no máximo 1024 px: a mesma imagem que a chamada de identificação já recebeu. --no-ximilar-stream-images envia só o texto. Sua conta da Ximilar precisa do serviço Cardstream.

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

Reveja no app da Ximilar

Cada sessão vai parar na seção Cardstream do app da Ximilar: o que você mostrou e quando, o valor do show, os produtos mais valiosos e as principais coleções, e cada carta com o recorte dela. Marque o que foi vendido, corrija uma correspondência errada, adicione anotações.

Abrir o app da Ximilar →

Retome depois de reiniciar

Passe o id da sessão no lugar de NEW e o show continua na mesma sessão. Mesmo que um encerramento limpo a tenha fechado, ela simplesmente reabre. Só o início de uma sessão é cobrado, então retomar não custa nada.

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

Workspaces de equipe

Uma sessão é salva no workspace padrão da sua chave da API. Indique outro com --ximilar-workspace e passe o mesmo id quando retomar uma sessão salva lá.

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

Operar com segurança

Uma chamada de identificação por carta distinta

Sinais locais (movimento, detecção, o filtro de identidade) decidem quando uma chamada de identificação realmente vale a pena. Estes são os ajustes que mantêm tudo sob controle.

Limiares

Um limiar de resultado mantém correspondências fracas fora do overlay; o limiar de similaridade decide entre mesma carta e carta nova; forget-after limpa a memória depois que a carta sumiu por tempo suficiente.

$ cardstream-web --result-threshold 0.35

A execução recomendada

Segmentação RF-DETR com um filtro de embedding em ONNX: os padrões que já vêm no pacote. Um cardstream-web sem argumentos roda exatamente isso assim que os pesos estão no lugar; escrever tudo por extenso dá o mesmo pipeline.

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

Mantenha no localhost

O app local não tem autenticação e guarda a sua chave da API. --host usa 127.0.0.1 por padrão: deixe assim e nunca exponha a porta para a rede local.

“Model not found” na inicialização

Os pesos dos modelos são um download à parte, não fazem parte do repositório. O script de instalação e a imagem Docker baixam eles; um checkout puro precisa deles em model/segmentation/ e model/similarity/, e scripts/build-from-source.sh --models faz isso por você.

Informe o jogo que você está mostrando

Um show de um jogo só não precisa que o endpoint adivinhe o jogo a cada chamada. Diga qual é e a busca se restringe a ele: respostas mais rápidas e menos versões erradas. Passe --alphabet junto, porque pré-ajustar o jogo faz o endpoint parar de detectar o sistema de escrita sozinho.

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

ffmpeg, quando precisar

--listen e --ffmpeg chamam o binário ffmpeg do sistema. Puxar um stream funciona com uma instalação só via pip; receber o envio do OBS, não.

Ir mais fundo

Além dos padrões

Troque os modelos ou leia o código: o pipeline inteiro é um único pacote instalável.

Traga seus próprios pesos

A detecção e o filtro de identidade são roteados por backend: a família escolhe a classe, a extensão do arquivo escolhe o runtime. RF-DETR ou RT-DETRv2, .onnx ou um diretório do transformers.

Backends de modelo →

O catálogo de modelos

Todos os pesos que o cardstream consegue carregar, treinados pela Ximilar e publicados sob Apache-2.0 junto com as versões: o que cada um faz, em que resolução roda e qual é a licença.

Catálogo de modelos →

Respostas curtas

Quanto custa, o que sai da máquina, quais cartas ele reconhece e os dois comandos que removem tudo de novo.

Ler as perguntas frequentes →

README e issues

O README cobre todas as flags; as issues são o lugar para bugs e dúvidas.

Ler o README →

Versões e artefatos

Wheels, checksums e o script de instalação, um conjunto por versão, além dos builds em Docker e a partir do código-fonte.

Página de download →