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

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

@@ -52,6 +52,11 @@ PITCH_RE = re.compile(r"^\s*[+-]?\d+\s*Hz\s*$")
 ID_RE = re.compile(r"^[A-Za-z0-9_.\-]+$")
 
 CPS = 4.2                                   # 每秒约 4.2 字（voicekit 实测中位口径）
+# 语速区间而不是单一 4.2：voicekit 校准实测 3.84–4.61 cps（9 个 persona，固定校准句），
+# 而 stylekit 的声线策略允许的 cps_band 是 3.6–5.6（rate 覆盖 ±15% 后）。
+# 只用中位数会误报：模板片实测 5.2 字/秒的句子被按 4.2 估 -> 全片多算 5.2 s ->
+# "剧本与 timeline 差 5.23 s"的假 WARN（v0.7.2 修，模板片复现）。
+CPS_LO, CPS_HI = 3.6, 5.6
 DEFAULT_LEAD, DEFAULT_TAIL, DEFAULT_MIN_DUR = 0.62, 0.92, 3.0
 TIMELINE_TOL = 0.5                          # 估算与 timeline 差超过这个秒数就 WARN
 
@@ -286,6 +291,11 @@ SCRIPT_SPEC = {
             "seed": {"t": "int", "min": 0},
             "seed_from_content": {"t": "bool"},
             "gain_db": {"t": "num"}, "duck_db": {"t": "num"},
+            # v0.7.1 旁白优先：mix_film 读这四个（背景在人声处额外让位多少 / 阈值）
+            "voice_duck_db": {"t": "num"}, "voice_duck_sfx_db": {"t": "num"},
+            "voice_thresh_db": {"t": "num"}, "voice_floor_db": {"t": "num"},
+            # v0.7.1 SNR 兜底：混音后实测人声/背景差，不足就整体压背景
+            "guard_snr_db": {"t": "num"}, "guard_cap_db": {"t": "num"},
             "seg": {"t": "num", "min": 0.0}, "amp": {"t": "num", "min": 0.0},
             "gain": {"t": "num", "min": 0.0}, "xfade": {"t": "num", "min": 0.0},
             "chords": {"t": "list", "item": {"t": "list", "item": {"t": "num"}}},
@@ -294,6 +304,13 @@ SCRIPT_SPEC = {
             "enabled": {"t": "bool"},
             "gain_db": {"t": "num"},
             "mix_gain_db": {"t": "num"},
+            # render.py 的 st_sfx 把它透传给 CueBus.build_audio()：按配方名覆盖基础电平。
+            # 以前 schema/filmcheck 都没写，用户写了会被当未知键警告（其实真的会生效）。
+            "base_db": {"t": "dict", "open": True},
+            # v0.7 音频差异化：content_seed 由 CueBus 读（位置派生 vs 内容派生）；
+            # duck_transitions 由 render.st_sfx 读（段落边界前的转场音效自动让位）。
+            "content_seed": {"t": "bool"},
+            "duck_transitions": {"t": "bool"},
             "cues": {"t": "list", "item": CUE_SPEC}}},
         "web": {"t": "dict", "props": {
             "entry": {"t": "str"},
@@ -468,6 +485,18 @@ def check_cross(script, script_path, rep, ctx):
         ids.append(lid)
     idset = set(ids)
 
+    # ---- lines[].tail 当前不生效（保留字段）：写了会静默无效，必须说出来 ----
+    for i, ln in enumerate(lines):
+        if _f(ln.get("tail", 0.0)) > 0:
+            lid = ln.get("id") or ("l%02d" % (i + 1))
+            rep.warn("lines[%d].tail" % i, (
+                "film.json 的逐句 tail 目前**不生效**：filmkit.build_timeline 只读 "
+                "tail_map，不读 lines[].tail（渲染跑得通，但句后留白没变）。要逐句"
+                "控制句后留白，请写顶层 tail_map（形如 l03: 1.4），或交给 voicekit 的 "
+                "voice_plan（--stage tts 落 work/voice_plan.json，st_layout 会并进 "
+                "tail_map）。例如 %s: 1.4" % lid),
+                "inert_line_tail")
+
     # ---- sfx.cues[].at 引用的场景 id 必须在 lines 里 ----
     sfx = script.get("sfx") if isinstance(script.get("sfx"), dict) else {}
     cues = sfx.get("cues") if isinstance(sfx.get("cues"), list) else []
@@ -497,23 +526,63 @@ def check_cross(script, script_path, rep, ctx):
     except (OSError, ValueError, KeyError, TypeError, json.JSONDecodeError) as e:
         rep.warn(str(tl_path), "读不了 timeline（%s），跳过时长对账" % e, "timeline_unreadable")
         return
-    lead = _f(script.get("lead", DEFAULT_LEAD), DEFAULT_LEAD) or DEFAULT_LEAD
-    tail = _f(script.get("tail", DEFAULT_TAIL), DEFAULT_TAIL) or DEFAULT_TAIL
-    min_dur = _f(script.get("min_dur", DEFAULT_MIN_DUR), DEFAULT_MIN_DUR) or DEFAULT_MIN_DUR
-    ghold = _f(script.get("hold", 0.0))
-    holds, est, speech = 0.0, 0.0, 0.0
+    # 节拍覆盖的优先级与 stylekit.resolve_script_style 一致：pacing > 顶层字段 > 默认。
+    # 不读 pacing 会把"pacing.lead=2.0"当成"没写 lead"，估出来的时长偏小一半 -> 假 WARN。
+    pace = script.get("pacing") if isinstance(script.get("pacing"), dict) else {}
+
+    def _pace(key, default):
+        for box in (pace, script):
+            v = box.get(key) if isinstance(box, dict) else None
+            if v is not None:
+                return _f(v, default)
+        return float(default)
+
+    lead = _pace("lead", DEFAULT_LEAD)
+    tail = _pace("tail", DEFAULT_TAIL)
+    min_dur = _pace("min_dur", DEFAULT_MIN_DUR)
+    ghold = _pace("hold", 0.0)
+    holds, speech, est_lo, est_hi = 0.0, 0.0, 0.0, 0.0
     for ln in lines:
-        voice = _weighted_chars(ln.get("text")) / CPS
+        chars = _weighted_chars(ln.get("text"))
         hold = _f(ln.get("hold", ghold))
         holds += hold
-        speech += voice
-        est += max(min_dur, lead + voice + tail + hold)
-    if abs(est - total) > TIMELINE_TOL:
+        speech += chars / CPS
+        # 快语速 = 时长短（下界），慢语速 = 时长长（上界）
+        est_lo += max(min_dur, lead + chars / CPS_HI + tail + hold)
+        est_hi += max(min_dur, lead + chars / CPS_LO + tail + hold)
+    # bar > 0 把每段向上取整到小节倍数，total 天然比逐句估算大；这时不拿估算对账。
+    drift = 0.0
+    if not (_f(script.get("bar", 0.0)) > 0):
+        if total < est_lo - TIMELINE_TOL:
+            drift = total - est_lo
+        elif total > est_hi + TIMELINE_TOL:
+            drift = total - est_hi
+    if drift:
         rep.warn(str(tl_path),
-                 "剧本 hold 合计 %.2f s + 语音预估 %.2f s（含 lead/tail）≈ 全片 %.2f s，"
-                 "与 timeline 的 total=%.2f s 差 %.2f s > %.1f s。"
+                 "剧本 hold 合计 %.2f s + 语音预估 %.2f–%.2f s（含 lead/tail）≈ 全片 "
+                 "%.2f–%.2f s，与 timeline 的 total=%.2f s 差 %.2f s > %.1f s。"
                  "改过台词 / hold / 节奏参数就重跑 --stage layout（别拿旧时间轴直接渲）"
-                 % (holds, speech, est, total, abs(est - total), TIMELINE_TOL), "timeline_drift")
+                 % (holds, est_lo, est_hi, est_lo, est_hi, total,
+                    abs(drift), TIMELINE_TOL), "timeline_drift")
+    # 台词内容逐句对账（最可靠的一条：build_timeline 把整条 line 原样拷进 scene，
+    # 所以 timeline.scenes[i].text 就是"上次排轴时那句话"）。改过台词没重跑 layout，
+    # 这里能精确点出来；比按时长估算准得多，也不会被语速/语气差异干扰。
+    tl_by_id = {str(s.get("id")): s for s in (tl.get("scenes") or []) if isinstance(s, dict)}
+    text_drift = []
+    for ln in lines:
+        lid = ln.get("id")
+        if lid is None or not str(lid).strip():
+            continue
+        scene = tl_by_id.get(str(lid))
+        if not isinstance(scene, dict) or "text" not in scene:
+            continue                                  # 老版本 timeline 不带 text：跳过
+        if str(scene.get("text")) != str(ln.get("text")):
+            text_drift.append(str(lid))
+    if text_drift:
+        rep.warn(str(tl_path),
+                 "timeline 里 %d 句的台词与 film.json 不一致（%s）：TTS 与字幕都还是旧词，"
+                 "改完台词必须重跑 --stage tts layout 再渲"
+                 % (len(text_drift), ", ".join(text_drift[:6])), "timeline_text")
     tl_ids = [str(s.get("id")) for s in (tl.get("scenes") or []) if isinstance(s, dict)]
     if idset and tl_ids and set(tl_ids) != idset:
         miss = sorted(idset - set(tl_ids))

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

@@ -591,6 +591,12 @@ def wav_write(path, samples, sr=SR, channels=None):
     v0.3.0：支持立体声（配乐/音效要声像）。老调用 wav_write(p, mono) 行为不变。
     """
     a = np.asarray(samples, dtype=np.float32)
+    # 非有限值必须报错：旧实现 np.clip 保留 NaN/Inf，astype(int16) 把 NaN 静默写成 0、
+    # 把 Inf 写成 undefined，wav 里出现"随机哑音"且函数还返回 nan 峰值（下游只看得到 no）。
+    if a.size and not np.all(np.isfinite(a)):
+        bad = int(a.size - np.count_nonzero(np.isfinite(a)))
+        raise ValueError("wav_write: 采样里有 %d 个 NaN/Inf（%s）——上游混音/合成有数值错误，"
+                         "拒绝写出损坏的 WAV" % (bad, path))
     if a.ndim == 2:
         n_ch = a.shape[1]
         if channels is None:
@@ -722,6 +728,12 @@ class AudioBus:
         if i0 >= len(self.bus):
             return self
         s = np.asarray(src, dtype=np.float32)
+        if i0 < 0:
+            # 负起点 = 从 0 秒开始、裁掉前面 |i0| 个采样（与 sfxkit._place 同口径）。
+            # 旧实现把负 i0 直接当负下标切片，n 变成 0 后广播崩（place(src, -0.25) 必炸）。
+            if i0 <= -len(s):
+                return self
+            s, i0 = s[-i0:], 0
         if pan_pos is not None and self.channels == 2 and s.ndim == 1:
             theta = (float(np.clip(pan_pos, -1.0, 1.0)) + 1.0) * np.pi / 4.0
             s = np.stack([s * np.cos(theta), s * np.sin(theta)], axis=1)
@@ -749,6 +761,11 @@ class AudioBus:
             return self
         t = float(start)
         idx = 0
+        if not (float(seg) > 0.0):
+            # seg=0 时 t 不前进 -> while 变成死循环（100000 次上限只是"慢死"，
+            # 6 秒片实测 >2 分钟）。schema 只约束 seg>=0，必须在入口拒绝。
+            raise ValueError("music_bed: seg 必须 > 0，收到 %r（v0.2 和弦床的段长，默认 4.0）"
+                             % (seg,))
         while t < self.total:
             freqs = chords[idx % len(chords)]
             dur = min(seg + xfade, max(0.25, self.total - t + xfade))
@@ -841,6 +858,21 @@ def scenes_anchors(scenes):
                  start=float(s["start"]), end=float(s["end"])) for s in scenes]
 
 
+def content_seed(base: int, style: str, content_fp: str, recipe: str, t: float) -> int:
+    """内容派生 seed（v0.7）：同影片同 cue 稳定，不同影片同一位置也换音色细节。
+
+    公式与 sfxkit.content_seed 一致（references/audio-variation.md §3.1）：
+        sha1("v0.7|<base>|<style>|<content_fp>|<recipe>|<t 三位小数>") -> 前 8 位 hex -> % 9000 + 1000
+
+    为什么不用 seed_base + i：那样只跟 cue 的**出现顺序**有关，两部内容完全不同的片子
+    只要 cues 一样，音效轨就逐样本相同（跨片"音效都一样"的直接来源）。
+    """
+    h = hashlib.sha1(
+        ("v0.7|%d|%s|%s|%s|%.3f" % (int(base), str(style), str(content_fp), str(recipe), float(t)))
+        .encode("utf-8")).hexdigest()
+    return int(h[:8], 16) % 9000 + 1000
+
+
 class CueBus:
     """提示点登记表：画面侧登记 -> 落盘 cues.json -> 音频侧按它合成音效。
 
@@ -918,11 +950,21 @@ class CueBus:
 
     # -- 合成 --
     def build_audio(self, total=None, sr=SR, base_db=None, default_gain_db=0.0,
-                    seed_base=1000, verbose=True):
+                    seed_base=1000, verbose=True,
+                    style=None, content_fp=None, key=None):
         """按提示点合成音效轨 -> (n,2) float32。
 
         依赖 scripts/sfxkit.py（v0.3.0 新增）。缺 sfxkit 时直接报错，不静默出哑片。
         未知提示点类型：告警一次并跳过（不 crash 整片混音）。
+        提示点参数非法（配方不认识的关键字 / 取值连枚举校验都过不了，TypeError 或
+        ValueError）：该条跳过并汇总 [WARN]，其余正常落位——不静默改渲染默认音色，
+        也不因一条 cue 写错丢整条音效轨。
+
+        v0.7 音频差异化（见 references/audio-variation.md）：
+          - style / content_fp 同时给时，每条 cue 的 seed 由
+            content_seed(seed_base, style, content_fp, type, t) 派生 -> 不同影片同一 cue
+            位置也拿到不同音色细节；任一为 None 时退回 seed_base + i（旧路径逐样本兼容）。
+          - key 非空时透传给配方（提示音调性跟随配乐，不再硬编码 Dm）。
         """
         try:
             import sfxkit as SX
@@ -937,19 +979,46 @@ class CueBus:
         n = int(round(dur * sr)) + int(sr * 0.5)
         bus = np.zeros((n, 2), dtype=np.float32)
         unknown, placed = set(), 0
+        bad_cues: list = []          # 参数非法/内部报错的 cue：跳过并汇总 WARN，不拖死整条音效轨
+        keyed = style is not None and content_fp is not None
+        if keyed and verbose:
+            print("   音效 seed: 内容派生（style=%s / fp=%s）" % (style, str(content_fp)[:8]))
+        elif verbose and style is not None:
+            print("   音效 seed: 位置派生（只给了 style 没给 content_fp）")
         for i, c in enumerate(self.resolved()):
             kind = str(c.get("type"))
             if kind not in reg:
                 unknown.add(kind)
                 continue
             params = {k: v for k, v in c.items()
-                      if k not in ("t", "type", "src", "gain", "pan", "base_db")}
+                      if k not in ("t", "type", "src", "gain", "pan", "base_db", "key")}
             params.pop("dur_hint", None)
+            if keyed:
+                seed = content_seed(seed_base, style, content_fp, kind, float(c["t"]))
+            else:
+                seed = int(seed_base) + i
+            if key is not None:
+                params["key"] = key
             try:
-                x = SX.render(kind, seed=int(seed_base) + i, **params)
-            except TypeError:
-                # 兼容严格签名的配方：退化成只传 seed
-                x = SX.render(kind, seed=int(seed_base) + i)
+                x = SX.render(kind, seed=seed, **params)
+            except (TypeError, ValueError) as err:
+                # 只对"配方不认识这个关键字"逐个删参重试（v0.4 严格签名配方的兼容）；
+                # 参数值非法（cue 里 pitch=None 之类）或配方内部 TypeError 不是签名问题，
+                # 必须报告——旧实现一路退化成"只传 seed"，把坏参数静默渲染成默认音色
+                # （用户改了 cue 参数却听不出变化，日志里一个字都没有）。
+                extra = dict(params)
+                while True:
+                    hit = re.search(r"unexpected keyword argument '([^']+)'", str(err))
+                    if not hit or hit.group(1) not in extra:
+                        bad_cues.append((kind, float(c["t"]), err))
+                        x = None
+                        break
+                    extra.pop(hit.group(1))
+                    try:
+                        x = SX.render(kind, seed=seed, **extra)
+                        break
+                    except (TypeError, ValueError) as err2:
+                        err = err2
             if x is None or len(x) == 0:
                 continue
             x = np.asarray(x, dtype=np.float32)
@@ -968,12 +1037,123 @@ class CueBus:
             placed += 1
         if unknown and verbose:
             print("   [WARN] 未知提示点类型（已跳过）: %s" % ", ".join(sorted(unknown)))
+        if bad_cues and verbose:
+            # 与"未知 type 跳过"同一条隔离策略：一条 cue 的参数写错不该让整条音效轨消失
+            # （st_sfx 会把 build_audio 的异常当成"音效合成失败"整轨丢弃）。但也不能静默：
+            # 逐条打印 cue 类型/时刻/原因，用户改完参数能立刻看到。
+            print("   [WARN] %d 条提示点参数非法（已跳过，其余正常落位）：" % len(bad_cues))
+            for kind_b, t_b, err_b in bad_cues[:6]:
+                print("     %-14s t=%.3fs  -> %s" % (kind_b, t_b, str(err_b)[:110]))
         if verbose:
             print("   音效轨：%d 个提示点落位 / %d 个登记（%.2fs）"
                   % (placed, len(self.items), dur))
         return bus[: int(round(dur * sr))]
 
 
+def voice_env(voice, sr=SR, block_s=0.01, thresh_db=-42.0, floor_db=-60.0):
+    """旁白的语音活跃度包络（0~1）：给"旁白优先"混音用的侧链源。
+
+    为什么需要它：v0.7 之前配乐基线只比旁白低 1.5 dB（`music.gain_db=-1.5`），
+    而视频是"以旁白为主"的——背景只要不明显低于人声，观众就得费力分辨字。
+    `mix_film` 现在用这条包络在**有人声的地方**把配乐/音效再压下去，
+    没人声的间隙自动让背景回来（否则整片背景像被闷住）。
+
+    实现：10 ms 块级 RMS -> dB -> 在 [floor_db, thresh_db] 之间线性映射成 0~1 ->
+    起音快 / 释放慢的单向平滑（与 `duck()` 同一套向量化手法，无逐采样循环）。
+    """
+    x = np.asarray(voice, dtype=np.float32)
+    if x.ndim == 2:
+        x = x.mean(axis=1)
+    n = len(x)
+    if n == 0:
+        return np.zeros(0, dtype=np.float32)
+    block = max(1, int(sr * float(block_s)))
+    nb = n // block
+    if nb == 0:                                # 极短旁白（< 10 ms）：整段当一块并补零
+        nb = 1                                 # （旧实现 reshape(1, block) 直接崩）
+        x = np.concatenate([x, np.zeros(block - n, dtype=np.float32)])
+    seg = x[: nb * block].reshape(nb, block)
+    rms = np.sqrt(np.mean(seg * seg, axis=1) + 1e-12)
+    db = 20.0 * np.log10(rms + 1e-12)
+    lo = float(min(floor_db, thresh_db - 1.0))
+    e = np.clip((db - lo) / (float(thresh_db) - lo), 0.0, 1.0)
+
+    def _smooth(v, tau_s):
+        # 极短旁白时块数可能比核还少：np.convolve(mode="same") 返回 max(len(v), k) 长度，
+        # 两个长度不同的平滑结果再做 np.maximum 会广播失败（v0.7.1 起 voice_env 崩在这里）。
+        k = min(max(1, int(sr * tau_s / block)), len(v))
+        w = np.ones(k, dtype=np.float32) / k
+        return np.convolve(v, w, mode="same")
+
+    e = np.maximum(_smooth(e, 0.06), _smooth(e, 0.45)).astype(np.float32)
+    return np.interp(np.arange(n), np.arange(nb) * block + block / 2.0, e).astype(np.float32)
+
+
+def duck_voice(track, voice, depth_db=6.0, sr=SR, thresh_db=-42.0, floor_db=-60.0):
+    """旁白说话时压低背景（配乐 / 音效）：旁白优先的侧链压缩（只压背景，不碰人声）。
+
+    depth_db 是"人声满电平时背景最多被压多少 dB"；间隙里包络回 0，背景恢复原电平。
+    与 `duck()`（音效压配乐）叠加使用：人声 > 音效 > 配乐，三条让位链互不冲突。
+    """
+    b = np.asarray(track, dtype=np.float32)
+    if b.ndim == 1:
+        b2 = np.stack([b, b], axis=1)
+    else:
+        b2 = b
+    n = len(b2)
+    if n == 0 or depth_db <= 0:
+        return b2
+    e = voice_env(voice, sr=sr, thresh_db=thresh_db, floor_db=floor_db)[:n]
+    if e.size == 0:
+        return b2
+    if e.size < n:
+        # 旁白比背景短（单独调用时可能遇到）：旁白结束之后没有侧链源，背景应原样恢复。
+        e = np.concatenate([e, np.zeros(n - e.size, dtype=np.float32)])
+    if float(np.max(e)) <= 1e-6:
+        return b2
+    gains = 10.0 ** (-float(depth_db) * e / 20.0)
+    return (b2 * gains[:, None]).astype(np.float32)
+
+
+def voice_snr(voice, bg, sr=SR, thresh_db=-42.0, floor_db=-60.0):
+    """在"有人声"的采样区间量 人声/背景 的响度差（dB）。旁白优先的客观指标。
+
+    只在语音活跃度 >= 0.5 的区间统计：静音间隙里背景当然是唯一声源，
+    把间隙算进来会稀释问题（真正让人听不清的，是人说话那一刻背景有多响）。
+    人声总长不足 50 ms 时返回 None（没有可判定的样本）。
+    """
+    v = np.asarray(voice, dtype=np.float64)
+    b = np.asarray(bg, dtype=np.float64)
+    if v.ndim == 2:
+        v = v.mean(axis=1)
+    if b.ndim == 2:
+        b = b.mean(axis=1)
+    n = min(len(v), len(b))
+    if n <= 0:
+        return None
+    v, b = v[:n], b[:n]
+    e = voice_env(v, sr=sr, thresh_db=thresh_db, floor_db=floor_db)
+    act = e >= 0.5
+    if int(np.sum(act)) < int(0.05 * sr):
+        return None
+    vr = float(np.sqrt(np.mean(v[act] ** 2)))
+    br = float(np.sqrt(np.mean(b[act] ** 2)))
+    return 20.0 * np.log10((vr + 1e-12) / (br + 1e-12))
+
+
+def guard_snr(voice, bg, target_db=12.0, cap_db=12.0, sr=SR,
+              thresh_db=-42.0, floor_db=-60.0):
+    """旁白清晰度兜底：人声/背景不足 target_db 时，返回背景应再压多少 dB。
+
+    返回 (trim_db, snr_db)：trim_db=0 表示已达标；cap_db 防止把背景压到无声
+    （压过头会变成"配乐忽有忽无"，比听不清更假）。判定口径同 `voice_snr()`。
+    """
+    snr = voice_snr(voice, bg, sr=sr, thresh_db=thresh_db, floor_db=floor_db)
+    if snr is None or snr >= float(target_db):
+        return 0.0, (snr if snr is not None else float("nan"))
+    return float(min(max(0.0, float(cap_db)), float(target_db) - snr)), snr
+
+
 def duck(music, sfx, depth_db=4.0, attack=0.03, release=0.35, sr=SR):
     """音效响起时配乐自动让位（最多 depth_db），避免重击被配乐吃掉。
 
@@ -991,13 +1171,18 @@ def duck(music, sfx, depth_db=4.0, attack=0.03, release=0.35, sr=SR):
     if env.size == 0 or float(env.max()) <= 1e-9:
         return m2
     block = max(1, int(sr * 0.01))
-    nb = max(1, n // block)
+    nb = n // block
+    if nb == 0:                                 # 极短音效（< 10 ms）：整段当一块并补零
+        nb = 1
+        env = np.concatenate([env, np.zeros(block - n, dtype=np.float32)])
     e = env[: nb * block].reshape(nb, block).max(axis=1)
     e = e / (float(np.percentile(e, 99.5)) + 1e-9)
     e = np.clip(e, 0.0, 1.0)
     # 单向平滑：起音快、释放慢（对包络做两次不同时间常数的指数平滑，仍保持向量化）
     def _smooth(x, tau_s):
-        k = max(1, int(sr * tau_s / block))
+        # 与 voice_env 同一处理：短片段（< release 0.35 s）时核不能比信号长，
+        # 否则 np.convolve(mode="same") 返回核长、np.maximum 广播失败（短片混音直接崩）。
+        k = min(max(1, int(sr * tau_s / block)), len(x))
         w = np.ones(k, dtype=np.float32) / k
         return np.convolve(x, w, mode="same")
     e = np.maximum(_smooth(e, attack), _smooth(e, release) * 0.7)
@@ -1008,17 +1193,35 @@ def duck(music, sfx, depth_db=4.0, attack=0.03, release=0.35, sr=SR):
 
 def mix_film(voice, music=None, sfx=None, total=None, sr=SR,
              voice_gain=1.0, music_gain_db=0.0, sfx_gain_db=0.0,
-             duck_db=3.0, peak_target=0.89, fade=0.4, verbose=True):
+             duck_db=3.0, peak_target=0.89, fade=0.4, verbose=True,
+             voice_duck_db=6.0, voice_duck_sfx_db=3.0,
+             voice_thresh_db=-42.0, voice_floor_db=-60.0,
+             guard_snr_db=12.0, guard_cap_db=30.0):
     """三总线混音：旁白 + 配乐 + 音效 -> 立体声 float32。
 
-    顺序照 ai-history-film 的成片混音：音乐比音效低一点，音效响时音乐让位，
-    最后统一做峰值保护（真正的响度标准化交给 ffmpeg 的 loudnorm）。
+    **旁白优先**（v0.7.1 起是硬行为，不是文档口号）：
+      1. 旁白电平固定 `voice_gain=1.0`，不被任何侧链影响；
+      2. 有人声的地方，配乐再压 `voice_duck_db`（默认 6 dB）、音效再压 `voice_duck_sfx_db`（默认 3 dB）
+         —— 保证"人声比背景响 ≥12 dB"这条可听清线；没人声的间隙自动恢复；
+      3. 音效响时配乐额外让位（`duck_db`，v0.7 默认 4 dB）；
+      4. 最后统一做峰值保护（真正的响度标准化交给 ffmpeg 的 loudnorm）。
+
+    `voice_duck_db=0` / `voice_duck_sfx_db=0` 可单独关掉旁白优先让位（旧片对比用）。
+
+    **SNR 兜底（guard_snr_db=12，0 = 关）**：按台词活跃区实测"人声/背景"响度差，
+    不足 12 dB 就整体再压背景（最多 guard_cap_db），保证"听清旁白"不依赖配乐素材的天然电平——
+    这是本仓库唯一一条会在混音后自己改电平的门禁。触发时会打印实际 SNR 与补压量。
     """
     def _to_stereo(x):
         a = np.asarray(x, dtype=np.float32)
         if a.ndim == 1:
             return np.stack([a, a], axis=1)
-        return a if a.shape[1] >= 2 else np.concatenate([a, a], axis=1)
+        if a.shape[1] == 1:
+            return np.concatenate([a, a], axis=1)
+        # 多于 2 声道（例如把 5.1 的 music.wav 塞进 work/）：只取前两声道。
+        # 旧实现原样返回 (n,3+)，back += mm 直接广播崩（mix_film 是公共 API，
+        # 而 wav_read 不限制声道数，用户完全可能踩到）。口径与 AudioBus._fit 一致。
+        return a[:, :2] if a.shape[1] > 2 else a
 
     n = None
     v = None if voice is None else _to_stereo(voice)
@@ -1033,18 +1236,57 @@ def mix_film(voice, music=None, sfx=None, total=None, sr=SR,
     if not n:
         return np.zeros((0, 2), dtype=np.float32)
 
-    out = np.zeros((n, 2), dtype=np.float32)
+    # v0.7.1 旁白优先：先算背景（配乐 + 音效各自让位），再用 SNR 兜底确认"人声压得住"。
+    # 侧链与 SNR 都用"实际交付的人声"（乘过 voice_gain）：voice_gain=0.5 时旧实现用未缩放
+    # 人声算 SNR，日志写"人声/背景=12 dB 达标"、交付出去只有 6 dB（兜底承诺失效）。
+    venv_kw = dict(sr=sr, thresh_db=float(voice_thresh_db), floor_db=float(voice_floor_db))
+    vg = None
+    if v is not None:
+        vg = v[:n] * float(voice_gain)
+    back = np.zeros((n, 2), dtype=np.float32)
     if s is not None:
-        out += s[:n] * (10.0 ** (float(sfx_gain_db) / 20.0))
+        ss = s[:n] * (10.0 ** (float(sfx_gain_db) / 20.0))
+        if vg is not None and float(voice_duck_sfx_db) > 0:
+            ss = duck_voice(ss, vg, depth_db=float(voice_duck_sfx_db), **venv_kw)
+        back += ss
     if m is not None:
         mm = m[:n] * (10.0 ** (float(music_gain_db) / 20.0))
         if s is not None:
             mm = duck(mm, s[:n], depth_db=duck_db, sr=sr)
         else:
             mm = _to_stereo(mm)
-        out += mm
+        if vg is not None and float(voice_duck_db) > 0:
+            mm = duck_voice(mm, vg, depth_db=float(voice_duck_db), **venv_kw)
+        back += mm
+    # SNR 兜底：实测人声活跃区的人声/背景比；不够就整体再压背景（不碰人声）。
+    if vg is not None and back.any() and float(guard_snr_db) > 0:
+        trim_db, snr_db = guard_snr(vg, back, target_db=float(guard_snr_db),
+                                    cap_db=float(guard_cap_db), **venv_kw)
+        if trim_db > 0.0:
+            back *= 10.0 ** (-trim_db / 20.0)
+        if verbose:
+            if snr_db == snr_db:                            # 非 NaN = 有可判定的人声段
+                note = "，达标"
+                if trim_db > 0:
+                    note = "，背景再压 %.1f dB" % trim_db
+                    if trim_db >= float(guard_cap_db) - 1e-6:
+                        note += "（已到兜底上限：检查配乐/音效素材电平）"
+                    elif trim_db > 18.0:
+                        note += "（补压很大：建议调低 music.gain_db）"
+                print("   旁白优先: 人声/背景 = %.1f dB（目标 %.1f）%s"
+                      % (snr_db, float(guard_snr_db), note))
+            else:
+                # snr_db 是 NaN = 活跃区为空：旁白电平低于 voice_thresh_db 时，旁白优先
+                # 与 SNR 兜底会**整体静默失效**（背景一点不压）。纯静音片是有意的，
+                # 但"目的是说话却录得很轻"必须在日志里喊出来，否则等于没有门禁。
+                vpk = float(np.max(np.abs(vg))) if vg.size else 0.0
+                if vpk > 1e-4:                                   # 有声音但到不了活跃区
+                    print("   [WARN] 旁白电平过低（峰值 %.1f dBFS，低于活跃度门限 %.0f dB）——"
+                          "旁白优先/SNR 兜底本次无法判定；检查 voice_gain / TTS 音量"
+                          % (20.0 * math.log10(vpk), float(voice_thresh_db)))
+    out = back
     if v is not None:
-        out += v[:n] * float(voice_gain)
+        out = out + v[:n] * float(voice_gain)
 
     raw = float(np.max(np.abs(out))) if out.size else 0.0
     if fade > 0:
@@ -1619,8 +1861,8 @@ def mux(video, audio, out, crf=18, preset="medium", audio_bitrate="192k",
     af = loudnorm_two_pass(audio, target_i=target_i, target_tp=target_tp) if loudnorm else None
     if loudnorm and not af:
         # 不静默降级：量不到就喊出来（qa 的响度门禁还在，但这里先说清楚）
-        print("   [WARN] loudnorm 两遍测量失败（ffmpeg 输出里没解析到 JSON），本次不做响度标准化",
-              flush=True)
+        print("   [WARN] loudnorm 两遍测量失败（拿不到可用测量值：全静音/极短音频会给出 -inf），"
+              "本次不做响度标准化", flush=True)
 
     vd = media_dur(video)
     ad = media_dur(audio)
@@ -1658,6 +1900,17 @@ def loudnorm_two_pass(src, target_i=-16.0, target_tp=-1.5, target_lra=11.0):
         j = json.loads(m.group(0))
     except Exception:
         return None
+    # 全静音 / 极短音频时 ffmpeg 会报 input_i=-inf、target_offset=inf：这些值塞进
+    # measured_* 会被 ffmpeg 拒绝（"Value -inf for parameter 'measured_I' out of range"），
+    # mux 直接失败（旧实现只判"解析到 JSON"，于是拿着 -inf 的滤镜串去编码）。
+    # 量不到可用测量值就返回 None：mux 会打 WARN 跳过响度标准化，qa 的响度门禁照旧兜底。
+    need = ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")
+    try:
+        bad = [k for k in need if not math.isfinite(float(j.get(k, 0.0)))]
+    except (TypeError, ValueError):
+        return None
+    if bad:
+        return None
     return ("loudnorm=I=%.1f:TP=%.1f:LRA=%.1f:measured_I=%s:measured_TP=%s:"
             "measured_LRA=%s:measured_thresh=%s:offset=%s:print_format=summary"
             % (target_i, target_tp, target_lra, j.get("input_i"), j.get("input_tp"),