From 54d67f892c2f6c39eb553a398f19073cfe518cf5 Mon Sep 17 00:00:00 2001 From: gahusb Date: Fri, 1 May 2026 11:14:25 +0900 Subject: [PATCH] =?UTF-8?q?docs(spec):=20music-lab=20YouTube=20=EC=88=98?= =?UTF-8?q?=EC=9D=B5=ED=99=94=20=EA=B3=A0=EB=8F=84=ED=99=94=20=EC=84=A4?= =?UTF-8?q?=EA=B3=84=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 시장 조사 자동화 + 영상 제작 파이프라인 + 수익화 추적 전체 설계. Phase 1(영상 제작) → Phase 2(시장 조사) → Phase 3(YouTube API) 로드맵 포함. Co-Authored-By: Claude Sonnet 4.6 --- ...1-music-lab-youtube-monetization-design.md | 359 ++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-01-music-lab-youtube-monetization-design.md diff --git a/docs/superpowers/specs/2026-05-01-music-lab-youtube-monetization-design.md b/docs/superpowers/specs/2026-05-01-music-lab-youtube-monetization-design.md new file mode 100644 index 0000000..a9c349e --- /dev/null +++ b/docs/superpowers/specs/2026-05-01-music-lab-youtube-monetization-design.md @@ -0,0 +1,359 @@ +# music-lab YouTube 수익화 고도화 설계 + +> 작성일: 2026-05-01 +> 범위: music-lab + agent-office 확장 + +--- + +## 1. 개요 + +Suno API로 생성한 음악을 YouTube 업로드 가능한 완성 영상으로 만들고, 시장 수요 분석을 통해 수익이 나는 콘텐츠를 정기적으로 생산하는 파이프라인 구축. + +**핵심 목표:** +- 시장 조사 자동화 → 만들 만한 장르/스타일 추천 +- 음악 + 영상 합성 → YouTube 업로드 패키지(MP4 + 메타데이터) 자동 생성 +- 수익 추적 → 채널별·장르별·국가별 RPM 분석 +- **Phase 1**: 파일 내보내기(수동 업로드) → **Phase 3**: YouTube API 자동 업로드 + +--- + +## 2. 결정 사항 요약 + +| 항목 | 결정 | +|------|------| +| 자동화 수준 | 반자동 — 수집·추천 자동, 생성·업로드 수동 트리거 | +| 업로드 방식 | Phase 1: 파일 내보내기, Phase 3: YouTube API | +| 영상 포맷 | 오디오 비주얼라이저 + AI 이미지 슬라이드쇼 | +| 시장 조사 데이터 | YouTube 트렌드 + Google Trends + Billboard (해외 시장 포함) | +| 음악 언어 전략 | 인스트루멘탈 + 영어 가사 혼합 | +| 이미지 소스 | Suno 커버이미지 + Pexels/Unsplash (추후 Stable Diffusion) | +| 주력 해외 시장 | 브라질, 인도네시아, 멕시코, 글로벌 | + +--- + +## 3. 아키텍처 + +``` +[외부 데이터 소스] + YouTube Data API v3 · Google Trends · Billboard · Pexels/Unsplash + ↓ 매일 09:00 스케줄 +[agent-office :18900] + YouTubeResearchAgent (신규) + - 국가별 트렌딩 수집·분석 + - POST /api/music/market/ingest → music-lab push + - 매주 월요일 08:00 텔레그램 인사이트 리포트 + ↓ +[music-lab :18600] + 기존: 음악 생성 · 라이브러리 + 신규: 시장 데이터 저장 · 영상 제작 파이프라인 · 수익화 추적 + ↓ +[내보내기 패키지] + output.mp4 + thumbnail.jpg + metadata.json + (Phase 3: YouTube API 자동 업로드) +``` + +**변경 없는 것:** 컨테이너 수, 포트 배정, Nginx 라우팅 (경로 1개 추가 제외) + +--- + +## 4. DB 스키마 (신규) + +### 4-1. music.db 신규 테이블 + +#### `market_trends` +| 컬럼 | 타입 | 설명 | +|------|------|------| +| id | INTEGER PK | | +| source | TEXT | `'youtube'` \| `'google_trends'` \| `'billboard'` | +| country | TEXT | `'BR'` \| `'ID'` \| `'MX'` \| `'US'` \| `'KR'` … | +| genre | TEXT | 장르 문자열 | +| keyword | TEXT | 검색 키워드 | +| score | REAL | 정규화 인기도 (0.0~1.0) | +| rank | INTEGER | 차트 순위 (nullable) | +| metadata | TEXT | JSON — 추가 원본 데이터 | +| collected_at | TEXT | ISO8601 | + +인덱스: `(country, source, collected_at DESC)` + +#### `trend_reports` +| 컬럼 | 타입 | 설명 | +|------|------|------| +| id | INTEGER PK | | +| report_date | TEXT UNIQUE | YYYY-MM-DD | +| top_genres | TEXT | JSON 배열 `[{genre, score, countries}]` | +| top_keywords | TEXT | JSON 배열 | +| recommended_styles | TEXT | JSON `[{genre, prompt, countries, reason}]` | +| insights | TEXT | AI 분석 텍스트 | +| created_at | TEXT | ISO8601 | + +#### `video_projects` +| 컬럼 | 타입 | 설명 | +|------|------|------| +| id | INTEGER PK | | +| track_id | INTEGER FK | → music_library.id | +| format | TEXT | `'visualizer'` \| `'slideshow'` | +| status | TEXT | `'pending'` \| `'rendering'` \| `'done'` \| `'failed'` | +| output_path | TEXT | MP4 로컬 경로 | +| output_url | TEXT | `/media/videos/…` 서빙 URL | +| thumbnail_path | TEXT | JPG 로컬 경로 | +| target_countries | TEXT | JSON 배열 `['BR', 'ID']` | +| yt_title | TEXT | Claude API 생성 제목 (최대 100자) | +| yt_description | TEXT | Claude API 생성 설명 (해시태그 포함) | +| yt_tags | TEXT | JSON 배열 (10-15개, 국가별 현지화) | +| render_params | TEXT | JSON — 렌더링 파라미터 (색상, 전환 효과 등) | +| error | TEXT | 실패 시 에러 메시지 | +| created_at | TEXT | ISO8601 | +| completed_at | TEXT | ISO8601 (nullable) | + +#### `revenue_records` +| 컬럼 | 타입 | 설명 | +|------|------|------| +| id | INTEGER PK | | +| video_project_id | INTEGER FK | → video_projects.id (nullable) | +| yt_video_id | TEXT | YouTube 영상 ID | +| record_month | TEXT | YYYY-MM | +| views | INTEGER | 조회수 | +| watch_hours | REAL | 시청 시간 (시간 단위) | +| revenue_usd | REAL | 수익 (USD) | +| rpm_usd | REAL | revenue / views * 1000 | +| country | TEXT | 국가별 분석용 (nullable) | +| source | TEXT | `'manual'` \| `'youtube_api'` | +| created_at | TEXT | ISO8601 | + +### 4-2. agent_office.db 신규 테이블 + +#### `youtube_research_jobs` +| 컬럼 | 타입 | 설명 | +|------|------|------| +| id | INTEGER PK | | +| status | TEXT | `'running'` \| `'completed'` \| `'failed'` | +| countries | TEXT | JSON 배열 — 수집 대상 국가 | +| trends_collected | INTEGER | 수집된 트렌드 건수 | +| report_id | INTEGER | 생성된 trend_reports.id (nullable) | +| error | TEXT | 실패 시 에러 | +| started_at | TEXT | ISO8601 | +| completed_at | TEXT | ISO8601 (nullable) | + +--- + +## 5. 신규 API 엔드포인트 + +### 5-1. music-lab — 시장 조사 + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| GET | `/api/music/market/trends` | 트렌드 목록 (`country`, `genre`, `source`, `days` 필터) | +| GET | `/api/music/market/report/latest` | 최신 분석 리포트 + 추천 스타일 | +| GET | `/api/music/market/report` | 리포트 이력 | +| POST | `/api/music/market/ingest` | agent-office → 트렌드 데이터 수신 | +| GET | `/api/music/market/suggest` | 트렌드 기반 제작 아이디어 추천 | + +### 5-2. music-lab — 영상 제작 + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| POST | `/api/music/video-project` | 프로젝트 생성 (`track_id`, `format`, `target_countries`) | +| GET | `/api/music/video-projects` | 프로젝트 목록 | +| GET | `/api/music/video-project/{id}` | 프로젝트 상세 + 렌더링 상태 | +| POST | `/api/music/video-project/{id}/render` | 렌더링 시작 (BackgroundTask) | +| GET | `/api/music/video-project/{id}/export` | 내보내기 패키지 (MP4 URL + metadata JSON) | +| DELETE | `/api/music/video-project/{id}` | 프로젝트 삭제 | + +### 5-3. music-lab — 수익화 추적 + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| GET | `/api/music/revenue` | 수익 기록 (`yt_video_id`, `year_month` 필터) | +| POST | `/api/music/revenue` | 수익 기록 추가 | +| PUT | `/api/music/revenue/{id}` | 수익 기록 수정 | +| DELETE | `/api/music/revenue/{id}` | 수익 기록 삭제 | +| GET | `/api/music/revenue/dashboard` | 총수익·RPM·장르별·국가별 집계 | + +### 5-4. agent-office — YouTube 리서치 + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| POST | `/api/agent-office/youtube/research` | 수동 리서치 트리거 (`countries` 지정 가능) | +| GET | `/api/agent-office/youtube/research/status` | 마지막 실행 상태 + 수집 건수 | + +--- + +## 6. 영상 제작 파이프라인 + +### 6-1. 오디오 비주얼라이저 (`format: 'visualizer'`) + +``` +MP3 (file_path) + 배경 이미지 (cover_images[0] 우선, 없으면 장르별 그라디언트 기본 배경) + → FFmpeg showwaves 필터 (1920×1080, 음파 오버레이) + → H.264 + AAC MP4 + → 썸네일 추출 (5초 지점 프레임) + → Claude API 메타데이터 생성 +``` + +핵심 FFmpeg 명령: +```bash +ffmpeg -loop 1 -i cover.jpg -i audio.mp3 \ + -filter_complex \ + "[1:a]showwaves=s=1920x200:mode=cline:colors=0xFF4444[wave]; \ + [0:v][wave]overlay=0:880[out]" \ + -map "[out]" -map 1:a \ + -c:v libx264 -c:a aac -shortest output.mp4 +``` + +적합 장르: Lo-fi, Ambient, Study Music, Phonk + +### 6-2. AI 이미지 슬라이드쇼 (`format: 'slideshow'`) + +``` +① 키워드 추출 (genre + moods + prompt → 검색어) +② 이미지 수집 + - Pexels API: 키워드 검색 4-6장 (무료 200req/시간) + - Suno 커버이미지: cover_images 필드에서 1-2장 +③ 이미지당 표시 시간 = track.duration_sec / 이미지 수 +④ FFmpeg xfade 전환 (fade, 1초) +⑤ H.264 + AAC MP4 출력 +⑥ 썸네일 추출 + Claude API 메타데이터 생성 +``` + +### 6-3. 공통 후처리 + +**Claude API 메타데이터 생성:** +- 입력: `genre`, `moods`, `lyrics`, `target_countries` +- 출력: + - `yt_title`: 최대 100자, SEO 최적화, 국가 감안 + - `yt_description`: 해시태그 + 타임스탬프 + 링크 플레이스홀더 + - `yt_tags`: 10-15개, 현지어 포함 (예: 브라질 타겟 → `"música relaxante"`, `"estudo música"`) + +**내보내기 패키지:** +``` +/data/videos/{project_id}/ + output.mp4 ← 최종 영상 + thumbnail.jpg ← 썸네일 + metadata.json ← {title, description, tags, target_countries, category} +``` + +--- + +## 7. YouTubeResearchAgent (agent-office) + +**파일:** `agents/youtube.py` + +**데이터 수집 (매일 09:00):** +1. YouTube Data API v3 — 국가별 (`BR`, `ID`, `MX`, `US`, `KR`) 트렌딩 음악 카테고리 50개 +2. pytrends — 장르별 Google Trends 점수 (최근 7일) +3. Billboard Hot 100 스크래핑 — 글로벌 차트 상위 20 + +**분석 → trend_reports 생성:** +- 소스별 score 정규화 후 장르 클러스터링 +- `recommended_styles` 생성: `{genre, suno_prompt, target_countries, reason}` +- Claude API로 `insights` 텍스트 생성 + +**push → music-lab:** +``` +POST http://music-lab:8000/api/music/market/ingest +body: {trends: [...], report: {...}} +``` + +**스케줄러:** +- 매일 09:00 — `youtube_research_job` +- 매주 월요일 08:00 — 주간 인사이트 텔레그램 발송 + +--- + +## 8. 인프라 변경사항 + +| 대상 | 변경 내용 | +|------|-----------| +| `music-lab/Dockerfile` | `RUN apt-get install -y ffmpeg` 추가 | +| `nginx/default.conf` | `/media/videos/` → `/data/videos/` 경로 추가 | +| `music-lab/requirements.txt` | `anthropic`, `Pillow` 추가 | +| `agent-office/requirements.txt` | `google-api-python-client`, `pytrends` 추가 | +| `.env` | `PEXELS_API_KEY`, `YOUTUBE_DATA_API_KEY` 추가 | +| `docker-compose.yml` | music-lab volume에 `/data/videos` 마운트 추가 | + +**CLAUDE.md 업데이트 필요:** +- Nginx: `/media/videos/` 경로 추가 +- music-lab API 목록에 신규 16개 추가 (시장조사 5 + 영상제작 6 + 수익화 5), agent-office 2개 추가 +- agent-office 스케줄러에 youtube_research_job 추가 + +--- + +## 9. 수익화 전략 + +### 9-1. YouTube 광고 수익 (CPM 기준) + +| 국가 | CPM 범위 | +|------|---------| +| 브라질 | $1.5 ~ $4 | +| 인도네시아 | $1.0 ~ $2.5 | +| 미국 | $3.0 ~ $8.0 | +| 한국 | $2.0 ~ $5.0 | + +Lo-fi / Ambient은 긴 시청 시간 유도 → RPM 유리. 인스트루멘탈은 언어 장벽 없음. + +### 9-2. 국가별 장르 전략 + +| 국가 | 주력 장르 | +|------|-----------| +| 브라질 | Funk, Phonk, Lo-fi | +| 인도네시아 | Pop, Study Music, Lo-fi | +| 멕시코 | Latin Pop, Reggaeton | +| 글로벌 | Ambient, Cinematic | + +### 9-3. 업로드 목표 + +- **주 3-5개** 영상 업로드 (시스템 안정화 후 일 1개 목표) +- 영상 **50개** 누적 → 수익 활성화 (구독자 1,000 + 시청 4,000시간) +- 영상 **200개** 누적 → 월 $100+ 수동 수익 목표 + +--- + +## 10. 구현 로드맵 + +### Phase 1 — 영상 제작 파이프라인 (약 2-3주) + +**music-lab 백엔드:** +- `video_producer.py` — FFmpeg 래퍼 (비주얼라이저 + 슬라이드쇼) +- `market.py` — 트렌드 데이터 수신·저장·조회·추천 +- `monetization.py` — 수익화 추적 CRUD +- DB 마이그레이션: `video_projects`, `revenue_records` +- 신규 API 12개 (영상 제작 6 + 수익화 5 + market ingest 1) +- Dockerfile `ffmpeg` 추가 +- Nginx `/media/videos/` 경로 추가 + +### Phase 2 — 시장 조사 자동화 (약 1-2주) + +**agent-office:** +- `agents/youtube.py` (YouTubeResearchAgent) +- YouTube Data API v3 연동 +- pytrends 연동 +- Billboard 스크래핑 +- 스케줄러 등록 (매일 09:00, 매주 월요일 08:00) +- `youtube_research_jobs` DB 테이블 +- 신규 API 2개 + agent-office API 2개 + +**music-lab:** +- DB 마이그레이션: `market_trends`, `trend_reports` +- 신규 API 4개 (트렌드 조회 3 + 추천 1) + +### Phase 3 — YouTube API 자동 업로드 (채널 안정화 후) + +- YouTube Data API OAuth 2.0 인증 +- 동영상 업로드·썸네일 설정 자동화 +- YouTube Studio 수익 데이터 자동 수집 (`source: 'youtube_api'`) +- 텔레그램 업로드 완료 알림 + +--- + +## 11. 신규 파일 목록 + +### music-lab/app/ +- `video_producer.py` — FFmpeg 비주얼라이저·슬라이드쇼 렌더링 +- `market.py` — 시장 트렌드 수신·저장·조회·추천 +- `monetization.py` — 수익 기록 CRUD·대시보드 + +### agent-office/app/agents/ +- `youtube.py` — YouTubeResearchAgent + +### agent-office/app/ +- `youtube_researcher.py` — YouTube/Trends/Billboard 데이터 수집 로직