akomlik/find-music

라이브 브라우저 및 로컬 풀 음악 매처 (/find-music)

목적

**"비디오를 위한 음악 워크플로우"**와 **"반복 방지 및 필수 음악 재사용 금지 법칙"**을 구현합니다:

1. 프로젝트 간 음악 재사용 금지: 모든 비디오는 고유한 사운드스케이프를 가져야 합니다. 이전 프로젝트(04_Project_Catalog/*/Storyboard.md 및 .fcproj)에서 사용된 트랙은 자동으로 제외됩니다.
2. 로컬 풀이 100곡을 초과할 때까지 온라인 검색 필수: 작은 로컬 풀은 반복적인 사운드트랙 선택으로 이어지기 때문에, /find-music과 /storyboard는 기존 로컬 트랙을 재사용하기 전에 CreatorMix 직접 온라인 카탈로그(fetch_creatormix_catalog.py)와 YouTube Studio 오디오 라이브러리에서 새로운 로열티 프리 트랙을 먼저 검색합니다.
3. 매끄러운 직접 CDN 가져오기: 모든 곡에 대해 수동 브라우저 탐색이 필요 없이, fetch_creatormix_catalog.py는 21개 앨범에서 134개 이상의 저작권 안전 트랙을 직접 쿼리하고, < 3:00 지속 시간으로 필터링한 후 CDN 스트림 URL을 통해 직접 03_Audio_Library/01_Curated_BGM/<Category>/[BPM]_[Mood]_[TrackName]_[Artist].mp3로 다운로드합니다!

디렉토리 및 분류 표준

모든 저장된 트랙은 03_Audio_Library/01_Curated_BGM/ 안에 위치합니다:

• 01_Rolling_Cadence/ — 110–125 BPM: 꾸준한 페달링, 평지 도로, 해안 도로
• 02_Scenic_Wonder/ — 80–105 BPM 앰비언트 / 멜로딕: 넓은 파노라마, 정상, 무지개, 해안 하이킹
• 03_Punchy_Climbs/ — 120–140 BPM 경쾌함 / 추진력: 안장에서 벗어난 노력, 빠른 내리막
• 04_Warm_Social_And_Retro/ — 75–115 BPM 어쿠스틱 / 보사 / 카페 / 레트로: 시장 방문(SaPobla_Market_Trip), 카페 정류장, 파티, 1977+ / 1980–1984 아카이브 슬라이드쇼
• 05_Short_Transitions/ — 15–30초 스팅거, 코믹 리프, 빠른 인트로

파일명 형식: [BPM]_[Mood]_[TrackName]_[Artist].mp3
(예시: 118bpm_ChillBeat_CircuitRush_TheMiniVandals.mp3, 085bpm_WarmChillhop_BubbleGum_Creatormix.mp3)

단계별 실행 워크플로우

1단계: 프로젝트 / 클립 모션 프로필 및 지속 시간 분석

1. <project_dir>/Storyboard.md와 <project_dir>/project_manifest.json을 읽습니다 (또는 대상 비디오 클립을 검사합니다).
2. 대상 비디오 지속 시간(규칙: < 3:00)과 장면 단계(예: 01_Rolling_Cadence $\rightarrow$ 04_Warm_Social_And_Retro)를 결정합니다.
3. 04_Project_Catalog/에서 과거 프로젝트를 스캔하여 제외된(이미 사용된) 트랙 목록을 컴파일합니다.

2단계: 새로운 음악 소싱 (직접 CreatorMix CLI 또는 YouTube Studio 브라우저)

옵션 A: 직접 CreatorMix 온라인 검색 및 자동 다운로드 (즉시, 브라우저 마찰 없음)

원하는 장르 또는 검색어와 함께 fetch_creatormix_catalog.py를 실행합니다:

# 특정 장르에서 새롭고 사용되지 않은 트랙 검색:
python3 ./.agents/skills/find-music/scripts/fetch_creatormix_catalog.py --genre chillhop --max-duration 180

# 선택된 트랙 다운로드 (예: 후보 #2):
python3 ./.agents/skills/find-music/scripts/fetch_creatormix_catalog.py --genre chillhop --download-idx 2

스크립트는 CreatorMix CDN에서 직접 고품질 MP3를 다운로드하고, 표준 [BPM]_[Mood]_[TrackName]_Creatormix.mp3 명명 규칙으로 포맷한 후 03_Audio_Library/01_Curated_BGM/<Category>/로 이동시키며, music_catalog.json을 자동으로 업데이트합니다!

옵션 B: YouTube Studio 오디오 라이브러리 브라우저 탭 (studio.youtube.com)

YouTube 오디오 라이브러리에서 특정 앰비언트 또는 빈티지 분위기를 검색하는 경우:

1. chrome-devtools 또는 /browser를 통해 열려 있는 YouTube Studio 탭에 연결합니다.
2. 필터 적용: 지속 시간 < 3:00, 장르 (Dance & Electronic, Ambient, Folk & Acoustic), 분위기 (Inspirational, Happy, Calm).
3. 트랙을 ~/Downloads에 다운로드하고 save_music_track.py를 실행하여 자동 태깅 및 이동:

   python3 ./.agents/skills/find-music/scripts/save_music_track.py \
     --source latest \
     --bpm 118 \
     --mood "ChillBeat" \
     --title "Circuit Rush" \
     --artist "The Mini Vandals" \
     --category "01_Rolling_Cadence" \
     --source-site "YouTube_Audio_Library"
   

3단계: 제작자에게 확인 및 타임라인 배치 제안

Alexander에게 새 트랙을 보고하고 /swap-music, /magic-movie 또는 /build-cut-table을 통해 트랙 A2에 배치할 것을 제안합니다.