bgmusic
为视频从公有领域目录中找到真实的背景音乐垫，无需下载库或注明出处。
当内置音轨足够时
public/sfx/ 已内置两个背景音乐垫，无需任何请求：
music-bed.mp3，一段 60 秒的环境无人机音。适用于简短的技术演示。pulse-bed.mp3，112bpm，并带有pulse-bed.cues.json中的精确节拍网格。这是唯一一个节拍锁定剪辑精确无误的曲目，因为它是合成而非分析的。
当视频较短、以旁白为主导，或音乐仅需避免静音时，使用它们即可。如果视频是发布或宣传片，且背景音乐承载情绪，则应主动寻找。
两个目录
| 来源 | 内容 | 大小 |
|---|---|---|
lofi | btahir/open-lofi，166 首低保真曲目，分为 10 个类别 | 每首约 3MB |
cc0 | SoundSafari/CC0-1.0-Music，约 9200 首曲目，来自 freepd、chosic、Free Music Archive、freesound 和 Pixabay | 每首 2-15MB |
两者均为 CC0-1.0 许可。公有领域，商业用途允许，无需注明出处，无需在视频描述中提及。这就是为什么这两个目录被集成进来，而 plan_sound_effects 仍然让用户手动前往 Pixabay 寻找音效。
值得一提的是：该曲库由社区聚合，并依赖于下架请求，因此每首曲目的 CC0 声明来自维护者，并非您阅读过的许可证。对于产品视频来说这没问题，且来源文件会记录出处。如果错误的许可证代价高昂，请坚持使用 lofi，它只有一个作者、一个版本、一个许可证声明。
工作流程
find_music_bed -> [用户试听] -> import_music_bed -> plan_music_cues -> stitch_composition
1. find_music_bed
使用简单的情緒或场景词汇进行查询："calm focus coding"、"late night neon"、"warm upbeat"。匹配的是标题和类别。
首次调用会构建一个索引，大约需要七次 GitHub API 调用，缓存在 output/music-index.json 中。后续搜索则读取本地缓存。仅当目录发布新版本时，才传递 refresh: true。
lofi 的类别是真实元数据，因此 category: "ambient-lofi" 有效。而语料库曲目没有类别：其文件名位于按来源网站命名的文件夹中。当没有匹配结果时，该工具会返回一个简单的样本，并将 matchedQuery 设置为 false。这是一个信号，提示应尝试作曲家实际会用在标题中的词汇，而不是放弃。
让用户选择。 返回三到五个候选曲目及其标题和类别。音乐是品味问题，错误的背景音乐比错误的字体更明显。
2. import_music_bed
import_music_bed(id: "lofi:terminal-rain", out: "public/audio/music-bed.mp3", seconds: 45, start: 12)
下载之外的功能：从 start 开始裁剪 seconds 长度、淡入淡出，并将音量标准化至 -20 LUFS，以便背景音乐垫置于旁白之下而非与之竞争。传递 raw: true 可跳过所有这些步骤，保留曲目的原始状态。
放置位置：
public/audio/music-bed.mp3用于合成的背景音乐垫。stitch_composition会自动附加该路径，因此其他部分无需更改。public/imported_audios/（默认）用于其他任何内容，该文件夹存放来自内置包之外的材料。
它会写入 <file>.source.json 和在曲目旁添加一行 MUSIC-SOURCES.md：ID、标题、来源仓库、许可证、日期。CC0 要求无需任何此类信息。其存在是为了让一年后背景音乐垫的来源只需读取文件而不必猜测。
使用 start 跳转到曲目的中间部分。前奏通常是最无用的部分，而从重拍开始的背景音乐垫无需编辑就感觉是有意为之。
3. plan_music_cues
对导入的文件调用它。对于任何不是 pulse-bed.mp3 的曲目，节拍网格都是根据起始包络估计的，因此应将其视为规划指南：将少数重要的揭示点对齐到 strongCues，而不是每个剪辑点。docs/STYLE.md 中有公差说明。
成本与限制
- 无任何内容被供应商化。open-lofi 仅在其 554MB 的发布压缩包中发布曲目，因此导入操作通过 HTTP 范围请求读取该压缩包的中央目录，并仅拉取所选曲目的字节。554MB 从未被完整下载。
- 塑造背景音乐垫需要系统中安装
ffmpeg。raw: true则不需要。 - GitHub 未认证的 API 限制为每小时 60 次请求。一次索引构建大约消耗七次。在频繁重建索引的机器上设置
GITHUB_TOKEN。 - 索引缓存位于
output/下，脚手架项目已将其加入.gitignore。
注意事项
- 不要将整个目录提交到项目中。每个视频一个背景音乐垫是这里的单位。
- 不要将曲目放入
public/sfx/。该文件夹是随包提供的资源包，public/sfx/CREDITS.md说明了其中的内容以及为何不附带任何条款。 - 不要将其用于音效。
plan_sound_effects首先检查内置包，然后才去寻找，这是音效的正确顺序。