| name | promo-bgm |
|---|---|
| description | 给产品宣传片 / 演示视频 / 更新短片配一支背景音乐 —— 纯代码合成，无第三方素材、 无版权风险，长度与剪辑点严丝合缝，改一个参数就能重出一版。 当用户说「给这支片子配个音乐 / 配个 BGM / 找个背景音乐」、「这段视频缺配乐」、 「音乐节奏跟画面对不上」、「换个更安静 / 更燃 / 更高级的曲子」、「口播底下垫一层」、 「做个 15 秒 / 30 秒 / 60 秒的版本」、「音量太吵 / 压不住人声」时使用。 也用于把已有的配乐重新对齐剪辑点、改长度、出各平台的响度版本、混进视频。 能做：明亮上扬、温暖克制、干净推进、电影感铺陈、轻快俏皮、夜色高级、稳重可信、 手作叙事、口播垫底，以及无缝循环版和 15 秒硬钩子版 —— 木质拨弦、 毛毡钢琴、尼龙弦、电钢、铺底、贝斯、沙锤/底鼓/响指。 不能做：人声与歌词、管弦乐、失真吉他、EDM、嘻哈采样、爵士即兴 —— 需要这些就去买授权， 别用这个 skill 硬凑。 |
promo-bgm · 给片子配一支自己的曲子
核心：配乐是一份 spec，不是一个音频文件。段落、和声、鼓的档位、目标长度写在一个
JSON 里，bgm.mjs 把它渲成音频。所以片子改了 3 秒，配乐跟着改 3 秒，而不是重新去找一首。
- 引擎：
assets/lib/synth.mjs（纯代码合成，定种子，同一份 spec 永远出逐字节相同的音频） - 命令行：
assets/bgm.mjs - 量片子：
assets/scripts/scan-video.mjs - 预设：
assets/presets/*.json
$SKILL 指本 skill 目录（Claude Code 下是 ~/.claude/skills/promo-bgm）。
0. 先确认依赖
第一次在这台机器上用之前先跑这个，别等渲到一半才发现缺东西：
node $SKILL/assets/scripts/check-deps.mjs
要 Node.js ≥ 18 和 ffmpeg（ffprobe 在同一个包里）。缺了的话这个脚本会打印当前系统
对应的安装命令，把它原样给用户，让他自己在终端里跑 —— 装包要密码，不要替他执行：
| 系统 | 装 ffmpeg |
|---|---|
| macOS | brew install ffmpeg |
| Debian / Ubuntu | sudo apt install ffmpeg |
| Fedora / Arch | sudo dnf install ffmpeg / sudo pacman -S ffmpeg |
| Windows | winget install Gyan.FFmpeg |
装完要重开一个终端再继续，PATH 才会重新加载。
用户暂时不想装 ffmpeg 也能干活：不带 --mp3 的渲染是纯 JS，照样出 wav，
只是没有响度归一化、没有 mp3、也没法量视频（改成从时间线抄帧号）。
先出 wav 让他听气质对不对，等定了再让他装 ffmpeg 做交付版本。
30 秒上手
cp $SKILL/assets/presets/bright-climb.json score.json
node $SKILL/assets/bgm.mjs score.json --print # 只看排布，不渲染
node $SKILL/assets/bgm.mjs score.json --mp3 # 出 score.wav + score.mp3
流程
1. 先问清四件事
不要一上来就渲。这四个答案决定了后面每一个参数，而且用户通常只想到第一个：
- 片子多长？有视频就直接量（第 2 步），没有就问打算做多长。
- 发到哪？决定响度目标和有没有必要出方版/短版（见
references/mastering.md）。 - 有没有旁白或人声？有 → 用
under-voice预设并在混音时做闪避，音乐不能有主旋律。 - 要什么气质？用户说不清是常态。别让他形容，报三个候选让他选，
照
references/brief.md的话术表来。
用户给了参考曲（"像 XX 那样"）也照 brief.md 拆成参数，别试图模仿具体旋律。
2. 量片子
node ~/.claude/skills/promo-bgm/assets/scripts/scan-video.mjs promo.mp4
给出时长、硬切位置、以及速度候选（哪个 bpm 能让小节线落在切点上）。 一镜到底的片子测不出切点，那就去片子的源工程里拿节拍帧号 —— 那是精确值，检测是猜的。
拿到时长和切点之后：切点秒数抄进 spec 的 accents，段落边界摆到最近的小节线上。
3. 选预设，改成这支片子的段落表
十一个预设在 assets/presets/，都是完整可渲的 spec。前八个是常规长度的气质选择：
| 预设 | 气质 | 用在什么片子上 | 音色 / 速度 |
|---|---|---|---|
bright-climb | 明亮上扬 | 默认。功能演示、产品介绍 | 木质拨弦 · 120 |
warm-minimal | 温暖克制 | 本地优先 / 隐私 / 手作感，慢镜头多 | 毛毡钢琴 · 96 |
focus-drive | 干净推进 | 开发者工具、效率产品 | 电钢 · 124 |
cinematic-swell | 电影感铺陈 | 愿景片、发布片开头 | 毛毡钢琴 + 次低音 · 84 |
playful-pop | 轻快俏皮 | 消费类产品、短视频投放 | 尼龙弦 + 摇摆 · 128 |
night-glass | 夜色高级 | 深色 UI、发布预告、开场悬念 | 钟 + 薄铺底 · 80 |
steady-proof | 稳重可信 | B2B、安全合规、金融、企业级 | 毛毡钢琴 + 拨片贝斯 · 104 |
nylon-story | 手作叙事 | 创始人故事、纪录片式、幕后花絮 | 尼龙弦、不摇摆 · 96 |
另外三个不是气质，是形态 —— 它们的段落结构本身就是为某种用法写的，别当普通预设改长度：
| 预设 | 形态 | 什么时候用 |
|---|---|---|
under-voice | 无主旋律、中频让给人声 | 有旁白、有真人说话。导出用 --lufs -20 |
open-loop | 8 小节无缝循环、不解决、无收尾 | 展台循环播放、官网 hero、等待画面 |
tight-hook | 15 秒、第一拍就有鼓、没有铺陈段 | 信息流投放、应用商店预览片、贴片广告 |
怎么挑：产品片默认 bright-climb；一燃就显得在推销的（企业级 / 安全 / 金融）用
steady-proof；要"贵"和"静"用 night-glass；有人说话一律 under-voice。
拿不准就渲两版给用户 A/B，比让他形容气质快得多。
然后按 references/arrangement.md 把段落表改成这支片子的：片子每换一个话题，配乐换一个段落。
4. 渲染，听，改
node $SKILL/assets/bgm.mjs score.json --print # 先看排布表：几点几秒进哪一段、鼓到第几档
node $SKILL/assets/bgm.mjs score.json --mp3
--print 会指出重音离小节线多远、小节数和目标时长对不对得上。先把这两件事弄干净再听。
5. 混进视频
ffmpeg -y -i promo.mp4 -i score.mp3 -map 0:v -map 1:a -c:v copy -shortest promo-scored.mp4
有旁白要闪避、要保留原片音效、要做循环版：references/video-fit.md。
两条硬规则
① 「涨」靠加声部，不靠加音量。
段落之间只差几个 dB，真正在变的是 kit（0 无 / 1 沙锤 / 2 加底鼓 / 3 加响指 / 4 十六分）
和 density（0 疏 / 1 走动 / 2 流动 / 3 密）。把 gain 从 0.6 拉到 1.0 换来的不是"更燃"，
是"更吵"。
② 重音落在画面换的那一帧上。
accents 里的秒数就是画面转折点。差半秒没人说得出哪里不对，但整支片子会显得松。
改了片子的节奏，就要回来改 accents 和段落小节数。
收尾清单
- 时长和视频完全一致（
--print报的秒数 =ffprobe报的秒数） - 重音离小节线 < 0.06s；段落切换与画面转折同帧
- 最后一小节是
ring: true，收尾和弦响到片尾，不是被淡出切断 - 目标响度对（社交平台 −14 LUFS，口播垫底 −20，见
references/mastering.md） - 用手机外放听一遍：贝斯还在不在、沙锤是不是变成了嘶嘶声
- 静音看一遍画面 —— 如果静音时信息就已经完整，配乐才是在加分而不是在补救
什么时候直接说做不了
引擎只有这些音色：木质拨弦 / 毛毡钢琴 / 尼龙弦 / 电钢 / 钟 + 贝斯三种 + 铺底两种 + 沙锤、底鼓、响指。人声、管弦、失真吉他、EDM、嘻哈、爵士即兴一律做不了。 用户要这些，如实说，建议去买授权曲（Artlist / Epidemic / Musicbed）， 或者只用这个引擎做一层垫底、主旋律用买来的。
配错了乐的推广片，比没配乐伤害大 —— 做不到就别硬凑。