web-page-backend/docs/superpowers/specs/2026-05-01-music-lab-youtube-monetization-design.md

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 명령:

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 데이터 수집 로직