@dsh-gis/dsh-video-studio-skill 0.9.1 → 1.0.4

package/tools/audio_similarity.py

@@ -9,18 +9,20 @@
 
 四组对照（阈值来自 skills/video-studio/references/audio-variation.md §5）：
 
-    A 跨片配乐（v0.7）：同风格/同 bpm/同调、只换内容指纹 -> 相关性（目标 <= 0.85）；
-                换风格 -> 相关性（目标 <= 0.52，且不能比改造前更接近）
-    B 跨片音效（v0.7）：同 cue 序列，legacy（不传 style/content_fp）必须逐样本相同；
+    A 跨片配乐（musicgen 参数化编排）：
+                同参数/同 bpm/同调、只换内容指纹 -> 相关性（目标 <= 0.85）；
+                换编排参数（mood + 音色） -> 相关性（目标 <= 0.52）
+    B 跨片音效：同 cue 序列，legacy（不传 style/content_fp）必须逐样本相同；
                 不同 content_fp 必须不同（否则"跨片音效都一样"没被修掉）
-    C 片内分离（v0.7）：duck 默认深度（目标 >= 3.5 dB）与配乐/音效的频谱质心对照
-    D 旁白优先（v0.7.1）：人声段 旁白/背景 响度差（目标 >= 12 dB）+ 侧链让位 >= 4 dB
+    C 片内分离：duck 默认深度（目标 >= 3.5 dB）与配乐/音效的频谱质心对照
+    D 旁白优先：人声段 旁白/背景 响度差（目标 >= 12 dB）+ 侧链让位 >= 4 dB
 
-本脚本在改造前是"诊断工具"，改造后是"验收工具"：--strict 会逐条对阈值判定。
+两种用法：不带 --strict 是诊断（打印对照数值），--strict 是验收（逐条对阈值判定，失败 exit 1）。
 """
 from __future__ import annotations
 
 import argparse
+import hashlib
 import re
 import sys
 from pathlib import Path
@@ -32,12 +34,12 @@ SCRIPTS = HERE.parent / "skills" / "video-studio" / "scripts"
 sys.path.insert(0, str(SCRIPTS))
 
 # 契约 §5 的阈值（改契约时两边一起改）
-THRESH_A_SAME_STYLE_MAX = 0.85      # 同风格、只换内容指纹的相关性上限
-THRESH_A_CROSS_STYLE_MAX = 0.52     # 换风格的相关性上限（改造前 0.534）
-# 实测余量提示（v0.7.2）：本机稳定测到 0.514（连跑 3 次逐位相同），离阈值只剩 0.006。
-# 这个生成链是确定性的，所以换平台/换 numpy 若把 0.514 推到 0.52 以上，
-# 更可能是「风格差异化真的缩水了」而不是浮点噪声 —— 请先查 scorekit 的变奏参数，
-# 别第一反应去抬阈值（抬到 0.53 就离改造前 0.534 只剩 0.004，等于这条门禁白设）。
+THRESH_A_SAME_STYLE_MAX = 0.85      # 同参数、只换内容指纹的相关性上限
+THRESH_A_CROSS_STYLE_MAX = 0.52     # 换编排参数的相关性上限（改造前实测 0.534，抬到 0.53 门禁就没意义了）
+# 配乐由 musicgen 参数化编排，这两条阈值是「跨片不能太像」的验收线：
+# 同参数换指纹要 <=0.85，换编排参数要 <=0.52。
+# 生成链是确定性的，换平台/换 numpy 若把实测值推过线，先查 musicgen 的参数有没有
+# 变成死旋钮，别第一反应去抬阈值。
 THRESH_C_DUCK_MIN = 3.5             # duck 默认深度下限（dB）
 THRESH_D_SNR_MIN = 12.0             # 人声段 旁白/背景 响度差下限（dB）
 
@@ -101,10 +103,35 @@ def _utf8_stdio():
             pass
 
 
-def _music(dur, style, fp):
-    import scorekit as SK
-    samples, _rep = SK.render_styled(dur, style=style, bpm=110, key="Dm",
-                                     mood="steady", seed=7, fingerprint=fp)
+def _music(dur, profile, fp):
+    """用参数化编排器现场生成一条配乐。
+
+    profile 是「一套编排参数」，对应旧版的一个 style id —— 换成 mood + 音色 + 和弦进行：
+      * "steady"    -> 稳重：pad=saw / bass=sine / arp=pluck / lead=bell
+      * "magazine"  -> 换一套色调：triangle 铺底 + bell 琶音 + hopeful
+    fp 除了派生 seed，还决定**和弦进行走哪一档**（结构层）：旧版 scorekit 的指纹会换
+    进行档，这里用同一思路 —— 否则只换 seed 时两段配乐的相关性接近 1.0，A1 门禁
+    就成了「永远通过」的假门禁。
+    """
+    import musicgen as MG
+    # 指纹 -> 两个**互相独立**的派生量：seed（音色/细节）与进行档（结构）。
+    # 早先用同一个 8 位片段同时取模，content-a / content-b 正好撞在一起（seed 与档位
+    # 全同 -> corr 恒 1.0，A1 门禁变成永远通过）。分开取片段才是真的"同一内容同一首、
+    # 换内容不像同一首"。
+    digest = hashlib.sha1(str(fp or "").encode("utf-8")).hexdigest()
+    seed = 7 + (int(digest[:12], 16) % (2 ** 31 - 1))
+    prog_idx = int(digest[12:20], 16) % 2
+    voices = {"steady": {"pad": "saw", "bass": "sine", "arp": "pluck", "lead": "bell"},
+              "magazine": {"pad": "triangle", "bass": "sine", "arp": "bell", "lead": "pluck"}}[profile]
+    progressions = [
+        {"calm": ["i", "VI", "iv", "v"], "body": ["i", "VI", "III", "VII"],
+         "drive": ["i", "VII", "VI", "V"], "climax": ["i", "VII", "VI", "V"]},
+        {"calm": ["i", "iv", "VI", "i"], "body": ["i", "III", "VII", "VI"],
+         "drive": ["i", "VI", "VII", "V"], "climax": ["i", "VI", "VII", "V"]},
+    ][prog_idx]
+    samples, _rep = MG.render(float(dur), bpm=110.0, key="Dm", scale="minor",
+                              mood="steady" if profile == "steady" else "hopeful",
+                              seed=seed, voices=voices, progressions=progressions)
     return samples
 
 
@@ -120,7 +147,7 @@ def _cue_track(content_fp=None, style=None, key=None):
 
 
 def _voice_priority_snr(sr=48000, guard_snr_db=12.0):
-    """量"人声比背景响多少"：用真实 scorekit 配乐 + 类人声，按 st_audio 的默认参数混音。
+    """量"人声比背景响多少"：用真实 musicgen 配乐 + 类人声，按 st_audio 的默认参数混音。
 
     返回 (人声活跃区 SNR dB, 间隙背景 RMS, 人声处背景额外让位 dB)。
     口径与 `filmkit.voice_snr` 一致：只统计人声活跃区（含间隙会稀释问题）。
@@ -130,16 +157,16 @@ def _voice_priority_snr(sr=48000, guard_snr_db=12.0):
     """
     import filmkit as K
     import numpy as np
-    import scorekit as SK
+    import musicgen as MG
     n = int(6.0 * sr)
     t = np.arange(n) / float(sr)
     voice = np.zeros(n, dtype=np.float64)
     for a, b in ((0.2, 2.6), (3.4, 5.8)):        # 两段"说话"，中间留间隙
         i, j = int(a * sr), int(b * sr)
         voice[i:j] = 0.12 * np.sin(2 * np.pi * 220 * t[i:j])
-    # 真实配乐（scorekit 输出 RMS 约 0.15，比"类人声"响 —— 正是需要侧链/兜底的场景）
-    music, _ = SK.render_styled(6.0, style="tech-deep", bpm=110, key="Am",
-                                mood="steady", seed=7, fingerprint="d-group")
+    # 真实配乐（musicgen 输出峰值 -6 dBFS，比"类人声"响 —— 正是需要侧链/兜底的场景）
+    music, _ = MG.render(6.0, bpm=110.0, key="Am", scale="minor",
+                         mood="steady", seed=7)
     music = np.asarray(music, dtype=np.float32)
     out = K.mix_film(voice.astype(np.float32), music, None, total=6.0, fade=0.0,
                      music_gain_db=-12.0, voice_duck_db=6.0,
@@ -165,7 +192,7 @@ def _duck_default():
 
 def main(argv=None):
     _utf8_stdio()
-    ap = argparse.ArgumentParser(description="配乐/音效相似度诊断（v0.7 验收）")
+    ap = argparse.ArgumentParser(description="配乐/音效相似度诊断与验收")
     ap.add_argument("--out", default="", help="把对照样本写成 wav 到这个目录")
     ap.add_argument("--dur", type=float, default=20.0, help="配乐对照时长（秒）")
     ap.add_argument("--strict", action="store_true", help="按契约 §5 阈值判定，失败 exit 1")
@@ -174,29 +201,29 @@ def main(argv=None):
     import sfxkit as SX
 
     print("=" * 72)
-    print("A. 跨片配乐（差异来源 = 风格 / bpm / 调 / 内容指纹 / seed）")
+    print("A. 跨片配乐（差异来源 = 编排参数 / bpm / 调 / 内容指纹 / seed）")
     print("=" * 72)
-    a1 = _music(args.dur, "tech-deep", "content-a")
-    a2 = _music(args.dur, "tech-deep", "content-b")
+    a1 = _music(args.dur, "steady", "content-a")
+    a2 = _music(args.dur, "steady", "content-b")
     a3 = _music(args.dur, "magazine", "content-a")
-    a4 = _music(args.dur, "tech-deep", "content-a")   # 同指纹复渲染，验证确定性
+    a4 = _music(args.dur, "steady", "content-a")   # 同指纹复渲染，验证确定性
     same_style = _corr(a1, a2)
     cross_style = _corr(a1, a3)
     rms_a1 = _rms(a1)
     print("  配乐非静音（RMS > -60 dBFS）    : %s  （rms=%.4f，静音时相关系数无定义）"
           % (rms_a1 > 0.001, rms_a1))
-    print("  同风格·同bpm·同调，只换内容指纹 : corr = %.3f  （目标 <= %.2f）"
+    print("  同参数·同bpm·同调，只换内容指纹 : corr = %.3f  （目标 <= %.2f）"
           % (same_style, THRESH_A_SAME_STYLE_MAX))
-    print("  换风格（tech-deep -> magazine） : corr = %.3f  （目标 <= %.2f）"
+    print("  换编排参数（steady -> magazine） : corr = %.3f  （目标 <= %.2f）"
           % (cross_style, THRESH_A_CROSS_STYLE_MAX))
     print("  同指纹两次渲染逐样本相同        : %s" % bool(np.array_equal(a1, a4)))
     if args.strict:
         # A0 是前置条件：若配乐渲染成静音/常量，A1/A2 的相关系数没有定义（NaN），
         # 必须显式判 FAIL，而不是让 NaN 比较悄悄变成 False 后只剩一句 corr=nan。
         _ok("A0 配乐非静音", rms_a1 > 0.001, "rms=%.4f" % rms_a1)
-        _ok("A1 同风格换指纹可区分", same_style <= THRESH_A_SAME_STYLE_MAX,
+        _ok("A1 同参数换指纹可区分", same_style <= THRESH_A_SAME_STYLE_MAX,
             "corr=%.3f" % same_style)
-        _ok("A2 换风格更不像", cross_style <= THRESH_A_CROSS_STYLE_MAX,
+        _ok("A2 换编排参数更不像", cross_style <= THRESH_A_CROSS_STYLE_MAX,
             "corr=%.3f" % cross_style)
         _ok("A3 配乐可复现", bool(np.array_equal(a1, a4)), "同指纹逐样本一致")
 
@@ -211,7 +238,7 @@ def main(argv=None):
     legacy_same = bool(np.array_equal(b_legacy1, b_legacy2))
     cross_diff = not bool(np.array_equal(b_new_a, b_new_b))
     repeat_same = bool(np.array_equal(b_new_a, b_new_a2))
-    print("  legacy（不传 style/fp）两次相同 : %s  （必须 True，v0.4 兼容）" % legacy_same)
+    print("  legacy（不传 style/fp）两次相同 : %s  （必须 True，逐样本兼容）" % legacy_same)
     print("  不同内容指纹 -> 音效轨不同      : %s  （必须 True）" % cross_diff)
     print("  同内容指纹两次相同              : %s  （必须 True，可复现）" % repeat_same)
     if args.strict:
@@ -237,7 +264,7 @@ def main(argv=None):
 
     print()
     print("=" * 72)
-    print("D. 旁白优先：人声与背景的响度差（v0.7.1）")
+    print("D. 旁白优先：人声与背景的响度差")
     print("=" * 72)
     snr_db, base_db, _duck_with_guard = _voice_priority_snr()
     # 侧链让位单独量一次（guard_snr_db=0）：兜底的整体补压也是"背景变低"，
@@ -256,10 +283,10 @@ def main(argv=None):
     if args.out:
         out = Path(args.out)
         out.mkdir(parents=True, exist_ok=True)
-        from scorekit import save as music_save
-        music_save(out / "music_tech_deep_a.wav", a1)
-        music_save(out / "music_tech_deep_b.wav", a2)
-        music_save(out / "music_magazine.wav", a3)
+        import musicgen as MG
+        MG.save(out / "music_steady_a.wav", a1)
+        MG.save(out / "music_steady_b.wav", a2)
+        MG.save(out / "music_magazine.wav", a3)
         for t in ("whoosh", "riser", "impact"):
             SX.save(out / ("sfx_%s.wav" % t), SX.render(t, seed=1000))
         print("\n对照样本已写入: %s" % out)
@@ -276,4 +303,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main())

package/tools/ci_check.py

@@ -4,7 +4,7 @@
 跑法：python tools/ci_check.py [-v]
 
 它检查的是**这个仓库作为"可分发的技能插件"的完整性**，而不是视频能不能出片
-（出片要靠 selfcheck.py + 真跑一遍 render.py，见 SKILL.md §14）：
+（出片要靠 selfcheck.py + 真跑一遍 render.py，见 SKILL.md §13）：
 
   1  语法：scripts/ + assets/ + tools/ 下的 .py 全部能编译（SyntaxWarning 也算失败）
   2  JS 语法：根目录与 assets/web/ 的 .js 通过 node --check
@@ -21,7 +21,7 @@
   10  CI workflow：step 名的裸冒号（会让整份 workflow 静默不跑），
      以及 run 里 python <路径>.py 指向的文件必须存在
   11  体积：单个文件不超过 400 KB（技能要能塞进上下文与包里）
-  12  film.json 契约：schemas/film.schema.json + scripts/filmcheck.py 校验模板（规则只留一份）
+  12  film.json 契约：schemas/film.schema.json + scripts/filmcheck.py 校验夹具（规则只留一份）
 
 三档结论（与技能自己的门禁账本同口径）：PASS = 这次真的查了且通过；FAIL = 查了没过；
 SKIP = **这次没执行**（比如本地没装 node / npm），**不等于通过**。
@@ -49,17 +49,23 @@ REFS = SKILL / "references"
 
 # 技能允许的三方依赖（与 README「环境前提」一一对应；加东西必须先改文档）
 ALLOWED_THIRD_PARTY = {"numpy", "PIL", "cv2", "scipy", "edge_tts", "playwright",
-                       # v0.8：ASR 回读门禁（可选，缺了 qaasr 自动降级到 ffmpeg whisper / skipped）
+                       # ASR 回读门禁（可选，缺了 qaasr 自动降级到 ffmpeg whisper / skipped）
                        "faster_whisper"}
 # 同目录同级模块（拷走整个目录后仍能互相 import）
 LOCAL_MODULES = {"filmkit", "sfxkit", "scorekit", "webengine", "qa_frames", "render", "selfcheck",
                  "stylekit", "voicekit", "scenes", "scenes_demo",
-                 # v0.6.0：门禁账本 / 交付报告 / 签核、阶段新鲜度守卫、film.json 契约校验器
+                 # 门禁账本 / 交付报告 / 签核、阶段新鲜度守卫、film.json 契约校验器
                  "gates", "stagewatch", "filmcheck",
-                 # v0.8.0：渲染前资源闸门、全片 VMAF/SSIM 门禁、ASR 回读门禁
+                 # 渲染前资源闸门、全片 VMAF/SSIM 门禁、ASR 回读门禁
                  "preflight", "qavmaf", "qaasr",
-                 # v0.9.0：场景语法（内容 -> 构图选型）。纯标准库，可被 scenes.py 反向 import
-                 "grammar"}
+                 # 场景语法（内容 -> 构图选型）。纯标准库，可被 scenes.py 反向 import
+                 "grammar",
+                 # 设计 DSL / 离线预览 / 提案器
+                 "designkit", "previewkit", "propose",
+                 # 没有 presetkit（随预设目录一起移除）；这里不能再列它，
+                 # 否则 ci_check 会去 import 一个不存在的模块
+                 # 参数化配乐编排器（不提供曲风表，按参数现场编排）
+                 "musicgen"}
 MAX_FILE_BYTES = 400 * 1024
 # 体积检查忽略的目录后缀：.team 是本地调研/自测工作区（gitignore），不随包发布；
 # 媒体文件本来就该大（样例片/参考视频），不该拿"能不能塞进上下文"的尺子量。
@@ -170,7 +176,7 @@ def t_json():
     assert not bad_badges, ("README 徽章版本 %s 与 package.json version %s 不一致"
                             % ("/".join(bad_badges), ver))
     # CHANGELOG 的第一条标题也必须是当前版本：以前只查 README 徽章，于是"发了新版本但
-    # CHANGELOG 顶部还是上一版"没人发现（历史真发生过，见 v0.7.2 的修复记录）。
+    # CHANGELOG 顶部还是上一版"没人发现（真发生过）。
     changelog = ROOT / "CHANGELOG.md"
     assert changelog.is_file(), "缺 CHANGELOG.md"
     m = re.search(r"^##\s+(\d+\.\d+\.\d+)", changelog.read_text(encoding="utf-8"), re.M)
@@ -254,8 +260,8 @@ def t_pack():
     missing = [m for m in must if m not in files]
     assert not missing, "包内缺文件：%s" % ", ".join(missing)
     # 目录部分改成**派生式**：skills/ schemas/ locale/ tools/ docs/ 下磁盘上有的（除缓存/字节码）
-    # 必须全部进包。以前这里是手写 must 列表，于是 v0.6 新增的 gates.py / stagewatch.py、
-    # v0.8 新增的 preflight.py / qavmaf.py / qaasr.py / tools/golden_frames.py 都不在列表里——
+    # 必须全部进包。手写 must 列表对新增文件天然免疫：gates.py / stagewatch.py /
+    # preflight.py / qavmaf.py / qaasr.py / tools/golden_frames.py 都曾被漏在列表外——
     # "必需文件必须在包里"这条检查对**新增文件天然免疫**，等于只保护了第一版写下的那些路径。
     shipped_dirs = ("skills", "schemas", "locale", "tools", "docs")
     on_disk = []
@@ -328,7 +334,7 @@ def t_doc_refs():
     # 第三种：带占位符的路径（<SKILL_DIR>/... 与 <REPO>/...）。ci_check 之前只认 scripts/|assets/|references/
     # 前缀，SKILL.md 里 <SKILL_DIR>/../../../tools/estimate.py 这种写错两级相对层级的命令一直没人查——
     # 实测它指向仓库上一级，是条**跑不通的命令**。语义：<SKILL_DIR> = skills/video-studio/，
-    # <REPO> = 包根（仓库根）。注意**不能**把它们当成"当前工作目录"：quickstart 把技能拷进 myfilm/ 后，
+    # <REPO> = 包根（仓库根）。注意**不能**把它们当成"当前工作目录"：把技能解到 myfilm/ 下面后，
     # 那里的 skills 与 tools 都不存在，但文档里的占位符指的是包内位置，仍然应当成立。
     ph_bad = []
     ph_re = re.compile(r"(<SKILL_DIR>|<REPO>)/([A-Za-z0-9_.\-/{}*]+)")
@@ -441,7 +447,7 @@ def t_py39():
 def t_md_fences():
     """每篇 .md 的代码围栏必须成对（按围栏状态机判，不是数出现次数）。
 
-    v0.7.1 之前这里写的是 startswith("\\`\\`\\`")——那是一个无效转义，Python 把反斜杠原样保留，
+    早期这里写的是 startswith("\\`\\`\\`")——那是一个无效转义，Python 把反斜杠原样保留，
     于是永远匹配不到真实的 ``` 行，检查恒过（"看着在查，其实查不出"，正是本仓库最怕的形态）。
     现在改成状态机：开围栏记下字符与长度，闭合围栏必须同字符、长度不小于开口、且不带信息串。
     """
@@ -532,9 +538,9 @@ def t_film_contract():
                        cwd=str(scripts), capture_output=True, text=True,
                        encoding="utf-8", errors="replace", timeout=120)
     out = (p.stdout or "") + (p.stderr or "")
-    assert p.returncode == 0, ("模板 film.json 没过契约校验（exit=%d）：\n%s"
+    assert p.returncode == 0, ("夹具 film.json 没过契约校验（exit=%d）：\n%s"
                                % (p.returncode, out.strip()[-600:]))
-    return "模板 film.json 通过契约校验；schema %d 字节" % len(schema.read_text(encoding="utf-8"))
+    return "夹具 film.json 通过契约校验；schema %d 字节" % len(schema.read_text(encoding="utf-8"))
 
 def main(argv=None) -> int:
     ap = argparse.ArgumentParser(description="仓库级体检（不需要 ffmpeg / 字体 / 网络）")

package/tools/estimate.py

@@ -40,21 +40,25 @@ import unicodedata
 from pathlib import Path
 
 # ============================================================================
-# 基准常量（v0.7.2 重新校准：换机请重测后回填，别把这里的数字当通用真理）
+# 基准常量（换机请重测后回填，别把这里的数字当通用真理）
 # ============================================================================
 
 W, H, FPS = 1920, 1080, 30          # filmkit.W/H/FPS：本项目写死，film.json 改不了
-PIL_FPS = (40.0, 80.0)              # PIL 逐帧渲染速度：中等复杂度 40–54 fps / 模板片 68–82 fps
+PIL_FPS = (40.0, 80.0)              # PIL 逐帧渲染速度：中等复杂度 40–54 fps / 夹具片 68–82 fps
 PARALLEL_EFF = 0.5                  # 分块并行的**实测效率**：2 进程只快 1.5×，不是 2×（见 CALIBRATION）
 WEB_SEC_PER_FRAME = (0.080, 0.130)  # web 引擎：Edge 无头 PNG 截图 80–130 ms/帧
 WEB_STARTUP_SEC = 6.0               # 浏览器冷启动 + CDP 连接（12 s 片 28–30 s 含启动）
 X264_FPS = 141.0                    # libx264 -preset medium -crf 17 ≈ 4.7× 实时（仅 reencode_video 用）
 TTS_SEC_PER_LINE = (2.0, 4.0)       # edge-tts：每句每 worker 的墙钟（联网，波动大）：实测 2.2 s，留到 4.0
-SCORE_REFS = ((29.0, 3.6, 6.5), (58.0, 4.5, 6.5), (389.0, 8.0, 18.0))
-#           ^ (片长 s, 耗时低, 耗时高)：前两个点是本机实测（29 s / 58 s 各 3 次），
-#             第三个点是片长外推锚点（不是本机实测），只用来保证长片不会被系统性算小
+# 配乐耗时锚点 (片长 s, 耗时低, 耗时高)。
+#
+# musicgen 实测值：30 s / 60 s / 120 s 分别 0.94 / 1.93 / 3.68 s（≈31× 实时）。
+# 参数化编排器是单遍事件合成，实测抖动也小（同参数逐采样确定，耗时只随片长线性涨）；
+# 早期逐层展开事件、多次 IIR 的配乐引擎实测 29 s 片要 3.6–6.5 s。
+# 区间仍给 0.7–1.5 系数包络：CI 机器与共享 CPU 会慢，报小了会让人以为卡住。
+SCORE_REFS = ((29.0, 0.9, 1.6), (58.0, 1.8, 3.0), (389.0, 11.5, 19.0))
 SFX_SEC_PER_CUE = 0.20              # 单条短音效 合成+落位（24 配方单次 ≤1.5 s 是上限口径）
-SFX_MIN_SEC = 0.8                   # 实测 18 条 cue 的模板片 sfx 墙钟 0.8 s（含 ffmpeg 写盘）
+SFX_MIN_SEC = 0.8                   # 实测 18 条 cue 的夹具片 sfx 墙钟 0.8 s（含 ffmpeg 写盘）
 LAYOUT_BASE, LAYOUT_PER_LINE = 0.05, 0.01  # 排轴 + srt/ass + 安全区/字形自查（实测 29 s 片 <0.15 s）
 CUES_BASE, CUES_PER_LINE = 0.05, 0.005     # 提示点落盘 + 排序（实测 29 s 片 <0.15 s）
 AUDIO_BASE, AUDIO_PER_SEC = 0.6, 0.012     # numpy 总线按采样点叠加 + 写 wav
@@ -65,12 +69,12 @@ MUX_PER_SEC = 0.045                 # 每片长秒（两遍 loudnorm 解码音
 QA_BASE_SEC = (1.0, 3.0)            # 固定开销：联系表 + 参考帧重渲染
 QA_SEC_PER_SEC = (0.12, 0.25)       # 随片长：帧级深检流式解码 + 响度曲线
 UNMEASURED_BAND = 0.30              # 没有实测的阶段（layout/cues/sfx/audio）给 ±30% 的区间，别假装精确
-# v0.8 G11（全片 VMAF/SSIM）：参考帧由场景函数**重渲一遍**再喂 libvmaf，成本跟帧数走、
+# G11（全片 VMAF/SSIM）：参考帧由场景函数**重渲一遍**再喂 libvmaf，成本跟帧数走、
 # 与 frames 阶段同量级。实测口径差异极大：qavmaf 作者 29 s 片 12.0 s（≈0.40× 片长）；
-# SKILL.md §12 同一部模板片 14.2 s；同机另一轮负载下 28.8 s。这里取 0.40–1.00× 片长
+# SKILL.md §12 同一部夹具片 14.2 s；同机另一轮负载下 28.8 s。这里取 0.40–1.00× 片长
 # （下限=干净机、上限=争 CPU 的长片外推），固定开销单独列 1–2 s。
-# 注：v0.7.2 那套 1.0–1.6× 的系数没有 v0.8 实测支撑，把 29 s 片算成 31–50 s（实际 12–29 s），
-# 预演总量因此系统性偏大近 2 倍——这类"拍脑袋的悲观系数"比低估更糟：排期会按假的数字走。
+# 注：1.0–1.6× 这类没有实测支撑的系数会把 29 s 片算成 31–50 s（实际 12–29 s），
+# 预演总量系统性偏大近 2 倍——"拍脑袋的悲观系数"比低估更糟：排期会按假的数字走。
 VMAF_BASE_SEC = (1.0, 2.0)          # 起渲染进程 + 参考帧管线搭建
 VMAF_SEC_PER_SEC = (0.40, 1.00)     # 每片长秒（参考帧重渲 + libvmaf 逐帧比）
 
@@ -80,8 +84,8 @@ CALIBRATION = dict(
              "SKILL.md §12 记录的作者机是 Ryzen AI 9 HX 370 / 12C24T / Radeon 890M"
              "（是否同一台未核实，只保证这些数字是在上述 24 逻辑核机器上测的）"),
     measured_at="2026-11-10",
-    sdk="video-studio v0.7.1 scripts（ffmpeg 自带 x264）",
-    film="29.011 s / 870 帧 / 模板片（assets/film.json + assets/scenes.py）",
+    sdk="video-studio scripts（ffmpeg 自带 x264）",
+    film="29.011 s / 870 帧 / 测试样片（assets/film.json + assets/scenes.py，仅用于基准校准）",
     method="render.py --stage all --jobs 2，逐 stage 取 [time] 行墙钟；同片重复 2 次",
     observed=dict(tts=2.2, layout=0.0, cues=0.0, score=6.3, sfx=0.8, audio=0.7,
                   frames=9.7, mux=1.9, qa=6.8, total=28.4),
@@ -89,14 +93,14 @@ CALIBRATION = dict(
           " score 58 s 片 4.5–5.0 s; qa 6.2–6.8 s",
 )
 CPS = 4.2                            # 每秒约 4.2 字（voicekit 校准 3.84–4.61 cps 的中位口径）
-DEFAULT_LEAD, DEFAULT_TAIL, DEFAULT_MIN_DUR = 0.62, 0.92, 3.0  # v0.5 body 基准
+DEFAULT_LEAD, DEFAULT_TAIL, DEFAULT_MIN_DUR = 0.62, 0.92, 3.0  # body 基准
 CORES = 12                           # HX 370：12C/24T；jobs > 12 不再线性加速
 TTS_BYTES_PER_LINE = 32 * 1024       # 单句 mp3 缓存（4 s 语音约 24 KB，留余量）
 WAV_BYTES_PER_SEC = 48000 * 2 * 2    # 48 kHz 立体声 PCM16 = 192 KB/s
 VIDEO_MBPS = (1.2, 3.0)              # crf17 @1080p30 图文内容（暗底大字 0.5–1 Mbps 属正常）
 AUDIO_MBPS = 0.192                   # AAC 192 kbps
 QA_DISK_BYTES = 12 * 1024 * 1024     # 联系表 + 静帧 + deep.png
-BASELINE_NOTE = ("区间来自 v0.7.2 本机实测（机型/样本见下方 calibration；"
+BASELINE_NOTE = ("区间来自本机实测（机型/样本见下方 calibration；"
                  "SKILL.md §12 记录的作者机是 Ryzen AI 9 HX 370 / 12C24T）；换机请先重测再采信")
 
 STAGE_LABELS = {
@@ -109,7 +113,7 @@ STAGE_LABELS = {
     "frames": "逐帧渲染+编码",
     "mux": "合成成片",
     "qa": "质检+抽帧",
-    # v0.8：交付前的三道新门禁单独列（它们的成本不能藏进 qa 里）
+    # 交付前的三道门禁单独列（它们的成本不能藏进 qa 里）
     "preflight": "渲染前预检",
     "vmaf": "全片VMAF/SSIM",
     "asr": "ASR回读",
@@ -152,8 +156,9 @@ def load_script(path, as_json=False):
     """读剧本；坏输入给一句话错误（退出码 2），不甩 traceback。"""
     p = Path(path).expanduser()
     if not p.exists():
-        _die("找不到剧本 %s（--script 指到 film.json；模板在 skills/video-studio/assets/film.json）"
-             % p, as_json)
+        _die("找不到剧本 %s（--script 指向你自己的 film.json；"
+             "仓库里只有一个用于测试的样例 skills/video-studio/assets/film.json，"
+             "它不是要抄的模板）" % p, as_json)
     try:
         raw = p.read_text(encoding="utf-8")
     except OSError as e:
@@ -308,7 +313,7 @@ def score_seconds(total):
 def _speedup(jobs):
     """分块并行的**有效加速比**：不是 jobs 倍。
 
-    实测（870 帧模板片）：jobs=1 → 14.37 s、jobs=2 → 9.53 s，只有 1.51×。
+    实测（870 帧夹具片）：jobs=1 → 14.37 s、jobs=2 → 9.53 s，只有 1.51×。
     原因很实在：父进程要 spawn 子进程、每段都要重新 import scenes.py / 解析主题、
     落盘 mux 串行、磁盘写带宽争用。按 jobs 线性折算会持续低估长片（越长的片分块越多）。
     这里用 1 + (jobs-1)*PARALLEL_EFF 的线性模型：比理论值保守，实测 2 进程刚好对上。
@@ -420,7 +425,7 @@ def build_report(script_path, script, args):
         _warn("engine=%r 不认识（只能是 pil / web），按 pil 预演" % engine)
         engine = "pil"
 
-    # v0.8：画幅/帧率可以按片配置（只允许 16:9 横屏 + 下采样输出，见 filmkit.video_plan）。
+    # 画幅/帧率可以按片配置（只允许 16:9 横屏 + 下采样输出，见 filmkit.video_plan）。
     # 预演必须跟着走，否则 720p 片会被按 1080p 估帧数与磁盘。
     try:
         import sys as _sys
@@ -449,7 +454,7 @@ def build_report(script_path, script, args):
         source_note = "真实帧数：%s" % tl_path
     else:
         total, _scenes = estimate_timeline(script)
-        # v0.8：没有 timeline.json 时也必须用 film.json 的 video.fps —— 定死 30 会让
+        # 没有 timeline.json 时也必须用 film.json 的 video.fps —— 定死 30 会让
         # 24/25/50/60 fps 的片子帧数、磁盘、分块全部按 30 fps 算（24 fps 高估 25%，
         # 60 fps 低估一半），而 render.py 的 build_timeline(fps=vp["fps"]) 用的是真实值。
         fps = int(_vp["fps"])
@@ -479,7 +484,7 @@ def build_report(script_path, script, args):
     n_cues = len(sfx_cfg.get("cues") or [])
     sfx_on = bool(sfx_cfg.get("enabled", True)) and n_cues > 0
     # 配乐口径对齐 filmkit.music_plan：mode=off/none 或 enabled=false 才算关；
-    # 只有 mode=score（或没写 mode 但写了 bpm）才会真跑 scorekit。
+    # 只有 mode=score（或没写 mode 但写了 bpm）才会真跑配乐引擎（musicgen）。
     mode = str(mus.get("mode") or "").strip().lower()
     has_bpm = "bpm" in mus or "bpm" in script
     music_on = bool(mus.get("enabled", True)) and mode not in ("off", "none")
@@ -510,8 +515,8 @@ def build_report(script_path, script, args):
     mux_lo, mux_hi = mux_seconds_pair(frames, jobs_eff, total, script)
     qa_lo = max(0.5, QA_BASE_SEC[0] + total * QA_SEC_PER_SEC[0])
     qa_hi = max(qa_lo, QA_BASE_SEC[1] + total * QA_SEC_PER_SEC[1])
-    # v0.8 的三个新门禁：预检（固定小开销）、全片 VMAF/SSIM、ASR 回读。
-    # 实测口径（29.0 s 模板片）：preflight 0.4 s；VMAF full 12–29 s（0.40–1.00× 片长，
+    # 三个可选门禁：预检（固定小开销）、全片 VMAF/SSIM、ASR 回读。
+    # 实测口径（29.0 s 夹具片）：preflight 0.4 s；VMAF full 12–29 s（0.40–1.00× 片长，
     # 参考帧重渲与 libvmaf 都在里面，见 VMAF_* 常量注释）；ASR small ≈ 6–10 s。
     # 这三项全在**交付前**跑，不写进预演就等于"预演说 40 s、实际 90 s"——所以单独列 stage。
     qcfg = script.get("qa") or {}
@@ -570,7 +575,7 @@ def build_report(script_path, script, args):
         dict(stage="score", lo=score_lo, hi=score_hi, measured=bool(score_on),
              note=("以实测点 29 s≈3.6–6.3 s / 58 s≈4.5–5.0 s 为锚（--stage all 里与其它阶段争 CPU 会更慢；389 s 只是外推锚点）"
                    if score_on else
-                   ("mode=%s：不跑 scorekit（%s）"
+                   ("mode=%s：不跑配乐引擎（%s）"
                     % (mode or "-", "外部配乐/和弦床/关掉配乐")))),
         dict(stage="sfx", lo=sfx_lo, hi=sfx_hi, measured=False,
              note=("%d 条音效（实测 18 条 0.8 s；单条上限口径 ≤1.5 s，长环境声 wind/rain 另计）"
@@ -624,7 +629,7 @@ def build_report(script_path, script, args):
         "source": source,
         "source_note": source_note,
         "video": {"title": script.get("title"),
-                  # v0.8：内部构图恒为 1080p，交付尺寸可以更小（_vp 从 film.json 的 video 块来）
+                  # 内部构图恒为 1080p，交付尺寸可以更小（_vp 从 film.json 的 video 块来）
                   "width": _vp["w"], "height": _vp["h"],
                   "out_width": _vp["out_w"], "out_height": _vp["out_h"],
                   "fps": fps, "frames": frames,
@@ -654,8 +659,8 @@ def build_report(script_path, script, args):
                        "advice": bottleneck_advice(worst["stage"], engine, jobs_eff)},
         "assumptions": [
             "内部构图恒为 1920x1080；交付尺寸/帧率可写 film.json 的 video 块"
-            "（v0.8，只允许 16:9 横屏且只能下采样；本次按 %d fps 估）" % fps,
-            "lead=%.2f / tail=%.2f / min_dur=%.1f（v0.5 body 基准；剧本写了就以剧本为准）"
+            "（只允许 16:9 横屏且只能下采样；本次按 %d fps 估）" % fps,
+            "lead=%.2f / tail=%.2f / min_dur=%.1f（body 基准；剧本写了就以剧本为准）"
             % (DEFAULT_LEAD, DEFAULT_TAIL, DEFAULT_MIN_DUR),
             "tts 耗时按 %d 句 ÷ workers × %.1f–%.1f s（每句每 worker）；实际受网络波动影响"
             % (n, TTS_SEC_PER_LINE[0], TTS_SEC_PER_LINE[1]),
@@ -663,7 +668,7 @@ def build_report(script_path, script, args):
             % (PARALLEL_EFF, CORES),
             "mux 默认 -c:v copy，只跟片长有关；reencode_video=true 才按帧数重编",
             "layout/cues/audio/sfx 给 ±%d%% 经验区间（无单阶段实测）" % int(UNMEASURED_BAND * 100),
-            "v0.8 新增门禁口径：preflight 0.4 s 固定；vmaf ≈ %.2f–%.2f× 片长 + %.1f–%.1f s"
+            "可选门禁口径：preflight 0.4 s 固定；vmaf ≈ %.2f–%.2f× 片长 + %.1f–%.1f s"
             "（参考帧重渲染 + libvmaf；同机负载不同实测差近 2×）；asr ≈ 0.18–0.35× 片长 + "
             "3.5–6.5 s（faster-whisper small / CPU int8）"
             % (VMAF_SEC_PER_SEC[0], VMAF_SEC_PER_SEC[1], VMAF_BASE_SEC[0], VMAF_BASE_SEC[1]),
@@ -689,7 +694,7 @@ def print_report(rep):
               "会自动改用真实帧数。")
     style = v.get("style")
     if style is None:
-        style = "(没写 style 字段 = v0.4 legacy 行为)"
+        style = "(没写 style 字段 = legacy 行为)"
     print("  《%s》  片长 %.1f s / %d 帧 / %dx%d@%d / engine=%s / crf=%s preset=%s / style=%s"
           % (v.get("title") or "(未写 title)", v["duration_s"], v["frames"], v["width"], v["height"],
              v["fps"], v["engine"], v["crf"], v["preset"], style))