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

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
 
 
@@ -848,7 +1090,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 +1123,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 +1254,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 +1287,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 +1318,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 +1341,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 +1392,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 +1404,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 +1466,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 +1480,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 +1504,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",
@@ -1427,8 +1809,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 +2034,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 +2127,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)