FAQ

Perguntas frequentes

As dúvidas que mais aparecem: instalar e remover, quanto custa, o que sai da sua máquina e o que ele consegue nomear. Tudo o que rende mais está na central de documentação.

Instalar e remover

Instalar, atualizar, desinstalar

O script de instalação mexe em exatamente dois lugares da sua máquina, e você pode apagar os dois quando quiser.

O que eu preciso para rodar?

Uma máquina com Python 3.11 ou mais recente, e pouco mais que isso. macOS arm64, Linux amd64 e Windows amd64 são cobertos pela mesma versão em Python puro, sem precisar de GPU. O binário ffmpeg do sistema só é necessário para as fontes por pull e em modo de escuta (RTSP, RTMP, SRT); uma webcam, um arquivo ou a interface no navegador dispensam ele.

Onde o script de instalação coloca as coisas?

Em dois lugares. ~/.cardstream é a raiz da instalação: um virtualenv em venv/ e os pesos dos modelos em models/. Os dois comandos, cardstream-web e cardstream-client, são pequenos shims (scripts de atalho) gravados em ~/.local/bin; eles executam os binários do virtualenv com os caminhos dos modelos já preenchidos, então qualquer flag que você passar tem prioridade. Os dois locais mudam com CARDSTREAM_HOME e INSTALL_DIR. Nada mais na máquina é tocado; em especial, o script nunca edita o perfil do seu shell: se ~/.local/bin não estiver no seu PATH, ele mostra um aviso e deixa a mudança por sua conta.

Como atualizo para uma versão nova?

Rode a mesma linha de novo. Ela instala a versão atual no virtualenv existente e regrava os shims. Os pesos que já estão em ~/.cardstream/models ficam como estão (só são baixados quando faltam), então uma atualização é um download pequeno, não mais um quarto de gigabyte. Para ficar em uma versão específica em vez da mais recente, defina CARDSTREAM_VERSION.

# a mesma linha; /install.sh redireciona para o script na branch 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

Como desinstalo?

Dois comandos. O primeiro remove o virtualenv e os pesos dos modelos; o segundo, os dois shims. Não sobra mais nada para limpar: nenhum daemon, nenhum item de login, nenhum pacote do sistema.

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

Se você instalou com CARDSTREAM_HOME ou INSTALL_DIR definidos, remova esses caminhos no lugar, e use sudo se apontou os shims para um diretório do sistema. O que você adicionou por conta própria continua sendo seu para desfazer: uma linha de PATH no perfil do shell, o export de XIMILAR_API_KEY e qualquer pasta que tenha passado para --store-images. O app não grava mais nada na sua pasta pessoal. Confira que sumiu com command -v cardstream-web em um shell novo; o antigo guarda o caminho em cache até você rodar hash -r.

Chaves e custo

Quanto custa e do que precisa

Sem plataforma no meio: seu hardware, sua chave e um motor cujo trabalho é chamar para fora o mínimo possível.

Preciso de uma chave da API da Ximilar?

Para o caminho de identificação padrão, sim, e ela é a única credencial de que o sistema inteiro precisa. Pegue uma em ximilar.com e exporte como XIMILAR_API_KEY antes de começar. Se em vez disso você conectar seu próprio reconhecedor, precisa do que esse endpoint pedir e de nada da Ximilar.

$ export XIMILAR_API_KEY=your-key

Quanto custa o cardstream em si?

Nada. Não tem assinatura, licença por usuário nem taxa de plataforma: é um pacote Python com licença permissiva que você roda no seu próprio hardware, com pesos de detecção publicados sob Apache-2.0 junto de cada versão. O que você paga são as chamadas de identificação ao endpoint que conectar, e manter esse número baixo é toda a razão de existir do motor local: mais ou menos uma chamada por carta diferente que você mostrar, cerca de cem em uma hora em que um pipeline ingênuo, quadro a quadro a 15 fps, dispararia 54.000. Salvar um show na sua conta da Ximilar acrescenta um início de sessão cobrado por show; retomar depois de reiniciar é grátis.

Posso usar meus próprios modelos ou meu próprio sistema de identificação?

Os dois. O localizador de cartas e o filtro de identidade são roteados por backend: a exportação RF-DETR .onnx que vem incluída, uma de RT-DETRv2, ou um diretório do transformers ou id do hub enquanto você ainda está iterando um fine-tuning. O passo de identificação que vem depois é só um endpoint, então apontá-lo para o seu próprio reconhecedor deixa intactos todos os filtros, limitadores e cooldowns que ficam na frente dele. Veja os backends de modelos e o catálogo de modelos.

Rodando

Hardware, streams e segurança

Ele roda ao lado do seu show, na mesma máquina de onde você já transmite.

Preciso de GPU?

Não. Os pesos incluídos são exportações ONNX dimensionadas para CPU, e tudo o que o motor local faz (o filtro de movimento, o limitador de detecção, o embedding que responde “mesma carta ou carta nova?”) roda no processador que você já tem. Uma GPU é uma opção para os seus próprios pesos de maior precisão, nunca um requisito para a configuração padrão.

Funciona com Whatnot ou Fanatics Live?

Sim, mas não se conectando ao marketplace: ele aproveita o vídeo que você já está produzindo. Uma câmera virtual do OBS, uma segunda saída RTMP ou SRT ao lado da que alimenta a plataforma, um pull RTSP de um encoder, ou simplesmente uma câmera própria apontada para a mesma mesa. O guia de venda ao vivo percorre os quatro caminhos do começo ao fim.

O que realmente sai da minha máquina?

No modo cliente, um recorte JPEG por carta diferente: nem o stream, nem os quadros em volta, nem o resto da mesa. Toda decisão sobre se algo deve ser enviado é tomada primeiro localmente, então uma hora de vídeo em que você mostra cem cartas vira cem requisições pequenas. A única exceção é você quem liga: com --ximilar-stream, o histórico do show (uma linha de texto por carta, mais o recorte a partir do qual ela foi identificada) também é salvo em uma sessão na sua própria conta da Ximilar. Vem desligado por padrão, e --no-ximilar-stream-images envia só o texto.

Posso rever um show depois?

Sim, se você salvar. Comece com --ximilar-stream NEW e cada carta que o histórico lista (com o preço, o tempo no ar e o recorte a partir do qual foi identificada) vai para uma sessão na sua conta da Ximilar enquanto o show acontece. Depois, abra a seção Cardstream do app da Ximilar: o valor do show, os produtos mais valiosos e as principais coleções, cada carta com a imagem dela; marque o que foi vendido e corrija uma correspondência errada. Precisou reiniciar no meio do show? Passe o id da sessão no lugar de NEW e tudo continua, mesmo que a sessão tenha sido fechada. Para salvar em um workspace de equipe, use --ximilar-workspace. Os detalhes.

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

Posso rodar na minha rede local para abrir a interface de outra máquina?

Não faça isso. A interface web não tem autenticação e guarda a sua chave da API, então o lugar dela é 127.0.0.1 e nenhum outro. O contêiner escuta em 0.0.0.0 internamente, e é por isso que o docker run documentado publica a porta só em 127.0.0.1. Se você realmente precisa acessar de outra máquina, coloque na frente um túnel autenticado seu em vez de abrir a porta.

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

Identificação

O que ele nomeia e com quanta certeza

Cada correspondência chega com a distância, o nível e as cartas que poderiam ter sido no lugar dela.

Quais cartas ele consegue identificar?

Quatro categorias, uma chave. Jogos de cartas colecionáveis: Pokémon, Magic: The Gathering, Yu-Gi-Oh!, One Piece, Lorcana e mais uns vinte, com cartas avulsas modernas e vintage lidas direto do vídeo. Cartas esportivas de todos os grandes esportes, até a paralela e o ano. Cartas graduadas (slabs), lidas pela etiqueta sem abrir a case. E quadrinhos, por título, edição e ano. Uma flag escolhe a categoria, ou o painel de configurações troca no meio da live. Veja a lista completa.

O que acontece quando ele erra a carta?

Você vê de longe. Cada correspondência traz a distância bruta e um nível Alto / Médio / Baixo (os cortes ficam em 0.30 e 0.40), além de até quatro cartas alternativas que poderiam ter sido, e a certa costuma estar nessa lista curta. Defina um limiar de resultado e tudo o que ficar abaixo nunca chega ao overlay. Se um show inteiro é de um só jogo ou de uma só coleção, os pré-ajustes estreitam a busca antes de ela começar: diga o jogo, o código da coleção ou o sistema de escrita e o endpoint para de adivinhar.

Código aberto. Hospedado por você. Sua live, seu stack.

Sem plataforma no meio do caminho, sem licença por assento: conecte a API da Ximilar ou seu próprio sistema de identificação e o cardstream chama uma vez por carta distinta, não uma vez por quadro. Não importa se você faz breaks na Whatnot, comanda um show no estilo Fanatics Live ou transmite seu próprio live commerce: coloque o cardstream para rodar hoje à noite no hardware que você já tem.

Dê uma estrela no GitHub Obtenha uma chave da API da Ximilar