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–30s 短促音效、喜剧即兴、快速片头

文件名格式： [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 → 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、流派（舞曲与电子、环境、民谣与原声）、情绪（鼓舞人心、快乐、平静）。
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 报告新的曲目，并提供将其放置到音轨 A2 的选项，可通过 /swap-music、/magic-movie 或 /build-cut-table 执行。