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

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

@@ -535,12 +535,77 @@ def check_bbox(box, safe=SAFE, tag=""):
     return []
 
 
+def _split_with_seps(text, words):
+    """把原文按词表切开，保留**词与词之间的原始分隔符**（空格/标点）。
+
+    返回 [(sep, token), ...] + 尾部残余；任何一步在原文里找不到时就返回 None。
+    为什么要保留 sep：edge-tts 的中文词表不含空格，但剧本里可能有
+    "用 DeepSeek 生成"这种中英混排——直接拼 token 会把空格吃成 "用DeepSeek生成"。
+    """
+    s = str(text or "")
+    toks = [str(w.get("text") or "") for w in (words or [])]
+    toks = [t for t in toks if t]
+    if not toks:
+        return None
+    out, pos = [], 0
+    for tk in toks:
+        i = s.find(tk, pos)
+        if i < 0:
+            return None
+        out.append((s[pos:i], tk))
+        pos = i + len(tk)
+    return out, s[pos:]
+
+
+def wrap_by_words(text, f, max_w, words):
+    """按**真实词边界**折行（v0.8）。词表对不上原文时返回 None（调用方回退字符折行）。
+
+    为什么值得：中文按字符折行会在一句话的中间硬切（"…不是读/稿"），
+    而词边界是 TTS 自己切的分词结果，折出来的断点读起来自然，也更容易和
+    词级高亮/字幕窗口对齐。
+    """
+    got = _split_with_seps(text, words)
+    if not got:
+        return None
+    pairs, tail = got
+    if tail.strip():                    # 词表没覆盖整句：不对齐，交回字符折行
+        return None
+    lines, cur = [], ""
+    for sep, tok in pairs:
+        trial = cur + sep + tok
+        if cur and text_w(trial, f) > max_w:
+            lines.append(cur)
+            cur = tok.lstrip()
+        else:
+            cur = trial
+    if tail:
+        cur += tail
+    if cur:
+        lines.append(cur)
+    return lines or None
+
+
 def fit_sub_lines(text: str, max_lines=2, max_w=1560, size=46, weight="reg",
-                  family="sans"):
-    """字幕折行：优先两行，超宽逐级缩字号。返回 (lines, font)。"""
+                  family="sans", words=None):
+    """字幕折行：优先两行，超宽逐级缩字号。返回 (lines, font)。
+
+    v0.8：传 words（句内词表）时优先按词边界折行；词表对不上原文、或折出来
+    仍超过 max_lines 时，**回退到原来的字符折行**——旧项目的排版不会因为升级而变样。
+    """
     for sz in (size, int(size * 0.92), int(size * 0.84), int(size * 0.76)):
         f = font(sz, weight, family)
-        lines = wrap_cn(text, f, max_w)
+        lines = None
+        if words:
+            lines = wrap_by_words(text, f, max_w, words)
+            if lines is not None and (len(lines) > max_lines
+                                      or any(text_w(l, f) > max_w for l in lines)):
+                # 两种情况都退回字符折行：①词边界折出来超过 max_lines；
+                # ②某个"词"本身就比 max_w 宽（wrap_by_words 对单个超宽 token 不会
+                # 断开，会把它当一整行放出去）。②不兜底时字幕横向溢出安全区，而
+                # qa_text_safe 用字符折行量宽度、看不出问题——门禁和画面不是同一套折法。
+                lines = None
+        if lines is None:
+            lines = wrap_cn(text, f, max_w)
         if len(lines) <= max_lines:
             return lines, f
     f = font(int(size * 0.76), weight, family)
@@ -548,16 +613,16 @@ def fit_sub_lines(text: str, max_lines=2, max_w=1560, size=46, weight="reg",
 
 
 def draw_subtitle(img, text: str, alpha=1.0, size=46, y=None, band_w=None,
-                  theme=None, family=None):
+                  theme=None, family=None, words=None):
     """烧字幕。v0.5.0 加 theme（stylekit 主题）与 family（字体族）；
-    theme=None 时与 v0.4 逐像素一致。"""
+    theme=None 时与 v0.4 逐像素一致。v0.8 加 words（按词边界折行）。"""
     if not text or alpha <= 0.01:
         return img
     if band_w is None:
         band_w = SUB_BAND[2] - SUB_BAND[0]
     th = theme if isinstance(theme, dict) else None
     fam = family or (th or {}).get("family") or "sans"
-    lines, f = fit_sub_lines(text, max_w=band_w, size=size, family=fam)
+    lines, f = fit_sub_lines(text, max_w=band_w, size=size, family=fam, words=words)
     lines = lines[:2]                       # 硬约束：最多两行
     lh = int(f.size * 1.32)
     cx = (SUB_BAND[0] + SUB_BAND[2]) // 2
@@ -591,6 +656,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 +793,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 +826,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))
@@ -804,10 +886,13 @@ CUE_BASE_DB = {
 def cue_time(at, scenes=None, total=None):
     """把提示点的 at 解析成成片绝对秒。
 
-    支持三种写法（CONTRACT.md §4.1）：
+    支持四种写法（CONTRACT.md §4.1）：
       "abs:12.5" / 12.5      -> 绝对秒
       "l03+0.35" / "l03-0.2" -> 场景 id 加/减偏移（相对场景 start）
       "l03"                  -> 场景起点
+      "l03:w2" / "l03:w2+0.1" -> **词锚点**（v0.8）：该句第 2 个词的起点 + 偏移。
+        下标从 1 开始（w1 = 第一个词）；找不到该词时**退化为句偏移**并告警，
+        不让一个写错的锚点把整条 cues 链路炸掉（与 v0.7.2 的"跳过并留痕"一致）。
     """
     if isinstance(at, (int, float)):
         return round(float(at), 3)
@@ -820,6 +905,32 @@ def cue_time(at, scenes=None, total=None):
         return round(float(s), 3)
     except ValueError:
         pass
+    # 词锚点：<id>:w<N>[+/-<offset>]
+    if ":w" in s:
+        head, _sep, tail = s.partition(":w")
+        # tail 形如 "2" / "2+0.1" / "2-0.1"：词序号 + 可选偏移（偏移可带符号）
+        m = re.match(r"^([0-9]+)(.*)$", tail)
+        if m:
+            num = m.group(1)
+            rest = m.group(2) or ""
+            off = 0.0
+            if rest:
+                try:
+                    off = float(rest)
+                except ValueError:
+                    off = 0.0
+            if scenes:
+                for sc in scenes:
+                    if str(sc.get("id")) != head:
+                        continue
+                    ws = sc.get("words_abs") or sc.get("words") or []
+                    idx = int(num) - 1
+                    if 0 <= idx < len(ws):
+                        return round(float(ws[idx]["start"]) + off, 3)
+                    print("   [WARN] cue at=%r：%s 只有 %d 个词，w%s 不存在，退化为句偏移"
+                          % (at, head, len(ws), num), flush=True)
+                    return round(float(sc["start"]) + off, 3)
+            raise ValueError("cue at=%r：找不到场景 %r（先跑 layout，或改用 abs:秒）" % (at, head))
     # 形如 <id>[+-]<offset>
     cut = len(s)
     for i, ch in enumerate(s):
@@ -841,6 +952,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 -> 音频侧按它合成音效。
 
@@ -852,6 +978,7 @@ class CueBus:
         self.scenes = scenes or []
         self.total = None if total is None else float(total)
         self.items = []
+        self._drop_warned = set()   # 已告警过的丢弃项：同一实例只报一次（见 resolved）
 
     # -- 登记 --
     def add(self, at, type, **params):
@@ -877,15 +1004,36 @@ class CueBus:
 
     # -- 解析 --
     def resolved(self):
-        """按时间排序、去掉明显无效项（超过片长 2 秒的丢弃并告警）。"""
+        """按时间排序、去掉明显无效项（超过片长 2 秒 / 负时刻），并**真的**告警。
+
+        为什么必须告警：st_sfx 只把 build_audio 的产物当音效轨，被丢掉的 cue 不会进
+        任何报告；以前这里静默 continue（文档却写着"丢弃并告警"），少一个提示音时
+        用户只能靠听。st_sfx 会调两次 resolved()（自己一次 + build_audio 内部一次），
+        所以只在**第一次**发现丢弃时打一条汇总，避免同一件事刷两遍。
+        """
         out = []
+        dropped = []
         for row in self.items:
             t = float(row["t"])
             if t < -0.05:
+                dropped.append(("负时刻", t))
                 continue
             if self.total is not None and t > self.total + 2.0:
+                dropped.append(("超出片长", t))
                 continue
             out.append(row)
+        fresh = [d for d in dropped if d not in self._drop_warned]
+        if fresh:
+            self._drop_warned.update(fresh)
+            late = [x for x in fresh if x[0] == "超出片长"]
+            neg = [x for x in fresh if x[0] == "负时刻"]
+            parts = []
+            if late:
+                parts.append("%d 条超过片长(%.2fs)+2s" % (len(late), float(self.total)))
+            if neg:
+                parts.append("%d 条时刻为负" % len(neg))
+            print("   [WARN] CueBus: 丢弃 %d 条提示点（%s）——检查 cue 的 at 写法/场景 id"
+                  % (len(fresh), "；".join(parts)), flush=True)
         return sorted(out, key=lambda r: float(r["t"]))
 
     def to_json(self, duration=None, fps=None, width=None, height=None, events=None):
@@ -918,11 +1066,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 +1095,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 +1153,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 +1287,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 +1309,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 +1352,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:
@@ -1271,9 +1629,127 @@ def tts_key_v2(text, voice, rate, pitch, volume="+0%", trim=True, trim_db=-42.0,
     return hashlib.sha1(payload.encode("utf-8")).hexdigest()[:16]
 
 
+# ---------------------------------------------------------------- TTS 后端
+# 为什么要有这一层（v0.8）：整条旁白链路现在只挂在一个**非官方**客户端（edge-tts）上。
+# 它的服务端随时可能改协议/加鉴权，而我们的时间轴、词级字幕、门禁全部建立在这些产物上。
+# 这里只做**接口**（不实现第二个后端）：把"合成一句话 -> 音频 + 词表"这个动作抽象出来，
+# 将来要换 Azure 官方 TTS / 离线引擎，只加一个 register 的实现，timeline/layout/QA 一行不改。
+#
+# 协议（实现者必须满足）：
+#   fn(text, out_mp3, *, voice, rate, pitch, volume, trim, trim_db, words) -> dict
+#   返回的 dict 至少含：path（可播放音频路径）、dur（实测秒数，**必须是时间轴权威**）、
+#                       words（可空列表）、trimmed（bool）
+TTS_BACKENDS = {}
+
+
+def register_tts_backend(name, fn, *, note=""):
+    """注册一个 TTS 后端实现。name 用于 film.json 的 tts.backend 选择。"""
+    if not callable(fn):
+        raise TypeError("register_tts_backend 需要一个可调用对象，收到 %r" % (fn,))
+    TTS_BACKENDS[str(name)] = dict(fn=fn, note=str(note or ""))
+    return str(name)
+
+
+def tts_backend_names():
+    return ["edge"] + sorted(n for n in TTS_BACKENDS if n != "edge")
+
+
+def tts_words_key(text, voice, rate, pitch, volume="+0%", trim=True,
+                   trim_db=-42.0) -> str:
+    """词级元数据的独立缓存键（v0.8）。
+
+    为什么不并进 tts_key_v2：并进去会让**所有老项目的音频缓存一次性失效**（必须重新联网
+    合成整片）。分开记 -> 老音频照旧复用，只有"这次显式要词级"时才补一次事件采集。
+    """
+    payload = "%s|%s|%s|%s|%s|%s|%s" % ("words", text, voice, rate, pitch,
+                                       volume, int(bool(trim)))
+    return hashlib.sha1(payload.encode("utf-8")).hexdigest()[:16]
+
+
+def trim_silence_bounds(pcm, sr=SR, thresh_db=-42.0, keep_ms=80):
+    """返回 trim_silence 会保留的样本区间 [a, b)。
+
+    v0.8 的词级时间戳需要它：edge-tts 的 WordBoundary offset 是相对**原始 mp3** 的，
+    而 trim=True 时 timeline 用的是裁剪后的语音。不减去 a，词就会整体提前 ~0.1–1 s。
+    与 trim_silence 共用同一套判据（idx[0]/idx[-1] ± keep），保证两边永远一致。
+    """
+    pcm = np.asarray(pcm, dtype=np.float32)
+    if pcm.size == 0:
+        return 0, 0
+    th = 10 ** (thresh_db / 20.0)
+    idx = np.where(np.abs(pcm) > th)[0]
+    if idx.size == 0:
+        return 0, 0
+    keep = int(sr * keep_ms / 1000.0)
+    a = max(0, int(idx[0]) - keep)
+    b = min(len(pcm), int(idx[-1]) + keep)
+    return a, b
+
+
+def words_normalize(events, *, offset_shift=0.0, dur=None, min_gap=0.0):
+    """把 edge-tts 的 WordBoundary 事件规整成 "句内词表"。
+
+    输入事件：{"type":"WordBoundary","offset":<100ns>,"duration":<100ns>,"text":str}
+    输出行： {"text":str,"start":秒,"dur":秒,"end":秒}（start/end 都是相对本句语音起点，
+             offset_shift 为裁剪掉的句首静音秒数，会从 start 里减掉）。
+
+    两个必须处理的现实（实测 edge-tts 7.3.1 zh-CN）：
+      * 词之间有 0.1–0.3 s 空隙，事件不覆盖空隙 —— 所以 start/dur 会留洞，这是对的；
+      * 句尾静音（约 0.5 s）不在任何事件里 —— 排轴时用"整句实测时长"兜底，不用词时长求和。
+    """
+    out = []
+    for ev in events or []:
+        txt = str(ev.get("text") or "").strip()
+        if not txt:
+            continue
+        try:
+            st = float(ev.get("offset") or 0.0) / 1e7 - float(offset_shift)
+            du = float(ev.get("duration") or 0.0) / 1e7
+        except (TypeError, ValueError):
+            continue
+        if st < 0:
+            # 裁剪把词首切掉一点：钳到 0，不丢词（丢词会让"字幕少一句"这类门禁误报）
+            du = max(0.0, du + st)
+            st = 0.0
+        row = dict(text=txt, start=round(st, 4), dur=round(du, 4),
+                   end=round(st + du, 4))
+        out.append(row)
+    out.sort(key=lambda r: r["start"])
+    # 单调性兜底：极端情况下服务端事件的 offset 可能轻微乱序/重叠，
+    # 这里按"后一个不得早于前一个"夹紧，保证下游（字幕、cue 锚点）拿到的是可用的序列。
+    prev_end = 0.0
+    for r in out:
+        if r["start"] < prev_end:
+            r["start"] = round(prev_end, 4)
+            r["end"] = round(r["start"] + r["dur"], 4)
+        prev_end = r["end"]
+    if dur is not None and out:
+        # 末词终点不得超过整句语音（防止边界事件把尾巴算到下一句）
+        lim = float(dur)
+        for r in out:
+            if r["end"] > lim + 1e-6:
+                r["end"] = round(lim, 4)
+                r["dur"] = round(max(0.0, r["end"] - r["start"]), 4)
+    return out
+
+
+def words_summary(words, dur=None):
+    """词表的自检摘要（给 QC 门禁用：单调性 / 覆盖率 / 末词偏差）。"""
+    ws = list(words or [])
+    n = len(ws)
+    gaps = []
+    for i in range(1, n):
+        gaps.append(round(float(ws[i]["start"]) - float(ws[i - 1]["end"]), 4))
+    covered = round(sum(float(r["dur"]) for r in ws), 4)
+    tail = round(float(dur) - float(ws[-1]["end"]), 4) if (dur and n) else None
+    mono = all(float(ws[i]["start"]) >= float(ws[i - 1]["start"]) for i in range(1, n))
+    return dict(n=n, covered=covered, gaps=gaps, tail=tail, mono=bool(mono),
+                start=round(float(ws[0]["start"]), 4) if n else None)
+
+
 def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
         cache=True, retries=4, trim=True, trim_db=-42.0, volume="+0%",
-        persona=None, tone=None):
+        persona=None, tone=None, words=False, backend="edge"):
     """逐句合成旁白（带输入校验的缓存 + 网络重试 + 可选尾静音裁剪）。
 
     v0.1 的缓存只判断文件是否存在，改一句台词会静默复用旧音频；
@@ -1286,25 +1762,59 @@ def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
     d = os.path.dirname(os.path.abspath(out_mp3))
     if d:
         os.makedirs(d, exist_ok=True)
+    # 可替换后端（v0.8）：接口只规定"返回音频 + 词表 + 实测时长"，
+    # 默认仍是 edge 的内联实现（逐字节不变）。
+    if str(backend or "edge") != "edge":
+        impl = (TTS_BACKENDS.get(str(backend)) or {}).get("fn")
+        if impl is None:
+            raise RuntimeError("未知的 TTS 后端 %r（已注册：%s）"
+                               % (backend, ", ".join(tts_backend_names())))
+        row = impl(text, out_mp3, voice=voice, rate=rate, pitch=pitch,
+                   volume=str(volume or "+0%"), trim=trim, trim_db=trim_db, words=words)
+        row = dict(row or {})
+        if "dur" not in row or not row.get("path"):
+            raise RuntimeError("TTS 后端 %r 的返回值缺 path/dur（协议见 filmkit.TTS_BACKENDS）"
+                               % backend)
+        row.setdefault("text", text)
+        row.setdefault("voice", voice)
+        row.setdefault("backend", str(backend))
+        return row
     meta_path = out_mp3 + ".json"
     vol = str(volume or "+0%")
     key = tts_key_v2(text, voice, rate, pitch, volume=vol, trim=trim, trim_db=trim_db)
     legacy_key = tts_key(text, voice, rate, pitch)
 
+    wk = tts_words_key(text, voice, rate, pitch, volume=vol, trim=trim,
+                       trim_db=trim_db)
+
+    def _words_ok(m):
+        """要词级时必须真有词级记录（老缓存没有 -> 补采一次，别静默返回空词表）。"""
+        if not words:
+            return True
+        return bool(m.get("words_key") == wk and m.get("words"))
+
+    audio_cached = None                 # 可用音频（可能缺词级记录）
     if cache and os.path.exists(out_mp3) and os.path.getsize(out_mp3) > 2000:
         try:
             m = json.load(open(meta_path, encoding="utf-8"))
             # v2 命中：key 已经含 volume/trim，不需要再分叉判断 trimmed
             if m.get("key") == key and m.get("text") == text:
                 if m.get("trimmed") and m.get("path") and os.path.exists(m["path"]):
-                    return m
+                    if _words_ok(m):
+                        return m
+                    audio_cached = m          # 有音频、缺词级：断网时降级复用它
                 if not m.get("trimmed") and not trim:
-                    return m
+                    if _words_ok(m):
+                        return m
+                    audio_cached = m
             # v1 老缓存（升级前合成的）只有在参数完全等于 v1 语义时才复用，
             # 避免"改了一个 volume 却拿到老音频"这种升级期的静默错配。
-            elif (legacy_key == tts_key(text, voice, rate, pitch)
-                  and str(m.get("key") or "") == legacy_key and m.get("text") == text
-                  and vol in ("+0%", "") and m.get("voice") == voice):
+            # trim 也必须一致：v1 的 key 里没有 trim，旧记录若 trimmed=True，用户把
+            # trim_silence 改成 false 后仍会命中并返回**裁剪版**音频（v0.4 修过的同一类
+            # "关了裁剪其实没关"，只是漏在 v1 兼容分支上）。
+            elif (str(m.get("key") or "") == legacy_key and m.get("text") == text
+                  and vol in ("+0%", "") and m.get("voice") == voice
+                  and bool(m.get("trimmed")) == bool(trim)):
                 if m.get("trimmed") and m.get("path") and os.path.exists(m["path"]):
                     return m
         except Exception:
@@ -1313,13 +1823,41 @@ def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
     import asyncio
     import time as _time
 
+    raw_events = []
     for attempt in range(max(1, int(retries))):
         try:
             import edge_tts
 
             async def go():
-                c = edge_tts.Communicate(text, voice, rate=rate, pitch=pitch, volume=vol)
-                await c.save(out_mp3)
+                # v0.8：要词级时不能再用 save()——save 会把 WordBoundary 丢掉（只写音频）。
+                # 显式传 boundary="WordBoundary"：默认是 SentenceBoundary，此时一条词事件都收不到
+                # （实测 edge-tts 7.3.1：不传 boundary 时 zh-CN 词事件数 = 0）。
+                c = edge_tts.Communicate(
+                    text, voice, rate=rate, pitch=pitch, volume=vol,
+                    boundary="WordBoundary" if words else "SentenceBoundary")
+                if not words:
+                    await c.save(out_mp3)
+                    return
+                raw_events.clear()
+                # 先写 .part 再 os.replace：中途中失败/断网时**绝不能**截断已有的缓存音频
+                # （旧实现直接 "wb" 打开目标文件，一次失败就把好音频清成 0 字节）。
+                part = out_mp3 + ".part"
+                try:
+                    with open(part, "wb") as fh:
+                        async for chunk in c.stream():
+                            if chunk["type"] == "audio":
+                                fh.write(chunk["data"])
+                            else:
+                                raw_events.append(dict(chunk))
+                    if not os.path.exists(part) or os.path.getsize(part) <= 2000:
+                        raise RuntimeError("合成产物异常")
+                    os.replace(part, out_mp3)
+                finally:
+                    if os.path.exists(part):
+                        try:
+                            os.remove(part)
+                        except OSError:
+                            pass
 
             asyncio.run(go())
             if not os.path.exists(out_mp3) or os.path.getsize(out_mp3) <= 2000:
@@ -1327,22 +1865,48 @@ def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
             break
         except Exception as e:              # noqa: BLE001
             if attempt == max(1, int(retries)) - 1:
+                if audio_cached is not None and words:
+                    # 断网 / 服务端拒绝时的降级：**音频还在**，只是这次没词级。
+                    # 不静默：打 WARN，并在 meta 里记 words_ok=False，让 gates 判 skipped。
+                    print("   [WARN] %s: 拿不到词级时间戳（%s），复用已有音频；"
+                          "本次词级门禁会记 skipped" % (os.path.basename(out_mp3), e),
+                          flush=True)
+                    audio_cached["words"] = []
+                    audio_cached["words_ok"] = False
+                    audio_cached["words_events"] = 0
+                    return audio_cached
                 raise RuntimeError("edge-tts 合成失败（重试 %d 次）：%s" % (retries, e)) from e
             _time.sleep(1.2 * (attempt + 1))
 
-    dur_raw = audio_dur(out_mp3)
+    # trim=True 时同一句 mp3 只需要解码一次：audio_dur() 内部就是 decode_pcm，
+    # 旧实现先 audio_dur 再 decode_pcm，每句多起一个 ffmpeg 进程、多做一次全量解码
+    # （55 句模板片就是 55 次多余的解码 + 进程启动，而 TTS 阶段本身是网络瓶颈）。
+    pcm_raw = decode_pcm(out_mp3) if trim else None
+    dur_raw = len(pcm_raw) / float(SR) if pcm_raw is not None else audio_dur(out_mp3)
     used = out_mp3
     dur = dur_raw
+    shift = 0.0                         # 句首被裁掉的静音秒数（词时间戳要减掉它）
     if trim:
-        pcm = trim_silence(decode_pcm(out_mp3), thresh_db=trim_db)
+        a, b = trim_silence_bounds(pcm_raw, thresh_db=trim_db)
+        pcm = pcm_raw[a:b] if b > a else pcm_raw
         wav_path = os.path.splitext(out_mp3)[0] + ".trim.wav"
         wav_write(wav_path, pcm)
         used = wav_path
         dur = len(pcm) / float(SR)
+        shift = a / float(SR) if pcm_raw.size else 0.0
 
     m = dict(path=used, mp3=out_mp3, text=text, voice=voice, rate=rate, pitch=pitch,
              volume=vol, key=key, spec_version=2, dur=dur, dur_raw=dur_raw,
              trimmed=bool(trim), trim_db=float(trim_db))
+    if words:
+        wlist = words_normalize(raw_events, offset_shift=shift, dur=dur)
+        m["words"] = wlist
+        m["words_key"] = wk
+        m["words_events"] = len(raw_events)
+        m["words_shift"] = round(float(shift), 4)
+        # 词事件收不到不是崩溃，而是"服务端行为变了"：留空表 + 事件计数，
+        # 由 gates 判 skipped 并写进 QC 报告（不许静默当成"有词级"）。
+        m["words_ok"] = bool(wlist)
     if persona:
         m["persona"] = str(persona)
     if tone:
@@ -1352,7 +1916,8 @@ def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
 
 
 def tts_batch(lines, workdir, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
-              workers=4, trim=True, plan=None, trim_db=-42.0):
+              workers=4, trim=True, plan=None, trim_db=-42.0, words=True,
+              backend="edge"):
     """并发逐句合成（并发只影响墙钟，不影响产物：每句独立缓存）。
 
     v0.5.0：plan=[{voice,rate,pitch,volume,persona,tone}, ...]（与 lines 等长）时
@@ -1375,7 +1940,7 @@ def tts_batch(lines, workdir, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0
                 rate=spec.get("rate") or rate,
                 pitch=spec.get("pitch") or pitch,
                 volume=spec.get("volume") or "+0%",
-                trim=trim, trim_db=trim_db,
+                trim=trim, trim_db=trim_db, words=words, backend=backend,
                 persona=spec.get("persona"), tone=spec.get("tone"))
         row = dict(ln)
         row.update(m)
@@ -1390,15 +1955,75 @@ def tts_batch(lines, workdir, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0
     return results
 
 
+# ---------------------------------------------------------------- 画幅规划
+VIDEO_FPS_ALLOWED = (24, 25, 30, 50, 60)
+VIDEO_OUT_ALLOWED = ((1920, 1080), (1280, 720), (960, 540), (2560, 1440))
+VIDEO_ASPECT = 16.0 / 9.0
+
+
+def video_plan(script=None):
+    """解析 film.json 的 video 块 -> 内部分辨率 / 输出分辨率 / 帧率（v0.8）。
+
+    设计取舍（都是刻意的）：
+      * **只做横屏 16:9**。竖屏不是"把宽高换一下"：安全区、版式几何、HUD、字幕折行
+        全部按 16:9 的像素坐标写死，换比例要重做一套版式（用户已确认本轮不做）。
+        竖屏/非 16:9 直接报错，而不是悄悄出个变形或带黑边的片子。
+      * **构图恒定 1920x1080，只允许下采样输出**（720p/540p/1440p 里 1440p 需上采样，
+        因此默认拒绝）：上采样不会增加信息，只会把"1080p 的清晰度"包装成"4K"，
+        与项目"文档真话化 / 不糊弄"的原则冲突。要 4K 就改内部构图分辨率。
+      * fps 只接受常见交付值；改 fps 只改时间→帧的换算，不改变画面内容。
+    """
+    v = dict((script or {}).get("video") or {})
+    try:
+        fps = int(v.get("fps") or (script or {}).get("fps") or FPS)
+    except (TypeError, ValueError):
+        raise ValueError("video.fps 必须是整数，收到 %r" % (v.get("fps"),))
+    if fps not in VIDEO_FPS_ALLOWED:
+        raise ValueError("video.fps=%d 不支持（可用：%s）"
+                         % (fps, "/".join(str(x) for x in VIDEO_FPS_ALLOWED)))
+    try:
+        ow = int(v.get("width") or v.get("out_width") or W)
+        oh = int(v.get("height") or v.get("out_height") or H)
+    except (TypeError, ValueError):
+        raise ValueError("video.width/height 必须是整数，收到 %r/%r"
+                         % (v.get("width"), v.get("height")))
+    if (ow, oh) == (W, H):
+        return dict(fps=fps, w=W, h=H, out_w=ow, out_h=oh, scale=False,
+                    label="%dx%d" % (ow, oh))
+    if ow < oh:
+        raise ValueError("video.width=%d height=%d 是竖屏：本项目只支持 16:9 横屏"
+                         "（安全区/版式按横屏像素写死，竖屏是另一套版式，本轮不做）"
+                         % (ow, oh))
+    if abs(ow / float(oh) - VIDEO_ASPECT) > 0.01:
+        raise ValueError("video.width=%d height=%d 不是 16:9（%.3f:1）：换宽高比要重做"
+                         "版式几何与字幕安全区，本轮只支持 16:9 横屏的缩放输出"
+                         % (ow, oh, ow / float(oh)))
+    if (ow, oh) not in VIDEO_OUT_ALLOWED:
+        raise ValueError("video 输出尺寸 %dx%d 不在允许列表 %s 内（要新尺寸先确认镜头/字号"
+                         "在目标分辨率下仍然成立，再把它加进 VIDEO_OUT_ALLOWED）"
+                         % (ow, oh, ", ".join("%dx%d" % s for s in VIDEO_OUT_ALLOWED)))
+    if ow > W or oh > H:
+        raise ValueError("video 输出 %dx%d 大于内部构图 %dx%d：那是上采样，只会把 1080p 的"
+                         "清晰度包装成更高分辨率（假 4K）。要真高清请改内部构图分辨率，"
+                         "而不是放大输出。" % (ow, oh, W, H))
+    return dict(fps=fps, w=W, h=H, out_w=ow, out_h=oh, scale=True,
+                label="%dx%d" % (ow, oh))
+
+
 # ---------------------------------------------------------------- 时间轴
 def build_timeline(lines, lead=0.55, tail=0.85, min_dur=3.0, tail_map=None, max_dur=None,
-                   hold=0.0, hold_map=None, bar=0.0, lead_map=None):
+                   hold=0.0, hold_map=None, bar=0.0, lead_map=None, fps=None):
     """由实测语音时长反推时间轴。第一段 start 必须严格为 0。
 
     hold / hold_map（v0.3.0）：语音结束后额外停留的秒数——这就是 ai-history-film 的"停留窗口"：
       观众没看清的地方加停留，而不是把整片放慢。hold 为全局默认，hold_map 按 id 覆盖，
       行内 `hold` 字段优先级最高。bar > 0 时把每段时长向上取整到 bar 的整数倍
       （配乐小节对齐用，例如 bar=2.0 = 120 BPM 的一小节）。
+
+    max_dur 只能截留白，不能截到语音结束之前：段时长被压到 lead+语音以下时，场景变短
+    而旁白仍按 voice_start 播完整长句 -> 下一句的语音压在本句上（音频总线里两条人声
+    重叠），字幕窗口也会倒挂。所以取 max(max_dur, 硬下限) 并打印 WARN；真要缩短请减
+    句长或改 lead/tail。
     """
     scenes, t = [], 0.0
     for ln in lines:
@@ -1410,16 +2035,33 @@ def build_timeline(lines, lead=0.55, tail=0.85, min_dur=3.0, tail_map=None, max_
         tail_i = float((tail_map or {}).get(ln["id"], tail))
         d = max(float(min_dur), lead_i + voice + tail_i + extra)
         if max_dur and d > float(max_dur):
-            d = float(max_dur)
+            # 硬下限 = min_dur 与 "句前留白 + 语音" 的较大者：min_dur 是"画面撑住"的下限，
+            # lead+voice 是"人声不被切断/不与下一句重叠"的物理下限。max_dur 只压得动
+            # tail/hold 这些留白；压到语音以下时必须报警（静默重叠比参数没生效更糟）。
+            floor = max(float(min_dur), lead_i + voice)
+            d = max(float(max_dur), floor)
+            if d > float(max_dur) + 1e-9:
+                print("   [WARN] build_timeline: %s 的 lead %.2fs + 语音 %.2fs 超过 "
+                      "max_dur=%.2fs，段时长取 %.2fs（不切断旁白；要更短请减句长或调 lead）"
+                      % (ln.get("id", "?"), lead_i, voice, float(max_dur), d), flush=True)
         if bar and float(bar) > 0:
             d = math.ceil(d / float(bar) - 1e-9) * float(bar)
-        scenes.append(dict(ln, start=round(t, 3), end=round(t + d, 3), dur=round(d, 3),
-                           voice_start=round(t + lead_i, 3),
-                           voice_end=round(t + lead_i + voice, 3)))
+        row = dict(ln, start=round(t, 3), end=round(t + d, 3), dur=round(d, 3),
+                   voice_start=round(t + lead_i, 3),
+                   voice_end=round(t + lead_i + voice, 3))
+        # v0.8：把句内词表平移成**绝对时间**，下游（字幕断行 / cue 词锚点 /
+        # 词级门禁）只需要读 words_abs，不必自己再算一遍 offset。
+        if ln.get("words"):
+            vs = row["voice_start"]
+            row["words_abs"] = [dict(w, start=round(vs + float(w["start"]), 4),
+                                     end=round(vs + float(w["end"]), 4))
+                                for w in ln["words"]]
+        scenes.append(row)
         t += d
     if scenes:
         scenes[0]["start"] = 0.0
-    return dict(total=round(t, 3), scenes=scenes, fps=FPS, frames=int(round(t * FPS)))
+    f = int(fps or FPS)
+    return dict(total=round(t, 3), scenes=scenes, fps=f, frames=int(round(t * f)))
 
 
 def sub_window(scenes, i, max_hold=None):
@@ -1431,7 +2073,9 @@ def sub_window(scenes, i, max_hold=None):
     s = scenes[i]
     t0 = s["voice_start"] - 0.12
     t1 = s["voice_end"] + 0.45
-    if max_hold:
+    if max_hold and float(max_hold) > 0:
+        # 0/负值当"不限制"：旧实现传 -0.5 会把 t1 钳到 voice_start-0.5，窗口倒挂、
+        # 整句字幕消失。sub_max_hold 是公共参数，外部调用可能原样透传。
         t1 = min(t1, s["voice_start"] + float(max_hold))
     t1 = min(t1, s["end"] - 0.06)
     nxt = scenes[i + 1]["voice_start"] - 0.12 if i + 1 < len(scenes) else 1e9
@@ -1446,6 +2090,15 @@ def sub_at(scenes, t, max_hold=None):
     return ""
 
 
+def sub_words_at(scenes, t, max_hold=None):
+    """取当前时刻上屏字幕对应的**词表**（v0.8）；没有词级就返回 None。"""
+    for i, s in enumerate(scenes):
+        t0, t1 = sub_window(scenes, i, max_hold)
+        if t0 <= t <= t1:
+            return s.get("words_abs") or None
+    return None
+
+
 def write_srt(scenes, path, max_hold=None):
     def fmt(x):
         ms = int(round(x * 1000))
@@ -1457,6 +2110,10 @@ def write_srt(scenes, path, max_hold=None):
     rows = []
     for i, s in enumerate(scenes):
         t0, t1 = sub_window(scenes, i, max_hold)
+        # 时间码不能为负、不能倒挂：首句 lead < 0.12 时 t0 = -0.12，直接写会得到
+        # "-1:59:59,880" 这种非法行（播放器整条丢弃或直接报错）。
+        t0 = max(0.0, t0)
+        t1 = max(t0, t1)
         body = s.get("sub") or s.get("text", "")
         rows.append("%d\n%s --> %s\n%s\n" % (i + 1, fmt(t0), fmt(t1), body))
     d = os.path.dirname(os.path.abspath(path))
@@ -1513,6 +2170,9 @@ def write_ass(scenes, path, max_hold=None, font_name="Microsoft YaHei", size=52,
     body = []
     for i, s in enumerate(scenes):
         t0, t1 = sub_window(scenes, i, max_hold)
+        # 同 write_srt：ASS 的 &H 时间码同样不接受负值（-0.12s 会写成 -1:59:59.88）。
+        t0 = max(0.0, t0)
+        t1 = max(t0, t1)
         txt = (s.get("sub") or s.get("text", "")).replace("\n", "\\N")
         body.append("Dialogue: 0,%s,%s,Default,,0,0,0,,%s" % (fmt(t0), fmt(t1), txt))
     d = os.path.dirname(os.path.abspath(path))
@@ -1531,11 +2191,21 @@ class FrameSink:
     """
 
     def __init__(self, out_path, w=W, h=H, fps=FPS, crf=18, preset="medium",
-                 audio=None, bitrate=None, strict=True, extra_args=None):
+                 audio=None, bitrate=None, strict=True, extra_args=None,
+                 out_w=None, out_h=None, scale_flags="lanczos"):
         self.out = str(out_path)
         self.w, self.h, self.fps = int(w), int(h), float(fps)
         self.strict = strict
         self.frames = 0
+        # v0.8：内部构图恒为 w x h（PIL 画布），输出可以更小（只允许下采样）。
+        # 缩放放在**编码这一遍**做（-vf scale），不二次编码、也不改变合成内容：
+        # 1920→1280 的 lanczos 下采样本身等于 1.5x 超采样，画面不会因为降规格而变糊。
+        self.out_w = int(out_w or self.w)
+        self.out_h = int(out_h or self.h)
+        if self.out_w > self.w or self.out_h > self.h:
+            raise ValueError("FrameSink: 输出 %dx%d 大于内部构图 %dx%d，拒绝上采样"
+                             % (self.out_w, self.out_h, self.w, self.h))
+        self.scale = (self.out_w, self.out_h) != (self.w, self.h)
         d = os.path.dirname(os.path.abspath(self.out))
         if d:
             os.makedirs(d, exist_ok=True)
@@ -1544,6 +2214,8 @@ class FrameSink:
                "-r", "%g" % self.fps, "-i", "-"]
         if audio:
             cmd += ["-i", str(audio)]
+        if self.scale:
+            cmd += ["-vf", "scale=%d:%d:flags=%s" % (self.out_w, self.out_h, scale_flags)]
         cmd += ["-c:v", "libx264", "-preset", preset, "-crf", str(crf),
                 "-pix_fmt", "yuv420p", "-g", str(int(self.fps * 2)),
                 "-keyint_min", str(int(self.fps * 2)), "-sc_threshold", "0"]
@@ -1575,11 +2247,19 @@ class FrameSink:
         self.frames += 1
 
     def close(self):
-        self.proc.stdin.close()
+        try:
+            self.proc.stdin.close()
+        except (BrokenPipeError, OSError):
+            # 编码进程已经死了：真正的死因在 stderr 里，下面统一报，别让 BrokenPipe
+            # 把 ffmpeg 的错误信息顶掉（旧实现只有裸 close，异常时看不到任何诊断）。
+            pass
+        # 先排空 stderr 再 wait：-v error 的报错行也可能多到写满 64KB 管道，
+        # 而 wait() 期间没人读它 -> ffmpeg 卡在写 stderr、双方一起死等。
+        err = self.proc.stderr.read() if self.proc.stderr is not None else b""
         rc = self.proc.wait()
         if rc != 0:
-            raise RuntimeError("ffmpeg 编码失败: "
-                               + self.proc.stderr.read().decode("utf-8", "replace")[:800])
+            raise RuntimeError("ffmpeg 编码失败（exitcode=%d）: %s"
+                               % (rc, err.decode("utf-8", "replace")[:800]))
         return self.out
 
 
@@ -1619,8 +2299,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 +2338,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"),
@@ -1683,9 +2374,15 @@ def loudness(path):
 
 
 def detect_black(path, dur=0.4, head=1.2, tail=None):
-    """长黑帧检测。head/tail 秒内是刻意的淡入淡出，不算问题。"""
+    """长黑帧检测。head/tail 秒内是刻意的淡入淡出，不算问题。
+
+    返回 None 表示**检测根本没跑成**（ffmpeg 打不开文件 / blackdetect 失败）。
+    这一点必须可区分：旧实现把失败也返回 0，qa 门禁于是把"没查"记成"0 段黑帧 = 通过"。
+    """
     p = _run([FFMPEG, "-hide_banner", "-nostats", "-i", str(path), "-vf",
               "blackdetect=d=%s:pic_th=0.98" % dur, "-f", "null", "-"])
+    if p.returncode != 0:
+        return None
     total = media_dur(path)
     tl = tail if tail is not None else head
     bad = 0
@@ -1698,8 +2395,11 @@ def detect_black(path, dur=0.4, head=1.2, tail=None):
 
 
 def detect_silence(path, th=-45, dur=1.2):
+    """长静音段计数。返回 None = 检测没跑成（理由同 detect_black，不许当 0 计入通过）。"""
     p = _run([FFMPEG, "-hide_banner", "-nostats", "-i", str(path), "-af",
               "silencedetect=n=%ddB:d=%s" % (th, dur), "-f", "null", "-"])
+    if p.returncode != 0:
+        return None
     return len(re.findall("silence_start", p.stderr.decode("utf-8", "replace")))
 
 
@@ -1786,6 +2486,11 @@ def encode_quality(film, ref_png, at_sec=None, ref_img=None):
         dec = cv2.imread(tmp, cv2.IMREAD_GRAYSCALE)
     if dec is None:
         return None
+    if ref.shape != dec.shape:
+        # v0.8：输出降到 720p 时，参考帧还是 1080p 的原图。不缩放就比 Laplacian 方差，
+        # 等于拿两个不同分辨率的东西比"锐不锐"——ratio 会假性偏低（v0.8 前只在
+        # 1920x1080 单一时是同一尺寸，所以没暴露）。这里统一缩到**交付分辨率**再比。
+        ref = cv2.resize(ref, (dec.shape[1], dec.shape[0]), interpolation=cv2.INTER_AREA)
     sa = float(cv2.Laplacian(ref, cv2.CV_64F).var())
     sb = float(cv2.Laplacian(dec, cv2.CV_64F).var())
     return dict(sharp_ref=round(sa, 1), sharp_dec=round(sb, 1),
@@ -1872,10 +2577,15 @@ def _probe_concat_part(path):
     except Exception:                       # noqa: BLE001
         dur = 0.0
     a = next((s for s in streams if s.get("codec_type") == "audio"), None)
+    # 音频参数也要探测：-c copy 拼接时各段采样率/声道不一致不会被 ffmpeg 校正，
+    # 而是按参照段解释（实测 48k 段 + 44.1k 段拼完频率 440Hz -> 478.6Hz，
+    # 即整段变调 1.086 倍，而 ffmpeg 返回码仍是 0）。
     return dict(ok=True, path=p, width=int(v.get("width") or 0),
                 height=int(v.get("height") or 0), fps=round(fps, 3),
                 fps_text=rate, codec=str(v.get("codec_name") or ""),
-                audio=bool(a), dur=dur)
+                audio=bool(a), dur=dur,
+                ar=int(a.get("sample_rate") or 0) if a else 0,
+                channels=int(a.get("channels") or 0) if a else 0)
 
 
 def _fmt_fps(info):
@@ -1922,6 +2632,15 @@ def _concat_issues(parts):
             issues.append("%s%s音轨，%s%s音轨"
                           % (who, "有" if inf["audio"] else "无",
                              base, "有" if r["audio"] else "无"))
+        elif inf["audio"] and r["audio"]:
+            # 有音轨时再比音频参数：copy 不做重采样/重混，参数不一致 ->
+            # 音高/时长/声道被按参照段解释（错片但返回码 0，属于"静默错"，必须走重编码）。
+            if inf.get("ar") and r.get("ar") and inf["ar"] != r["ar"]:
+                issues.append("%s音频采样率 %d Hz != %s %d Hz（-c copy 会让音高/时长错位）"
+                              % (who, inf["ar"], base, r["ar"]))
+            if inf.get("channels") and r.get("channels") and inf["channels"] != r["channels"]:
+                issues.append("%s音频声道数 %d != %s %d"
+                              % (who, inf["channels"], base, r["channels"]))
     return infos, issues, ref
 
 
@@ -1974,7 +2693,12 @@ def _concat_reencode(parts, out, infos, ref, lst):
             fc.append("[%d:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo[a%d]"
                       % (i, i))
         else:
-            dur = max(float(inf.get("dur") or 0), ref_dur, 0.1)
+            # 静音长度必须等于**这一段自己的**视频长度。旧实现取 max(段长, 参照段长)：
+            # 参照段更长时会给短的无音轨段多补几秒静音，拼接后音频比视频长
+            # （实测 3s 有声 + 1s 无声 -> 输出 6s，视频只有 4s，后半段音画差 2s）。
+            # 段长读不出来（ffprobe 没有 duration）时才退回参照段时长。
+            seg_dur = max(float(inf.get("dur") or 0), 0.0)
+            dur = max(seg_dur if seg_dur > 0 else ref_dur, 0.1)
             fc.append("anullsrc=r=48000:cl=stereo,atrim=duration=%.3f,asetpts=PTS-STARTPTS[a%d]"
                       % (dur, i))
     labels = "".join("[v%d]%s" % (i, "[a%d]" % i if any_audio else "")
@@ -2065,15 +2789,22 @@ def concat_segments(parts, out, workdir=None):
 
 # ---------------------------------------------------------------- 总质检
 def qa_report(path, expect_frames=None, ref_png=None, ref_sec=None, ref_img=None,
-              expected_subtitles=None, min_bitrate=0, notes=None, theme=None):
+              expected_subtitles=None, min_bitrate=0, notes=None, theme=None,
+              expect_w=None, expect_h=None, expect_fps=None):
     """分档质检：errors 必须修，warnings 看情况。
 
     v0.2 修正：
     - 真峰现在能测到（loudness 加 peak=true），<= -1 dBTP 才是真门禁；
     - 码率默认不再当"下限"（暗色简洁内容本来就只有 0.5Mbps，v0.1 会误判）；
     - 新增字幕条数校验（expected_subtitles），这是"静默丢字幕"的唯一检查点。
+
+    v0.8：交付规格可配置（expect_w/expect_h/expect_fps）。以前这里死比 K.W/K.H/K.FPS，
+    于是 720p/24fps 的合法交付会被报成"分辨率/帧率不符"——门禁判据跟交付规格脱节，
+    比误报更糟的是它会让人去"修"一个根本没错的东西。缺省仍回落到模块常量（老行为不变）。
     """
     errors, warns = [], []
+    W, H, FPS = (int(expect_w or globals()["W"]), int(expect_h or globals()["H"]),
+                 float(expect_fps or globals()["FPS"]))
     pr = probe(path)
     fmt = pr.get("format", {})
     streams = pr.get("streams") or [{}]
@@ -2088,7 +2819,7 @@ def qa_report(path, expect_frames=None, ref_png=None, ref_sec=None, ref_img=None
             num, _, den = rate.partition("/")
             got = float(num) / float(den or 1)
             if abs(got - float(FPS)) > 0.05:
-                errors.append("帧率 %.3f != %d（SKILL 要求严格一致）" % (got, FPS))
+                errors.append("帧率 %.3f != %g（SKILL 要求严格一致）" % (got, FPS))
         except Exception:
             pass
     if not au:
@@ -2123,9 +2854,14 @@ def qa_report(path, expect_frames=None, ref_png=None, ref_sec=None, ref_img=None
     else:
         warns.append("未能测到真峰（ebur128 解析失败），责任门禁缺一项")
     nb = detect_black(path)
-    if nb > 0:
+    if nb is None:
+        warns.append("长黑帧检测未执行（ffmpeg blackdetect 失败），本项不能当作通过")
+    elif nb > 0:
         warns.append("首尾之外检测到 %d 段长黑帧" % nb)
-    if detect_silence(path) > 0:
+    ns = detect_silence(path)
+    if ns is None:
+        warns.append("长静音检测未执行（ffmpeg silencedetect 失败），本项不能当作通过")
+    elif ns > 0:
         warns.append("检测到长静音段（确认是否有意留白）")
     if isinstance(theme, dict):
         # 主题体检的结论带进报告：这样"深色主题必然贴空窗阈值"这种事实不是靠嘴说