timeline-bgm

免费、本地合成的视频 BGM。主入口是一份手写的 timeline.json，所以 Remotion、HTML/Canvas、Python 逐帧或其他任何渲染器都能用。也可以从工程里自动提取时间轴。不需要付费服务。

安装

python3 -m venv .venv && .venv/bin/pip install numpy soundfile

需要 ffmpeg（响度标准化和混音）。

用法

1. 手写时间轴（推荐）

字段说明见 docs/TIMELINE_FORMAT.md。复制模板再改时间即可：

cp examples/template-timeline.json timeline.json
.venv/bin/python scripts/generate_bgm.py timeline.json -o bgm.wav \
  --bpm 120 --key 'A minor' --downbeat 17 --seed 0 --lufs -16

--bpm、--key、--downbeat 会覆盖 JSON 里的同名字段；JSON 没写时，速度默认 120、调性默认 A minor、节拍从 0 秒起算。downbeat 让小节的第一拍正好落在那一秒（通常是 drop 的起点），前面的段落沿同一条网格往回排。每个 drop 和这个强拍之前大约 1 拍，鼓会让开并接一段短上升音（breath，可在 JSON 里关掉）。

已有 Markdown 分镜表时，不必手填 JSON：

.venv/bin/python scripts/storyboard_to_timeline.py storyboard.md -o timeline.json --fps 30 --total 62

表头里只要有「时间 / 时间码 / time / 开始 / 结束」这类列。时间可以写成 12.4、12.4-17、00:12.4-00:17、0:12-0:17、12s~17s，或分成开始、结束两列。风格列（风格 / style）和重音（@21s 数字、@41 文字、@4 转场，写在重点 / 事件 / 备注）都是可选的。没写风格时，第一段 intro、最后一段 outro、中间 build / drop 交替。

62 秒样例：examples/relativity-timeline.json（intro 0–12.4，build 12.4–17，drop 17–53，outro 53–62，数字重音在 21 / 25 / 29 / 33 / 49）。试听：demo3.mp3（--downbeat 17）。

2. 从工程自动提取

提取是可选的。Remotion 工程或单个 HTML 文件都能试，结果仍是同一份 timeline JSON：

.venv/bin/python scripts/extract_timeline.py <Remotion目录或html文件> -o timeline.json
.venv/bin/python scripts/generate_bgm.py timeline.json -o bgm.wav --bpm 120 --key 'A minor' --seed 0 --lufs -16

示例工程：example-proj/，试听：demo2.mp3。

3. 混进视频

scripts/mix_video.sh video.mp4 bgm.wav out.mp4

特点

• 手写时间轴或分镜表即可，不绑定某一种渲染器
• 场景风格：intro、build、drop、outro
• 和弦进行、低音、铺底、琶音、drop 主旋律、鼓组、上升音
• downbeat 把小节线对齐到指定秒数；气口（breath）在强拍前留出大约 1 拍
• 文字、数字、转场等重音吸到对齐后的 16 分音符上
• 目标响度可调（默认 -16 LUFS，真峰值 ≤ -1 dB），混音时自动避让原视频声音（-14 LUFS）
• 同一 seed 结果完全一致
• 时间轴缺字段或写错时，用中文说明问题；超出范围或互相重叠的重音只警告

注意

自动提取是尽力识别：Remotion 在示例工程上测过，HTML/Canvas 靠正则猜场景。手写或分镜表转出的时间轴不经过这一步，用之前对一下场景时间和重音即可。