@oh-story/dsh 0.1.12 → 0.1.13

package/lib/video-recap/skills/video-assemble/scripts/lib.py

@@ -8,8 +8,6 @@ import tempfile
 
 
 # ── 配置 ──────────────────────────────────────────────────────────────
-_EXISTING_CONFIG_REF = globals().get("CONFIG")
-
 
 def env_int(name, default, *, minimum=None):
     """Read an integer env var; an unset/empty value yields `default`, a malformed one is an error."""
@@ -54,36 +52,25 @@ _foreign_source_audio = env_bool("FOREIGN_SOURCE_AUDIO", False)
 _foreign_under_narration_volume = 0.05  # original volume under narration when source audio is foreign
 
 CONFIG = {
-    "fade_ms": env_int("FADE_MS", 120, minimum=0),  # 每段 TTS 淡入淡出(ms)；过大会让紧凑的句子一顿一顿，120ms 防爆音又不发闷
-    "ducking_mode": "fixed",  # fixed | sidechaincompress | none
-    "ducking_threshold": 0.15,
-    "ducking_ratio": 3,
-    "ducking_attack": 10,
-    "ducking_release": 300,
-    "ducking_level_sc": 2.0,
-    "ducking_makeup": 1.2,
+    "fade_ms": 120,  # 每段 TTS 淡入淡出(ms)；过大会让紧凑的句子一顿一顿，120ms 防爆音又不发闷
     "ducking_narr_weight": 1.5,
-    "ducking_orig_volume": env_float("DUCKING_ORIG_VOLUME", 0.3, minimum=0.0),  # 解说时原声基准音量
-    # Derived report of the FOREIGN_SOURCE_AUDIO knob this skill implements: it selects the
-    # ducking volumes below. Declared so callers can see which policy is in effect.
-    "foreign_source_audio": _foreign_source_audio,
+    "ducking_orig_volume": 0.3,  # 解说时原声基准音量；仅在 beat 无放置信息时兜底
     "zone_ducking_volume": env_float("ZONE_DUCKING_VOLUME",
         _foreign_under_narration_volume if _foreign_source_audio else 0.12, minimum=0.0),  # 解说时原声压低到的音量
     "idle_orig_volume": env_float("IDLE_ORIG_VOLUME", 1.0, minimum=0.0),  # 解说块之间的"原声块"音量：默认满音量(1.0)，让精彩原声整段放出来，不被压低（用户要求解说成块、原声也成块）
     "duck_fade_seconds": env_float("DUCK_FADE_SECONDS", 0.3, minimum=0.0),  # 解说块/原声块切换的淡入淡出(秒)，略放宽到 0.3 让满音量↔压低的过渡更顺
     "duck_bridge_seconds": env_float("DUCK_BRIDGE_SECONDS", 1.5, minimum=0.0),  # 仅把间隔小于此值的相邻解说窗口并成一段压低；超过则视为作者特意留的"原声块"，原声放回满音量。默认 1.5s：解说块内部连续压低，块与块之间的留白放出满音量原声。该值只控制短间隔合并，不设定旁白/原声配额。调大→更连续铺底、原声块更少；调小→更碎
     "bgm_path": os.environ.get("BGM_PATH", "").strip(),  # 背景音乐文件(可选)，留空则不加 BGM
-    "source_video": os.environ.get("SOURCE_VIDEO", "").strip(),  # 剪辑模式下的原始视频(可选)，用于时间线/剪映导出引用原片片段
-    "source_video_explicit": False,  # 仅 assemble.py --source-video 显式传入时为 True；环境变量 SOURCE_VIDEO 不算显式
+    "source_video": "",  # 剪辑模式下的原始视频，只由 assemble.py --source-video 设置；用于时间线/剪映导出引用原片片段
     "export_jianying": env_bool("EXPORT_JIANYING", False),  # 渲染后可选导出剪映草稿(默认关；与核心解耦)
     "jianying_draft_dir": os.environ.get("JIANYING_DRAFT_DIR", "").strip(),  # 剪映草稿输出父目录(留空=work_dir)
     "jianying_bundle_media": env_bool("JIANYING_BUNDLE_MEDIA", True),  # 默认开：macOS 剪映沙箱读不到外部路径，须把素材拷进草稿目录
     "bgm_volume": env_float("BGM_VOLUME", 0.18, minimum=0.0),  # BGM 铺底音量
     "bgm_ducking_volume": env_float("BGM_DUCKING_VOLUME", 0.10, minimum=0.0),  # 旁白时 BGM 压低到的音量
     "narration_speed": env_float("NARRATION_SPEED", 1.15, minimum=0.5),  # 解说整体提速(atempo)，默认回到可懂区间；长片可设 1.0
-    "narration_cumulative_tempo_max": env_float("NARRATION_CUMULATIVE_TEMPO_MAX", 1.35, minimum=1.0),  # TTS rate × 全局 atempo × 段内 atempo 的累计上限
-    "narration_cumulative_tempo_hard_max": env_float("NARRATION_CUMULATIVE_TEMPO_HARD_MAX", 1.40, minimum=1.0),  # QC/阻断硬上限
-    "tts_segment_tempo_max": env_float("TTS_SEGMENT_TEMPO_MAX", 1.20, minimum=1.0),  # 兼容旧段内 atempo 上限；实际会被累计预算收紧
+    "narration_cumulative_tempo_max": 1.35,  # TTS rate × 全局 atempo × 段内 atempo 的累计上限
+    "narration_cumulative_tempo_hard_max": 1.40,  # QC/阻断硬上限
+    "tts_segment_tempo_max": 1.20,  # 兼容旧段内 atempo 上限；实际会被累计预算收紧
     "mask_source_subtitles": env_bool("MASK_SOURCE_SUBTITLES", False),  # 遮挡原片烧录字幕；必须配合显式 SOURCE_SUBTITLE_MASK_POLICY
     "source_subtitle_mask_policy_declared": bool(os.environ.get("SOURCE_SUBTITLE_MASK_POLICY", "").strip()),
     "source_subtitle_mask_policy": (
@@ -96,16 +83,17 @@ CONFIG = {
     "subtitle_mask_padding": env_int("SUBTITLE_MASK_PADDING", 4, minimum=0),
     "subtitle_y_top": env_int("SUBTITLE_Y_TOP", -1, minimum=-1),  # 自动旋转后的显示画布坐标；top/bot 同时有效时贴合原字幕带
     "subtitle_y_bot": env_int("SUBTITLE_Y_BOT", -1, minimum=-1),
-    "narration_delay_seconds": env_float("NARRATION_DELAY_SECONDS", 0.0, minimum=0.0),  # 默认严格采用 Agent 写入的 start；旧项目可显式恢复延迟
-    "narration_tighten": env_bool("NARRATION_TIGHTEN", True),  # 段落内把句子紧贴上一句实际收尾播放，句间间隔稳定≤tight_pause，杜绝"一句解说一段空白"的卡顿
-    "narration_run_gap_seconds": env_float("NARRATION_RUN_GAP_SECONDS", 1.6, minimum=0.0),  # 作者留白超过此值=新段落（让精彩原声透出）；小于则视为同一连续段落
-    "narration_tight_pause_seconds": env_float("NARRATION_TIGHT_PAUSE_SECONDS", 0.35, minimum=0.0),  # 段落内句间固定间隔(秒)
-    "narration_max_pull_seconds": env_float("NARRATION_MAX_PULL_SECONDS", 1.2, minimum=0.0),  # 收紧时一句最多比作者标注提前的秒数（漂移上限，越小越贴画面）
-    "narration_tail_pad_seconds": 0.1,  # 解说尾部最少留白；短 slot 会自动压低 delay 避免截断
+    # 段落内把句子紧贴上一句实际收尾播放，句间间隔稳定≤tight_pause，杜绝"一句解说一段空白"的卡顿
+    "narration_run_gap_seconds": 1.6,  # 作者留白超过此值=新段落（让精彩原声透出）；小于则视为同一连续段落
+    "narration_tight_pause_seconds": 0.35,  # 段落内句间固定间隔(秒)
+    "narration_max_pull_seconds": 1.2,  # 收紧时一句最多比作者标注提前的秒数（漂移上限，越小越贴画面）
     "quiet_overlap_min_ratio": 0.8,  # 解说段至少多少比例落在安静窗口内才标记为非对白重叠
     "speech_ducking_volume": env_float("SPEECH_DUCKING_VOLUME",
         _foreign_under_narration_volume if _foreign_source_audio else 0.2, minimum=0.0),    # 解说与对白重叠时原声音量
     "burn_subtitles": env_bool("BURN_SUBTITLES", True),  # 烧录解说字幕（默认开；遮挡原字幕后需自带字幕，否则字幕区空白）
+    # 显式要求烧录（设了 BURN_SUBTITLES 或传了 --burn-subtitles）时缺 libass 直接失败；只是默认开时降级为外挂 .srt
+    "burn_subtitles_explicit": "BURN_SUBTITLES" in os.environ,
+    "burn_subtitles_degraded": None,  # 降级原因（如 ffmpeg_missing_libass），由 render_preflight 写入
     "subtitle_original_in_gaps": env_bool("SUBTITLE_ORIGINAL_IN_GAPS", True),  # 原声留白处补烧原声台词字幕（来自 ASR）
     "force_video_reencode": env_bool("FORCE_VIDEO_REENCODE", False),  # 组装时重编码视频，修复部分容器时间戳问题
     # 成片压制（仅在重编码时生效：烧字幕/遮罩/缩放/FORCE_VIDEO_REENCODE 任一触发重编码）。
@@ -115,9 +103,11 @@ CONFIG = {
     # 成片末端整体响度归一（默认混音偏轻，归一后更接近常见短视频响度；样片约 -11.9，默认取更安全的 -14）
     "final_loudnorm": env_bool("FINAL_LOUDNORM", True),  # 组装末端做一次整体响度归一
     "target_lufs": env_float("TARGET_LUFS", -14.0),       # 目标综合响度 (LUFS)
-    "target_true_peak": env_float("TARGET_TRUE_PEAK", -1.0),  # 目标真峰值 (dBTP)
-    "target_lra": env_float("TARGET_LRA", 11.0),          # 目标响度范围 (LU)
-    "final_limiter_peak": env_float("FINAL_LIMITER_PEAK", 0.98, minimum=0.1),  # loudnorm 后峰值保护 limiter
+    "target_true_peak": -1.0,  # 目标真峰值 (dBTP)
+    "target_lra": 11.0,          # 目标响度范围 (LU)
+    "final_limiter_peak": 0.98,  # loudnorm 后峰值保护 limiter
+    # 峰值放不下线性增益时，先过真峰值限幅器再线性增益；限幅器最多削这么多 dB，超出部分才下调目标响度。0=不限幅
+    "loudness_limiter_max_db": env_float("LOUDNESS_LIMITER_MAX_DB", 6.0, minimum=0.0),
     "subtitle_font_name": os.environ.get("SUBTITLE_FONT_NAME", "Arial"),
     # 可选字体文件：ASS 烧录经 fontsdir 加载，画面文字经 drawtext fontfile 使用；family 名仍由 SUBTITLE_FONT_NAME 指定
     "subtitle_font_file": os.environ.get("SUBTITLE_FONT_FILE", "").strip(),
@@ -127,18 +117,14 @@ CONFIG = {
     "subtitle_outline": env_float("SUBTITLE_OUTLINE", 2.0, minimum=0.0),
     "subtitle_shadow": env_float("SUBTITLE_SHADOW", 1.0, minimum=0.0),
     "subtitle_margin_v": env_int("SUBTITLE_MARGIN_V", 48, minimum=0),
-    "subtitle_margin_l": env_int("SUBTITLE_MARGIN_L", 40, minimum=0),
-    "subtitle_margin_r": env_int("SUBTITLE_MARGIN_R", 40, minimum=0),
+    "subtitle_margin_l": 40,
+    "subtitle_margin_r": 40,
     "subtitle_alignment": env_int("SUBTITLE_ALIGNMENT", 2, minimum=1),
     "subtitle_max_chars": env_int("SUBTITLE_MAX_CHARS", 20, minimum=6),
     "subtitle_max_lines": env_int("SUBTITLE_MAX_LINES", 2, minimum=1),
     "subtitle_play_res_x": env_int("SUBTITLE_PLAY_RES_X", 1280, minimum=1),
     "subtitle_play_res_y": env_int("SUBTITLE_PLAY_RES_Y", 720, minimum=1),
 }
-if isinstance(_EXISTING_CONFIG_REF, dict):
-    _EXISTING_CONFIG_REF.clear()
-    _EXISTING_CONFIG_REF.update(CONFIG)
-    CONFIG = _EXISTING_CONFIG_REF
 
 def narration_tempo_budget(tts_rate_offset=0.0):
     """Return the canonical tempo budget shared by voiceover and assemble.

package/lib/video-recap/skills/video-assemble/scripts/loudness.py

@@ -0,0 +1,332 @@
+"""Final-mix loudness: two-pass linear loudnorm, behind a true-peak limiter when peaks block the gain.
+
+ffmpeg's `loudnorm=linear=true` applies one constant gain only while
+measured_TP + (I - measured_I) <= TP and measured_LRA <= LRA; otherwise it silently runs
+dynamic (3-second AGC) normalisation, which pumps. Real mixes often carry a few transients
+(gunshots, music hits) at 0 dBTP, so reaching TARGET_LUFS with one gain needs those peaks
+limited first. The chain then is: constant pre-gain -> oversampled lookahead limiter (sample
+peaks at 4x the rate approximate true peaks) -> second loudnorm pass in linear mode, measured
+on the limited signal, that trims the last fraction of a LU without crossing TP.
+
+Every stage aims at a pre-encode true-peak target (`peak_target`, default TP). The AAC
+encode raises the delivered true peak over it, so `codec_peak.py` renders the first time
+CODEC_PEAK_HEADROOM_DB under TP and lowers the target further when the delivered file
+still measures over TP.
+"""
+
+import functools
+import json
+import math
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from lib import CONFIG, filter_file_args, log, run_cmd
+
+# loudnorm's LRA option range is 1-20 in older ffmpeg (1-50 in current releases).
+_LOUDNORM_MAX_LRA = 20.0
+# The limiter ceiling sits this far under the true-peak target, leaving the linear loudnorm
+# stage room to make up the loudness the limiter shaved off (about 0.3 LU at 6 dB of
+# reduction on a real film mix, 1.1 LU at 10 dB).
+LIMITER_HEADROOM_DB = 1.0
+# The limiter runs at 4x the 48 kHz mix rate so its sample peaks track the true peak.
+_LIMITER_OVERSAMPLE_RATE = 192000
+_LIMITER_ATTACK_MS = 5
+_LIMITER_RELEASE_MS = 100
+# AAC at 192 kb/s raised the true peak 0.3-1.4 dB over the loudnorm stage's output on real
+# renders (most on heavily limited mixes); the first render aims this far under TP.
+CODEC_PEAK_HEADROOM_DB = 0.5
+
+
+def first_render_peak_target():
+    """The pre-encode true-peak target (dBTP) of the first render: TP minus codec headroom."""
+    return round(float(CONFIG["target_true_peak"]) - CODEC_PEAK_HEADROOM_DB, 2)
+
+
+def _peak_target(peak_target):
+    return float(CONFIG["target_true_peak"]) if peak_target is None else float(peak_target)
+
+
+def _limiter_filter():
+    return f"alimiter=limit={CONFIG['final_limiter_peak']:.2f}:level=false"
+
+
+@functools.lru_cache(maxsize=None)
+def _alimiter_compensates_latency():
+    """Whether this ffmpeg's alimiter has the `latency` option (asked once per process).
+
+    Without it the lookahead delays the audio by the attack time (5 ms).
+    """
+    if shutil.which("ffmpeg") is None:
+        return False
+    result = subprocess.run(["ffmpeg", "-hide_banner", "-h", "filter=alimiter"],
+                            stdin=subprocess.DEVNULL, capture_output=True, text=True,
+                            encoding="utf-8", errors="replace", timeout=20)
+    return "latency" in result.stdout
+
+
+def _measured_values(measured):
+    """(I, TP, LRA, threshold) from a loudnorm measurement, or None when it is unusable."""
+    try:
+        values = [float(measured[key])
+                  for key in ("input_i", "input_tp", "input_lra", "input_thresh")]
+    except (KeyError, TypeError, ValueError):
+        return None
+    measured_i, measured_tp, measured_lra, measured_thresh = values
+    # ffmpeg's own "not measured" sentinels (silence measures -inf / -70 / 0).
+    if (not all(math.isfinite(v) for v in values) or measured_tp == 99
+            or measured_thresh == -70 or measured_lra == 0 or measured_i == 0):
+        return None
+    return values
+
+
+def _linear_loudnorm_targets(measured, peak_target=None):
+    """Second-pass targets that keep loudnorm linear, or None when no such targets exist.
+
+    The integrated target is lowered until the gained true peak fits under `peak_target`
+    (default TP; quieter than TARGET_LUFS instead of compressed), and the LRA target, which
+    linear mode never applies, is raised to the measured range.
+    """
+    values = _measured_values(measured)
+    if values is None:
+        return None
+    measured_i, measured_tp, measured_lra, _thresh = values
+    requested = float(CONFIG["target_lufs"])
+    true_peak = _peak_target(peak_target)
+    # 0.01 LU under the exact limit: ffmpeg compares the floating-point sum.
+    peak_limited = math.floor((true_peak - measured_tp + measured_i) * 100) / 100 - 0.01
+    integrated = round(min(requested, peak_limited), 2)
+    lra = max(float(CONFIG["target_lra"]), measured_lra)
+    if integrated < -70 or lra > _LOUDNORM_MAX_LRA:
+        return None
+    return {
+        "integrated": integrated,
+        "lra": lra,
+        "true_peak": true_peak,
+        "gain_capped_db": round(max(0.0, requested - integrated), 2),
+    }
+
+
+def _peak_limiter_plan(measured, peak_target=None):
+    """Pre-gain and ceiling for the true-peak limiter, or None when it is not needed.
+
+    The ceiling sits LIMITER_HEADROOM_DB under `peak_target` (default TP). None when one
+    linear gain already reaches TARGET_LUFS under the target, when the measurement is
+    unusable or too wide for linear mode (a limiter does not narrow LRA), or when
+    LOUDNESS_LIMITER_MAX_DB is 0. Above that maximum the pre-gain stops where the limiter
+    would remove exactly the maximum; the rest of the gain is capped as before.
+    """
+    values = _measured_values(measured)
+    max_reduction = float(CONFIG["loudness_limiter_max_db"])
+    if values is None or max_reduction <= 0:
+        return None
+    measured_i, measured_tp, measured_lra, _thresh = values
+    if max(float(CONFIG["target_lra"]), measured_lra) > _LOUDNORM_MAX_LRA:
+        return None
+    gain = float(CONFIG["target_lufs"]) - measured_i
+    true_peak = _peak_target(peak_target)
+    if measured_tp + gain <= true_peak:
+        return None
+    ceiling = round(true_peak - LIMITER_HEADROOM_DB, 2)
+    required = measured_tp + gain - ceiling
+    pre_gain = min(gain, ceiling + max_reduction - measured_tp)
+    return {
+        "pre_gain_db": round(pre_gain, 2),
+        "ceiling_dbtp": ceiling,
+        "required_reduction_db": round(required, 2),
+        "max_reduction_db": max_reduction,
+    }
+
+
+def _peak_limiter_chain(limiter):
+    """Constant pre-gain, then the oversampled lookahead limiter, back at the mix rate."""
+    limit = 10 ** (limiter["ceiling_dbtp"] / 20)
+    latency = ":latency=true" if _alimiter_compensates_latency() else ""
+    return (
+        f"volume={limiter['pre_gain_db']}dB,aresample={_LIMITER_OVERSAMPLE_RATE},"
+        f"alimiter=limit={limit:.6f}:attack={_LIMITER_ATTACK_MS}"
+        f":release={_LIMITER_RELEASE_MS}:level=false{latency},aresample=48000"
+    )
+
+
+def _loudnorm_stage_measurement(measured, limiter):
+    """What the second loudnorm pass sees: the limited signal when a limiter runs."""
+    return limiter["measurement"] if limiter else measured
+
+
+def _loudness_mode(measured=None, normalization_type=None, limiter=None):
+    """`limiter_only`, `equivalent` (single pass), or the two-pass mode ffmpeg really ran.
+
+    `normalization_type` is what the final render's loudnorm reported; without it the mode
+    is predicted from whether `_linear_loudnorm_targets` found linear targets.
+    """
+    if not CONFIG["final_loudnorm"]:
+        return "limiter_only"
+    if not measured:
+        return "equivalent"
+    if normalization_type is None:
+        stage = _loudnorm_stage_measurement(measured, limiter)
+        normalization_type = "linear" if _linear_loudnorm_targets(stage) else "dynamic"
+    if normalization_type != "linear":
+        return "two_pass_dynamic"
+    return "two_pass_linear_peak_limited" if limiter else "two_pass_linear"
+
+
+def final_loudnorm_filter(measured=None, limiter=None, peak_target=None):
+    """Final-mix loudness normalization/limiter filter from CONFIG.
+
+    Ducking branches set only relative balance; this single stage owns the
+    absolute output loudness so the recap is not left too quiet. When `measured`
+    is supplied from a first loudnorm pass, ffmpeg runs the deterministic second
+    pass with the targets from `_linear_loudnorm_targets`, behind the `limiter` chain
+    when one was planned (its loudnorm then uses the limited signal's measurement);
+    without it we still force the same target and peak limiter as a documented
+    equivalent/fallback path. Every path aims at `peak_target` (default TP).
+    """
+    if not CONFIG["final_loudnorm"]:
+        return _limiter_filter()
+    stage = _loudnorm_stage_measurement(measured, limiter) if measured else None
+    targets = _linear_loudnorm_targets(stage, peak_target) if stage else None
+    integrated = targets["integrated"] if targets else CONFIG["target_lufs"]
+    lra = targets["lra"] if targets else CONFIG["target_lra"]
+    filt = (
+        f"loudnorm=I={integrated}"
+        f":TP={_peak_target(peak_target)}"
+        f":LRA={lra}"
+        f":linear=true"
+    )
+    if stage:
+        for src, dst in (
+            ("input_i", "measured_I"),
+            ("input_tp", "measured_TP"),
+            ("input_lra", "measured_LRA"),
+            ("input_thresh", "measured_thresh"),
+            ("target_offset", "offset"),
+        ):
+            if src in stage:
+                filt += f":{dst}={stage[src]}"
+    filt += ":print_format=summary"
+    if measured and limiter:
+        filt = f"{_peak_limiter_chain(limiter)},{filt}"
+    return f"{filt},{_limiter_filter()}"
+
+
+def _parse_loudnorm_json(text):
+    """Extract ffmpeg loudnorm JSON from stderr/stdout."""
+    for match in reversed(list(re.finditer(r"\{[\s\S]*?\}", text))):
+        try:
+            data = json.loads(match.group(0))
+        except ValueError:
+            continue
+        if {"input_i", "input_tp", "input_lra", "input_thresh", "target_offset"} <= set(data):
+            return data
+    return None
+
+
+def _loudnorm_summary_value(text, label):
+    """Last `<label>: <number>` in a loudnorm summary (None when absent, e.g. `-inf`)."""
+    matches = re.findall(rf"{label}:\s*([+-]?\d+(?:\.\d+)?)\b", text)
+    return float(matches[-1]) if matches else None
+
+
+def loudnorm_final_pass(stderr, measured=None, limiter=None, peak_target=None):
+    """What the final render's loudness stage actually did, from its `print_format=summary`.
+
+    `normalization_type` is `linear` or `dynamic` (None when ffmpeg printed no summary);
+    `target` holds the second-pass targets when a first pass measured the mix, and its
+    `gain_capped_db` is how far the delivered target sits under TARGET_LUFS. `peak_limiter`
+    is the limiter that ran before it (None when none did). `output_true_peak` is the
+    stage's pre-encode output; the AAC file's own peak is `codec_peak`'s `delivered`.
+    """
+    text = stderr or ""
+    kinds = re.findall(r"Normalization Type:\s*(Linear|Dynamic)", text)
+    stage = _loudnorm_stage_measurement(measured, limiter) if measured else None
+    return {
+        "normalization_type": kinds[-1].lower() if kinds else None,
+        "target": _linear_loudnorm_targets(stage, peak_target) if stage else None,
+        "output_integrated": _loudnorm_summary_value(text, "Output Integrated"),
+        "output_true_peak": _loudnorm_summary_value(text, "Output True Peak"),
+        "peak_limiter": limiter if measured else None,
+    }
+
+
+def _loudnorm_first_pass_filter():
+    return (
+        f"loudnorm=I={CONFIG['target_lufs']}"
+        f":TP={CONFIG['target_true_peak']}"
+        f":LRA={CONFIG['target_lra']}"
+        f":print_format=json"
+    )
+
+
+def _measure_loudness(input_video, narration_wav, original_audio_input,
+                      bgm_input, filter_complex, work_dir, pre_chain=None):
+    """Measure the exact mixed audio graph (after `pre_chain` when given) before the render.
+
+    Returns ffmpeg loudnorm JSON, or None when probing fails.
+    """
+    stage = f"{pre_chain}," if pre_chain else ""
+    probe_fc = f"{filter_complex};[aout]{stage}{_loudnorm_first_pass_filter()}[lnprobe]"
+    probe_script = Path(work_dir) / ".filter_complex_loudnorm_probe.txt"
+    probe_script.write_text(probe_fc, encoding="utf-8")
+    cmd = [
+        "ffmpeg", "-y",
+        "-i", str(input_video),
+        "-i", str(narration_wav),
+        *original_audio_input,
+        *bgm_input,
+        *filter_file_args("filter_complex", probe_script),
+        "-map", "[lnprobe]",
+        "-f", "null", "-",
+    ]
+    try:
+        result = run_cmd(cmd)
+    finally:
+        probe_script.unlink(missing_ok=True)
+    if result.returncode != 0:
+        log(f"  ⚠️ loudnorm 测量失败: {result.stderr}")
+        return None
+    measured = _parse_loudnorm_json(result.stdout + "\n" + result.stderr)
+    if not measured:
+        log("  ⚠️ loudnorm 测量未返回 JSON")
+    return measured
+
+
+def plan_final_loudness(input_video, narration_wav, original_audio_input,
+                        bgm_input, filter_complex, work_dir, peak_target=None, measured=None):
+    """Measure the mix and pick the final loudness stage for `peak_target`: (measured, limiter).
+
+    `measured` is the first-pass loudnorm JSON (None: single-pass fallback); a caller that
+    already has it passes it in and only the limited signal is measured. `limiter` is
+    the planned true-peak limiter plus `measurement` (the limited signal's loudnorm JSON)
+    and `reduction_db` (measured true peak before minus after it), or None when one linear
+    gain fits or the limited signal could not be measured (the gain is then capped).
+    """
+    if not CONFIG["final_loudnorm"]:
+        return None, None
+    args = (input_video, narration_wav, original_audio_input, bgm_input, filter_complex,
+            work_dir)
+    measured = measured or _measure_loudness(*args)
+    if not measured:
+        log("  ⚠️ loudnorm 首遍测量不可用，降级到单遍目标滤镜+limiter")
+        return None, None
+    limiter = _peak_limiter_plan(measured, peak_target)
+    if limiter:
+        limited = _measure_loudness(*args, pre_chain=_peak_limiter_chain(limiter))
+        if limited and _linear_loudnorm_targets(limited, peak_target):
+            reduction = (float(measured["input_tp"]) + limiter["pre_gain_db"]
+                         - float(limited["input_tp"]))
+            limiter = {**limiter, "reduction_db": round(reduction, 2), "measurement": limited}
+            log(f"  成片真峰值限幅：先增益 {limiter['pre_gain_db']} dB，峰值压到 "
+                f"{limiter['ceiling_dbtp']} dBTP（削去 {limiter['reduction_db']} dB），"
+                "再线性增益到目标响度")
+        else:
+            log("  ⚠️ 限幅后的混音无法测量或无法线性归一，改为下调目标响度")
+            limiter = None
+    targets = _linear_loudnorm_targets(_loudnorm_stage_measurement(measured, limiter),
+                                       peak_target)
+    if targets and targets["gain_capped_db"] > 0:
+        log(f"  成片目标响度从 {CONFIG['target_lufs']} 降到 {targets['integrated']} LUFS"
+            f"（限幅上限 {CONFIG['loudness_limiter_max_db']} dB），保持线性增益")
+    return measured, limiter