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

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

@@ -48,32 +48,216 @@ CUE_ALIASES = {
 
 
 # ---------------------------------------------------------------- ffmpeg
+# ffmpeg 探测必须 fail-closed：候选"文件存在"不等于"能用"。
+# 本机曾静默选中 C:\Program Files\EVCapture\ffmpeg.exe（2019 旧版，没有 xfade），
+# 一路跑到滤镜阶段才挂，报错离原因太远。现在每个候选都必须真的跑通
+# "ffmpeg -version" 且 returncode == 0 才算可用（超时/异常一律视为不可用）。
+_FFMPEG_ENV = "FILMKIT_FFMPEG"
+_FFMPEG_STRICT_ENV = "FILMKIT_FFMPEG_STRICT"
+_FFMPEG_UP_LEVELS = 5           # 从 cwd 向上最多找 5 层父目录的便携布局
+_FFMPEG_NAMES = ("ffmpeg.exe", "ffmpeg") if os.name == "nt" else ("ffmpeg", "ffmpeg.exe")
+
+# 来源键 -> 给人看的说明（ffmpeg_source() 用；backend 回显 / 日志都靠它）
+FFMPEG_SOURCE_LABELS = {
+    "env": "显式指定（FILMKIT_FFMPEG）",
+    "portable": "向上搜索（tools/ffmpeg）",
+    "hardcoded": "硬编码候选（WinGet/系统路径）",
+    "path": "PATH（shutil.which）",
+    "fallback": "未找到（回退裸命令，默认宽松模式）",
+}
+_FFMPEG_CACHE = {}              # {候选集合 tuple: (可执行路径, 来源键)}：同一候选集合只探测一次
+_FFPROBE_CACHE = {}             # {ffmpeg 路径: ffprobe 路径}：ffprobe 定位也不重复做
+
+_FFMPEG_STRICT_HINT = (
+    "找不到可用的 ffmpeg：FILMKIT_FFMPEG、从当前目录向上 %d 层的 tools/ffmpeg、"
+    "WinGet/系统固定路径、PATH 里都没有能跑通 \"ffmpeg -version\"（returncode=0）的可执行文件。"
+    "装了没有？winget install Gyan.FFmpeg 可以装；装在哪？便携版放到 <项目>/tools/ffmpeg/ffmpeg.exe "
+    "即可被自动发现；怎么指？设置环境变量 FILMKIT_FFMPEG=D:/tools/ffmpeg.exe。"
+    "（当前 FILMKIT_FFMPEG_STRICT=1，所以直接退出；去掉该变量会回退成裸命令 ffmpeg。）"
+    % _FFMPEG_UP_LEVELS
+)
+
+
+def _probe_ffmpeg(path):
+    """候选是否真的可用：返回可执行路径，不可用返回 None（fail-closed）。
+
+    必须跑通 "-version"；文件不存在 / 不是可执行文件 / 权限拒绝 / 超时 / 非 0 退出，
+    一律视为不可用。异常吞掉继续试下一个候选——探测阶段不应该把 import 炸掉。
+    """
+    try:
+        if not path:
+            return None
+        exe = str(path)
+        if not os.path.isfile(exe):
+            exe = shutil.which(exe) or ""   # 允许 FILMKIT_FFMPEG=ffmpeg 这种裸名字
+            if not exe:
+                return None
+        elif not os.path.isabs(exe):
+            exe = os.path.abspath(exe)      # 相对路径候选按 cwd 解析，别让 execvp 去 PATH 里找
+        p = subprocess.run([exe, "-version"], capture_output=True, timeout=10)
+        if p.returncode != 0:
+            return None
+        return exe
+    except Exception:                       # noqa: BLE001 —— 探测失败=候选不可用，换下一个
+        return None
+
+
+def _iter_up_dirs(levels=None):
+    """cwd + 向上 levels 层父目录（含 cwd 共 levels+1 个）。cwd 被删时安全退化。"""
+    try:
+        d = os.path.abspath(os.getcwd())
+    except Exception:                       # noqa: BLE001
+        return
+    yield d
+    for _ in range(int(_FFMPEG_UP_LEVELS if levels is None else levels)):
+        parent = os.path.dirname(d)
+        if parent == d:                     # 到盘符根 / 文件系统根，停
+            break
+        d = parent
+        yield d
+
+
+def _portable_ffmpeg_candidates():
+    """便携布局：<目录>/tools/ffmpeg/ffmpeg(.exe) 与 <目录>/tools/ffmpeg(.exe)。"""
+    out = []
+    for d in _iter_up_dirs():
+        for name in _FFMPEG_NAMES:
+            out.append(os.path.join(d, "tools", "ffmpeg", name))
+        for name in _FFMPEG_NAMES:
+            out.append(os.path.join(d, "tools", name))
+    return out
+
+
+def _hardcoded_ffmpeg_candidates():
+    """原有硬编码候选（WinGet Links / Unix 常见路径）。顺序保持原样，不新增 EVCapture 之类的意外构建。"""
+    out = []
+    local = os.environ.get("LOCALAPPDATA", "")
+    user = os.environ.get("USERPROFILE", "")
+    if local:
+        out.append(os.path.join(local, "Microsoft", "WinGet", "Links", "ffmpeg.exe"))
+    if user:
+        out.append(os.path.join(user, "AppData", "Local", "Microsoft", "WinGet",
+                                "Links", "ffmpeg.exe"))
+    out += ["/usr/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/opt/homebrew/bin/ffmpeg"]
+    return out
+
+
+def _ffmpeg_candidates():
+    """按优先级返回 [(候选路径, 来源键)]：显式指定 -> 向上搜索 -> 硬编码 -> PATH。"""
+    cands, seen = [], set()
+
+    def add(path, src):
+        path = (path or "").strip()
+        if len(path) >= 2 and path[0] == path[-1] and path[0] in "\"'":
+            path = path[1:-1].strip()       # 容忍用户把路径连引号一起粘进环境变量
+        if not path:
+            return
+        key = os.path.normcase(os.path.abspath(path))
+        if key in seen:
+            return
+        seen.add(key)
+        cands.append((path, src))
+
+    add(os.environ.get(_FFMPEG_ENV), "env")
+    for p in _portable_ffmpeg_candidates():
+        add(p, "portable")
+    for p in _hardcoded_ffmpeg_candidates():
+        add(p, "hardcoded")
+    add(shutil.which("ffmpeg"), "path")
+    return cands
+
+
+def _resolve_ffmpeg():
+    """探测并缓存 ffmpeg，返回 (可执行路径, 来源键)。
+
+    默认宽松：一个候选都不可用时回退裸命令 "ffmpeg"（让真正调用 subprocess 的地方自己报错）；
+    FILMKIT_FFMPEG_STRICT=1 时改为 raise SystemExit，并在消息里说清怎么装/放哪/怎么指。
+    """
+    cands = _ffmpeg_candidates()
+    key = tuple((os.path.normcase(os.path.abspath(p)), s) for p, s in cands)
+    hit = _FFMPEG_CACHE.get(key)
+    if hit is not None:
+        # 回退结果命中缓存时也要按"当前"STRICT 再判一次：改完 env 不 reset 也不能漏掉 fail-closed
+        if hit[1] != "fallback" or (os.environ.get(_FFMPEG_STRICT_ENV) or "").strip() != "1":
+            return hit
+        raise SystemExit(_FFMPEG_STRICT_HINT)
+    for cand, src in cands:
+        exe = _probe_ffmpeg(cand)
+        if exe:
+            res = (exe if isinstance(exe, str) else cand, src)
+            _FFMPEG_CACHE[key] = res
+            return res
+    if (os.environ.get(_FFMPEG_STRICT_ENV) or "").strip() == "1":
+        raise SystemExit(_FFMPEG_STRICT_HINT)
+    res = ("ffmpeg", "fallback")
+    _FFMPEG_CACHE[key] = res
+    return res
+
+
 def _find_ffmpeg() -> str:
-    env = os.environ.get("FILMKIT_FFMPEG")
-    if env and os.path.exists(env):
-        return env
-    cands = [
-        os.path.join(os.environ.get("LOCALAPPDATA", ""), "Microsoft", "WinGet", "Links", "ffmpeg.exe"),
-        os.path.join(os.environ.get("USERPROFILE", ""), "AppData", "Local", "Microsoft",
-                     "WinGet", "Links", "ffmpeg.exe"),
-        "/usr/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/opt/homebrew/bin/ffmpeg",
-    ]
-    for c in cands:
-        if c and os.path.exists(c):
-            return c
-    return shutil.which("ffmpeg") or "ffmpeg"
+    """旧内部接口保留：返回探测到的 ffmpeg 可执行路径。"""
+    return _resolve_ffmpeg()[0]
+
+
+def _reset_ffmpeg_cache():
+    """清空探测缓存并立即重探（测试改过 os.environ / cwd 后必须调它）。
+
+    同时刷新模块级 FFMPEG，保证 filmkit.FFMPEG、ffprobe_path()、向上搜索布局
+    在同一个进程里改环境后能拿到新结果。
+    """
+    global FFMPEG
+    _FFMPEG_CACHE.clear()
+    _FFPROBE_CACHE.clear()
+    FFMPEG = _find_ffmpeg()
+    return FFMPEG
 
 
 FFMPEG = _find_ffmpeg()
 PY = sys.executable
 
 
+def _find_ffprobe(ffmpeg=None) -> str:
+    """ffprobe 定位：先找 ffmpeg 同目录的 ffprobe(.exe)，再用 shutil.which 兜底。
+
+    不再做 FFMPEG.replace("ffmpeg", "ffprobe")：ffmpeg 被改名（如 ffmpeg-full.exe）时
+    字符串替换出来的路径根本不存在，调用要到远处才炸。
+    """
+    ff = str(ffmpeg or FFMPEG)
+    hit = _FFPROBE_CACHE.get(ff)
+    if hit:
+        return hit
+    cand = ""
+    looks_pathy = os.path.isabs(ff) or os.sep in ff or bool(os.altsep and os.altsep in ff)
+    if looks_pathy:
+        d = os.path.dirname(os.path.abspath(ff))
+        names = ("ffprobe.exe", "ffprobe") if os.name == "nt" else ("ffprobe", "ffprobe.exe")
+        for name in names:
+            p = os.path.join(d, name)
+            if os.path.exists(p):
+                cand = p
+                break
+    if not cand:
+        cand = shutil.which("ffprobe") or "ffprobe"
+    _FFPROBE_CACHE[ff] = cand
+    return cand
+
+
 def ffprobe_path() -> str:
-    base = os.path.basename(FFMPEG)
-    cand = FFMPEG[: -len(base)] + ("ffprobe.exe" if base.endswith(".exe") else "ffprobe")
-    if os.path.exists(cand):
-        return cand
-    return shutil.which("ffprobe") or FFMPEG.replace("ffmpeg", "ffprobe")
+    """ffprobe 可执行文件路径（按 ffmpeg 路径缓存；_reset_ffmpeg_cache() 可清）。"""
+    return _find_ffprobe()
+
+
+def ffmpeg_source() -> str:
+    """可读的 ffmpeg 来源回显，如 "显式指定（FILMKIT_FFMPEG）: D:/tools/ffmpeg.exe"。
+
+    供 backend / 日志说明"到底用了哪个 ffmpeg、它从哪来的"。
+    """
+    path, src = _resolve_ffmpeg()
+    txt = "%s: %s" % (FFMPEG_SOURCE_LABELS.get(src, src), path)
+    env = (os.environ.get(_FFMPEG_ENV) or "").strip()
+    if env and src != "env":
+        txt += "；注意 %s=%r 不可用，已跳过" % (_FFMPEG_ENV, env)
+    return txt
 
 
 def _run(cmd, **kw):
@@ -96,11 +280,55 @@ FONT_CANDIDATES = {
 }
 
 
-def font(size: int, weight: str = "bold") -> ImageFont.FreeTypeFont:
-    key = (int(size), weight)
+# ---------------------------------------------------------------- 字体族（v0.5.0）
+# 换片要换气质，字体是第一眼。但"换字体族"必须同时换**所有**缓存键，
+# 否则会出现"用 A 字体量宽度、用 B 字体绘制"——文字直接溢出安全区。
+# 每一族都给中文回退：找不到 serif/kai 时退到同族 reg 再退 sans，**绝不退到 mono**（无中文字形）。
+FONT_FAMILIES = {
+    "sans": {                      # 现状：微软雅黑一族
+        "bold": [r"C:\Windows\Fonts\msyhbd.ttc", r"C:\Windows\Fonts\simhei.ttf",
+                 "/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc"],
+        "reg": [r"C:\Windows\Fonts\msyh.ttc", r"C:\Windows\Fonts\simhei.ttf",
+                "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc"],
+        "light": [r"C:\Windows\Fonts\msyhl.ttc", r"C:\Windows\Fonts\msyh.ttc"],
+    },
+    "serif": {                     # 杂志 / 史诗：宋体系
+        "bold": [r"C:\Windows\Fonts\NotoSerifSC-VF.ttf", r"C:\Windows\Fonts\simsun.ttc",
+                 r"C:\Windows\Fonts\msyhbd.ttc"],
+        "reg": [r"C:\Windows\Fonts\NotoSerifSC-VF.ttf", r"C:\Windows\Fonts\simsun.ttc",
+                r"C:\Windows\Fonts\msyh.ttc"],
+        "light": [r"C:\Windows\Fonts\NotoSerifSC-VF.ttf", r"C:\Windows\Fonts\simsun.ttc",
+                  r"C:\Windows\Fonts\msyh.ttc"],
+    },
+    "kai": {                       # 手绘纸感：楷体
+        "bold": [r"C:\Windows\Fonts\simkai.ttf", r"C:\Windows\Fonts\simfang.ttf",
+                 r"C:\Windows\Fonts\msyhbd.ttc"],
+        "reg": [r"C:\Windows\Fonts\simkai.ttf", r"C:\Windows\Fonts\simfang.ttf",
+                r"C:\Windows\Fonts\msyh.ttc"],
+        "light": [r"C:\Windows\Fonts\simkai.ttf", r"C:\Windows\Fonts\msyh.ttc"],
+    },
+    "round": {                     # 圆润：等线 / 雅黑回退
+        "bold": [r"C:\Windows\Fonts\Dengb.ttf", r"C:\Windows\Fonts\msyhbd.ttc"],
+        "reg": [r"C:\Windows\Fonts\Deng.ttf", r"C:\Windows\Fonts\msyh.ttc"],
+        "light": [r"C:\Windows\Fonts\Dengl.ttf", r"C:\Windows\Fonts\msyhl.ttc"],
+    },
+}
+FAMILY_IDS = tuple(FONT_FAMILIES.keys())
+
+
+def font(size: int, weight: str = "bold", family: str = "sans") -> ImageFont.FreeTypeFont:
+    """取字体。family 缺省 sans = v0.4 行为（老调用 font(46, "reg") 输出不变）。"""
+    fam = str(family or "sans")
+    if fam not in FONT_FAMILIES:
+        fam = "sans"                 # 未知族名退到 sans，不让拼写错误炸掉渲染
+    key = (int(size), weight, fam)
     if key in _font_cache:
         return _font_cache[key]
-    for path in FONT_CANDIDATES.get(weight, []) + FONT_CANDIDATES["reg"]:
+    chain = list(FONT_FAMILIES[fam].get(weight) or [])
+    chain += list(FONT_FAMILIES[fam]["reg"])
+    chain += list(FONT_CANDIDATES.get(weight) or [])
+    chain += list(FONT_CANDIDATES["reg"])
+    for path in chain:
         if path and os.path.exists(path):
             try:
                 f = ImageFont.truetype(path, int(size), index=0)
@@ -257,24 +485,25 @@ _wrap_cache = {}
 _tw_cache = {}
 
 
-def wrap_cn_cached(s: str, size: int, max_w: float, weight: str = "reg"):
+def wrap_cn_cached(s: str, size: int, max_w: float, weight: str = "reg",
+                   family: str = "sans"):
     """带缓存的换行。场景函数每帧都要调用，务必用这个版本。
 
     实测：每帧重新排版（12 张卡片 x 2 个 wrap_cn）会让单帧从 4.6ms 涨到 12ms。
     """
-    key = (s, int(size), int(max_w), weight)
+    key = (s, int(size), int(max_w), weight, str(family or "sans"))
     r = _wrap_cache.get(key)
     if r is None:
-        r = wrap_cn(s, font(size, weight), max_w)
+        r = wrap_cn(s, font(size, weight, family), max_w)
         _wrap_cache[key] = r
     return r
 
 
-def text_w_cached(s: str, size: int, weight: str = "reg") -> float:
-    key = (s, int(size), weight)
+def text_w_cached(s: str, size: int, weight: str = "reg", family: str = "sans") -> float:
+    key = (s, int(size), weight, str(family or "sans"))
     r = _tw_cache.get(key)
     if r is None:
-        r = text_w(s, font(size, weight))
+        r = text_w(s, font(size, weight, family))
         _tw_cache[key] = r
     return r
 
@@ -306,23 +535,29 @@ def check_bbox(box, safe=SAFE, tag=""):
     return []
 
 
-def fit_sub_lines(text: str, max_lines=2, max_w=1560, size=46, weight="reg"):
+def fit_sub_lines(text: str, max_lines=2, max_w=1560, size=46, weight="reg",
+                  family="sans"):
     """字幕折行：优先两行，超宽逐级缩字号。返回 (lines, font)。"""
     for sz in (size, int(size * 0.92), int(size * 0.84), int(size * 0.76)):
-        f = font(sz, weight)
+        f = font(sz, weight, family)
         lines = wrap_cn(text, f, max_w)
         if len(lines) <= max_lines:
             return lines, f
-    f = font(int(size * 0.76), weight)
+    f = font(int(size * 0.76), weight, family)
     return wrap_cn(text, f, max_w), f
 
 
-def draw_subtitle(img, text: str, alpha=1.0, size=46, y=None, band_w=None):
+def draw_subtitle(img, text: str, alpha=1.0, size=46, y=None, band_w=None,
+                  theme=None, family=None):
+    """烧字幕。v0.5.0 加 theme（stylekit 主题）与 family（字体族）；
+    theme=None 时与 v0.4 逐像素一致。"""
     if not text or alpha <= 0.01:
         return img
     if band_w is None:
         band_w = SUB_BAND[2] - SUB_BAND[0]
-    lines, f = fit_sub_lines(text, max_w=band_w, size=size)
+    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 = lines[:2]                       # 硬约束：最多两行
     lh = int(f.size * 1.32)
     cx = (SUB_BAND[0] + SUB_BAND[2]) // 2
@@ -335,10 +570,17 @@ def draw_subtitle(img, text: str, alpha=1.0, size=46, y=None, band_w=None):
     bx1 = cx + widest / 2 + 34
     by0 = base_y - 16
     by1 = base_y + total_h + 16
-    d.rounded_rectangle([bx0, by0, bx1, by1], radius=10, fill=(0, 0, 0, int(150 * alpha)))
+    if th is None:
+        plate = (0, 0, 0, int(150 * alpha))
+        ink = (245, 248, 252, int(255 * alpha))
+    else:
+        # 浅色主题不能"黑底白字"：背板取 bg2 半透，字取 ink
+        plate = tuple(th["bg2"]) + (int(170 * alpha),)
+        ink = tuple(th["ink"]) + (int(255 * alpha),)
+    d.rounded_rectangle([bx0, by0, bx1, by1], radius=10, fill=plate)
     for i, ln in enumerate(lines):
         lw = text_w(ln, f)
-        d.text((cx - lw / 2, base_y + i * lh), ln, font=f, fill=(245, 248, 252, int(255 * alpha)))
+        d.text((cx - lw / 2, base_y + i * lh), ln, font=f, fill=ink)
     return img
 
 
@@ -349,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:
@@ -480,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)
@@ -507,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))
@@ -599,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 -> 音频侧按它合成音效。
 
@@ -676,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
@@ -695,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)
@@ -726,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），避免重击被配乐吃掉。
 
@@ -749,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)
@@ -766,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)
@@ -791,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:
@@ -848,7 +1332,9 @@ def music_plan(script, has_music_file: bool = False):
     """
     mus = script.get("music") or {}
     raw = str(mus.get("mode") or "").strip().lower()
-    bpm = script.get("bpm")
+    # v0.5.0：bpm 可以是 "auto"（由 stylekit 按风格梯度和内容指纹决定）。
+    # 这里只判断"有没有 bpm 这个概念"，具体数值由 st_score 解析后传入 scorekit。
+    bpm = mus.get("bpm", script.get("bpm"))
     if raw == "auto":
         raw = ""
     if raw in ("off", "none", "mute"):
@@ -879,6 +1365,82 @@ def music_plan(script, has_music_file: bool = False):
     return "none", "缺省配乐：没有 bpm / music.chords / work/music.wav，本片无配乐"
 
 
+# ---------------------------------------------------------------- 风格 / 主题（v0.5.0）
+def _stylekit():
+    """惰性 import stylekit（同目录；缺了就明确报错，而不是静默回落到单一样式）。"""
+    try:
+        import stylekit as ST
+        return ST
+    except Exception as e:                                  # noqa: BLE001
+        raise RuntimeError("找不到 stylekit.py（v0.5.0 起 scenes/render 都依赖它，"
+                           "请与 filmkit.py 放在同一目录）：%s" % e)
+
+
+def resolve_theme(script, scene=None):
+    """给场景取主题字典。
+
+    优先级：scene["theme"]（同明暗族才允许） > script 里解析出的风格主题。
+    stylekit 不在时退回内置 tech-deep（只为了让老工作目录少一个文件也能跑）。
+    """
+    try:
+        ST = _stylekit()
+        plan = script.get("_style")
+        if not isinstance(plan, dict):
+            plan = ST.resolve_script_style(script)
+        th = dict(ST.THEMES[plan["theme_id"]])
+        sid = (scene or {}).get("theme")
+        if sid and sid in ST.THEMES:
+            alt = ST.THEMES[sid]
+            if ST.family_compatible(th, alt):
+                th = dict(alt)
+        return th
+    except Exception:                                       # noqa: BLE001
+        return _FALLBACK_THEME
+
+
+def style_plan(script):
+    """解析剧本的风格计划（含 legacy 判定）。stylekit 缺失时返回 legacy 计划。"""
+    try:
+        ST = _stylekit()
+        plan = script.get("_style")
+        return plan if isinstance(plan, dict) else ST.resolve_script_style(script)
+    except Exception:                                       # noqa: BLE001
+        return {"legacy": True, "style": "legacy", "theme_id": "tech-deep",
+                "music": {"style": "legacy", "bpm": script.get("bpm") or 120.0,
+                          "key": (script.get("music") or {}).get("key") or "Dm",
+                          "mood": "steady",
+                          "seed_effective": int((script.get("music") or {}).get("seed", 7) or 7)},
+                "voice": {"map": {}, "policy": {"auto": False, "jitter": 0.0, "max_distinct": 2}},
+                "pacing": {"lead": float(script.get("lead", 0.62)),
+                           "tail": float(script.get("tail", 0.92)),
+                           "min_dur": float(script.get("min_dur", 3.2)),
+                           "hold": float(script.get("hold", 0.0)),
+                           "item_stagger": 0.32}}
+
+
+# v0.4 的深蓝橙，作为"没装 stylekit 也能出片"的兜底（与 assets/scenes.py 的老 THEME 同值）
+_FALLBACK_THEME = {
+    "id": "tech-deep", "label": "科技深蓝", "keywords": (),
+    "bg": (7, 14, 26), "bg2": (17, 33, 54), "surface": (26, 42, 64),
+    "ink": (240, 245, 252), "muted": (150, 174, 200), "dim": (120, 142, 168),
+    "accent": (243, 132, 60), "accent2": (86, 170, 232),
+    "good": (108, 178, 110), "bad": (226, 96, 92), "rule": (255, 255, 255),
+    "vignette": 0.40, "vignette_tint": (0, 0, 0), "grain": 5.0, "grain_freq": 0.31,
+    "texture": "dots", "texture_alpha": 0.045,
+    "family": "sans",
+    "scale": {"display": (96, "bold"), "heading": (64, "bold"), "sub": (38, "light"),
+              "body": (34, "reg"), "kicker": (28, "bold"), "chip": (27, "reg"),
+              "brand": (23, "reg")},
+    "line_gap": 1.30, "tracking": 0.0,
+    "layout": "left-stack",
+    "card": {"radius": 14, "fill_a": 16, "outline_a": 28, "pad": 34, "h": 96, "gap": 118},
+    "safe_bias": 0,
+    "ease": "out3", "entrance_dx": 0, "entrance_dy": 26, "push": 0.04,
+    "item_stagger": 0.32, "transition": "black", "hud": "chip-left",
+    "qa": {"luma_max": 0.030, "flicker_thresh": 6.0, "dark": True},
+}
+
+
 # ---------------------------------------------------------------- 程序化音源
 def tone(freq, dur, sr=SR, amp=0.2, kind="sine", decay=2.2, harmonics=(1.0,)):
     """单音衰减。kind 参数保留以兼容 v0.1（目前只实现 sine）。"""
@@ -934,16 +1496,32 @@ def whoosh(dur=0.45, sr=SR, amp=0.06, seed=3):
 
 # ---------------------------------------------------------------- TTS
 def tts_key(text, voice, rate, pitch) -> str:
+    """v1 缓存键：4 参签名保持不变（selfcheck 与用户脚本都在用）。"""
     h = hashlib.sha1(("%s|%s|%s|%s" % (text, voice, rate, pitch)).encode("utf-8"))
     return h.hexdigest()[:16]
 
 
+def tts_key_v2(text, voice, rate, pitch, volume="+0%", trim=True, trim_db=-42.0,
+               keep_ms=None) -> str:
+    """v2 缓存键：把 volume / trim 开关也纳入。
+
+    为什么必须升 v2（v0.4 的真 bug）：trim 不进键，用户把 trim_silence 改成 false 之后，
+    老 meta 里 trimmed=True 仍会命中第一条分支，返回**裁剪版**——"关了裁剪其实没关"。
+    """
+    payload = "%s|%s|%s|%s|%s|%s|%s|%s" % ("v2", text, voice, rate, pitch,
+                                           volume, int(bool(trim)), round(float(trim_db), 3))
+    return hashlib.sha1(payload.encode("utf-8")).hexdigest()[:16]
+
+
 def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
-        cache=True, retries=4, trim=True, trim_db=-42.0):
+        cache=True, retries=4, trim=True, trim_db=-42.0, volume="+0%",
+        persona=None, tone=None):
     """逐句合成旁白（带输入校验的缓存 + 网络重试 + 可选尾静音裁剪）。
 
     v0.1 的缓存只判断文件是否存在，改一句台词会静默复用旧音频；
     v0.2 起把 text/voice/rate/pitch 的哈希写进 meta，变了就重新合成。
+    v0.5.0：加 volume（edge-tts 原生支持，之前一直没传）+ persona/tone 审计字段；
+            缓存键升 v2（把 volume/trim 也纳入，修掉"关了裁剪其实没关"的静默 bug）。
     trim=True 时另外落一份裁剪后的 wav 并在 meta.path 指向它，dur 为裁剪后实测时长。
     """
     out_mp3 = str(out_mp3)
@@ -951,16 +1529,26 @@ def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
     if d:
         os.makedirs(d, exist_ok=True)
     meta_path = out_mp3 + ".json"
-    key = tts_key(text, voice, rate, pitch)
+    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)
 
     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 not m.get("trimmed") and not trim:
                     return 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):
+                if m.get("trimmed") and m.get("path") and os.path.exists(m["path"]):
+                    return m
         except Exception:
             pass
 
@@ -972,7 +1560,7 @@ def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
             import edge_tts
 
             async def go():
-                c = edge_tts.Communicate(text, voice, rate=rate, pitch=pitch)
+                c = edge_tts.Communicate(text, voice, rate=rate, pitch=pitch, volume=vol)
                 await c.save(out_mp3)
 
             asyncio.run(go())
@@ -995,23 +1583,42 @@ def tts(text, out_mp3, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
         dur = len(pcm) / float(SR)
 
     m = dict(path=used, mp3=out_mp3, text=text, voice=voice, rate=rate, pitch=pitch,
-             key=key, dur=dur, dur_raw=dur_raw, trimmed=bool(trim))
+             volume=vol, key=key, spec_version=2, dur=dur, dur_raw=dur_raw,
+             trimmed=bool(trim), trim_db=float(trim_db))
+    if persona:
+        m["persona"] = str(persona)
+    if tone:
+        m["tone"] = str(tone)
     json.dump(m, open(meta_path, "w", encoding="utf-8"), ensure_ascii=False)
     return m
 
 
 def tts_batch(lines, workdir, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0Hz",
-              workers=4, trim=True):
-    """并发逐句合成（并发只影响墙钟，不影响产物：每句独立缓存）。"""
+              workers=4, trim=True, plan=None, trim_db=-42.0):
+    """并发逐句合成（并发只影响墙钟，不影响产物：每句独立缓存）。
+
+    v0.5.0：plan=[{voice,rate,pitch,volume,persona,tone}, ...]（与 lines 等长）时
+    逐句用各自的声线/语气；plan=None 时行为与 v0.4 完全一致。
+    """
     from concurrent.futures import ThreadPoolExecutor
 
     tts_dir = os.path.join(workdir, "tts")
     os.makedirs(tts_dir, exist_ok=True)
     results = [None] * len(lines)
+    specs = list(plan) if plan is not None else [None] * len(lines)
+    if len(specs) != len(lines):
+        raise ValueError("plan 长度 %d 与 lines 长度 %d 不一致" % (len(specs), len(lines)))
 
     def one(i, ln):
+        spec = specs[i] or {}
         mp3 = os.path.join(tts_dir, str(ln["id"]) + ".mp3")
-        m = tts(ln["text"], mp3, voice=voice, rate=rate, pitch=pitch, trim=trim)
+        m = tts(ln["text"], mp3,
+                voice=spec.get("voice") or voice,
+                rate=spec.get("rate") or rate,
+                pitch=spec.get("pitch") or pitch,
+                volume=spec.get("volume") or "+0%",
+                trim=trim, trim_db=trim_db,
+                persona=spec.get("persona"), tone=spec.get("tone"))
         row = dict(ln)
         row.update(m)
         print("  tts %-10s %6.2fs  %s" % (ln["id"], m["dur"], ln["text"][:34]), flush=True)
@@ -1027,7 +1634,7 @@ def tts_batch(lines, workdir, voice="zh-CN-YunyangNeural", rate="+0%", pitch="+0
 
 # ---------------------------------------------------------------- 时间轴
 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):
+                   hold=0.0, hold_map=None, bar=0.0, lead_map=None):
     """由实测语音时长反推时间轴。第一段 start 必须严格为 0。
 
     hold / hold_map（v0.3.0）：语音结束后额外停留的秒数——这就是 ai-history-film 的"停留窗口"：
@@ -1039,14 +1646,18 @@ def build_timeline(lines, lead=0.55, tail=0.85, min_dur=3.0, tail_map=None, max_
     for ln in lines:
         voice = float(ln.get("dur") or 0.0)
         extra = float(ln.get("hold", (hold_map or {}).get(ln["id"], hold)) or 0.0)
-        d = max(float(min_dur), float(lead) + voice + float((tail_map or {}).get(ln["id"], tail)) + extra)
+        # v0.5.0：lead 也支持逐句（行内 lead > lead_map > 全局），
+        # 与 tail_map 同构 —— 不同语气档的"句前呼吸"本来就不该一样长。
+        lead_i = float(ln.get("lead", (lead_map or {}).get(ln["id"], lead)))
+        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)
         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 + float(lead), 3),
-                           voice_end=round(t + float(lead) + voice, 3)))
+                           voice_start=round(t + lead_i, 3),
+                           voice_end=round(t + lead_i + voice, 3)))
         t += d
     if scenes:
         scenes[0]["start"] = 0.0
@@ -1097,7 +1708,8 @@ def write_srt(scenes, path, max_hold=None):
     return len(rows)
 
 
-def write_ass(scenes, path, max_hold=None, font_name="Microsoft YaHei", size=52):
+def write_ass(scenes, path, max_hold=None, font_name="Microsoft YaHei", size=52,
+              theme=None):
     """直接写 ASS，并在头里声明 PlayResX/Y=1920/1080。
 
     这样交 libass 不会按 PlayResY=288 反推，避免"字号小得看不见"
@@ -1110,6 +1722,18 @@ def write_ass(scenes, path, max_hold=None, font_name="Microsoft YaHei", size=52)
         s, cs = cs // 100, cs % 100
         return "%d:%02d:%02d.%02d" % (h, m, s, cs)
 
+    primary, outline, back = "&H00FCF8F5", "&H00101010", "&H96000000"
+    if isinstance(theme, dict):
+        # ASS 的颜色是 &HAABBGGRR（BGR 顺序 + alpha 在前，alpha 0=不透明）
+        def _ass(rgb, alpha=0):
+            r, g, b = rgb
+            return "&H%02X%02X%02X%02X" % (int(alpha), int(b), int(g), int(r))
+        primary = _ass(theme["ink"])
+        outline = _ass(theme["bg2"])
+        back = _ass(theme["surface"], 0x60)
+        fam = str(theme.get("family") or "sans")
+        # 字体族 -> Windows 上的实际字体名（libass 认 name 不认路径）
+        font_name = {"serif": "SimSun", "kai": "KaiTi", "round": "DengXian"}.get(fam, "Microsoft YaHei")
     head = [
         "[Script Info]",
         "ScriptType: v4.00+",
@@ -1122,8 +1746,8 @@ def write_ass(scenes, path, max_hold=None, font_name="Microsoft YaHei", size=52)
         "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, "
         "BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, "
         "BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
-        "Style: Default,%s,%d,&H00FCF8F5,&H000000FF,&H00101010,&H96000000,-1,0,0,0,100,100,0,0,"
-        "1,3,1,2,60,60,56,1" % (font_name, int(size)),
+        "Style: Default,%s,%d,%s,&H000000FF,%s,%s,-1,0,0,0,100,100,0,0,"
+        "1,3,1,2,60,60,56,1" % (font_name, int(size), primary, outline, back),
         "",
         "[Events]",
         "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
@@ -1237,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)
@@ -1276,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"),
@@ -1427,8 +2062,224 @@ def contact_sheet(frames, out_png, cols=4, thumb_w=480, labels=None):
     return out_png
 
 
+# ---------------------------------------------------------------- 拼接
+# 事故背景：混 fps 的片段以前直接 -c copy，拼出半速成片还不报错。
+# 现在拼前先查参数一致性；不一致或 copy 失败都自动降级重编码，只有重编码也失败才 raise。
+_LAST_CONCAT = {}
+
+
+def concat_last_state():
+    """最近一次 concat_segments 的结果（mode/reencoded/issues/out/concat_txt）。
+
+    返回副本；没跑过返回 {}。给测试和 backend 回显判断"这次到底有没有重编码"用，
+    不改变 concat_segments 的返回值（仍然是 str(out)）。
+    """
+    return dict(_LAST_CONCAT)
+
+
+def _set_concat_state(**kw):
+    _LAST_CONCAT.clear()
+    _LAST_CONCAT.update(kw)
+
+
+def _stderr_brief(raw, limit=300):
+    """ffmpeg stderr 摘要：真正的错误通常在一堆行里的最后几条，取末尾三行拼成一句。"""
+    txt = (raw or b"").decode("utf-8", "replace").strip()
+    lines = [ln.strip() for ln in txt.splitlines() if ln.strip()]
+    if not lines:
+        return "（ffmpeg 没有输出错误信息）"
+    return " | ".join(lines[-3:])[:limit]
+
+
+def _concat_quote(path):
+    """生成 ffmpeg concat 清单的一行：绝对路径 + 单引号转义。
+
+    concat demuxer 的引号规则照抄 shell：单引号内不能再出现单引号，
+    标准写法是把 ' 变成 '\''（先闭合、转义一个引号、再打开）。
+    路径里真的含单引号（Windows 文件名允许）也不会坏。
+    """
+    p = os.path.abspath(str(path)).replace("\\", "/")
+    return "file '%s'\n" % p.replace("'", "'\\''")
+
+
+def _probe_concat_part(path):
+    """单段探测（纯读）：返回 dict，ok=False 时 why 说明原因。"""
+    p = str(path)
+    if not os.path.isfile(p):
+        return dict(ok=False, path=p, why="文件不存在")
+    pr = probe(p)
+    streams = pr.get("streams") or []
+    v = next((s for s in streams if s.get("codec_type") == "video"), None)
+    if v is None:
+        return dict(ok=False, path=p, why="ffprobe 读不出视频流（文件损坏或不是视频）")
+    rate = str(v.get("r_frame_rate") or "0/0")
+    fps = 0.0
+    try:
+        num, _, den = rate.partition("/")
+        fps = float(num) / float(den or 1)
+    except Exception:                       # noqa: BLE001 —— 脏帧率不崩，交给诊断
+        fps = 0.0
+    dur = 0.0
+    try:
+        dur = float((pr.get("format") or {}).get("duration") or 0)
+    except Exception:                       # noqa: BLE001
+        dur = 0.0
+    a = next((s for s in streams if s.get("codec_type") == "audio"), None)
+    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)
+
+
+def _fmt_fps(info):
+    """帧率说人话：30/1 -> 30；30000/1001 -> 29.97；读不出来 -> 原始文本。"""
+    try:
+        fps = float(info.get("fps") or 0.0)
+    except Exception:                       # noqa: BLE001
+        fps = 0.0
+    if fps <= 0:
+        return str(info.get("fps_text") or "未知")
+    if abs(fps - round(fps)) < 0.01:
+        return "%d" % int(round(fps))
+    return "%.2f" % fps
+
+
+def _concat_issues(parts):
+    """逐段探测并与参照段比对（纯读）。返回 (infos, issues, ref_index)。
+
+    参照段 = 第一个能读出来的段（正常就是第 1 段）；每条 issue 都写清"哪段、差在哪"。
+    """
+    infos = [_probe_concat_part(p) for p in parts]
+    issues = []
+    ref = None
+    for i, inf in enumerate(infos):
+        if not inf.get("ok"):
+            issues.append("第 %d 段%s：%s" % (i + 1, inf.get("why", "探测失败"),
+                                             inf.get("path", parts[i])))
+            continue
+        if ref is None:
+            ref = i
+            continue
+        r = infos[ref]
+        who, base = "第 %d 段" % (i + 1), "第 %d 段" % (ref + 1)
+        if (inf["width"], inf["height"]) != (r["width"], r["height"]):
+            issues.append("%s分辨率 %dx%d != %s %dx%d"
+                          % (who, inf["width"], inf["height"], base, r["width"], r["height"]))
+        if abs(float(inf["fps"]) - float(r["fps"])) > 0.01:
+            issues.append("%s fps %s != %s fps %s"
+                          % (who, _fmt_fps(inf), base, _fmt_fps(r)))
+        if inf["codec"] != r["codec"]:
+            issues.append("%s视频编码 %s != %s %s"
+                          % (who, inf["codec"] or "?", base, r["codec"] or "?"))
+        if bool(inf["audio"]) != bool(r["audio"]):
+            issues.append("%s%s音轨，%s%s音轨"
+                          % (who, "有" if inf["audio"] else "无",
+                             base, "有" if r["audio"] else "无"))
+    return infos, issues, ref
+
+
+def concat_preflight(parts):
+    """拼接前的参数一致性检查（纯读：不写文件、不改全局状态、不碰 out）。
+
+    逐段 ffprobe 比对 width / height / r_frame_rate / codec_name（外加有无音轨），
+    以第一个能读出来的段为参照。返回 (ok, issues)：
+      ok=False 表示不能直接 -c copy，调用方应降级重编码；issues 是可直接打印的中文诊断。
+    注意：这里只回答"能不能 copy"，不检查画面内容 / 时间轴是否正确。
+    """
+    parts = [str(p) for p in parts]
+    if not parts:
+        return False, ["parts 为空（没有可拼接的片段）"]
+    _infos, issues, _ref = _concat_issues(parts)
+    return (not issues), issues
+
+
+def _concat_reencode(parts, out, infos, ref, lst):
+    """降级路径：重编码后再拼（libx264 crf20 + aac 192k），返回 str(out)。
+
+    不用"concat demuxer + 重编码"：那仍然要求各段分辨率/像素格式一致，混分辨率时
+    会花屏或直接失败。这里用 concat 滤镜，逐段把画面统一到参照段的宽高/帧率
+    （等比缩放 + 补边，不拉伸），音轨统一 48kHz 立体声；某段没音轨就补等长静音，
+    避免 v=1:a=1 的 concat 滤镜拒收。只有所有段都没音轨时才输出纯视频。
+    """
+    if ref is None:
+        raise RuntimeError(
+            "[concat] 降级失败：%d 段全都读不出视频流。先逐段跑 ffprobe -show_streams "
+            "确认文件没坏；concat.txt 保留在：%s" % (len(parts), lst))
+    r = infos[ref]
+    tw, th = int(r.get("width") or 0), int(r.get("height") or 0)
+    if tw <= 0 or th <= 0:
+        tw, th = W, H
+    # yuv420p 要求偶数宽高（参照段是奇数尺寸时裁掉 1px，别让重编码挂在最后一步）
+    tw, th = max(2, tw - tw % 2), max(2, th - th % 2)
+    fps_arg = str(r.get("fps_text") or "")
+    if fps_arg in ("", "0/0"):
+        fps_arg = "%g/1" % (float(r.get("fps") or 0) or float(FPS))
+    any_audio = any(inf.get("ok") and inf.get("audio") for inf in infos)
+    ref_dur = max(float(r.get("dur") or 0), 0.0)
+    fc = []
+    for i, inf in enumerate(infos):
+        fc.append("[%d:v]fps=%s,scale=%d:%d:force_original_aspect_ratio=decrease,"
+                  "pad=%d:%d:(ow-iw)/2:(oh-ih)/2,setsar=1,format=yuv420p[v%d]"
+                  % (i, fps_arg, tw, th, tw, th, i))
+        if not any_audio:
+            continue
+        if inf.get("ok") and inf.get("audio"):
+            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)
+            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 "")
+                     for i in range(len(parts)))
+    fc.append("%sconcat=n=%d:v=1:a=%d[v]%s"
+              % (labels, len(parts), 1 if any_audio else 0, "[a]" if any_audio else ""))
+    fc_text = ";".join(fc)
+
+    cmd = [FFMPEG, "-y", "-v", "error"]
+    for src in parts:
+        cmd += ["-i", str(src)]
+    script_path = None
+    try:
+        if len(fc_text) > 8000:
+            # 段数多时滤镜串会撞 Windows 命令行长度上限：落成临时脚本再引用
+            fd, script_path = tempfile.mkstemp(prefix="filmkit_concat_", suffix=".txt")
+            os.close(fd)
+            with open(script_path, "w", encoding="utf-8") as fh:
+                fh.write(fc_text)
+            cmd += ["-filter_complex_script", script_path]
+        else:
+            cmd += ["-filter_complex", fc_text]
+        cmd += ["-map", "[v]"]
+        if any_audio:
+            cmd += ["-map", "[a]", "-c:a", "aac", "-b:a", "192k"]
+        cmd += ["-c:v", "libx264", "-preset", "medium", "-crf", "20",
+                "-pix_fmt", "yuv420p", "-movflags", "+faststart", str(out)]
+        proc = _run(cmd)
+    finally:
+        if script_path:
+            try:
+                os.remove(script_path)
+            except OSError:
+                pass
+    if proc.returncode != 0:
+        raise RuntimeError(
+            "[concat] 重编码拼接也失败：%d 段既不能 -c copy，concat 滤镜重编码也没成。\n"
+            "  先逐段跑 ffprobe -show_streams 找坏段/缺流；concat.txt 保留在：%s\n"
+            "  ffmpeg: %s" % (len(parts), lst, _stderr_brief(proc.stderr)))
+    return str(out)
+
+
 def concat_segments(parts, out, workdir=None):
-    """分段无损拼接（各段编码参数必须一致，否则 copy 拼接会失败或花屏）。"""
+    """分段拼接：参数一致走 -c copy（快、无损），不一致或 copy 失败自动降级重编码。
+
+    向后兼容：签名和返回值不变（返回 str(out)）。降级发生时打印 [concat] 诊断，
+    并把 mode/issues/reencoded 记到 concat_last_state()，供调用方和测试判断。
+    """
+    parts = [str(p) for p in parts]
+    if not parts:
+        raise RuntimeError("concat_segments: parts 为空（没有可拼接的片段）")
+    _LAST_CONCAT.clear()                    # 失败时别让上一次的 mode 误导调用方
     lst = os.path.join(workdir or os.path.dirname(str(out)), "concat.txt")
     d = os.path.dirname(os.path.abspath(lst))
     if d:
@@ -1436,19 +2287,38 @@ def concat_segments(parts, out, workdir=None):
     # 必须写绝对路径：concat 文件里的相对路径按 ffmpeg 的 cwd 解析，
     # 而不是按 concat.txt 所在目录（实测会拼成 work2/work2/... 打不开）。
     with open(lst, "w", encoding="utf-8") as f:
-        for p in parts:
-            ap = os.path.abspath(str(p))
-            f.write("file '%s'\n" % ap.replace("\\", "/"))
-    p = _run([FFMPEG, "-y", "-v", "error", "-f", "concat", "-safe", "0", "-i", lst,
-              "-c", "copy", str(out)])
-    if p.returncode != 0:
-        raise RuntimeError("concat 失败: " + p.stderr.decode("utf-8", "replace")[:600])
+        for src in parts:
+            f.write(_concat_quote(src))
+    infos, issues, ref = _concat_issues(parts)
+    base_state = dict(out=str(out), parts=len(parts), issues=list(issues), concat_txt=lst)
+    if not issues:
+        proc = _run([FFMPEG, "-y", "-v", "error", "-f", "concat", "-safe", "0",
+                     "-i", lst, "-c", "copy", str(out)])
+        if proc.returncode == 0:
+            _set_concat_state(mode="copy", reencoded=False, **base_state)
+            return str(out)
+        detail = _stderr_brief(proc.stderr)
+        print("[concat] -c copy 失败（%s），降级为重编码拼接（libx264 crf20 + aac 192k）"
+              % detail, flush=True)
+        base_state = dict(base_state, copy_error=detail)
+    else:
+        print("[concat] 拼接前检查发现 %d 处参数不一致：" % len(issues), flush=True)
+        for it in issues:
+            print("   [concat] " + it, flush=True)
+        summ = "；".join(issues[:3])
+        if len(issues) > 3:
+            summ += "；等 %d 处" % len(issues)
+        print("[concat] 参数不一致（%s），已降级为重编码（libx264 crf20 + aac 192k）"
+              % summ, flush=True)
+        print("   [concat] concat.txt 保留供排查：%s" % lst, flush=True)
+    _concat_reencode(parts, out, infos, ref, lst)
+    _set_concat_state(mode="reencode", reencoded=True, **base_state)
     return str(out)
 
 
 # ---------------------------------------------------------------- 总质检
 def qa_report(path, expect_frames=None, ref_png=None, ref_sec=None, ref_img=None,
-              expected_subtitles=None, min_bitrate=0, notes=None):
+              expected_subtitles=None, min_bitrate=0, notes=None, theme=None):
     """分档质检：errors 必须修，warnings 看情况。
 
     v0.2 修正：
@@ -1510,6 +2380,13 @@ def qa_report(path, expect_frames=None, ref_png=None, ref_sec=None, ref_img=None
         warns.append("首尾之外检测到 %d 段长黑帧" % nb)
     if detect_silence(path) > 0:
         warns.append("检测到长静音段（确认是否有意留白）")
+    if isinstance(theme, dict):
+        # 主题体检的结论带进报告：这样"深色主题必然贴空窗阈值"这种事实不是靠嘴说
+        lmax = float(theme.get("qa", {}).get("luma_max", 0.045))
+        warns_t = ["主题 %s：空窗阈值 luma_max=%.3f、闪烁阈值 %.1f"
+                   % (theme.get("label") or theme.get("id"), lmax,
+                      float(theme.get("qa", {}).get("flicker_thresh", 6.0)))]
+        warns.extend(warns_t)
     quality = None
     if ref_img is not None or (ref_png and os.path.exists(ref_png)):
         q = encode_quality(path, ref_png, ref_sec, ref_img=ref_img)