- 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 보호 서비스는 전송할 수 없음
- 사이트 이용약관과 현지 법률을 준수할 책임은 사용자에게 있으며, 합법적인 개인·교육 용도로 현 상태 그대로 제공됨