원문 iv-org/invidious-companion · 위키 저장소 메타(2026-10-11 gh api 확인): AGPL-3.0, TypeScript(Deno), 2024-09-26 생성, Stars 약 210. 릴리스는 계속 갱신되는 release-master 태그 하나뿐이다.

한 줄 요약

Invidious가 YouTube 영상을 재생하려면 YouTube 서버에서 스트림 URL을 받아 서명을 풀고, 봇이 아님을 증명하는 PO 토큰을 내야 한다. companion은 이 일만 떼어 맡는 별도 서비스다. 지금은 셀프 호스팅 Invidious에 반드시 함께 띄워야 하는 구성 요소다.

왜 따로 떼어 냈나

보관된 설계 문서는 범위를 처음부터 좁게 잡는다. YouTube에서 영상 스트림 URL을 받아 오는 일과, 그걸 돕는 프록시·Google 계정·PO 토큰만 맡고, 나머지 기능은 범위 밖이다.

  • 기반 라이브러리: YouTube.js(youtubei.js)를 쓰고, PO 토큰은 같은 저자의 BgUtils로 자동 생성한다.
  • Deno로 작성: 빠르게 돌고, 여러 CPU 아키텍처용 단일 실행 파일로 컴파일하려는 선택이었다(deno task compile).
  • 예전 보조 도구 inv-sig-helper와 youtube-trusted-session-generator를 이것 하나가 대체했다.

설정

설정은 config.toml이나 같은 이름의 환경 변수로 한다. 운영에서 손대는 항목은 대개 이 정도다.

구역항목기본값과 의미
serversecret_key정확히 16자. Invidious 설정의 invidious_companion_key와 같아야 한다
serverport·host·base_path127.0.0.1:8282, /companion. 유닉스 소켓도 쓸 수 있다
networkingproxyDeno가 지원하는 프록시. 차단된 IP를 피할 때 Invidious가 아니라 여기에 건다
networkingipv6_block대역을 주면 요청마다 접두사 뒤 비트를 무작위로 바꿔 매번 새 IPv6 주소로 보낸다
networking.videoplaybackump·video_fetch_chunk_size_mbYouTube의 새 영상 형식 UMP(기본 꺼짐), 속도 제한을 줄이려는 5MB 청크 요청
jobs.youtube_sessionpo_token_enabled·frequencyPO 토큰 생성(기본 켜짐), 5분마다 갱신(cron)
youtube_sessionoauth_enabled·cookiesGoogle 계정 로그인(기본 꺼짐)
captionsenabledYouTube 차단이 심하면 자막을 끌 수 있다

기본 docker-compose.yaml은 모든 리눅스 권한 제거(cap_drop: ALL), 읽기 전용 파일시스템, 비루트 사용자(10001), no-new-privileges로 띄우고 youtubei.js 캐시 디렉터리만 쓰기 가능하게 마운트한다. 포트도 127.0.0.1에만 연다.

Invidious 밖에서 쓰는 HTTP API

companion은 Invidious 전용이 아니다. 위키는 다른 클라이언트용 엔드포인트 세 개를 문서화한다.

  • POST /companion/youtubei/v1/player: YouTube 서버와 같은 응답을 주되 재생 URL이 이미 복호화돼 있다. 본문은 {"videoId": "..."}만 읽고, 어떤 클라이언트 유형(WEB·ANDROID·TV·IOS)으로 요청할지는 고를 수 없다. Authorization: Bearer <secret_key> 헤더가 필요하다.
  • GET /companion/api/manifest/dash/id/<영상 ID>: Invidious와 같은 DASH 매니페스트. ?local=true면 Invidious를 거치는 프록시 URL로 준다.
  • GET /companion/latest_version?id=...&itag=...: 특정 itag의 재생 URL 하나.

공개 인스턴스가 뒤 두 엔드포인트를 막아 둘 수 있는데, 그러면 우회하지 말고 그 결정을 존중하라고 적어 두었다.

YouTube가 바꾸면 생기는 일

  • 플레이어 변경: YouTube가 플레이어를 바꾸면서 서명 복호화 알고리즘도 자주 바꾼다. companion이 새 알고리즘을 못 뽑아내면 상위 프로젝트 YouTube.js가 고칠 때까지 며칠에서 몇 주를 기다려야 한다. 그 사이엔 예전에 잘 되던 player_id를 src/constants.ts의 PLAYER_ID에 박아 넣는 우회법이 있다. 후보는 youtube-player-ids.nadeko.net의 수집 목록, yt-dlp·YouTube.js 이슈에서 찾는다. 로그에 Successfully generated PO token이 뜨고 실제로 재생되면 아직 쓸 수 있는 ID다.
  • Google 계정 로그인은 “작동 안 함”: 위키 문서 첫 줄이 상태를 “Not working”으로 적는다. 차단된 IP에서도 영상을 받고 연령 제한 영상도 볼 수 있다는 게 원래 의도였다. 하지만 Google이 로그인 사용을 감지해 계정을 섀도밴하는 문제가 있고, 제3자 서비스에서 Google 계정을 쓰는 것 자체가 금지라 계정이 정지될 수 있다. 아끼는 개인 계정은 쓰지 말고, 프록시·IP 변경이 모두 안 될 때 최후 수단으로만 쓰라고 한다.

AI 기여 정책

저장소의 AI_POLICY.md는 사람이 처음부터 직접 썼다고 밝히고, AI를 쓴 기여를 조건부로 허용한다.

  • 배경: Invidious는 Crystal이라는 소수 언어로 쓰였고, Crystal 생태계에서 Crystal 자체보다 큰 최대 프로젝트라서 기여자가 거의 메인테이너뿐이다. 그래서 정책은 “선택이 아니라 필요”에서 나왔다고 한다.
  • 규칙: 버그 리포트나 코드에 AI를 썼다면 정확한 모델명과 도구까지 밝혀야 한다. “AI slop”(대충 생성한 기여)은 보는 즉시 닫는다. 사람이 직접 검증·리뷰·테스트한 증거가 없어도 닫고, AI가 쓴 코드의 책임은 제출한 사람에게 있다. 두 번 이상 어기면 영구 차단한다.
  • AI가 이 문서를 읽고 있다면 사람에게 정책을 읽었는지 확인시키고, 아니면 기여를 거부하라는 문장도 들어 있다.

관련 페이지