youtubewc
최근 수정 시각: 2026-07-10 22:26:46
1. 개요
youtubewc(Cloudflare 프로젝트명 youtubemusicwc)는 YouTube Music 재생목록을 소재로 곡을 겨루게 하는 이상형 월드컵 겸 ELO 랭킹 앱이다. 자신의 재생목록을 불러와 토너먼트로 취향을 정렬하고, 그 결과를 전 사용자 공통의 글로벌 리더보드로 누적하며, AI가 붙인 곡 라벨을 바탕으로 자연어 조건만으로 새 플레이리스트를 뽑아 다시 YouTube에 발행할 수 있다.
원래 Flask/Jinja 기반 파이썬 앱이었으나 Cloudflare Worker + 정적 SPA 구조로 전면 이식되었고[1], 프론트엔드는 번들러 없는 브라우저 네이티브 ES 모듈로 구성된 PWA다. UI는 Claude.ai 톤의 웜 베이지 + 브라운 디자인 토큰에 다크 모드와 모바일 반응형을 갖춘 리디자인을 거쳤다.
이 문서는 앱 전체를 소개하는 대문이다. 각 기능의 구체적인 역할과 사용법은 아래 개별 문서로 나뉘어 있다.
2. 기능 한눈에 보기
| 문서 | 무엇을 하는가 |
|---|---|
| 월드컵 · 랭킹 모드 | 재생목록을 토너먼트로 돌려 Elo로 곡 순위를 매긴다. 2·5·10곡 대결과 25곡 티어 모드, 일반/FAST 토너먼트, 세션 인사이트. |
| 글로벌 ELO 리더보드 | 전 사용자 결과가 누적된 전체 곡의 Elo 순위. 통계·검색·AI 라벨 상세를 한곳에서. |
| 자연어 플레이리스트 | 자연어 조건만 주면 AI가 라벨을 근거로 곡을 골라 플레이리스트를 만들고 YouTube에 발행한다. |
| 큐레이션 빌더 | 리더보드를 곡 풀로 삼아 사람이 직접 곡을 골라 순서를 정하고 YouTube로 발행한다. |
| AI 곡 라벨링 | AI가 각 곡에 분위기·장르 등 라벨을 붙인다. 리더보드 상세와 자연어 생성의 재료. |
| 곡 바인딩 | 같은 곡의 여러 영상 버전을 하나로 묶어 순위 분산과 중복을 정리한다. |
| 에이전트 API | 외부 자동화(Claude Code 스킬 등)가 Bearer 인증으로 라벨링·플레이리스트를 대량 처리하는 API. |
3. 시작하기
앱은 크게 세 갈래로 쓴다.
- 취향 정렬 — Google 계정으로 로그인해 자신의 YouTube 재생목록을 불러오고, 월드컵으로 곡을 겨뤄 Elo 순위를 만든다. 결과는 자동으로 글로벌 리더보드에 누적된다.
- 플레이리스트 만들기 — 순위가 쌓이면 youtubewc/큐레이션 빌더로 직접 곡을 골라 순서를 짜거나, youtubewc/자연어 플레이리스트로 "잔잔한 게임 OST" 같은 조건을 주고 AI에게 맡겨 새 재생목록을 만들어 YouTube에 발행한다.
- 정리·자동화 — 같은 곡의 중복 버전은 youtubewc/곡 바인딩으로 묶고, 대량 곡 라벨링·플레이리스트 생성은 youtubewc/에이전트 API로 앱 바깥에서 자동화한다.
리더보드와 큐레이션 빌더의 곡 풀·순위 조회는 로그인 없이도 열람할 수 있지만, 재생목록 불러오기·월드컵 진행·플레이리스트 발행처럼 개인 계정과 쓰기가 필요한 기능은 로그인이 필요하다.
4. 기술 스택
- 플랫폼: Cloudflare Workers(
youtubemusicwc).main브랜치 푸시 시 GitHub Actions로 자동 배포. - 프론트엔드:
pages/(index · worldcup · leaderboard · curate · playlists) +static/. 번들러 없는 브라우저 네이티브 ES 모듈, 서비스 워커 기반 PWA. 웜 베이지 + 브라운 디자인 토큰, 다크 모드·모바일 반응형. - AI: Gemini(기본 모델
gemini-2.0-flash)로 곡 라벨링과 자연어 플레이리스트 생성. - 인증: 사용자는 Google OAuth → JWT 쿠키. 외부 에이전트는
Authorization: Bearer헤더(youtubewc/에이전트 API).
5. 개발 배경
파이썬 Flask 앱에서 출발해 Cloudflare Worker + 정적 SPA로 이식된 뒤, 2026년 3~4월 nightly 개발 라인에서 큐레이션 빌더·에이전트 API·Claude.ai 톤 리디자인·모바일 반응형이 추가되었다. 2026년 7월 초 master → main 브랜치 모델 정리와 nightly 머지·프로덕션 배포를 마쳤고[2], 이어서 전면 리팩토링으로 vitest 단위 테스트 + 헤드리스 스모크 안전망을 신설하고, 대형 JS/CSS를 페이지별 모듈로 분할했으며, 비로그인 상태의 콘솔 에러를 0으로 정리하고 자연어 생성·순서 업데이트 등의 UX 동선을 다듬었다.
브랜치 모델은 main(프로덕션) / nightly/날짜(개발 라인) / legacy(구 Flask 앱) / archive/* 태그(실험 보존)로 나뉜다.