Castor는 웹 페이지나 직접 스트림 URL에서 실제 영상 스트림을 찾아 TV에 맞게 변환하고, 화면 미러링 없이 원본 품질로 실시간 전송하는 터미널 도구임

• 헤드리스 Chrome과
  Chrome DevTools Protocol로 네트워크 트래픽을 관찰하며, 페이지 클릭·최대 iframe 진입·재클릭을 거쳐 스트림을 추출하지만 자동 재생을 허용하지 않는 페이지에서는 작동하지 않을 수 있음
  DLNA/UPnP를 지원하는 스마트 TV와 Kodi·VLC·Plex에서 사용할 수 있고, Chromecast 지원은 구현됐지만 아직 실험적이며 테스트되지 않음
• 재생 가능한 H.264 영상은 재인코딩 없이 전달하고, 필요하면 하드웨어 인코더나
  libx264

로 변환하며 whisper로 생성한 자막을 영상에 삽입할 수도 있음

• 영상·카탈로그·소스를 제공하거나 DRM을 우회하지 않으며, 사용자가 직접 지정하고 이용 권한을 가진 페이지와 스트림만 전송하도록 설계됨

웹 영상을 실제 스트림으로 전송

• Castor는 임의의 웹 영상을 직접 전송하지 못하는 스마트 TV와 지연·해상도 저하가 있는 화면 미러링을 대신해,
  실제 영상 스트림을 전체 품질로 전송함
• 웹 페이지 또는 직접 스트림 URL을 입력하면 영상을 탐색하고 스트림을 추출한 뒤 TV에 맞게 트랜스코딩해 실시간으로 전송함
• 사용자가 구성한 소스에서
  IMDB/TMDB ID를 조회하거나 자동 생성 자막을 영상에 삽입할 수 있음
  castor cast

를 실행하면 터미널 기반 대화형 브라우저에서 작품을 탐색하고 전송할 수 있음

스트림 추출 방식과 한계

• 헤드리스 Chrome을 실행하고
  Chrome DevTools Protocol로 네트워크 트래픽을 관찰해 스트림을 찾음

• 재생 시작을 위해 짧은 동작 파이프라인을 수행함

• 페이지 클릭

• 가장 큰 iframe으로 이동

• 대체 동작으로 다시 클릭

• 자동 재생을 허용하는 페이지에서 작동하며, 모든 사이트를 지원하지는 않음

설치와 실행 요건

• 권장 방식은 TV와 같은 네트워크에서 실행되는
  네이티브 바이너리임
• 실행 환경의
  PATH

에 다음 도구가 필요함

• Chrome 또는 Chromium: 헤드리스 스트림 추출
  ffmpeg

: 트랜스코딩
ffprobe

: 미디어 형식 감지

• macOS에서는 Homebrew로 설치할 수 있음

brew install --cask stupside/tap/castor

• 소스 빌드에는
  Go 1.26+ 와 CMake가 필요함
• whisper.cpp 바인딩이 cgo를 사용하며 로컬에서 빌드한
  libwhisper.a

에 연결됨

• 로컬
  replace

와 사전 빌드된 정적 라이브러리가 필요하므로 go install

은 작동하지 않음

git clone --recurse-submodules https://github.com/stupside/castor.git
cd castor
make

기본 사용 흐름

castor scan

으로 TV 이름을 찾고 config.yaml

의 device

에 정확한 이름과 장치 유형을 지정함

device:
name: "Living Room TV"
type: dlna

• 웹 페이지나 직접 스트림 URL은
  cast player

로 전송함

castor cast player https://example.com/watch/some-video

• 대화형 작품 검색에는 TMDB API 키와 사용자가 구성한 소스가 필요하며, 전체 명령과 플래그는
  castor --help

에서 확인할 수 있음

구성과 사용자 제공 소스

config.yaml

은 현재 디렉터리 또는 --config

로 지정한 경로에서 읽으며, 필수 항목은 전송 대상 장치 설정뿐임

• 시간 제한, 탐색, 캡처, 트랜스코딩, 네트워크 인터페이스, Chrome 탐색에는 기본값이 제공됨
• 비밀 값은 Git에서 제외한
  config.local.yaml

로 덮어쓰거나 CASTOR_SECTION__FIELD

형식의 환경 변수로 지정할 수 있음
cast movie

, cast episode

, 대화형 브라우저는 사용자가 구성한 소스에 작품 ID를 대입함

• Castor 자체에는 소스, 카탈로그, 조회 기능이 포함되지 않음
• 사용자가 작성한
  templates

에 ID를 대입하고 각 proxies

를 앞에 붙여 페이지를 연 뒤 cast player

와 같은 방식으로 스트림을 추출함

• 여러 프록시는 지정된 순서대로 시도함

sources:
- proxies: ["https://your-source.example";]
templates:
movie: "/embed/movie/{itemID}"
episode: "/embed/tv/{itemID}/{season}-{episode}"

TMDB 검색과 자동 자막

• 대화형 브라우저는 작품 검색에
  TMDB API 키를 사용함
• 키는 themoviedb.org에서 받을 수 있음
  cast movie <id>

같은 직접 명령에는 TMDB 키가 필요하지 않음

• 자동 자막은 whisper로 음성을 전사해 영상에 삽입하며 기본적으로 비활성화돼 있음
• 기본 언어는 영어임
• 기본 모델은 약 75MB인
  ggml-tiny.en

이며 자동 다운로드됨

지원 장치

**DLNA/UPnP **MediaRenderer:1

프로필을 구현한 TV를 지원함

• Samsung은 테스트됐으며 LG, Sony Bravia, Panasonic Viera, Philips, Hisense, TCL, VIZIO, Sharp가 지원 대상임
• Kodi, VLC, Plex 같은 네트워크 플레이어도 사용할 수 있음

castor scan

으로 같은 네트워크의 장치를 조회함

• Chromecast 지원은 구현됐지만
  실험적이며 테스트되지 않음

Docker 제약과 네트워크 구성

• Linux 전용 Docker 이미지는 Chrome,
  ffmpeg

, ffprobe

를 함께 제공함

• Docker에서는 TV와 같은 LAN의
  Linux 호스트가 필요하며, SSDP 멀티캐스트 검색과 Castor 재생 서버 연결을 위해 --network host

를 사용해야 함

• Docker Desktop의 macOS·Windows에서는
  --network host

가 LAN으로 연결되지 않음

• 컨테이너가 Docker Desktop 내부 VM 서브넷에 배치돼
  scan

이 장치를 찾지 못하고 전송도 실패함

• macOS·Windows에서는 네이티브 바이너리를 사용하거나 Linux VM을 LAN에 브리지해야 함

/config.yaml

을 마운트해 설정을 제공하고, 볼륨에 자동 다운로드된 whisper 모델을 보존할 수 있음
latest

대신 릴리스 태그를 사용하면 버전을 고정할 수 있음

미디어 패스스루와 인코딩

• TV가 허용하는 프로필과 레벨의 H.264 영상을 이미 재생할 수 있으면
  스트림 복사를 사용해 CPU 사용량을 거의 0으로 낮춤
• TV가 코덱을 거부하거나 자막을 삽입해야 하면 재인코딩함
• Linux의 VA-API 또는 네이티브 macOS 바이너리의 VideoToolbox처럼 실제로 작동하는 하드웨어 H.264 인코더를 우선 선택함
• 사용할 수 없으면 소프트웨어
  libx264

로 대체함

• Docker 컨테이너에서 Intel GPU의 VA-API를 사용하려면
  --device /dev/dri

가 필요하며, --network host

만으로는 GPU가 노출되지 않음

용도와 제한

• Castor는 특정 사이트에 연결된 서비스가 아닌
  범용 전송 도구임
• 영상, 카탈로그, 소스를 호스팅하거나 번들로 제공하지 않으며, 사용자가 지정하고 이용 권한을 가진 페이지·스트림·소스만 처리함
• DRM을 해독하거나 우회하지 않으며
  DRM 보호 서비스는 전송할 수 없음
• 사이트 이용약관과 현지 법률을 준수할 책임은 사용자에게 있으며, 합법적인 개인·교육 용도로 현 상태 그대로 제공됨