akomlik/find-music

即時瀏覽器與本地音樂庫配對器（/find-music）

目的

實作 「影片配樂工作流程」 與 「反單調與強制音樂不重複法則」：

1. 零音樂跨專案重複使用： 每個影片都必須有獨特的音景。過去專案（04_Project_Catalog/*/Storyboard.md 與 .fcproj）中已使用的曲目會自動排除。
2. 強制線上搜尋直到本地資料庫超過 100 首曲目： 因為小型本地資料庫容易導致配樂選擇重複，/find-music 與 /storyboard 在重複使用任何現有本地曲目前，會先從 CreatorMix Direct Online Catalog（fetch_creatormix_catalog.py）和 YouTube Studio 音效庫查詢新的免版稅曲目。
3. 無摩擦的 Direct CDN 擷取： 無需為每首歌手動瀏覽網頁，fetch_creatormix_catalog.py 可直接查詢橫跨 21 個專輯、134 首以上版權安全的曲目，依 < 3:00 長度過濾，並直接透過 CDN 串流網址下載到 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 Ambient / Melodic：寬廣全景、山頂、彩虹、海岸健行
• 03_Punchy_Climbs/ — 120–140 BPM Upbeat / Driving：站姿踩踏、快速下坡
• 04_Warm_Social_And_Retro/ — 75–115 BPM Acoustic / Bossa / Café / Retro：市場之旅（SaPobla_Market_Trip）、咖啡店停留、派對與 1977+ / 1980–1984 檔案幻燈片
• 05_Short_Transitions/ — 15–30s 短音效、喜劇 riff、快速開場

檔名格式： [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 音效庫中搜尋特定的 ambient 或復古情緒：

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 上。