配乐定调（配什么、什么调性、什么速度）
适用场景
- 给成片铺一条与片子调性一致的音乐床（广告/口播/纪录/剧情/促销）
- 需要"配乐风格统一"而不是"每段随手换一首"
- 需要判断"这片子到底该不该配乐"
一、定调四问（先答完再动手）
一·〇、先读提示词（2026-09-23 新增，优先于四问）
配乐的输入源是提交渲染的原始提示词（render_scripts.md / prompt_package / 一句话 brief）。先跑：
bgmread.brief --prompt-text "夜幕下的城市霓虹，主角在雨中奔跑，结尾反转揭晓，快剪高能"
它会把提示词翻成配乐简报，四问里的答案往往已经在里面了：
| 简报字段 | 来源 | 用途 |
|---|---|---|
recipeId / genreTags | 32 题材关键词表（中英双语，如 美食/探店/food、科技/AI/tech、口播/讲解/talking head、婚礼/wedding、体育/sports）；含反例词（人文/口播文本里的"运动会"不判 sports） | 锁定配方 |
energyLevel + bpmScale | 情绪词（燃/快剪 → 高能；治愈/舒缓 → 低能；克制/高级感 → 低能） | 调 BPM 与力度 |
instrumentation.avoid | 禁忌词（不要鼓点 → 去 kick/hat；保留现场声 → 走 keep-all） | 过滤候选、定分层 |
climax.position/atSec | 高潮线索（结尾反转 → 85% 处；黄金三秒 → 8% 处；中段爆发 → 50% 处） | 选段对齐的依据 |
musicLevelDeltaDb | "音乐要轻/要突出" | 微调配乐电平（±3dB） |
noMusic | "不要背景音乐" | 直接判无需配乐（do-no-harm） |
命中不了题材时简报如实给低置信度，按明确请求和曲目元数据选配方；不分析源片声音/对白/能量品质来决定是否接受。默认 compose-only 本地取源，明确请求其他来源政策才联网。
- 题材：32 类——16 既有（产品广告/口播访谈/美食/科技/旅拍/夜景/美妆/亲子/汽车/房产/促销/纪录/高端品牌/剧情/悬疑/喜剧）+ T-15 新增（婚礼/体育/电竞/时尚/母婴/家居/新能源/财经/城市黄昏/节庆/科普/生活 vlog/情感故事/品牌宣言/宠物/健身）——决定风格族。这些题材用于请求简报与音乐候选元数据，不形成源片品质评分；按请求选一条实际方案，不试渲品质候选。
- 场景与主体：棚拍白底、室内半身、菜品特写、屏幕演示、街拍空镜……决定配器厚薄（主体越细，配器越薄）。
- 情绪目标：干净可信 / 可信亲和 / 诱人温暖 / 冷静精密 / 开阔通透 / 戏剧现代 / 通透可信 / 明亮有温度 / 强劲精密 / 明亮通透 / 热烈紧迫 / 真实克制 / 克制质感 / 情绪推进 / 不安张力 / 轻快明亮——决定调式（大调/小调/多利亚/弗里吉亚）与力度。
- 发哪个平台：抖音/小红书/视频号/B站/YouTube——决定高频是否要更亮、低频是否要更收（手机外放）。
四问答不出来的，先按 bgmread.recipes 的速查表取一条最接近的配方，再说明"为什么是它、被否掉了谁"。
二、配方库用法
bgmread.recipes --list # 当前随包配方（32 条）
bgmread.recipes --genre 美食 --mood 诱人温暖 # 定向检索
bgmread.recipes --id food # 取单条（含禁忌与备注）
配方字段与含义：
| 字段 | 含义 | 用法 |
|---|---|---|
key / mode | 调性 / 调式 | 决定"明/暗"：major 明亮、aeolian 内敛、dorian 冷静、phrygian 不安 |
bpm | 配方基准速度 | 只作基准；真实速度还要看剪辑节奏（见第三节） |
chords | 和弦级数进行 | 4 个级数循环；一/四级明亮、六级/小四级内敛 |
instrumentation | 配器 | pad（地基）/ bass（低频走向）/ pluck（推进）/ kick·hat（节拍）/ bell（点缀） |
musicLevelDb | BGM 在成片里的平均电平 | 口播 -26、广告 -22、促销 -19（数值越大越"站前台"） |
duckingDb | 人声出现时的让位深度 | 口播/纪录 13–14、广告/促销 10–12 |
avoid | 创作禁忌 | 在选型阶段过滤音乐方案；已处理成片不因此自动重做 |
三、速度决策：配方 BPM 还是剪辑点反推
卡点对不齐，九成是速度错了。两条规则：
- 剪辑节奏优先：相邻剪辑点间距 ÷ 一拍 = 整拍数，反推 BPM（
bpm_strategy=cut-driven）； 与配方 BPM 相对差 ≤25% 时采用反推值，否则沿用配方 BPM 并说明冲突。 - 同一项目只用一个速度：不要"开场 128、正片 96"，那听着像两条片子拼的。
显式剪辑点的网格参考：最近拍点误差 ≤80ms 可用于明确诊断的落拍标注；这不是默认源镜品质闸。回执记录采用 BPM 与请求网格，未测卡点达标率不能写通过，不据此自动重混。
三·二、选段：从曲子里挑"最合适的那一段"（含高潮段）
外部曲目往往 2–3 分钟，片子只有 15–60 秒——"裁哪一段"和"配什么曲子"同等重要。
bgmread.structure --in track.wav # 看结构：intro/verse/build/drop/breakdown/outro + BPM + 高潮候选
bgmwrite.mix ... --section auto # 自动选段（默认口径）
bgmwrite.mix ... --section climax # 明确要高潮段
bgmwrite.mix ... --section calm # 明确要铺垫段
bgmwrite.mix ... --section-start 62 --section-end 78 # 手工指定（秒）
选段只分析请求音乐：auto/climax/calm 使用该曲的规则式结构，显式起止按用户提供秒数执行；不计算原片对白峰值、非对白能量、嘴型或“安全窗口”。best 默认整曲/作曲方案一次混音；选段回执保留 mode/chosen/reason。
三条纪律：
- 显式起止必须有限、起点不小于 0、终点大于起点且不越曲目时长；非法参数明确失败。
- 结构识别是音乐能量分位数、走向和起音密度的规则式分段，不是乐谱或深度学习语义证明。
- 未测片子高潮、对白占比和质量余量为 null/未评审，不编造“高潮已对齐”；不按诊断自动二次加工。
四、结构（片子多长就写多长）
| 段落 | 占比 | 配器 | 作用 |
|---|---|---|---|
| 前奏 intro | ~15% | 只留 pad + bass | 不抢开场第一句话 |
| 主体 body | ~73% | 加 pluck，必要时 kick/hat | 承担推进感 |
| 尾奏 outro | ~12% | 回落到 pad | 自然收束，不做硬切 |
不用"裁歌"：外部曲目短于片长时循环铺满（工位使用实际本地循环拼接与时间轴滤镜），不靠剪断一句旋律来对齐时长。
五、创作禁忌（选型参考，用户反馈才形成新请求）
- 情绪与画面相反（婚礼片配悬疑底、悼念场景配促销节奏）；
- 一个项目混用多套配乐语言（调性/配器不一致）；
- 打击乐压在口播句读上（口播片默认不进 kick/hat）；
- 用户明确关心对白削波/底噪时单独记录意见；默认不测源声音品质、不自动分离或退回上游；
- 在"笑点/揭示/报价"这些关键信息前后加花抢注意力（该留白的地方留白）。
六、允许的结论：不配
bgmwrite.best 仅在明确 brief 要求“不要背景音乐/保留原声”时给 no_bgm_needed，保留真实源片 SHA256；不能因已有音乐、人声活动 ≥90%、底噪或无安全窗口自动决定不配。现场声为内容时，可在请求里明确不加配乐；没有这样的请求则执行所选方案一次。
默认保留完整原节目，省略分轨才走原节目路径；显式独立分轨必须真实有效，不能把原片声称为已分离对白。音源/许可/租户/当前字节失败保持明确，不静默换曲或降级。
输出契约
选型说明必须能回答四个问题：什么题材、什么场景/主体、什么情绪目标、发哪个平台， 并附：配方 id、调性/调式、BPM 及依据（配方/剪辑点反推）、配器清单、配乐电平、让位深度。
参数边界与单次执行
- BPM/电平/让位/淡入淡出按实际接口合法范围处理；请求目标不是实测质量值。
- 仅分析音乐素材以计算选段和请求增益，不测源对白/环境/响度/嘴型品质。
- 原片只读、默认原节目声音；music-only 必须明确丢弃授权，replace-bed 必须独立对白来源。
- best 按请求与音乐元数据选择一次方案，score=null；不跑源片或成片品质候选投票。
- 实际 FFmpeg/取源/许可失败明确失败，不能自动降 3dB 重试或静默改原声交付。
失败模式（症状 → 原因 → 处置）
| 症状 | 检测器/原因 | 处置 | 案例 |
|---|---|---|---|
| 请求配方或曲目不存在 | 当前曲库 ID/文件 | 指名缺件，停止；不换未知曲 | — |
| 曲目许可/签章不符 | 真实来源授权和当前 SHA256 | 授权失败，不联网换源绕过 | — |
| 用户说题材或情绪不符 | 请求简报与采用配方 | 形成明确换配方请求，不自动品质重试 | FC-BGM-001 |
| 用户说音乐太响/不够突出 | 用户反馈与请求电平 | 明确调电平/让位后新本地请求，不默认测余量判失败 | — |
| 用户要求卡点但节奏不符 | 明确 cut_points 与采用 BPM | 调整请求速度或写明选择依据，旧成片保持 | — |
| 选段越界/无法读取 | 明确起止与音乐规格 | 返回请求/工具错误，不编高潮位置 | — |
| 本地合成/混音失败 | FFmpeg stderr、输出路径 | 保存真实失败，无产物不算完成 | — |
| 原声静音/已有音乐/底噪高 | 原节目实际流 | 默认接受，不能自动不配或追加 ASR/TTS | — |
知识库引用
知识库：library/bgm-kb/ — SCORE-002 题材风格适配决策树（定调四问与配方选型依据）、SCORE-003 卡点与音乐结构（速度决策与选段对齐依据）、SCORE-006 明确不配乐请求（不配是用户意图，非自动源品质否决）、SCORE-008 常见事故案例库（错配事故的复盘入口）。检索入口：library/bgm-kb/_INDEX.md