bgmusic
为视频寻找真正的音乐背景，从公共领域目录中获取，无需下载库或欠任何人署名。
当内置文件足够时
public/sfx/ 已经包含两个背景音乐，且无需任何请求：
music-bed.mp3，一段60秒的环境嗡鸣音。适用于简短的技术演示视频。pulse-bed.mp3，112bpm，并附带精确的提示网格文件pulse-bed.cues.json。这是唯一一首节拍锁定剪切精确而非估计的曲目，因为它是合成而非分析得到的。
当视频较短、以旁白为主或音乐只需避免静音时，使用它们。当视频是发布或推广作品，且背景音乐承载情绪时，再去寻找其他音乐。
两个目录
| 来源 | 内容 | 大小 |
|---|---|---|
lofi | btahir/open-lofi，166首lo-fi曲目，分为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。
- 处理背景音乐需要系统PATH中有
ffmpeg。raw: true不需要。 - GitHub未认证API的限制是每小时60次请求。构建一次索引大约需要七次。如果频繁重建索引，可在相应机器上设置
GITHUB_TOKEN。 - 索引缓存位于
output/下，脚手架项目已经将其加入gitignore。
注意事项
- 不要将整个目录提交到项目中。每个视频一首背景音乐是这里的单位。
- 不要将曲目放入
public/sfx/。该文件夹是与包一起提供的套件，public/sfx/CREDITS.md说明了其中的内容以及为什么它没有使用条款。 - 不要将其用于音效。
plan_sound_effects首先检查内置包，然后才去其他地方查找，这才是音效的正确顺序。