개요
TubeHaus는 Google 계정 없이 YouTube를 보는 개인용 클라이언트다. 화면 배치와 단축키는 YouTube와 같게 만들고, 구독·시청 기록·재생 위치는 Google이 아니라 내 서버나 내 기기에 둔다. 2026-10-18에 “HomeTube”라는 이름으로 시작해 2주 만에 커밋 132개, 서버 v0.7.17·앱 0.5.10까지 왔고(2026-11-01 기준 별 191개), 같은 날 Product Hunt에 올렸다. 라이선스는 2026-10-11-github-iv-org-invidious와 같은 AGPL-3.0이다.
형태가 둘이다. 이름과 겉모습은 같지만 YouTube와 통신하는 주체가 다르다.
서버판 (main) | 앱판 (android-app 등 5개 브랜치) | |
|---|---|---|
| 설치 | VPS·홈 PC·라즈베리파이에 docker compose | Android(TV 포함)·Windows·macOS·Linux·iPad/iPhone(Sideloadly) |
| YouTube와 통신 | 서버가 Invidious + Cloudflare WARP를 거쳐서 | 기기가 앱 내장 엔진으로 직접(InnerTube) |
| YouTube가 보는 IP | WARP 주소 | 기기 자신의 IP |
| 라이브러리 위치 | 서버(가족 공유) | 기기(0.5.4부터 서버와 동기화 선택 가능) |
| 이쪽에만 있는 기능 | 라이브 실시간 자막, TV로 보내기, 고화질 저장, TV 모드, 사이드로딩 없는 iPhone 사용 | 오프라인 저장, 백그라운드·PiP, 데스크톱 mpv 재생 |
서버판의 구조
브라우저 ─► Caddy ─┬─ /y/*, 페이지 ───────────► web/ (정적 앱)
├─ /api/p/*, /api/v1/videos/* ► TubeHaus 서버
├─ /companion/* ─────────────► invidious-companion
└─ 나머지 ───────────────────► Invidious
▼
Cloudflare WARP(프록시 모드) ─► YouTube
YouTube 데이터 수집은 2026-10-11-github-iv-org-invidious와 2026-10-11-github-iv-org-invidious-companion이 맡는다. TubeHaus는 그 코드를 고치지 않고 공식 이미지를 그대로 쓰며, 옆에 작은 서버와 자체 프런트엔드를 붙인다. companion의 private_url을 TubeHaus 서버로 돌려서, 요청을 통과시키면서 빠진 것(라이브 HLS URL, 오래된 영상에 없는 storyboards 키)을 채우고 YouTube가 막으면 WARP를 다시 연결한다.
- 서버는 파이썬 표준 라이브러리만 쓰는 파일 하나(
tubehaus_server.py, 3,084줄), 웹 앱은 빌드 단계 없는 ES 모듈(약 5,200줄)이다. 플레이어는 Shaka Player 위에 만들었다. docker compose up -d한 번으로 Caddy, WARP가 들어간 TubeHaus 서버, 라이브용 PO 토큰 제공기, whisper.cpp, Invidious·companion·PostgreSQL이 함께 뜬다. 요구 사양은 2코어·RAM 4GB·디스크 10~20GB다. 영상은 저장하지 않고 스트리밍만 한다.--doctor옵션이 WARP·YouTube·Invidious·실제 영상 조회를 한 줄씩 점검한다.
눈에 띄는 기능
- WARP 경유: 클라우드 IP는 YouTube에서 “봇이 아님을 확인하려면 로그인하세요”를 자주 받는다. 모든 YouTube 요청을 공식 WARP 클라이언트(프록시 모드)로 내보내고, 막히면 재연결 후 재시도해 싼 클라우드 VM에서도 돌게 했다. 비공식
wgcf는 Cloudflare가 속도 제한을 건다고 적었다. - 빠른 클릭: 영상 정보를 로컬 캐시에서 바로 주고 백그라운드에서 갱신하며, 다음에 열 만한 영상을 미리 받아 둔다(README 수치: 처음 1~2초, 캐시 적중 시 수 ms).
- 라이브 실시간 자막: YouTube가 자막을 주지 않는 라이브 방송을 whisper.cpp로 재생보다 몇 초 앞서 받아쓴다. CPU 코어 하나면 된다고 한다.
- 차분 모드(Calm mode): 스위치 하나로 홈을 구독 채널 새 영상만 남기고, 쇼츠·인기·추천을 모두 숨기고, 자동 재생을 끄고, 댓글을 접어 둔다.
- 서버에서 배우는 쇼츠 추천: 시청 시간·반복·좋아요·넘김으로 채널·주제별 점수를 서버 파일에 쌓고, 네 번째 칸마다 새로운 것을 끼운다. 일반 영상에는 개인화 추천을 일부러 두지 않는다(ROADMAP “계획 없음”).
- 그 밖에 SponsorBlock, Return YouTube Dislike, 폰에서 고른 영상을 TV에서 여는 “TV로 보내기”(Chromecast 없이 롱폴링), ffmpeg로 합치는 1080p/4K 저장, 13개 언어(한국어 원문 포함), Google Takeout·NewPipe·FreeTube·Invidious·OPML 가져오기·내보내기.
공개 인스턴스 모드
TUBEHAUS_PUBLIC=1이면 방문자 라이브러리를 각자의 브라우저 로컬 저장소에 두고 서버는 상태를 갖지 않는다. TV로 보내기·서버 다운로드는 꺼진다. 동시 시청자 수·최대 화질·분당 요청 수 상한을 둘 수 있고, 같은 영상 요청은 YouTube에 한 번만 묻는다. deploy/docker-compose.public.yml은 앞단에 Anubis 작업 증명 검사, 가입 필수(PBKDF2 60만 회 해시), 접근 로그 없음까지 묶어 둔다. 대역폭과 “한 IP에 시청자가 몰리면 YouTube 차단이 빨라진다”는 점은 README가 직접 경고한다.
앱판
Kotlin 공통 소스 하나를 Jetpack Compose(Android), Compose for Desktop(Windows·macOS·Linux), Compose Multiplatform/Kotlin Native(iOS)로 세 번 빌드하고, 플레이어만 ExoPlayer·libmpv·AVPlayer로 다르게 쓴다. Invidious 없이 앱 내장 엔진이 InnerTube를 직접 부르며, iOS판은 재설치 없이 엔진을 스스로 갱신한다고 한다. App Store에는 없어 iPad/iPhone은 Sideloadly로 설치하고, 무료 Apple ID면 7일마다 다시 서명해야 한다. macOS 앱은 아직 Apple 서명이 없다.
평가와 주의점
-
이 노트의 근거는 저장소 README·문서뿐이다. 응답 속도, 라이브 자막의 CPU 사용량, 8K 버퍼링 같은 성능 주장은 직접 재 보지 않았다.
-
YouTube 쪽 위험은 Invidious와 같다. InnerTube를 비공식으로 쓰므로 YouTube가 바꾸면 깨질 수 있고, 연령 제한 영상은 재생되지 않는다. WARP 회전으로 차단을 피하는 방식은 Cloudflare·YouTube 이용 약관 문제와 함께 볼 일이다. README 면책 조항도 약관 준수와 다운로드 영상의 재배포 책임을 사용자에게 돌린다.
-
자체 계정이 없다. 서버판은 그 주소를 여는 누구나 같은 라이브러리를 공유하므로, 외부에 열기 전에 내장 basic auth나 Authelia·Authentik 같은 로그인을 앞에 둬야 한다.
-
매우 젊은 프로젝트다. 2주 동안 GitHub 릴리스가 서버 26개·앱 16개(데스크톱 1개 포함)일 만큼 빠르게 바뀌고, 앱은 모두 베타다. 커밋 일부에는 Claude Opus 5.5 공동 작성 트레일러가 붙어 있다(관리자 커밋 117개 중 6개). 1인 관리자가 이 속도를 얼마나 유지할지는 지켜볼 부분이다.
-
같은 날 볼트에 들어온 Karpathy의 HackerTube(2026-11-01-x-lucas-flatwhite-karpathy-hackertube, HN 추천 영상만 모은 YouTube 복제)와 문제의식이 겹친다. 둘 다 “알고리즘 피드에 지쳤다”에서 출발하지만, HackerTube는 콘텐츠 자체를 고르고 TubeHaus는 같은 YouTube를 추천 없이 보는 쪽이다.
-
X 소개 글(@Techjunkie_Aman, 2026-11-01)은 “Google 계정·추적 없음, 오프라인 저장, 백그라운드·PiP, 최대 4K, iPhone/iPad·Android·Windows·macOS·Linux·Apple TV·웹, iOS 16+ 탈옥 없이 Sideloadly·AltStore·SideStore 설치, 자체 서버로 라이브러리 동기화”를 내세우며 라이선스를 GPL-3.0이라고 적었다. 저장소 기준 라이선스는 위의 AGPL-3.0이다.
관련 노트
- 2026-10-11-github-iv-org-invidious — TubeHaus 서버판의 YouTube 백엔드
- 2026-10-11-github-iv-org-invidious-companion — 스트림 수급·PO 토큰을 맡는 동반 서비스
- 2026-04-05-open-source-video-download-extensions — 오픈소스 영상 다운로드 확장 정리
- moc-multimedia