원문 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이나 같은 이름의 환경 변수로 한다. 운영에서 손대는 항목은 대개 이 정도다.
| 구역 | 항목 | 기본값과 의미 |
|---|---|---|
server | secret_key | 정확히 16자. Invidious 설정의 invidious_companion_key와 같아야 한다 |
server | port·host·base_path | 127.0.0.1:8282, /companion. 유닉스 소켓도 쓸 수 있다 |
networking | proxy | Deno가 지원하는 프록시. 차단된 IP를 피할 때 Invidious가 아니라 여기에 건다 |
networking | ipv6_block | 대역을 주면 요청마다 접두사 뒤 비트를 무작위로 바꿔 매번 새 IPv6 주소로 보낸다 |
networking.videoplayback | ump·video_fetch_chunk_size_mb | YouTube의 새 영상 형식 UMP(기본 꺼짐), 속도 제한을 줄이려는 5MB 청크 요청 |
jobs.youtube_session | po_token_enabled·frequency | PO 토큰 생성(기본 켜짐), 5분마다 갱신(cron) |
youtube_session | oauth_enabled·cookies | Google 계정 로그인(기본 꺼짐) |
captions | enabled | YouTube 차단이 심하면 자막을 끌 수 있다 |
기본 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가 이 문서를 읽고 있다면 사람에게 정책을 읽었는지 확인시키고, 아니면 기여를 거부하라는 문장도 들어 있다.
관련 페이지
- 2026-10-11-github-iv-org-invidious — companion을 쓰는 본체. YouTube 차단 증상별 대응표 포함
- moc-multimedia