@dsh-gis/dsh-video-studio-skill 0.6.0 → 0.8.1

package/skills/video-studio/references/audio-variation.md

@@ -0,0 +1,159 @@
+# 音频多样性改造（v0.7）—— 接口契约
+
+> 起草：lead，2026-11-09。本文件是本次改造的**唯一定义源**。
+> 三路并行改动的文件写域不重叠，但**接口必须按本文件逐字实现**，否则集成会失败。
+> 诊断证据见 `tools/audio_similarity.py` 的输出（改完后必须重跑，阈值见 §5）。
+
+## 1. 要解决的两个问题（都有实测数据）
+
+| 问题 | 实测 | 根因 |
+|---|---|---|
+| A. 跨视频配乐雷同 | 同风格/同 bpm/同调、只换内容指纹：corr **0.966** | 指纹只改 seed（音色细节），和弦进行/动机/鼓型/段落骨架全固定 |
+| B. 跨视频音效雷同 | 同 cue 序列两次渲染逐样本相同 | `CueBus.build_audio` seed = `seed_base + i`，只跟 cue 顺序有关 |
+| C. 片内配乐与音效难分 | impact 质心 1001 Hz / whoosh 1589 Hz / music 5451 Hz；提示音硬编码 Dm 五声 | 提示音调性硬编码 + 配乐过门与 sfx 轨同边界同频段 + duck 仅 2.5–4.5 dB |
+
+## 2. 改动总览（按写域分三路）
+
+| 路 | 负责文件 | 改什么 |
+|---|---|---|
+| A 配乐变奏 | `skills/video-studio/scripts/scorekit.py` | 指纹参与**和声/动机/鼓型/结构**，不再只影响音色细节 |
+| B 音效差异化 | `skills/video-studio/scripts/sfxkit.py`、`assets/scenes.py`、`assets/film.json` | `in_key` 跟随配乐调性；`cues()` 按画面内容生成；模板 cue 去固定化 |
+| C 接线与混音 | `skills/video-studio/scripts/filmkit.py`（lead）、`render.py`（lead）、`stylekit.py`（只读）、`selfcheck.py`（lead） | CueBus 内容派生 seed、调性传给 sfxkit、duck 加深、风格过门避让 |
+
+**写域规则**：A 路只改 scorekit.py；B 路只改 sfxkit.py / assets/scenes.py / assets/film.json；
+C 路由 lead 改 filmkit.py / render.py / selfcheck.py。**任何一路不得改别人的文件**（包括顺手"优化"）。
+
+## 3. 接口契约（逐字实现，向后兼容）
+
+### 3.1 sfxkit（B 路）
+
+```python
+# 1) 调性跟随：新增 key 参数，默认 None = 旧行为（Dm 五声）
+def in_key(freq: float, key: str | None = None) -> float:
+    """key=None -> 旧行为（硬编码 D 小调五声，逐样本兼容）。
+    key 给 "Dm"/"C"/"Am"/... -> 吸附到该调（小调用自然小调五声，大调用大调五声）。"""
+
+# 2) 所有走 in_key 的配方接受 key（通过 **kw 透传，签名末位加 key=None 或直接从 kw 取）：
+#    ui_blip / answer_chime / text_stream(voice="tone") / data_chirp / roulette_tick
+#    未知调名必须 raise ValueError（不静默降级，与 _enum 同口径）。
+
+# 3) 内容派生 seed 的辅助函数（供 filmkit.CueBus 用）
+def content_seed(base: int, style: str, content_fp: str, recipe: str, t: float) -> int:
+    """稳定的 32 位非负 int：sha1(\"v0.7|%d|%s|%s|%s|%.3f\") -> int(h[:8],16)%9000+1000。"""
+```
+
+### 3.2 filmkit.CueBus.build_audio（C 路，lead）
+
+```python
+def build_audio(self, total=None, sr=SR, base_db=None, default_gain_db=0.0,
+                seed_base=1000, verbose=True,
+                style=None,           # 风格 id；None = 旧行为
+                content_fp=None,      # 内容指纹 full；None = 旧行为
+                key=None):            # 配乐调性；None = 旧行为（sfxkit 用 Dm）
+    """每条 cue 的 seed：
+       - style/content_fp 任一为 None -> seed = seed_base + i（旧路径，逐样本兼容）
+       - 都给 -> seed = sfxkit.content_seed(seed_base, style, content_fp, kind, t)
+    并把 key 透传给配方（render(kind, seed=..., key=key, **params)）。"""
+```
+
+### 3.3 scorekit.render_styled（A 路）
+
+签名不变。**内部**行为变化：
+
+- `full` 指纹（已有 `fingerprint` 参数，当前只用于 seed）必须影响**和声与动机**：
+  - 和弦替换：按指纹从该风格的 `progressions` 里选 tier，再对**每两小节**做一次稳定替换
+    （从同大小的替代级数集里挑：i↔i7 / VI↔VI7 / III↔III7 / VII↔VII7；大调侧 I↔Imaj7 / IV↔IVmaj7）。
+    只在与乐句末/片尾规则不冲突时替换。
+  - 动机变形：`motif` 的每个 (拍, 级数, 时值) 按指纹做 **±1 级数的稳定偏移**，
+    只改级数不改节奏；问题句偏移与答句偏移必须独立派生（保证两部片子不会同步变形）。
+  - 鼓型：`drums[tier]` 的 kick 落点按指纹加 **最多一个 ghost 落点**（在 0.5 拍网格上，
+    不与现有落点重复）；clap 位置按指纹 ±0.5 拍。
+- **必须保证**：同 `fingerprint` 逐采样一致；不同 fingerprint 的相关性显著下降（§5 阈值）。
+- 新增报告字段：`variation`（dict：`{"chord_swaps": n, "motif_shifts": n, "drum_ghosts": n}`），
+  写进 work/score.json，方便审计。
+- legacy 路径（style=None）**逐字节不变**（`scorekit.py --selftest` 的第 20 条会验；
+  别和 `selfcheck.py` 的编号搞混——那边第 21 条只查 scorekit 同 seed 确定性）。
+
+### 3.4 assets/scenes.py 的 cues()（B 路）
+
+现在只出 `ui_blip × items` + `answer_chime × outro`。改为按画面事件生成，并且**类型按场景 kind 与内容变化**：
+
+- `hook`：段首 `impact`（size 按字数 0.9~1.3），落定 `riser`。
+- `body`：条目落位仍用 `ui_blip`，但 **pitch 由条目文本 sha1 派生**（json 的 items 文本）；
+  最后一个条目后加 `answer_chime`（若 kind=body 且 items≥3）；段尾 `whoosh`（going 到下一段）。
+- `quote`：`reverse_swell` + 落定 `impact`（轻）。
+- `outro`：`answer_chime` + 片尾 `sub_drop`。
+- 不许再出现"每段都一样的三连击"：同类型 cue 在一段内重复时，`gain` 必须递减（-2/-4/-6），pitch 必须不同。
+- **保持向后兼容**：仍有 `stagger` 对齐逻辑（与 _draw_items 同节拍），返回 schema 不变。
+
+### 3.5 assets/film.json 模板（B 路）
+
+模板里的 `sfx.cues` 固定三条 whoosh/riser/impact 是"跨片雷同"的直接来源之一。改为：
+
+- 模板只保留 1 条转场 whoosh 作为示例，并加注释说明"具体提示点建议交给 scenes.py 的 cues() 钩子"。
+- `sfx` 增加可选字段 `content_seed: true`（默认 true）：走内容派生 seed；显式 false 回到旧行为。
+
+## 4. render.py 接线（C 路，lead）
+
+- `st_score`：把 `plan_s["music"]["key"]` 与 `plan_s` 的 `fingerprint` 传给 sfx 阶段（经 `script["_style"]`）。
+- `st_sfx`：读 `script["_style"]`，把 `style` / `content_fp` / `key` / `sfx.content_seed` 传给
+  `bus.build_audio(...)`；没有 `_style`（legacy）时不传，保持旧行为。
+- `st_audio`：duck 默认值改为按风格：在现有表基础上整体 +1.0 dB，且 `music.duck_db` 显式值仍然优先。
+  另外新增**过门避让**：`scorekit` 的过门音效已经在 music.wav 里，sfx 轨在
+  [段落边界 - 2.2s, 边界] 区间内的 whoosh/riser/reverse_swell 需要自动 -3 dB（在 filmkit 里做，
+  或 st_sfx 后处理；由 lead 决定实现位置，**B 路不要碰**）。
+
+## 5. 验收阈值（改完必须重跑 `python <REPO>/tools/audio_similarity.py`）
+
+| 指标 | 改前 | 目标 | 落地实测（2026-11-09） |
+|---|---|---|---|
+| A 同风格换指纹 corr | 0.966 | **≤ 0.85**（仍要像同一风格，但不能像同一首） | **0.645** |
+| A 换风格 corr | 0.534 | ≤ 0.52（不能变得更像） | **0.514**（v0.7.2 复测，余量 0.006；连跑 3 次逐位相同。余量薄是有意的：抬到 0.53 就离改造前的 0.534 只剩 0.004，这条门禁就没意义了） |
+| B 同 cue 序列跨片逐样本相同 | True | **False**（不同内容指纹必须不同） | False（同 fp 仍逐样本相同） |
+| B legacy（不传 style/fp） | True | **必须仍为 True**（向后兼容） | True |
+| C duck 默认 | 2.5–4.5 dB | 3.5–5.5 dB | 4.0（mono 3.0 / cinema 5.5） |
+| D 人声段旁白/背景响度差 | 约 1.5 dB（配乐 -1.5 无侧链） | **≥ 12 dB** | **15.0 dB** |
+| D 旁白处背景额外让位 | 0 | ≥ 4 dB | 6.0 dB |
+
+> v0.7.1 追加 D 组（旁白优先）：视频以旁白为主，BGM 与音效是可选层。`mix_film` 的
+> `voice_duck_db=6` / `voice_duck_sfx_db=3` + `music.gain_db=-12` 把"人声比背景响 12 dB"
+> 从文档口号变成可执行断言（selfcheck 35/36 条 + 本脚本 D 组）。
+
+**已知边界（不是回归，是设计取舍）**：同风格不同内容指纹有约 1/3 概率落到同一个
+和弦进行档位偏移上，此时两段配乐 corr 约 0.93（只剩七和弦色彩与鼓型 ghost 的差别）。
+要再压下去需要"每段独立选档"或"同档时轮转"，会削弱"片内是一条曲子"的连贯性，
+本轮不做；`--strict` 用固定的 content-a / content-b 做验收，两者落在不同档。
+
+另有硬性回归（任何一条红都不算完成）：
+
+> 下面 1–4 的路径都按**仓库根**写（`python skills/video-studio/scripts/…`）；如果你已经 `cd` 进技能目录，
+> 去掉 `skills/video-studio/` 前缀即可。`<REPO>` = 仓库根 / 装好后的包根。
+
+1. `python skills/video-studio/scripts/selfcheck.py` 全 PASS（现在 51 条；v0.7.2 时的 43 条是旧的）。
+2. `python skills/video-studio/scripts/scorekit.py --selftest` 全 PASS。
+3. `python skills/video-studio/scripts/sfxkit.py --selftest` 全 PASS。
+4. `python <REPO>/tools/ci_check.py` 全 PASS（在包根执行）。
+5. legacy 逐样本不变：`scorekit.py --selftest` 第 20 条 + `selfcheck.py` 第 26（风格 legacy）/33（音效 legacy）条，**这些断言不要改**。
+
+## 6. 协作规则
+
+- 每个 teammate 只跑自己文件的 `--selftest`，**全量 selfcheck / ci_check 由 lead 统一跑**（避免并行抢 CPU 和临时目录）。
+- 改完在 `CHANGELOG.md` 追加的条目由 lead 统一写（teammate 不要改 CHANGELOG）。
+- 任何接口拿不准的地方，按本文件逐字实现；本文件没写的自由发挥请控制在"不改变签名"的范围内。
+- 完成后向 lead 报告：改了哪些函数、自测输出摘要、与契约的偏差（如果有）。
+
+## 7. 实现备注（落地后回填，2026-11-09）
+
+三路改动全部落盘后，实测与契约之间的**已知偏差**都记在这里（不改契约本身）：
+
+| 项 | 契约原文 | 实际实现 | 判断 |
+|---|---|---|---|
+| 配乐 tier 选择 | §3.3 只列了和弦替换/动机偏移/鼓型 ghost | 额外让指纹从 `progressions` 的 calm/body/drive 三档里选一档（该风格自带的三套进行，不发明新和弦） | 接受：单靠七和弦替换压不到 0.85，实测换 tier 后 0.966 → 0.645；仍是"同风格同一套素材" |
+| `roulette_tick` 调性 | §3.1 列进"走 in_key 的配方" | v0.6 本来没走 in_key；实现为 key=None 保持旧公式、key 非空才吸附 | 接受：不破坏 legacy 逐样本 |
+| 同段重复 cue 的 gain | §3.4 写 -2/-4/-6 | 每次再降 2 dB 不封顶（items 很多时会到 -2n） | 待观察：模板 5 条时最末一条 -8 dB；若听感偏轻改 `_cue_gain_decay` 一行 |
+| `content_seed` 实现位置 | §3.1 放 sfxkit | filmkit 与 sfxkit 各有一份逐字相同的实现（filmkit 走函数内延迟 import，模块级 from 会改导入时机） | 接受：两侧同参同值已核对；注释互相指认 |
+
+**回归基线**（改前先录、改后逐条比对）：
+
+- sfxkit 9 条渲染的 sha256（ui_blip ×3 / answer_chime / text_stream ×2 / data_chirp / roulette_tick ×2）逐条相同。
+- scorekit legacy 路径（style=None）6 s 渲染逐样本与 v0.6 相同。

package/skills/video-studio/references/audio.md

@@ -28,15 +28,17 @@ wav = bus.mix(normalize=True, fade=0.6)
 | 声道 | 单声道总线 → 双声道输出 | 旁白单声道足够 |
 | 母带响度 | **-16 LUFS ± 1** | 网络视频标准 |
 | 真峰 | **≤ -1 dBTP** | AAC 编码会推高约 0.9 dB，混流前留 1.4 dB 余量 |
-| 旁白与间隙比 | ≥ 12 dB | 人声必须明显突出 |
-| 配乐电平 | 旁白以下 12–18 dB | 否则听不清字 |
+| 旁白与间隙比 | ≥ 12 dB | 人声必须明显突出（v0.7.1 起有代码保障：`mix_film` 旁白侧链） |
+| 配乐电平 | 旁白以下 12–18 dB | 否则听不清字（v0.7.1 默认 `music.gain_db=-12`，旧版 -1.5 不合格） |
 
 ## 3. 响度链路（三步）
 
 ```python
 # 本仓库**实际**链路（filmkit.mix_film + mux）：
-#   旁白 voice_gain=1.0 居中 → 配乐 music.gain_db(默认 -1.5) → 音效按 CUE_BASE_DB 逐条
-#   → duck(3 dB) → 峰值保护 0.89 → ffmpeg loudnorm 两遍到 -16 LUFS / 目标真峰 -1.5
+#   旁白 voice_gain=1.0 居中（不被侧链动）
+#   → 音效按 CUE_BASE_DB 逐条，再按旁白包络压 3 dB
+#   → 配乐 music.gain_db(默认 -12) → 音效响时 duck(按风格 3.0–5.5) → 旁白包络再压 6 dB
+#   → 求和 → 峰值保护 0.89 → ffmpeg loudnorm 两遍到 -16 LUFS / 目标真峰 -1.5
 af = K.loudnorm_two_pass("work/audio.wav", target_i=-16.0, target_tp=-1.5)
 ```
 
@@ -185,7 +187,8 @@ print("peak:", np.max(np.abs(bus.bus)))      # 期望 < 0.99
 |---|---|---|
 | 后半段静音 | ffmpeg 多输入混流 | numpy 总线 |
 | 爆音/削波 | 先 astype 再判 dtype | 先判 dtype 再转；打印中间峰值 |
-| 听起来糊 | 配乐电平过高 | 配乐压到旁白以下 12–18 dB |
+| 听起来糊 | 配乐电平过高 | 配乐压到旁白以下 12–18 dB（v0.7.1 默认 -12 且带旁白侧链） |
+| 听不清台词 | 背景与人声响度接近 | `music.gain_db` 降到 -12、`voice_duck_db` 开 6；别用"整体拉高"救 |
 | 响度上不去 | AAC 推高真峰后限幅 | 混流前留 1.4 dB 余量 |
 | 环境音接缝咔 | 直接拼接 | 频域整周期噪声 |
 | 配音机械 | 语速超过 +15% | 降到 +6% 左右，加自然停顿 |
@@ -418,3 +421,62 @@ out.append({"at": "%s+0.3" % s["id"], "type": "text_stream",
 `sfxkit` 的算法思想改编自 `ai-history-film`（MIT）的 `sfx/` 包，实现为本项目单文件重写；
 文件头已注明出处。配方名、参数名保持与上游一致，方便对照上游文档。
 
+## 13. 片间差异与片内分离（v0.7 新增）
+
+> 完整契约与改动清单见 **references/audio-variation.md**；这里只记"怎么用、怎么验"。
+
+### 13.1 为什么 v0.5 之后还会"差不多"
+
+v0.5 的 style pack 决定的是**风格**（8 套），不是**这一部的具体样子**：
+
+- 配乐：内容指纹只进 `seed`（音色细节），和弦进行/动机/鼓型/段落骨架全固定
+  → 同风格下两段 20 s 配乐相关性 **0.966**（实测）。
+- 音效：`CueBus.build_audio` 的 seed 是 `seed_base + i`（只跟 cue 顺序）
+  → 同一批 cue 跨片逐样本相同。
+- 片内：提示音硬编码 D 小调五声、配乐过门与 sfx 转场在同一段落边界撞车、duck 只有 3 dB。
+
+### 13.2 现在怎么变
+
+| 层 | 行为 | 开关 |
+|---|---|---|
+| 配乐和声/动机/鼓型 | 内容指纹做稳定局部替换（每两小节、±1 级数、ghost 击） | `style: auto`（默认）；`seed_from_content: false` **只关 seed 派生**（音符细节不再随内容变），结构变奏照旧——`render.py` 只要不是 legacy 就把 `fingerprint` 传给 scorekit（`st_score` 里 `fp_hex` 那段）。想连结构一起回到旧行为只有不写 `style`（legacy） |
+| 音效 seed | `content_seed(base, style, fp, type, t)`，随内容变 | `sfx.content_seed`（默认 true；false = 旧 seed_base+i） |
+| 提示音调性 | `in_key(freq, key)` 跟随配乐调性 | `CueBus.build_audio(key=...)`，render.py 自动传 |
+| 段落边界 | [边界-2.2s, 边界] 内的 whoosh/riser 自动 -3 dB | `sfx.duck_transitions`（默认 true） |
+| duck | 按风格 3.0–5.5 dB（默认 4.0） | `music.duck_db` 显式覆盖 |
+
+**legacy 兼容**：不写 `style` 字段 = 全部旧行为（配乐逐样本一致、音效 seed_base+i、提示音 Dm 五声）。
+
+### 13.2.1 旁白优先（v0.7.1）
+
+视频以旁白为主，**BGM 与音效是可选层**：它们负责情绪与重音，不能抢字。具体做法：
+
+| 手段 | 默认值 | 说明 |
+|---|---|---|
+| 配乐基线 | `music.gain_db=-12` | 旧版 -1.5 时背景与台词几乎等高；-12 是"人声明显压住背景"的经验线 |
+| 旁白侧链（配乐） | `voice_duck_db=6` | 有人声的地方再压 6 dB；间隙由包络自动恢复（不会整片闷住） |
+| 旁白侧链（音效） | `voice_duck_sfx_db=3` | 提示音/转场也让人声 |
+| 语音阈值 | `voice_thresh_db=-42` / `voice_floor_db=-60` | 10 ms 块 RMS 映射成 0~1 的活动度，起音快、释放慢 |
+| 旁白自身 | `voice_gain=1.0` | **不被任何侧链影响**——旁白优先不等于"压人声" |
+| SNR 兜底 | `guard_snr_db=12` / `guard_cap_db=30` | 混音后实测人声活跃区的人声/背景差，不足就整体补压背景（只压背景） |
+
+实测（真实 edge-tts 旁白 + scorekit 配乐）：旧混音 **SNR -4.2 dB**（背景比台词还响，就是"听不清"的原因），
+新混音 **SNR 12.0 dB**；合成信号口径 15.0 dB，真实配乐素材口径 12.9 dB。
+设 `voice_duck_db=0` / `voice_duck_sfx_db=0` / `guard_snr_db=0` 可分别关掉对应机制。
+
+### 13.3 验收：别靠耳朵，跑脚本
+
+```bash
+python <REPO>/tools/audio_similarity.py --strict   # 在包根执行
+```
+
+A 组量"同风格换内容指纹"和"换风格"的相关性；B 组量"跨片音效是否还逐样本相同"（同时验
+legacy 兼容）；C 组读 `render.py` 的 duck 默认值并打印质心对照；
+D 组构造"有人声段 + 间隙"，量人声段旁白/背景响度差。任何一项不达标 exit 1。
+
+### 13.4 改音频代码后的自检清单
+
+1. `python <REPO>/tools/audio_similarity.py --strict` —— A/B/C 三组达标（在包根执行）。
+2. `python selfcheck.py` —— 51 条全 PASS（第 33 条盯 legacy 逐样本兼容，第 35–38 条盯旁白优先，第 39 条盯音频边界）。
+3. `python scorekit.py --selftest` / `python sfxkit.py --selftest` —— 各自全 PASS。
+4. 改 `assets/scenes.py` 的 `cues()` 后，跑一次 `--stage cues` 看类型分布是否覆盖 hook/body/quote/outro。

package/skills/video-studio/references/change-impact.md

@@ -37,14 +37,14 @@
 |---|---|---|
 | 改了 `text` 只重跑 `tts` | 新语音配旧时间轴 → 字幕漂移、音效错位 | 跑 `--stage explain`，按它给的最小重跑命令 |
 | 改了 `style` 只重跑 `frames` | 画风换了但配乐/声线还是旧的（或反之） | `style` 是所有下游的上游，通常整链重跑 |
-| 手工删 `work/_plan.json` 绕过指纹 | 拼接出的片子画面和旁白对不上，且**不报错** | 删 `work/segments` 整目录重渲 |
+| 手工删 `work/segments/_plan.json` 绕过指纹 | 拼接出的片子画面和旁白对不上，且**不报错** | 删 `work/segments` 整目录重渲 |
 
 ## 3. 一条命令代替这张表
 
 ```bash
 python render.py --stage explain          # 哪些阶段过时了、为什么、最小重跑命令
-python render.py --stage explain --json   # 机读（给脚本/agent 用）
 python render.py --stage qa --strict-stale  # 有过时就失败（CI / 交付前）
+python scripts/stagewatch.py --work work --json   # 机读（给脚本/agent 用；render.py 没有 --json）
 ```
 
 ## 4. 和人工签核的关系

package/skills/video-studio/references/quality-gates.md

@@ -1,7 +1,27 @@
-# 质量门禁（G0–G6）
+# 质量门禁（方法论 G0–G8）
 
 Agent 看不见画面、听不见声音，所以**验收必须脚本化 + 静帧目检**双轨。
 
+> ## ⚠ 两套编号别混用
+>
+> 本页的 `G0–G8` 是 v0.3 起的**方法论分组**（按"查什么"分类，写给写剧本/写场景的人看）。
+> `render.py` 落进 `work/gates.json` 与 `out/QC-REPORT.md` 的，是**运行时账本 id**（按"哪一步判"排）。
+> 两套编号**有重名但不同义**，看到 `G0` 先确认是哪一套：
+>
+> | 本页（方法论） | 账本 id（运行时） | 关系 |
+> |---|---|---|
+> | G0 内容门禁：上屏数字可溯源 | `G0` 渲染前资源预检（v0.8） | **同名不同义**：账本 G0 查字形/字体/TTS/web 页，不核对数字出处 |
+> | G1 帧级门禁（确定性/单帧预算/元素存在性） | — | 人工/代码评审，不进账本 |
+> | G2 静帧门禁（母版预览目检） | `signoff`（`stills` 闸） | 目检结论走人工签核 |
+> | G3 音频门禁（音效/混音/母带） | `G5` 响度/真峰 | 账本只查成片级的两个数 |
+> | G4 成片门禁（容器/时长/锐度/字幕/黑帧） | `G4` 容器 · `G5` 响度 · `G6` 锐度比 · `G7` 字幕条数 · `G8` 黑帧 | 账本把 G4 拆成 5 行 |
+> | G7 时间层门禁（闪烁/空窗/同步） | `G9` 帧级深检 | **同名不同义**：账本 G9 才是时间层 |
+> | G8 页面层门禁（web 文字重叠/出画） | web 引擎 qa_text 结果 | 只有 `--engine web` 才有 |
+> | — | `G10` 词级时间戳 · `G11` VMAF/SSIM · `G12` ASR 回读 | **v0.8 新增**，详见 [v08-quality.md](v08-quality.md) 与 [word-timeline.md](word-timeline.md) |
+>
+> 一句话记法：**本页 G0–G8 是"查什么"，账本 G0 + G4–G12 是"哪一行判"**。
+> 账本里**没有** `G1`/`G2`/`G3`：`G0` 之后直接从 `G4` 开始（容器），人工目检走 `signoff` 的 `stills` 闸，不进 gate matrix。
+
 ## G0 内容门禁：上屏数字可溯源
 
 | 判据 | 做法 |
@@ -61,7 +81,9 @@ pr = K.probe(film); f = pr["format"]
 # 容器
 assert f["duration"] > 0
 v = [s for s in pr["streams"] if s["codec_type"] == "video"][0]
-assert (v["width"], v["height"]) == (W, H)
+# v0.8：比的是**交付规格**不是内部构图。qa_report(expect_w=, expect_h=, expect_fps=) 会从
+# timeline.json 的 video 块取期望值；缺省回落 1920x1080@30（老项目行为不变）。
+assert (v["width"], v["height"]) == (W, H)   # W/H 这里代表交付宽高，不是 1920x1080 常量
 assert any(s["codec_type"] == "audio" for s in pr["streams"]), "无音轨"
 
 # 时长
@@ -221,5 +243,5 @@ python webengine.py textqa ./web/index.html --step 0.2
 信号：-16.3 LUFS / 真峰 -1.2 dBTP / 锐度比 0.94 / 黑帧 0 / 字幕 86 条 = 剧本 86 句
 时间：单帧闪烁 0 / 画面空窗 0 / 音画同步最大偏差 38 ms
 页面：文字重叠 0 / 出画 0 / 一闪而过 0 / 从没露面 0
-自检：python selfcheck.py -> PASS 29 / FAIL 0 / SKIP 0
+自检：python selfcheck.py -> PASS 51 / FAIL 0 / SKIP 0
 ```

package/skills/video-studio/references/style-packs.md

@@ -112,7 +112,9 @@ v0.4 及以前，所有"身份参数"都是模块级常量：
 | voice.jitter | 0.35 | 语速/音高微扰，0 = 关 |
 | voice.max_distinct | 3 | 全片最多几把声音 |
 | pacing.* | 风格默认 | 语前留白/语后留白/最短段长/条目落位步长 |
-| lines[].voice/tone/rate/pitch/volume/lead/tail | — | 逐句覆盖（最高优先级） |
+| lines[].persona / lines[].voice / lines[].tone | — | 逐句覆盖（最高优先级，voicekit 真的读这三个） |
+| lines[].lead | — | 逐句语前留白（filmkit.build_timeline 读） |
+| lines[].rate / pitch / volume / tail | — | **当前不生效**（保留字段）：voicekit 只认 persona/voice/tone，filmcheck 会对这三个报"未知键"；要改语速/音高请换 persona 或 tone，或在顶层写 rate/pitch/volume |
 
 ## 4. 三级指纹：改错别字不会换整首曲子
 
@@ -123,7 +125,9 @@ v0.4 及以前，所有"身份参数"都是模块级常量：
 | style | 标题（配合关键词评分破平） | 风格 id |
 
 所以：改一个错别字 -> full 变（音色纹理微变），tempo/style 不变（还是同一首曲子、同一个调）；
-换一部片 -> 三个都变。要完全锁死就写 music.seed + music.seed_from_content: false。
+换一部片 -> 三个都变。`music.seed_from_content: false` 只锁住 **seed 派生**（音色细节）；
+`full` 指纹仍会传给 scorekit 参与结构变奏（和弦替换/动机偏移/鼓型 ghost，见
+[audio-variation.md](audio-variation.md) §3.3）。要把声音完全锁回 v0.4 行为，只能不写 `style`（legacy）。
 
 ## 5. 片内变化：整体是一套，但每段有呼吸
 
@@ -173,6 +177,6 @@ stylekit.theme_lint(theme) 在 --stage style 就拦，不用等渲完 300 帧：
 |---|---|---|
 | 画面换了、配乐还是老的 | 只改了 visual.theme 没改 music.style | 直接改 style，或两个都写 |
 | 同一部片前后像两部片 | 段界跨了明暗族 | 用同族主题；或拆成两部 |
-| 改台词后配乐变了 | 改了标题或 kind 结构 -> tempo 指纹变 | 写死 music.key/music.bpm，或 seed_from_content:false |
+| 改台词后配乐变了 | 改了标题或 kind 结构 -> tempo 指纹变（BPM/调性跟着换） | 写死 music.key / music.bpm（`seed_from_content:false` 只管音色 seed，压不住 BPM/调性变化） |
 | 旁白听感像广播剧 | max_distinct 太大 / 相邻句频繁换人 | 降到 2，靠 tone 而不是换人做变化 |
 | 字幕在浅色主题上看不清 | 用了 v0.4 的黑底白字 | 传 theme= 给 draw_subtitle（render.py 已自动传） |

package/skills/video-studio/references/v08-quality.md

@@ -0,0 +1,256 @@
+# v0.8 三道新门禁：渲前预检 / 全片 VMAF / ASR 回读
+
+> 本页只讲这三个**模块**（`G0` / `G11` / `G12`）。账本里 v0.8 还有第四行 `G10` 词级时间戳，
+> 它的判据与关闭方式在 [word-timeline.md](word-timeline.md)。
+
+> 三个模块、三道账本门禁，都是**可选**的（不拷对应 .py 就记 `skipped` 并写明原因，不会让渲染失败）。
+> 三档语义沿用 v0.6：`pass` = 这次真的查了且通过；`fail` = 查了没过；
+> `skipped` = **这次没执行**——它**不等于通过**，交付时要逐项说明为什么没跑。
+
+| 模块 | 门禁 id | 什么时候跑 | 实测代价 | 关掉 |
+|---|---|---|---|---|
+| `scripts/preflight.py` | `G0` | `frames` 之前（任何 stage 开渲前） | < 1 s | `--no-preflight`（留痕，不算通过） |
+| `scripts/qavmaf.py` | `G11` | `qa` 收尾，全片逐帧 | 29 s 片 **14.2 s**（同机负载高时 28.8 s） | `--vmaf off` / `"qa": {"vmaf": {"mode": "off"}}` |
+| `scripts/qaasr.py` | `G12` | `qa` 收尾，转写成片音轨 | 29 s 片 **8.7 s**（faster-whisper small / CPU） | `"qa": {"asr": {"enabled": false}}` |
+
+---
+
+## 1. G0：渲染前资源预检（`preflight.py`）
+
+### 1.1 为什么要有它
+
+缺字形（✓ / emoji / 生僻字）和坏 TTS 音频都是"**渲染完才报**"的问题：`filmkit.glyph_missing_chars()`
+本身是准的，但它之前在 `layout` / `qa` 才被调用——等 870 帧渲完，才发现某句 `big` 里有个方块。
+preflight 不新写检测器，只把现成检测**前移**，并把结论整理成「字符 + 字段 + 句 id」：
+
+```
+[FAIL][preflight] 2 处问题（下面是前几条）：
+  - l02.big：缺字形 '✓'（字体候选里没有这个字，渲染时会画成方框）
+  - l03.sub：缺字形 '🚀'
+```
+
+### 1.2 五个检查项（三档语义，**"没查"不许写成"通过"**）
+
+| id | 查什么 | skipped 何时出现 |
+|---|---|---|
+| `script` | 剧本可解析、最小结构合法（title / lines / id 唯一 / text 非空） | 不 skip |
+| `glyphs` | 所有上屏文本逐字过 `glyph_missing_chars`；**按字段实际绘制的字重**检测（big/kicker=bold、lead=light、sub=reg+light、items=reg、text=bold+reg、title/chapter=reg） | 不 skip |
+| `tts` | `work/tts/*.mp3` **若存在**，必须能被 ffprobe 解析出音频流（坏文件/半截缓存在这里就暴露） | `work` 没给 / 还没有 TTS 产物 |
+| `fonts` | 字体候选至少一个真的能加载（对 bold / reg / light 各取一次 `filmkit.font()`） | 不 skip |
+| `web_page` | `engine="web"` 时入口页存在（`script.web.entry` 或 `<剧本目录>/web/index.html`） | pil 引擎 |
+
+> 为什么要按权重分：`msyhbd / msyh / msyhl` 是三个文件，字形覆盖不完全相同。用错权重会把
+> "只有 reg 缺、但该字段画 reg"误报成没事，或者反过来。
+
+### 1.3 单独跑 / 接 CI
+
+```bash
+python preflight.py --script film.json --work work --engine pil --json
+#   --json 时 stdout 只有 JSON，人读提示走 stderr
+#   退出码 0 = 没有 error；1 = 有 error；--strict 时 skipped 也算 error
+```
+
+它是**纯函数**：`check(script, *, work=None, engine="pil", timeline=None) -> {ok, errors, warnings, checks, engine}`，
+不打印、不落盘、不改入参。`render.py` 调 `_run_preflight`，有 error 就**在渲染前**返回非 0
+（`--no-preflight` 可通过，但会在 QC 报告"本次绕过的门禁"里留痕）。
+
+---
+
+## 2. G11：全片 VMAF / SSIM（`qavmaf.py`）
+
+### 2.1 这条门禁的关键不是阈值，是**参考帧从哪来**
+
+**参考帧必须由场景函数实时重渲染**（`scenes.draw_frame`），绝不能拿成片自己抽的帧当参考——
+那是"拿成片和成片比"，VMAF 恒等于 100，门禁形同虚设。
+
+实现路径与 `frames` 阶段同一套绘制管线：`draw_frame -> draw_subtitle -> 片头/片尾淡入淡出`，
+逐帧生成 rgb24 经 **stdin 管道**喂给 ffmpeg 的 rawvideo 输入，与成片解码流做 libvmaf / ssim 比较。
+**只渲一遍帧**：一次 ffmpeg 调用里用 `filter_complex + split` 同时算 VMAF 与 SSIM。内存恒定（不缓存整片帧序列）。
+
+### 2.2 三档语义与阈值
+
+| 档 | 条件 | 账本 |
+|---|---|---|
+| `fail` | VMAF 均值 **< 92.0**（`qavmaf.VMAF_PASS`） | G11 = fail，阻断交付 |
+| `pass` + warning | **92.0 ≤ VMAF < 96.0**（`qavmaf.VMAF_WARN`） | G11 = pass，但打印"建议复核 / 别降档" |
+| `pass` | VMAF ≥ 96.0 | G11 = pass |
+| `skipped` | 没拷 `qavmaf.py` / web 引擎（没有可重渲的参考帧）/ `--vmaf off` / 成片不存在 / 缺 timeline / 缺 filmkit / ffmpeg 无 libvmaf / 解码失败 / 比较 0 帧 | G11 = skipped，写明原因 |
+
+**SSIM 是诊断项**，低于阈值只记 warning、不单独阻断（文本画面的 SSIM 对字幕边缘过敏感，VMAF 才是感知门禁）。
+
+### 2.3 阈值 92 / 96 是怎么来的（**只有一份权威定义**）
+
+判据来自 qavmaf 作者对**同一部模板片**（参考帧含字幕与片头片尾淡入淡出）的三组实测：
+crf17 → **97.24**（pass）、crf30 → **95.74**（pass + warning）、二次编码 + 缩放坏片 → **29.45**（fail）。
+
+**阈值只有一份**：权威定义是 `qavmaf.py` 的 `VMAF_PASS=92.0` / `VMAF_WARN=96.0`
+（SSIM 0.95 / 0.98 只作诊断、不单独阻断）。`render.py` **刻意不再设第二套常量**——
+同一事实只留一个权威值，改阈值只改 `qavmaf.py` 一处。
+
+按片收紧或放宽：`film.json` 的 `"qa": {"vmaf": {"pass": 92, "warn": 96}}`（会透传给 qavmaf）。
+
+> 参考：另一份 1080p **无字幕纯测试图**的 CRF 阶梯是 96.98 / 96.32 / 94.87 / **92.25** / 83.03 / 50.23
+> （crf18 / 22 / 26 / 30 / 36 / 46）——它的 crf30 恰好压在 92 的失败线上。**素材不同不可直接比较**，
+> 所以判据以带字幕的真实成片标定为准；这也说明"crf30 附近会抖动"，交付时按片覆盖阈值或直接降一步 CRF。
+
+**门禁反证（判据必须能失败）**：
+
+| 素材 | VMAF | 判定 |
+|---|---|---|
+| crf17 正常片 | **97.24** | pass |
+| crf30 正常片（模块默认 92/96 下） | **95.74** | pass + warning（低于 warn 96） |
+| 二次编码 + 缩放坏片 | **29.45** | **fail** |
+
+也就是说：好片落在 95+、坏片直接掉到 29，中间没有灰区——阈值取 92/96（模块默认）时，
+"crf30 该提醒"和"坏片该阻断"两件事同时成立。
+
+**720p / 540p 的阈值沿用 1080p 标定**：分数不完全可比（降采样后比较分辨率变了），
+qavmaf 会在报告里打 warning 提醒这一点，但**不因此改判**——实测同片 720p VMAF 比 1080p 只低
+**0.12 分**（另一份独立素材测得 -0.22），说明"内部 1080p 构图 + 编码时 lanczos 下采样"
+确实是**超采样式降规格**，不是糊。
+
+### 2.4 分辨率：下采样合法，上采样是 fail
+
+结构性不符是 **fail**（不是"没法查"）：
+
+- 成片分辨率 **> 内部构图 1920x1080**：上采样不是合法交付（把 1080p 包装成"更高分辨率"）；
+- 宽高比不是 16:9 横屏；成片尺寸与 `timeline.video` 声明的交付尺寸不一致；读不出成片分辨率；
+- **下采样交付是合法配置**：内部构图恒 1080p，编码时 lanczos 缩到 720p / 540p。此时 qavmaf
+  **在成片分辨率下比较**——参考流在 ffmpeg 滤镜图里用 `scale=w:h:flags=lanczos` 缩到成片分辨率
+  （与 `FrameSink` 编码时同口径，不用 PIL resize），返回的 `ref_scale` 记录映射关系。
+  VMAF 阈值仍按 1080p 标定沿用（实测 720p 与 1080p 的 VMAF 差不到 3 分）。
+
+### 2.5 实测耗时与成本
+
+| 项 | 实测 |
+|---|---|
+| 29.011 s 模板片全片（870 帧，1080p 交付） | **14.2 s**（同机负载高时同一份代码测到过 28.8 s，见下"成本口径"） |
+| 720p@24 交付（696 帧） | **7.2 s**（帧数少 + libvmaf 比较分辨率低） |
+| 分项吞吐 | 参考帧渲染受 ffmpeg 消费速度限制；libvmaf threads=min(8, CPU) 时约 124–160 帧/秒（threads=0 只有约 20 帧/秒） |
+| 抽样模式 | `--vmaf sample`（每 5 帧取 1）实测 8.0 s 跑完 184 帧，VMAF 与全片差 0.34 分 |
+| 分数稳定性 | 对 n_threads **完全不敏感**（threads=0/1/4/8/16 与跨进程复跑的逐帧分数 sha1 全同） |
+
+**成本口径要说清**：全片门禁 = 参考帧渲染 + 比较，模板场景 1080p 约 **0.5× 片长**（29 s 片 14.2 s）；
+创意场景 `draw_frame` 更重（模板 6–10 ms/帧，复杂场景 30–50 ms/帧），整体按 **0.4–1× 片长** 估，
+12 分钟片按 0.4× 外推约 **5 分钟**。**同一台机器负载不同能差近 2×**（另一轮同代码实测 28.8 s），
+所以这里只写"这一跑"的数，不写承诺。纯 libvmaf 比较（参考帧已就绪）约 1.2× 实时——
+**别把"纯比较的 1.2×"当成端到端成本**。
+
+**v0.8 之后 qa 比渲染还贵**：29 s 模板片 `--stage all --cost` 实测总 **47.3 s**，
+其中 `frames` 12.5 s、`qa` 23.9 s（VMAF 14.2 + ASR 8.7 + 其余）；v0.7 的全链约 28 s。
+决策影响：**批量出片的瓶颈从渲染转到质检**——想压回渲染量级就 `--vmaf off` 或 `--vmaf sample`。
+
+### 2.6 单独跑 / 可证伪性
+
+```bash
+python qavmaf.py --film out/film.mp4 --timeline work/timeline.json \
+    --scenes scenes.py --script film.json --mode full --out work/qa/vmaf.json --json
+# 退出码：0=pass；1=fail；2=skipped（CI 必须把 2 也当"没通过"处理）
+python qavmaf.py --selftest     # 内置自检：验证三档语义不许"没查写成通过"
+```
+
+**证明它真的在查**：把 `crf` 从 18 调到 36 重渲一遍，G11 **必须**从 pass 掉进 fail。
+不掉就是参考帧/对齐环节没接对。
+
+---
+
+## 3. G12：ASR 回读（`qaasr.py`）
+
+### 3.1 为什么
+
+v0.7 及以前的质检只看"容器 / 响度 / 帧 / 音画同步"，都建立在一个假设上：
+**成片音轨里念的就是剧本那几句话**。可是 TTS 缓存串了、换声线时漏了某句、混音把某段压没了、
+重新渲了但音轨是旧的——这些从容器和波形上都看不出来。把音轨转回文字逐句对账才能发现。
+
+### 3.2 引擎优先级与匹配方式
+
+1. **faster-whisper**（本机已装，import 失败才降级）→
+2. **ffmpeg whisper 滤镜**（ffmpeg 9.0.2-full_build 带 `--enable-whisper`，实测有 whisper 滤镜、没有 asr 滤镜）→
+3. 两者都不可用 → `skipped`（**不许把"没查"写成 pass**）。
+
+匹配：按 `timeline.json` 每段 `start/end` 取 ASR 结果里落在窗口内的文本，
+去标点 / 空白 / 数字写法差异 / 常用繁体（whisper 中文输出常夹繁体）后做**字符级多重集召回**。
+- 字符级：中文没有词边界，词级召回不成立；
+- 多重集而不是集合："是"这种字重复出现要计数，否则少一句也能凑出高召回。
+
+每句还报 ASR 首字相对 `voice_start`（缺省 `start`）的偏移，`|偏移| > 0.35 s` 给 warning。
+
+### 3.3 三档语义与阈值
+
+| 档 | 条件 | 账本 |
+|---|---|---|
+| `fail` | 字符召回 **< 0.72**（`render.QA_ASR_RECALL_WARN`） | G12 = fail |
+| `pass` + warning | **0.72 ≤ 召回 < 0.85**（`render.QA_ASR_RECALL_PASS`） | G12 = pass，但提示"可能串了缓存" |
+| `pass` | 召回 ≥ 0.85 | G12 = pass |
+| `skipped` | 没拷 `qaasr.py` / `qa.asr.enabled=false` / 两个引擎都不可用 / 模型下载失败 / 成片没音轨 | G12 = skipped，写明原因 |
+
+按片覆盖：`"qa": {"asr": {"recall_pass": 0.85, "recall_warn": 0.72, "model": "small"}}`。
+
+### 3.4 为什么默认线是 0.85 而不是 0.95
+
+实测（29 s 模板片，含 "DeepSeek 4.1 Flash / DeepSeek Harness" 这类中英混排专名）：
+
+| 场景 | 召回 |
+|---|---|
+| 干净模板片 1080p（4 段全对上、缺句 0） | **0.803** |
+| 干净模板片 720p@24（同剧本） | **0.853** |
+| 干净模板片（另一轮） | **0.811 – 0.828** |
+| 丢句反证：把 l03 从音轨剪掉、timeline 仍写 3 句 | **0.677**（`missing_lines=["l03"]`、gate=fail、exit 1） |
+
+0.803–0.853 不是流水线坏了，是 ASR 对中英混排专名的正常误差——实测把 "DeepSeek 4.1 Flash"
+听成过 "DIXX4.1flash"、"DeepX Carnacy" 等变体，但 4 段**全对上、缺句 0**。
+所以这条门禁的定位是**"抓整句丢失 / 音轨不是这一版"，不是逐字校对**：
+
+- **< 0.72 才说明"整句丢了 / 音轨跟剧本不是一套"**——这是真正要阻断的；
+- 0.72–0.85 给 warning：仍然出片，但提示可能是缓存串了；
+- **≥ 0.95 会把干净的模板片判成 fail**，所以不能拿短测试片的 0.985（19.87 s 纯中文素材，
+  没有专名）当默认线。
+
+### 3.5 实测耗时
+
+| 阶段 | 实测 |
+|---|---|
+| 模型加载（small，CPU int8） | 1.99 s |
+| 转写 28.9 s 音轨 | 3.79 s（RTF ≈ 0.13） |
+| 合计（第一次实测） | **6.18 s**（`elapsed_s`） |
+| 合计（全链 `--stage all` 里） | 1080p 交付 **8.7 s** / 720p 交付 **6.4 s**（同机负载与交付时长不同） |
+| 模型体积 | 484 MB（HF 缓存 972 MB = fp16 + int8 两份），内存峰值 < 1 GB |
+| tiny 模型 | 只适合快速冒烟：加载 1.36 s、转写 0.50 s，但错字多、时间戳只到整秒 |
+
+### 3.6 两个已知限制（写下来别装看不见）
+
+1. **中英混排专名会掉召回**：这是判据本身的限制，不是片子坏了。真要更严就按片覆盖
+   `recall_pass`，但要先确认"专名被听错"和"真的丢了句"能区分开——用 `missing_lines` 定位。
+2. **偏移检查依赖 `voice_start`**：手搓的 timeline 若没有 `voice_start`，偏移会退化成"相对段 start"，
+   于是每句都多算一个 `lead`（默认 0.55 s）→ 全片报偏移 warning。`filmkit.build_timeline` 写的
+   timeline 一定带 `voice_start`，只有手搓才会缺。
+
+### 3.7 单独跑 / 可证伪性
+
+```bash
+python qaasr.py out/film.mp4 --timeline work/timeline.json --script film.json \
+    --model small --lang zh --out work/qa/asr.json
+# 退出码：0=pass；1=fail；2=skipped
+# 阈值只有一份权威：qaasr.py 的 QA_RECALL_PASS=0.85 / QA_RECALL_WARN=0.72，
+# render.py 的 G12 直接引用同一组常量（CLI 默认值与 --recall-pass/--recall-warn 同源）。
+# v0.8.0 之前 CLI 默认是 0.95/0.90，于是同一部片 render 判 pass、单独跑 CLI 判 fail——
+# 两套权威已合并，别再按旧口径传 0.95。
+python qaasr.py --selftest                    # 不联网自检
+# 离线回放（CI 用，不加载模型）：
+python qaasr.py film.mp4 --timeline ... --asr-json <已有 ASR 结果.json>
+```
+
+**证明它真的在查**：拿一条音轨把某句剪掉、timeline 不动，G12 **必须** fail（实测召回 0.677、exit 1）。
+不 fail 就是窗口/对齐没接对。
+
+---
+
+## 4. 三道门禁一起关掉会怎样
+
+`skipped` 是**合法的**（例如线上机器没装 faster-whisper、或 web 引擎路线），
+但交付前请把每一行 `skipped` 的理由抄进验收话术：**"没查"必须说出来，不能混进"通过"里**。
+`--strict-gates` 会把所有 `skipped` 升级成失败——交付流水线里建议开着它跑最后一次。
+
+另外 `<REPO>/tools/golden_frames.py` 是**像素级**金帧回归（不进门禁账本）：
+`--check` 渲 3 帧算 SHA-256 与 `assets/golden_frames.json` 比对，
+同环境像素变了 = fail，换机器（字体指纹不同）= skipped。改绘制代码后先跑它，再跑 `selfcheck.py`。