English 
Español 
日本語 
简体中文 
ไทย 
Português 
Français 
Italiano 
Deutsch 
हिन्दी 
বাংলা 
پنجابی 
Dansk 
Svenska 
Polski 
Русский 
العربية 
Tiếng Việt 
Türkçe 
Nederlands 
Bahasa Indonesia 문서
모든 것이 내 컴퓨터에서 실행됩니다. 설치하고, 카메라를 향하게 하고, 외부 호출을 언제 허용할지 조정하세요. 하려는 작업별로 묶었습니다.
아무것도 없는 상태에서 화면에 카드가 뜨기까지
명령어 하나로 클라이언트, 모델 가중치, 심(shim)이 설치됩니다. 시스템 전체에서 필요한 자격 증명은 Ximilar API 키 하나뿐입니다.
설치 스크립트
~/.cardstream에 가상 환경(venv)을 만들고, 릴리스 wheel을 체크섬으로 검증하고, 모델 가중치를 내려받은 뒤 두 명령어를 PATH에 등록합니다. wheel, Docker, 소스 등 다른 설치 방법은 다운로드 페이지에 있습니다.
$ curl -fsSL https://raw.githubusercontent.com/Ximilar-com/cardstream/main/scripts/install.sh | sh 모든 설치 방법 → 수동 설치
체크아웃한 뒤 pip로 설치해도 됩니다. extras는 서로 독립적입니다. [client]는 UI와 소스(입력)를, [onnx] 또는 [torch]는 디텍터와 임베더 백엔드를 제공합니다.
$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream $ pip install -e '.[client,onnx]'
Ximilar API 키
식별은 Ximilar collectibles/v2가 담당합니다. 어디서든 읽는 환경 변수는 XIMILAR_API_KEY 하나뿐이며, 나머지 설정은 모두 플래그입니다.
$ export XIMILAR_API_KEY=your-key
첫 실행
웹캠을 연결한 브라우저 UI가 열립니다. 카드를 들어 올리면 오버레이에 상태 머신이 판단하는 과정이 표시되고, 확정되는 순간 일치한 카드가 나타납니다.
$ cardstream-web # → http://127.0.0.1:8001
설치 내용 확인
두 명령어 모두 버전을 출력하고 종료합니다. 모델 파일이 필요 없으므로 설치가 끝나는 즉시 동작합니다.
$ cardstream-web --version
cardstream 0.5.0 헤드리스 실행 (방송 리그용)
브라우저 없이 같은 파이프라인을 실행하고 결과를 터미널에 출력합니다. 플래그는 cardstream-web과 동일하며, 카메라 옆에서 프로세스 하나만 띄우면 됩니다.
$ cardstream-client --source 0 방송 영상 넣기
소스(입력)는 자유롭게 바꿀 수 있고, 어느 것을 고르든 분석은 동일합니다. 모든 설정은 플래그이며, 중요한 항목은 설정 대화 상자에서 방송 중에 바로 조정할 수 있습니다.
웹캠과 파일
cardstream-web의 기본값은 브라우저 웹캠입니다. 장치 번호, 동영상 파일, 정지 이미지는 어디서나 사용할 수 있습니다. 방송 전 테스트에 좋습니다.
$ cardstream-web # 브라우저 웹캠 $ cardstream-client --source clip.mp4
스트림 받아오기
IP 카메라, 인코더, 리스트리머를 지정할 수 있습니다. rtsp://, rtmp://, srt:// 및 ws:// JPEG 피드를 지원하며, 상한이 있는 백오프로 자동 재접속합니다.
$ cardstream-web --source rtsp://cam/stream1 OBS에서 보내기
리스너 모드로 실행하고 OBS에 RTMP 또는 SRT 출력을 하나 추가하면 됩니다. 시스템 ffmpeg 바이너리가 필요합니다(brew install ffmpeg).
$ cardstream-web --source rtmp://0.0.0.0:1935/live --listen 사전 지정으로 검색 범위 좁히기
게임, 세트 코드, 문자 체계는 전송 전에 로컬에서 검증됩니다. --game을 넘길 때는 반드시 --alphabet도 함께 넘기세요. 게임을 사전 지정하면 엔드포인트가 문자 체계를 스스로 감지하지 않기 때문입니다.
$ cardstream-web --game "Pokémon" --alphabet japanese --set-code M4
설정 대화 상자
카테고리, 게임, 세트 코드, 문자 체계, 임계값은 방송 중에 브라우저에서 바로 바꿀 수 있습니다. 재시작이 필요 없고, 컨트롤에는 프로세스와 동일한 검증이 적용됩니다.
세 가지 해상도 설정
카메라가 촬영하는 해상도, 전송하는 해상도, 분석하는 해상도는 각각 별개의 값입니다. 분석은 작은 해상도로 실행되고, 식별용 크롭은 전체 프레임에서 다시 잘라냅니다.
$ cardstream-web --camera-width 3840 --width 1280 방송을 저장하고 나중에 돌아보기
기본값은 꺼져 있습니다. 플래그 하나면 페이지가 쌓아 가는 기록(보여 준 모든 카드와 그 크롭)이 여러분의 Ximilar 계정 안의 세션에 저장되므로, 다음 날 아침에도 방송이 그대로 남아 있습니다.
썸네일이 붙은 기록
브라우저 UI는 보여 준 모든 카드를 최신순으로 나열합니다. 식별에 쓰인 크롭의 썸네일, --price-stats를 켰다면 그 가격, 그리고 방송에 머문 시간이 함께 표시됩니다. 이 목록은 내 컴퓨터에 보관됩니다.
방송 저장하기
--ximilar-stream NEW는 세션을 시작하고 그 id를 출력합니다. 그때부터 방송이 진행되는 동안 기록의 각 행이 저장됩니다. 업로드는 백그라운드에서 묶어서 처리되고, 네트워크 오류가 나면 재시도하며, 방송을 붙잡아 두는 일은 절대 없습니다. 정상적으로 종료하면 남은 것을 업로드하고 세션을 닫습니다.
$ cardstream-web --game "Pokémon" --alphabet latin \ --price-stats --ximilar-stream NEW방송 저장 자세히 보기 →
업로드되는 것
텍스트로 된 행(카드, 세트, 가격, 방송에 머문 시간, 그 행에 쓰인 유료 호출)과 각 행의 식별에 쓰인 최대 1024 px의 크롭입니다. 식별 호출이 이미 받았던 바로 그 이미지입니다. --no-ximilar-stream-images를 쓰면 텍스트만 보냅니다. Ximilar 계정에 Cardstream 서비스가 필요합니다.
$ cardstream-web --ximilar-stream NEW --no-ximilar-stream-images Ximilar 앱에서 돌아보기
모든 세션은 Ximilar 앱의 Cardstream 섹션에 쌓입니다. 무엇을 언제 보여 줬는지, 방송의 가치, 가장 값비싼 상품과 상위 세트, 그리고 크롭이 붙은 카드 하나하나까지. 팔린 카드를 표시하고, 잘못된 매칭을 바로잡고, 메모를 남기세요.
Ximilar 앱 열기 →재시작한 뒤 이어서 하기
NEW 대신 세션 id를 넘기면 같은 세션에서 방송이 이어집니다. 정상 종료로 세션이 닫혔더라도 그냥 다시 열립니다. 과금되는 것은 세션 시작뿐이므로 이어서 하는 데는 비용이 들지 않습니다.
$ cardstream-web --ximilar-stream <session-id>
팀 워크스페이스
세션은 API 키의 기본 워크스페이스에 저장됩니다. --ximilar-workspace로 다른 워크스페이스를 지정할 수 있으며, 그곳에 저장한 세션을 이어서 할 때도 같은 id를 넘기세요.
$ cardstream-web --ximilar-stream NEW \ --ximilar-workspace <workspace-id>
카드 한 장당 식별 호출 한 번
모션, 감지, 동일성 게이트 같은 로컬 신호가 식별 호출이 정말 필요한지를 판단합니다. 이를 정확하게 유지해 주는 설정 항목들입니다.
임계값
결과 임계값은 약한 일치를 오버레이에서 걸러내고, 유사도 임계값은 같은 카드인지 새 카드인지를 판정하며, forget-after는 카드가 충분히 오래 사라진 뒤 기억을 지웁니다.
$ cardstream-web --result-threshold 0.35 권장 구성
RF-DETR 세그멘테이션과 ONNX 임베딩 게이트의 조합이 기본 제공되는 설정입니다. 가중치만 갖춰져 있으면 인자 없는 cardstream-web이 정확히 이 구성으로 실행되며, 명시적으로 적어도 같은 파이프라인입니다.
$ cardstream-web \ --segmentor-model model/segmentation/onnx/model.onnx \ --embed-model model/similarity/onnx/model.onnx
localhost 밖으로 내보내지 않기
로컬 앱은 인증이 없고 API 키를 보관하고 있습니다. --host의 기본값은 127.0.0.1입니다. 그대로 두고, 포트를 LAN에 절대 노출하지 마세요.
시작 시 “Model not found”
모델 가중치는 저장소에 포함되어 있지 않고 별도로 내려받아야 합니다. 설치 스크립트와 Docker 이미지는 자동으로 가져옵니다. 저장소를 그대로 체크아웃한 경우에는 model/segmentation/과 model/similarity/에 직접 넣어야 하며, scripts/build-from-source.sh --models가 이를 대신해 줍니다.
진행 중인 게임 지정하기
한 가지 게임만 다루는 방송이라면 호출할 때마다 엔드포인트가 게임을 추측할 필요가 없습니다. 게임을 지정하면 검색이 그 게임으로 좁혀져 응답이 빨라지고 잘못된 판본이 줄어듭니다. --alphabet도 함께 넘기세요. 게임을 사전 지정하면 엔드포인트가 문자 체계를 스스로 감지하지 않기 때문입니다.
$ cardstream-web --game "Pokémon" --alphabet japanese
ffmpeg이 필요한 경우
--listen과 --ffmpeg은 시스템 ffmpeg 바이너리를 호출합니다. 일반적인 스트림 수신은 pip만으로 설치해도 동작하지만, OBS에서 보내는 구성은 그렇지 않습니다.
기본값 너머로
모델을 교체하거나 코드를 읽어 보세요. 파이프라인 전체가 설치 가능한 패키지 하나입니다.