@dsh-gis/dsh-video-studio-skill 0.4.0 → 0.7.2

package/skills/video-studio/scripts/webengine.py

@@ -32,6 +32,7 @@ import asyncio
 import base64
 import hashlib
 import json
+import math
 import os
 import re
 import shutil
@@ -186,6 +187,31 @@ def _format_contract(contract: dict) -> str:
                "有" if contract.get("hasFK") else "无"))
 
 
+async def page_number(page, key: str, *, default=None) -> float:
+    """读页面上的数值契约（window.DURATION / window.FPS），缺了或不是正数就给可操作报错。
+
+    v0.5 以前直接 float(await page.evaluate("window.DURATION"))：页面忘了导出 DURATION
+    时得到的是 None，报错只剩一句 "float() argument must be ... 'NoneType'"，看不出
+    是页面契约缺字段（实测 page_meta / export_cues 都会这样）。
+    default 传 None 表示必填（DURATION）；传数字表示缺省值（FPS 历史口径是 30）。
+    """
+    raw = await page.evaluate("k => window[k]", key)
+    if raw is None:
+        if default is not None:
+            return float(default)
+        raise RuntimeError(
+            "页面没有导出 window.%s（页面契约见 references/web-engine.md §3）。"
+            "index.html 里在 film.js 之前写 window.WINDOW_DURATION = 秒数，"
+            "或让模板按场景表自动推导（assets/web/film.js 的 resolveDuration）。" % key)
+    try:
+        val = float(raw)
+    except (TypeError, ValueError):
+        raise RuntimeError("页面 window.%s 不是数字：%r（必须是数字）" % (key, raw))
+    if not math.isfinite(val) or val <= 0:
+        raise RuntimeError("页面 window.%s 非法：%r（必须是正数）" % (key, raw))
+    return val
+
+
 async def open_page(pw, url, width=W, height=1080, log=False, deterministic=None,
                     ready_timeout=300_000):
     """打开页面并等到 window.ready === true，返回 (browser, page, cdp)。
@@ -279,8 +305,8 @@ async def _page_meta_async(html_path, deterministic=None):
     async with _playwright()() as pw:
         browser, page, _cdp = await open_page(pw, url, deterministic=deterministic)
         try:
-            duration = float(await page.evaluate("window.DURATION"))
-            fps = float(await page.evaluate("window.FPS || 30"))
+            duration = await page_number(page, "DURATION")
+            fps = await page_number(page, "FPS", default=FPS)
             return duration, fps
         finally:
             try:
@@ -315,7 +341,7 @@ async def _snap_async(html_path, times, out: Path, tag: str, deterministic=None)
     async with _playwright()() as pw:
         browser, page, cdp = await open_page(pw, url, W, H, deterministic=deterministic)
         try:
-            fps = float(await page.evaluate("window.FPS || 30"))
+            fps = await page_number(page, "FPS", default=FPS)
             for t in times:
                 png = await _grab(page, cdp, int(round(t * fps)))
                 path = out / ("%st%07.2f.png" % (tag, t))
@@ -353,6 +379,13 @@ def _norm_cue_list(raw, src: str) -> list:
 
 
 def _norm_events(raw) -> list:
+    """规整页面导出的视觉事件；统一打 src="web" 标记。
+
+    为什么打标记：render.py 在 engine=web 时会把 film.json / scenes.py 的 cue 与页面 cue
+    **三路合并**（三路都是合法的登记方式），但 scenes.py 的 cue 是按 PIL 时间轴算的，
+    与页面动画时间基准不同。qa_frames 的 sync_check 靠 src 判断"能不能配"，
+    否则会拿 29s PIL 时间轴上的 ui_blip 去配 12s 页面上的 ui_blip，报出假 FAIL。
+    """
     out = []
     for item in raw or []:
         if not isinstance(item, dict):
@@ -362,6 +395,7 @@ def _norm_events(raw) -> list:
             continue
         ev["t"] = round(float(ev["t"]), 3)
         ev.setdefault("kind", "misc")
+        ev.setdefault("src", "web")
         out.append(ev)
     out.sort(key=lambda e: e["t"])
     return out
@@ -378,8 +412,8 @@ async def _export_cues_async(html_path, deterministic=None) -> dict:
     async with _playwright()() as pw:
         browser, page, _cdp = await open_page(pw, url, W, H, deterministic=deterministic)
         try:
-            duration = float(await page.evaluate("window.DURATION"))
-            fps = float(await page.evaluate("window.FPS || 30"))
+            duration = await page_number(page, "DURATION")
+            fps = await page_number(page, "FPS", default=FPS)
             cues = await page.evaluate("window.getCues ? window.getCues() : []")
             events = await page.evaluate("window.getEvents ? window.getEvents() : []")
         finally:
@@ -532,17 +566,26 @@ async def _write_chunk(br: _Browser, f0: int, f1: int, dst: Path, fps: float,
     part = dst.with_name(dst.name[: -len(".mp4")] + PART_SUFFIX)
     if part.exists():
         part.unlink()
-    proc = subprocess.Popen(
-        _encoder_cmd(part, fps, crf, preset),
-        stdin=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-    )
+    # stderr 落临时文件，不用 PIPE：编码器一旦刷出超过管道缓冲（Windows 64 KB）的 stderr，
+    # 没人读就会写阻塞；而我们这边 proc.stdin.write 是**同步**阻塞调用（不交出事件循环），
+    # 两边互等就是死锁 —— asyncio.wait_for 也救不了它。临时文件没有缓冲上限，也不会堵。
+    errf = tempfile.TemporaryFile()
+    try:
+        proc = subprocess.Popen(
+            _encoder_cmd(part, fps, crf, preset),
+            stdin=subprocess.PIPE,
+            stderr=errf,
+        )
+    except BaseException:
+        errf.close()
+        raise
     try:
         for f in range(f0, f1):
             proc.stdin.write(await br.frame(f))
         proc.stdin.close()
         rc = proc.wait(timeout=300)
-        err = (proc.stderr.read() or b"").decode("utf-8", "replace")
+        errf.seek(0)
+        err = errf.read().decode("utf-8", "replace")
     except BaseException:
         try:
             proc.kill()
@@ -560,7 +603,7 @@ async def _write_chunk(br: _Browser, f0: int, f1: int, dst: Path, fps: float,
         raise
     finally:
         try:
-            proc.stderr.close()
+            errf.close()
         except Exception:
             pass
     if rc != 0:
@@ -702,7 +745,7 @@ async def _qa_text_async(html_path, t0, t1, step, deterministic=None) -> dict:
         browser, page, _cdp = await open_page(pw, url, W, H, deterministic=deterministic)
         try:
             if t1 is None:
-                t1 = float(await page.evaluate("window.DURATION"))
+                t1 = await page_number(page, "DURATION")
             result = await page.evaluate(
                 "([a, b, c]) => window.qaText(a, b, c)", [float(t0), float(t1), float(step)]
             )
@@ -1262,7 +1305,18 @@ def main(argv=None) -> int:
         return 2
 
     if args.cmd == "snap":
-        times = _parse_times(args.times)
+        try:
+            times = _parse_times(args.times)
+        except ValueError:
+            print("[错误] --times 里有不是数字的项：%r（要逗号分隔的秒数，如 3,9.5,13）"
+                  % (args.times,), flush=True)
+            return 2
+        if args.every is not None and float(args.every) <= 0:
+            # 以前 --every 0 被当成"没写"、--every -1 则是死循环：先 page_meta 开一次浏览器，
+            # 之后 while k <= end 永远成立，times 一路追加到内存爆掉（实测 40 s 都出不来）。
+            print("[错误] --every 必须是正数秒（当前 %r）；不想等间隔采样就别传 --every" % (args.every,),
+                  flush=True)
+            return 2
         if args.every:
             end = args.t_to if args.t_to is not None else page_meta(args.html)[0]
             k = float(args.t_from)

package/tools/audio_similarity.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""audio_similarity.py — 配乐/音效同质化诊断 + 音频改造验收（只读，不产片）。
+
+用法：
+    python tools/audio_similarity.py                 # 打印 4 组对照
+    python tools/audio_similarity.py --strict        # 额外按契约阈值判定，失败 exit 1
+    python tools/audio_similarity.py --out dir/      # 把对照样本写成 wav 便于人耳试听
+
+四组对照（阈值来自 skills/video-studio/references/audio-variation.md §5）：
+
+    A 跨片配乐（v0.7）：同风格/同 bpm/同调、只换内容指纹 -> 相关性（目标 <= 0.85）；
+                换风格 -> 相关性（目标 <= 0.52，且不能比改造前更接近）
+    B 跨片音效（v0.7）：同 cue 序列，legacy（不传 style/content_fp）必须逐样本相同；
+                不同 content_fp 必须不同（否则"跨片音效都一样"没被修掉）
+    C 片内分离（v0.7）：duck 默认深度（目标 >= 3.5 dB）与配乐/音效的频谱质心对照
+    D 旁白优先（v0.7.1）：人声段 旁白/背景 响度差（目标 >= 12 dB）+ 侧链让位 >= 4 dB
+
+本脚本在改造前是"诊断工具"，改造后是"验收工具"：--strict 会逐条对阈值判定。
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+import numpy as np
+
+HERE = Path(__file__).resolve().parent
+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_C_DUCK_MIN = 3.5             # duck 默认深度下限（dB）
+THRESH_D_SNR_MIN = 12.0             # 人声段 旁白/背景 响度差下限（dB）
+
+FAILS = []
+
+
+def _ok(name, cond, detail):
+    print("   [%s] %s  %s" % ("PASS" if cond else "FAIL", name, detail))
+    if not cond:
+        FAILS.append("%s: %s" % (name, detail))
+
+
+def _fmt_db(v):
+    """dB 值格式化：NaN（无可判定区间）打印成 'n/a' 而不是让 %f 抛 TypeError。"""
+    try:
+        v = float(v)
+    except (TypeError, ValueError):
+        return "n/a"
+    return "n/a" if v != v else ("%.1f" % v)
+
+
+def _rms(x):
+    a = np.asarray(x, dtype=np.float64)
+    return float(np.sqrt(np.mean(np.square(a)))) if a.size else 0.0
+
+
+def _corr(x, y):
+    x = np.asarray(x, dtype=np.float64)
+    y = np.asarray(y, dtype=np.float64)
+    if x.ndim == 2:
+        x = x.mean(axis=1)
+    if y.ndim == 2:
+        y = y.mean(axis=1)
+    n = min(len(x), len(y))
+    x, y = x[:n], y[:n]
+    if n == 0:
+        return float("nan")
+    sx, sy = float(np.std(x)), float(np.std(y))
+    if sx <= 1e-12 or sy <= 1e-12:
+        # 常量/全静音信号：相关系数没有定义。旧实现返回 0，于是"配乐渲染成静音"这种
+        # 最严重的回归会让 A1/A2 反而判 PASS（0 <= 0.85）。
+        return float("nan")
+    return float(np.mean((x - x.mean()) * (y - y.mean())) / (sx * sy))
+
+
+def _centroid_hz(x, sr=48000):
+    x = np.asarray(x, dtype=np.float64)
+    if x.ndim == 2:
+        x = x.mean(axis=1)
+    spec = np.abs(np.fft.rfft(x))
+    freqs = np.fft.rfftfreq(len(x), 1.0 / sr)
+    return float((spec * freqs).sum() / (spec.sum() + 1e-12))
+
+
+def _utf8_stdio():
+    for st in (sys.stdout, sys.stderr):
+        try:
+            if st is not None and not st.isatty():
+                st.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:                                   # noqa: BLE001
+            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)
+    return samples
+
+
+def _cue_track(content_fp=None, style=None, key=None):
+    import filmkit as K
+    scenes = [{"id": "l01", "kind": "hook", "start": 0.0, "end": 2.0},
+              {"id": "l02", "kind": "body", "start": 2.0, "end": 6.0}]
+    rows = [{"at": "l02", "type": "ui_click"}, {"at": "l02+0.5", "type": "whoosh"}]
+    bus = K.CueBus(scenes=scenes, total=6.0)
+    bus.extend(rows)
+    return bus.build_audio(total=6.0, verbose=False, style=style,
+                           content_fp=content_fp, key=key)
+
+
+def _voice_priority_snr(sr=48000, guard_snr_db=12.0):
+    """量"人声比背景响多少"：用真实 scorekit 配乐 + 类人声，按 st_audio 的默认参数混音。
+
+    返回 (人声活跃区 SNR dB, 间隙背景 RMS, 人声处背景额外让位 dB)。
+    口径与 `filmkit.voice_snr` 一致：只统计人声活跃区（含间隙会稀释问题）。
+
+    guard_snr_db 默认 12（= st_audio 默认，量"最终交付"的 SNR）；测"侧链本身让位多少"
+    时传 0 关掉兜底——否则兜底的整体补压会被算成侧链效果，D2 在侧链被删掉时也能过。
+    """
+    import filmkit as K
+    import numpy as np
+    import scorekit as SK
+    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")
+    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,
+                     guard_snr_db=float(guard_snr_db), verbose=False)
+    v2 = np.stack([voice, voice], axis=1)
+    bg = out - v2
+    snr = K.voice_snr(voice.astype(np.float32), bg)
+    gap = slice(int(2.8 * sr), int(3.2 * sr))
+    gap_rms = float(np.sqrt(np.mean(bg[gap] ** 2)))
+    # 人声处背景相对"未压背景"的额外让位：未压背景 = music * 10^(-12/20)
+    base_bg = music * 10 ** (-12.0 / 20.0)
+    b_talk = slice(int(0.5 * sr), int(2.2 * sr))
+    duck_eff = 20 * np.log10((float(np.sqrt(np.mean(base_bg[b_talk] ** 2))) + 1e-12) /
+                             (float(np.sqrt(np.mean(bg[b_talk] ** 2))) + 1e-12))
+    return snr, gap_rms, duck_eff
+
+
+def _duck_default():
+    src = (SCRIPTS / "render.py").read_text(encoding="utf-8")
+    m = re.search(r"duck_default\s*=\s*([0-9.]+)", src)
+    return float(m.group(1)) if m else float("nan")
+
+
+def main(argv=None):
+    _utf8_stdio()
+    ap = argparse.ArgumentParser(description="配乐/音效相似度诊断（v0.7 验收）")
+    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")
+    args = ap.parse_args(argv)
+
+    import sfxkit as SX
+
+    print("=" * 72)
+    print("A. 跨片配乐（差异来源 = 风格 / bpm / 调 / 内容指纹 / seed）")
+    print("=" * 72)
+    a1 = _music(args.dur, "tech-deep", "content-a")
+    a2 = _music(args.dur, "tech-deep", "content-b")
+    a3 = _music(args.dur, "magazine", "content-a")
+    a4 = _music(args.dur, "tech-deep", "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）"
+          % (same_style, THRESH_A_SAME_STYLE_MAX))
+    print("  换风格（tech-deep -> 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,
+            "corr=%.3f" % same_style)
+        _ok("A2 换风格更不像", cross_style <= THRESH_A_CROSS_STYLE_MAX,
+            "corr=%.3f" % cross_style)
+        _ok("A3 配乐可复现", bool(np.array_equal(a1, a4)), "同指纹逐样本一致")
+
+    print()
+    print("=" * 72)
+    print("B. 跨片音效（CueBus 内容派生 seed）")
+    print("=" * 72)
+    b_legacy1, b_legacy2 = _cue_track(), _cue_track()
+    b_new_a = _cue_track("aaaa1111", "tech-deep", "Dm")
+    b_new_b = _cue_track("bbbb2222", "tech-deep", "Dm")
+    b_new_a2 = _cue_track("aaaa1111", "tech-deep", "Dm")
+    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("  不同内容指纹 -> 音效轨不同      : %s  （必须 True）" % cross_diff)
+    print("  同内容指纹两次相同              : %s  （必须 True，可复现）" % repeat_same)
+    if args.strict:
+        _ok("B1 legacy 逐样本兼容", legacy_same, "两次渲染相同")
+        _ok("B2 跨片音效可区分", cross_diff, "不同 content_fp 不再逐样本相同")
+        _ok("B3 音效可复现", repeat_same, "同 content_fp 逐样本一致")
+
+    print()
+    print("=" * 72)
+    print("C. 片内分离：混音 duck 深度 + 频谱质心对照")
+    print("=" * 72)
+    duck = _duck_default()
+    print("  duck 默认深度                   : %.1f dB  （目标 >= %.1f）"
+          % (duck, THRESH_C_DUCK_MIN))
+    for name, x in (("impact", SX.render("impact", seed=1000)),
+                    ("whoosh", SX.render("whoosh", seed=1000)),
+                    ("riser", SX.render("riser", seed=1000)),
+                    ("music(前4s)", a1[: 48000 * 4])):
+        print("  %-12s 频谱质心 ~ %6.0f Hz" % (name, _centroid_hz(x)))
+    print("  提示音调性跟随：in_key 现在接受 key=（配乐调性），不再硬编码 Dm。")
+    if args.strict:
+        _ok("C1 duck 加深", duck >= THRESH_C_DUCK_MIN, "duck=%.1f dB" % duck)
+
+    print()
+    print("=" * 72)
+    print("D. 旁白优先：人声与背景的响度差（v0.7.1）")
+    print("=" * 72)
+    snr_db, base_db, _duck_with_guard = _voice_priority_snr()
+    # 侧链让位单独量一次（guard_snr_db=0）：兜底的整体补压也是"背景变低"，
+    # 混在一起算会把 D2 变成"guard 生效"的证据，侧链被删掉时 D2 照样 PASS。
+    _snr_no_guard, _gap_no_guard, duck_db_eff = _voice_priority_snr(guard_snr_db=0.0)
+    print("  人声段 旁白/背景 响度差       : %s dB  （目标 >= %.1f，含 guard 兜底）"
+          % (_fmt_db(snr_db), THRESH_D_SNR_MIN))
+    print("  人声处背景额外让位             : %s dB  （目标 >= 4，仅侧链，guard 关）"
+          % _fmt_db(duck_db_eff))
+    print("  间隙里背景电平                 : %.3f（应为恢复后的基线）" % base_db)
+    if args.strict:
+        _ok("D1 旁白听得清", snr_db is not None and snr_db == snr_db
+            and snr_db >= THRESH_D_SNR_MIN, "SNR=%s dB" % _fmt_db(snr_db))
+        _ok("D2 旁白侧链生效", duck_db_eff >= 4.0, "让位 %s dB" % _fmt_db(duck_db_eff))
+
+    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)
+        for t in ("whoosh", "riser", "impact"):
+            SX.save(out / ("sfx_%s.wav" % t), SX.render(t, seed=1000))
+        print("\n对照样本已写入: %s" % out)
+
+    if args.strict:
+        print()
+        if FAILS:
+            print("STRICT FAIL: %d 项未达标" % len(FAILS))
+            for f in FAILS:
+                print("  - %s" % f)
+            return 1
+        print("STRICT PASS: 全部阈值达标（A/B/C/D 四组）")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())