@oh-story/dsh 0.1.12 → 0.1.13

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

@@ -4,49 +4,33 @@ import json
 import os
 from pathlib import Path
 
-from artifacts import _explicit_source_video
-from lib import log, run_cmd
-
-def _load_cut_timeline_plan(work_dir):
-    """The cut plan, preferring clip_plan_validated.json unless the raw plan is newer; None in full mode."""
-    raw_plan_path = Path(work_dir) / "clip_plan.json"
-    validated_plan_path = Path(work_dir) / "clip_plan_validated.json"
-    if not validated_plan_path.exists():
-        return json.loads(raw_plan_path.read_text(encoding="utf-8")) if raw_plan_path.exists() else None
-    if not raw_plan_path.exists():
-        return json.loads(validated_plan_path.read_text(encoding="utf-8"))
-    if validated_plan_path.stat().st_mtime_ns >= raw_plan_path.stat().st_mtime_ns:
-        return json.loads(validated_plan_path.read_text(encoding="utf-8"))
-    return json.loads(raw_plan_path.read_text(encoding="utf-8"))
-
+from lib import CONFIG, log, run_cmd
 
 def _plan_clip_spans(work_dir):
     """Cut-mode clip spans [{source_start, source_end, output_start, output_end, entry}], or None.
 
-    clip_plan.json is either a bare list or {"clips": [...]}; a clip names its source range as
-    source_start/source_end or start/end. Clips without explicit output_start/output_end are laid
-    out back to back on the output timeline.
+    Read only clip_plan_validated.json: edited_source.mp4 was rendered from it, and its clips
+    carry explicit source/output spans. Without it this is full mode (None = identity mapping).
+    A validated plan older than clip_plan.json no longer describes the picture, so it fails.
     """
-    plan = _load_cut_timeline_plan(work_dir)
-    if plan is None:
+    work_dir = Path(work_dir)
+    validated_path = work_dir / "clip_plan_validated.json"
+    if not validated_path.exists():
         return None
-    entries = plan["clips"] if isinstance(plan, dict) else plan
-    spans, cursor = [], 0.0
-    for entry in entries:
-        ss = float(entry.get("source_start", entry.get("start")))
-        se = float(entry.get("source_end", entry.get("end")))
-        if "output_start" in entry:
-            out_s, out_e = float(entry["output_start"]), float(entry["output_end"])
-            cursor = max(cursor, out_e)
-        else:
-            out_s, out_e = cursor, cursor + (se - ss)
-            cursor = out_e
-        spans.append({
-            "source_start": ss, "source_end": se,
-            "output_start": out_s, "output_end": out_e,
+    raw_path = work_dir / "clip_plan.json"
+    if raw_path.exists() and validated_path.stat().st_mtime_ns < raw_path.stat().st_mtime_ns:
+        raise ValueError(
+            "clip_plan.json 在剪辑之后被修改，clip_plan_validated.json 已过期；请先重新剪辑再组装"
+        )
+    plan = json.loads(validated_path.read_text(encoding="utf-8"))
+    return [
+        {
+            "source_start": float(entry["source_start"]), "source_end": float(entry["source_end"]),
+            "output_start": float(entry["output_start"]), "output_end": float(entry["output_end"]),
             "entry": entry,
-        })
-    return spans
+        }
+        for entry in plan["clips"]
+    ]
 
 
 def _ratio_to_float(value, default=1.0):
@@ -152,10 +136,10 @@ def _build_video_clips(input_video, work_dir, duration_s):
 
     In cut mode each plan entry becomes a clip referencing the ORIGINAL source
     range. Multi-source validated plans carry per-clip source_path and do not
-    require an explicit ambient --source-video. Without any declared source (full
+    require --source-video. Without any declared source (full
     mode, or cut mode rendered without --source-video) the rendered input is one clip.
     """
-    explicit_source_video = _explicit_source_video()
+    explicit_source_video = CONFIG["source_video"]
     spans = _plan_clip_spans(work_dir)
     multi_source = spans is not None and any(span["entry"].get("source_path") for span in spans)
     if spans is None or not (explicit_source_video or multi_source):
@@ -188,3 +172,139 @@ def _build_video_clips(input_video, work_dir, duration_s):
                       "timeline_start": timeline_start,
                       "timeline_end": timeline_end})
     return clips
+
+
+# Delivered-picture format. `_probe_video_format`, `_output_color_tags`,
+# `_color_tag_filter` and `_color_tag_args` are intentional function-level copies shared
+# with the cut render (tests/orchestrator/test_render_format_parity.py keeps them identical).
+_COLOR_FIELDS = (
+    ("color_space", "colorspace"),
+    ("color_primaries", "color_primaries"),
+    ("color_transfer", "color_trc"),
+)
+_UNTAGGED_COLOR = {None, "", "unknown", "unspecified", "reserved", "N/A"}
+# ffprobe's colour space for an RGB picture (PNG, libx264rgb, FFV1 RGB). ffmpeg rejects
+# `-colorspace gbr`, and the delivered picture is YUV anyway, so it is never written.
+_RGB_COLOR_SPACE = "gbr"
+# Pixel-format name prefixes of ffmpeg's RGB family (packed, planar `gbr*`, paletted, Bayer).
+# Some RGB sources report no colour space at all (QuickTime RLE `argb`, raw `bgr24`, GIF
+# `pal8`), so the pixel format decides too; tests/assemble/test_render_delivery.py checks
+# the prefixes against every format a real ffprobe lists.
+_RGB_PIX_FMT_PREFIXES = (
+    "rgb", "bgr", "gbr", "argb", "abgr", "0rgb", "0bgr", "x2rgb", "x2bgr", "pal8", "bayer_",
+)
+# Names ffprobe prints that setparams and the -colorspace/-color_primaries/-color_trc
+# output options accept and libx264 writes back (tests/assemble/test_render_delivery.py
+# runs each through a real ffmpeg); anything else is not written explicitly.
+_KNOWN_COLOR_VALUES = {
+    "colorspace": {
+        "bt709", "fcc", "bt470bg", "smpte170m", "smpte240m", "ycgco", "bt2020nc", "bt2020c",
+        "smpte2085", "chroma-derived-nc", "chroma-derived-c", "ictcp",
+    },
+    "color_primaries": {
+        "bt709", "bt470m", "bt470bg", "smpte170m", "smpte240m", "film", "bt2020",
+        "smpte428", "smpte431", "smpte432",
+    },
+    "color_trc": {
+        "bt709", "bt470m", "bt470bg", "smpte170m", "smpte240m", "linear", "log100",
+        "log316", "iec61966-2-4", "bt1361e", "iec61966-2-1", "bt2020-10", "bt2020-12",
+        "smpte2084", "smpte428", "arib-std-b67",
+    },
+}
+# setparams only knows the BT.470 transfers by their ffprobe names, while ffmpeg 8's
+# -color_trc output option only knows them as gamma22/gamma28 (ffmpeg 9 takes both).
+_COLOR_OPTION_SPELLING = {"color_trc": {"bt470m": "gamma22", "bt470bg": "gamma28"}}
+
+
+def _probe_video_format(video_path):
+    """Codec, pixel format, size and colour tags of the first video stream ({} if unreadable)."""
+    result = run_cmd([
+        "ffprobe", "-v", "error", "-select_streams", "v:0",
+        "-show_entries",
+        "stream=codec_name,pix_fmt,width,height,color_space,color_primaries,color_transfer,color_range",
+        "-of", "json", str(video_path),
+    ])
+    if result.returncode != 0:
+        return {}
+    try:
+        streams = json.loads(result.stdout).get("streams") or []
+    except (ValueError, AttributeError):
+        return {}
+    return streams[0] if streams and isinstance(streams[0], dict) else {}
+
+
+def _output_color_tags(stream):
+    """Colour tags to write on the delivered picture, as {ffmpeg option: value}.
+
+    An untagged or BT.709 source is labelled BT.709, which is how players already decode
+    untagged web video. Any other declared colour space passes through as declared. The
+    range follows the source: full range stays `pc`, everything else is limited `tv`.
+    For a YUV source nothing here converts pixels; it only fixes the labels.
+
+    An RGB source (colour space `gbr`, or an RGB pixel format with or without a colour
+    space) has no YUV matrix to keep: it is converted to BT.709 limited range, and
+    `from_rgb` tells `_color_tag_filter` to do that conversion explicitly instead of
+    letting ffmpeg pick a matrix.
+    """
+    declared = {option: stream.get(key) for key, option in _COLOR_FIELDS}
+    from_rgb = (
+        declared["colorspace"] == _RGB_COLOR_SPACE
+        or str(stream.get("pix_fmt") or "").startswith(_RGB_PIX_FMT_PREFIXES)
+    )
+    if from_rgb:
+        declared["colorspace"] = "bt709"
+    if all(value in _UNTAGGED_COLOR or value == "bt709" for value in declared.values()):
+        tags = {option: "bt709" for _, option in _COLOR_FIELDS}
+    else:
+        tags = {
+            option: value for option, value in declared.items()
+            if value in _KNOWN_COLOR_VALUES[option]
+        }
+    if from_rgb:
+        tags["color_range"] = "tv"
+        tags["from_rgb"] = True
+    else:
+        tags["color_range"] = "pc" if stream.get("color_range") == "pc" else "tv"
+    return tags
+
+
+def _color_tag_filter(tags):
+    """setparams filter that stamps the tags on every frame before the encoder.
+
+    Output options alone are not enough when re-encoding: ffmpeg 8/9 let the (untagged)
+    frame properties win for primaries and transfer, so the bitstream would stay untagged.
+    An RGB frame is first converted to BT.709 yuv420p explicitly: stamping a YUV colour
+    space on an RGB frame makes ffmpeg's own later conversion use the BT.601 matrix
+    while the file says BT.709.
+    """
+    parts = [f"{option}={tags[option]}" for _, option in _COLOR_FIELDS if option in tags]
+    parts.append(f"range={tags['color_range']}")
+    setparams = "setparams=" + ":".join(parts)
+    if tags.get("from_rgb"):
+        return (
+            f"scale=out_color_matrix=bt709:out_range={tags['color_range']},"
+            f"format=yuv420p,{setparams}"
+        )
+    return setparams
+
+
+def _color_tag_args(tags):
+    """Output options that write the tags into the container (and encoder) metadata."""
+    args = []
+    for _, option in _COLOR_FIELDS:
+        if option in tags:
+            value = _COLOR_OPTION_SPELLING.get(option, {}).get(tags[option], tags[option])
+            args += [f"-{option}", value]
+    return args + ["-color_range", tags["color_range"]]
+
+
+def _video_copy_safe(stream):
+    """True when the source picture can be stream-copied and still match a re-encoded
+    delivery: H.264, 8-bit 4:2:0 (yuvj420p is the same layout in full range), even size."""
+    width, height = stream.get("width"), stream.get("height")
+    return (
+        stream.get("codec_name") == "h264"
+        and stream.get("pix_fmt") in {"yuv420p", "yuvj420p"}
+        and isinstance(width, int) and isinstance(height, int)
+        and width % 2 == 0 and height % 2 == 0
+    )

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

@@ -4,6 +4,7 @@ import os
 import wave
 from pathlib import Path
 
+from audio_mix import _dialogue_free_pull_start, _paragraph_pull_evidence
 from lib import CONFIG, get_video_duration, log, narration_tempo_budget, run_cmd
 
 def _apply_narration_speed(
@@ -44,6 +45,7 @@ def _adjust_tts_speed(
     tts_rate_offset=0.0,
     *,
     tempo_policy=None,
+    segment_index=None,
 ):
     """Fit overlong TTS with bounded atempo; never time-trim speech in assemble.
 
@@ -98,8 +100,9 @@ def _adjust_tts_speed(
             "placed_audio_duration": 0.0,
             "needed_tempo_factor": ratio,
         })
+        label = "" if segment_index is None else f"段 {segment_index + 1} "
         log(
-            f"  TTS 无安全放置: {current_dur:.1f}s 需 x{ratio:.2f}，"
+            f"  TTS 无安全放置: {label}{current_dur:.1f}s 需 x{ratio:.2f}，"
             f"超过段内预算 x{effective_max:.2f}（assemble 不按时间硬切）"
         )
         return (str(audio_path), current_dur, meta)
@@ -196,18 +199,16 @@ def _build_timed_narration(
     no_safe_fit_count = 0  # 超预算但不能安全截断；交由 QC/manifest 阻断
     prev_authored_end = None  # 上一段作者标注的结束时间，用于判断"段落"边界
     run_gap = CONFIG["narration_run_gap_seconds"]   # 作者留白 > 此值 = 新段落
-    tighten = CONFIG["narration_tighten"]
     tight_pause_samples = int(CONFIG["narration_tight_pause_seconds"] * sample_rate)
     # 漂移上限：收紧时一句最多比作者标注的时间提前 max_pull 秒，避免整段解说被全部压到前面、与画面脱节
     max_pull_samples = int(CONFIG["narration_max_pull_seconds"] * sample_rate)
-    configured_delay = CONFIG["narration_delay_seconds"]
-    tail_pad = CONFIG["narration_tail_pad_seconds"]
+    pull_evidence = None  # (dialogue, quiet)，第一次真的要提前时才读
 
     for seg in tts_segments:
         wav_path = seg["audio_path"]
         pause_samples = int(seg["pause_after_ms"] * sample_rate / 1000)
         # 段落收紧：同一段落内（与上一句作者留白 <= run_gap）把这一句紧贴上一句的实际收尾播放，
-        # 句间间隔固定为 tight_pause，不受 slot 内居中延迟 / TTS 时长波动影响。段落之间（作者特意留
+        # 句间间隔固定为 tight_pause，不受 slot 余量 / TTS 时长波动影响。段落之间（作者特意留
         # 的大留白，让精彩原声透出）才放回原声。这样句间间隔稳定、不会出现"一句解说一段空白"。
         cur_authored_start = float(seg["start"])
         is_run_start = (placed_count == 0 or prev_authored_end is None
@@ -234,21 +235,26 @@ def _build_timed_narration(
         tts_rate_offset = seg["tts_rate_offset"]
         tts_dur = seg["audio_duration"]
 
-        slot_duration = max(0.0, float(seg["end"]) - float(seg["start"]))
-        max_delay = max(0.0, slot_duration - tts_dur - tail_pad)
-        narration_delay = min(configured_delay, max_delay)
-        start_sample = int((seg["start"] + narration_delay) * sample_rate)
+        start_sample = int(seg["start"] * sample_rate)
         end_boundary = int(min(seg["end"], video_duration) * sample_rate)
 
         # 段间间隔：使用前一段的 pause_after_ms（来自 narration.json）
         min_start_with_pause = last_written_end + prev_pause_samples
-        if tighten and not is_run_start:
-            # 段落内：紧贴上一句的实际收尾播放，句间间隔固定为 tight_pause（不被 slot 内居中延迟撑大），
+        if not is_run_start:
+            # 段落内：紧贴上一句的实际收尾播放，句间间隔固定为 tight_pause（不被 slot 余量撑大），
             # 但不早于"作者标注起始 - max_pull"，防止整段被压到前面与画面脱节。
             drift_floor = int(cur_authored_start * sample_rate) - max_pull_samples
             actual_start = max(last_written_end + tight_pause_samples, drift_floor)
+            if actual_start < start_sample:
+                # 校验只检查过写的 start；提前的这一段不能进入原声对白，否则停在最后一段对白结束处
+                if pull_evidence is None:
+                    pull_evidence = _paragraph_pull_evidence(work_dir)
+                safe_start = _dialogue_free_pull_start(
+                    actual_start / sample_rate, cur_authored_start, *pull_evidence
+                )
+                actual_start = min(start_sample, max(actual_start, int(round(safe_start * sample_rate))))
         else:
-            # 段落起点（或关闭收紧）：尊重作者标注的起始 + 入场延迟，让画面/原声先立住
+            # 段落起点：采用作者标注的起始，让画面/原声先立住；上一块超时则顺延到它结尾 + pause_after_ms
             actual_start = max(start_sample, min_start_with_pause)
         actual_start = min(actual_start, end_boundary)  # 不超出 slot 边界
 
@@ -259,11 +265,12 @@ def _build_timed_narration(
             if tempo_policy:
                 wav_path, _actual_dur, fit_meta = _adjust_tts_speed(
                     wav_path, available_duration, tts_rate_offset,
-                    tempo_policy=tempo_policy,
+                    tempo_policy=tempo_policy, segment_index=seg["index"],
                 )
             else:
                 wav_path, _actual_dur, fit_meta = _adjust_tts_speed(
-                    wav_path, available_duration, tts_rate_offset
+                    wav_path, available_duration, tts_rate_offset,
+                    segment_index=seg["index"],
                 )
             seg.update({
                 "fit_status": fit_meta["fit_status"],
@@ -273,6 +280,8 @@ def _build_timed_narration(
                 "blocking": fit_meta["blocking"],
             })
             if fit_meta["fit_status"] == "no_safe_fit":
+                if "needed_tempo_factor" in fit_meta:
+                    seg["needed_tempo_factor"] = round(fit_meta["needed_tempo_factor"], 4)
                 _unplaced(seg, actual_start / sample_rate, "no_safe_fit",
                           fit_meta["truncate_reason"], blocking=True)
                 prev_pause_samples = pause_samples
@@ -331,7 +340,7 @@ def _build_timed_narration(
             # consonant/vowel release. _adjust_tts_speed must produce a complete file
             # that fits; otherwise block and ask the Agent to shorten/move the block.
             over = (audio_samples - available) / sample_rate
-            log(f"  TTS 无安全放置: 段 {seg['index']} 超出可用窗口 {over:.3f}s；禁止裁尾，交由 QC 阻断")
+            log(f"  TTS 无安全放置: 段 {seg['index'] + 1} 超出可用窗口 {over:.3f}s；禁止裁尾，交由 QC 阻断")
             _unplaced(seg, actual_start / sample_rate, "no_safe_fit", "no_safe_boundary", blocking=True)
             prev_pause_samples = pause_samples
             skipped_count += 1
@@ -342,7 +351,7 @@ def _build_timed_narration(
         if actual_start < last_written_end:
             overlap_ms = (last_written_end - actual_start) * 1000 / sample_rate
             if last_written_end >= actual_start + write_samples:
-                log(f"  跳过重叠段: {actual_start/sample_rate:.1f}s "
+                log(f"  跳过重叠段: 段 {seg['index'] + 1} {actual_start/sample_rate:.1f}s "
                        f"(与前段重叠 {overlap_ms:.0f}ms)")
                 _unplaced(seg, seg["start"], "no_safe_fit", "no_room", blocking=True)
                 prev_pause_samples = pause_samples
@@ -391,6 +400,11 @@ def _build_timed_narration(
         buffer[actual_start * 2: actual_start * 2 + write_samples * 2] = wf_data
         seg["actual_place_start"] = actual_start / sample_rate
         seg["actual_place_end"] = (actual_start + write_samples) / sample_rate
+        if actual_start < start_sample:
+            # 段落收紧把这一块提前到写的 start 之前；若它成为新压低段的首块，
+            # 原声交接会用自己的入口判定覆盖这个状态
+            seg["source_entry_status"] = "paragraph_tightened"
+            seg["written_start"] = cur_authored_start
         seg["placed_audio_duration"] = write_samples / sample_rate
         last_written_end = actual_start + write_samples
         prev_pause_samples = pause_samples

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

@@ -1,9 +1,12 @@
-"""Local ffmpeg capability preflight for subtitle burn-in."""
+"""Local ffmpeg capability preflight for subtitle burn-in and drawtext overlays."""
 
 import shutil
 import subprocess
+from pathlib import Path
 
-from lib import CONFIG
+from assemble_constants import VISUAL_OVERLAYS
+from lib import CONFIG, log
+from visual_render import _load_visual_overlays
 
 def _ffmpeg_filters():
     """Return ffmpeg's compiled-in filter names (caller has confirmed ffmpeg exists)."""
@@ -19,15 +22,53 @@ def _ffmpeg_filters():
     return filters
 
 
+SUBTITLE_BURN_DEGRADED = "subtitle_burn_degraded"
+LIBASS_MISSING = "ffmpeg_missing_libass"
+
+
 def _preflight_burn_subtitles():
-    """Fail before the (re-encoding) render when burn-in is on but ffmpeg lacks the libass
-    `subtitles` filter. Only fires when ffmpeg EXISTS but can't burn — an absent ffmpeg fails
-    the render regardless."""
+    """Settle subtitle burn-in before the render when ffmpeg lacks the libass `subtitles`
+    filter. An explicit request (--burn-subtitles or BURN_SUBTITLES in the environment)
+    fails here. The implicit default degrades: burn turns off, the reason is recorded in
+    CONFIG["burn_subtitles_degraded"], and the run delivers the .srt sidecar instead (the
+    warning lands in visual_qc.json and assembly_manifest.json). Only fires when ffmpeg
+    EXISTS but can't burn; an absent ffmpeg fails the render regardless."""
     if not CONFIG["burn_subtitles"]:
         return
     if shutil.which("ffmpeg") is None:
         return
-    if "subtitles" not in _ffmpeg_filters():
+    if "subtitles" in _ffmpeg_filters():
+        return
+    if CONFIG["burn_subtitles_explicit"]:
         raise SystemExit(
-            "字幕烧录已开启，但当前 ffmpeg 不支持 subtitles/libass 滤镜，渲染会在最后一步失败。\n"
-            "  解决：安装带 libass 的 ffmpeg，或加 --no-burn-subtitles 关闭烧录（仍输出 .srt 外挂字幕）。")
+            "已显式要求烧录字幕（--burn-subtitles 或 BURN_SUBTITLES），但当前 ffmpeg 不支持"
+            " subtitles/libass 滤镜，渲染会在最后一步失败。\n"
+            "  解决：安装带 libass 的 ffmpeg；或去掉显式烧录要求，默认运行会改为输出 .srt 外挂字幕；"
+            "或加 --no-burn-subtitles。")
+    CONFIG["burn_subtitles"] = False
+    CONFIG["burn_subtitles_degraded"] = LIBASS_MISSING
+    log("⚠️ 当前 ffmpeg 不支持 subtitles/libass 滤镜：本次不烧录字幕，改为输出 .srt 外挂字幕"
+        "（visual_qc.json / assembly_manifest.json 记录 subtitle_burn_degraded）。"
+        "要烧录字幕请安装带 libass 的 ffmpeg。")
+
+
+def _preflight_visual_overlays(work_dir):
+    """Fail before the render when visual_overlays.json asks for text but this ffmpeg has no
+    drawtext (libfreetype). Overlays are authored content, never a default, so they are not
+    silently dropped: remove them or install an ffmpeg with drawtext. An unreadable overlay
+    file is left to the render's own validation."""
+    if shutil.which("ffmpeg") is None:
+        return
+    try:
+        overlays, _source = _load_visual_overlays(work_dir)
+    except ValueError:
+        return
+    if not any(str(item.get("text", "")).strip() for item in overlays):
+        return
+    if "drawtext" in _ffmpeg_filters():
+        return
+    raise SystemExit(
+        f"{Path(work_dir) / VISUAL_OVERLAYS} 有 {len(overlays)} 个画面文字叠加，但当前 ffmpeg 不支持"
+        " drawtext 滤镜（需要 libfreetype），渲染会在最后一步失败。\n"
+        "  解决：安装带 drawtext/libfreetype 的 ffmpeg，或删掉这些叠加"
+        "（recap 运行时删掉 narration.json 各段的 visual_overlays）后重跑。")

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

@@ -57,11 +57,11 @@ def _source_subtitle_mask_policy(work_dir=None):
     if raw_policy == "off":
         active = False
     elif raw_policy in {"opt_in", "forced"}:
-        active = burn and legacy_flag
+        active = legacy_flag
         trigger = "burn_subtitles_and_legacy_mask_flag"
         reason = "explicit policy permits masking only with burned recap subtitles"
     elif raw_policy == "safe":
-        active = burn and (legacy_flag or user_subtitles)
+        active = legacy_flag or user_subtitles
         trigger = "safe_policy_with_burned_subtitles"
         reason = "safe policy masks only when recap subtitles are burned and an original-subtitle source is declared"
     else:
@@ -70,8 +70,15 @@ def _source_subtitle_mask_policy(work_dir=None):
         reason = "mask_source_subtitles requires explicit SOURCE_SUBTITLE_MASK_POLICY"
     if not burn and active:
         active = False
-        trigger = "burn_subtitles_disabled"
-        reason = "mask-only black band is forbidden without burned recap subtitles"
+        if CONFIG["burn_subtitles_degraded"]:
+            trigger = "burn_subtitles_degraded"
+            reason = (
+                "subtitle burn-in degraded to the .srt sidecar; a mask-only black band is "
+                "forbidden without burned recap subtitles"
+            )
+        else:
+            trigger = "burn_subtitles_disabled"
+            reason = "mask-only black band is forbidden without burned recap subtitles"
     return {
         "policy": raw_policy,
         "declared": bool(declared and raw_policy in allowed),
@@ -269,14 +276,18 @@ def _narration_gap_windows(tts_segments, video_duration, min_gap=_MIN_GAP_TO_SUB
 
 def _original_gap_subtitle_entries(tts_segments, work_dir, video_duration):
     """Subtitle entries for the ORIGINAL dialogue during the original-audio blocks (narration
-    gaps), so the band is not blank while the original speaks. Off unless we are burning and
+    gaps), so the band is not blank while the original speaks. Off unless subtitles are
+    delivered (burned, or burn degraded to the .srt sidecar because ffmpeg lacks libass) and
     subtitle_original_in_gaps is set; no-op when there is no ASR. Cut mode remaps ASR to output."""
     # Fill the gaps when either (a) we are masking the source's own burned-in subs (so the band is
     # blank without us), or (b) the user supplied their own subtitle file — a clear signal they want
     # the original dialogue shown, e.g. a clean/foreign source with mask OFF (no burned subs to
     # double). Without a user file we keep the mask requirement so we don't double the source's own
     # visible subs. subtitle_original_in_gaps is the explicit override either way.
-    if not (CONFIG["burn_subtitles"]
+    # A degraded burn keeps the cues a burned run would show, so the sidecar .srt is the same
+    # subtitle deliverable; with the mask off only the user-file trigger can still pass.
+    delivering = CONFIG["burn_subtitles"] or bool(CONFIG["burn_subtitles_degraded"])
+    if not (delivering
             and CONFIG["subtitle_original_in_gaps"]
             and (_source_subtitle_mask_covers_gaps(work_dir) or _has_user_subtitles(work_dir))):
         return []

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

@@ -13,6 +13,13 @@ from assemble_constants import (
 )
 from media import _ratio_to_float
 
+# Measured subtitle bands accept near-square pixels: Y rows are converted between the display
+# canvas and the decoded frame exactly (_frame_row), so the only SAR effect left is a burned
+# ASS line stretched horizontally by the same factor — invisible within 2%. Kept equal to the
+# orchestrator's preflight copy and the measuring tool's (parity-tested).
+SUBTITLE_BAND_SAR_TOLERANCE = 0.02
+
+
 def _seconds_to_srt_time(seconds):
     """Floor times to SRT milliseconds without float remainder artifacts.
 
@@ -102,9 +109,11 @@ def _measured_subtitle_band(canvas):
     if y_top < 0 and y_bot < 0:
         return None
     sar_text = canvas["sample_aspect_ratio"]
-    if abs(_ratio_to_float(sar_text, 0.0) - 1.0) >= 1e-9:
+    # Unspecified SAR ("0:1"/"N/A") is square, exactly as the canvas probe reads it.
+    if abs(_ratio_to_float(sar_text, 1.0) - 1.0) > SUBTITLE_BAND_SAR_TOLERANCE + 1e-9:
         raise ValueError(
-            f"字幕带坐标仅支持方形像素画布 (SAR 1:1)；当前 SAR={sar_text}"
+            "字幕带坐标仅支持方形或近方形像素画布 "
+            f"(SAR 与 1:1 相差不超过 {SUBTITLE_BAND_SAR_TOLERANCE:.0%})；当前 SAR={sar_text}"
         )
     canvas_h = canvas["height"]
     if not 0 <= y_top < y_bot <= canvas_h:
@@ -115,6 +124,19 @@ def _measured_subtitle_band(canvas):
     return y_top, y_bot
 
 
+def _frame_row(canvas, display_y):
+    """Display-canvas row → row of the decoded, auto-rotated frame that drawbox paints on.
+
+    The canvas keeps the frame's pixel width and stretches the height by the SAR only for a
+    90°/270° stream (its stored width becomes the height); otherwise both share rows exactly.
+    """
+    rotated = canvas["rotation"] in {90, 270}
+    frame_h = canvas["storage_width"] if rotated else canvas["storage_height"]
+    if frame_h == canvas["height"]:
+        return display_y
+    return round(display_y * frame_h / canvas["height"])
+
+
 def _style_for_measured_subtitle_band(style, canvas):
     """Fit the ASS baseline and font into explicit auto-rotated display-frame Y coordinates."""
     style = dict(style)

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

@@ -16,8 +16,6 @@ from pathlib import Path
 
 SCHEMA_VERSION = 1
 
-# Digest keys older tracks declared; they are ignored, never a reason to fail.
-_LEGACY_BINDING_KEYS = frozenset({"sha256", "edit_sha256"})
 _EVIDENCE_KINDS = frozenset(
     {
         "human_verified",
@@ -112,7 +110,7 @@ def _load_document(path_or_mapping):
 
 def _validate_picture_binding(binding, expected):
     binding = _strict_fields(
-        binding, required={"path"}, optional={"edit_plan"} | _LEGACY_BINDING_KEYS,
+        binding, required={"path"}, optional={"edit_plan"},
         path="bindings.picture",
     )
     expected = _mapping(expected, "expected_picture_identity")
@@ -137,8 +135,7 @@ _AUDIO_BINDING_FACTS = ("selected_stream", "sample_rate", "packet_count")
 
 def _validate_audio_binding(binding, expected):
     binding = _strict_fields(
-        binding, required=set(_AUDIO_BINDING_FACTS), optional=_LEGACY_BINDING_KEYS,
-        path="bindings.audio",
+        binding, required=set(_AUDIO_BINDING_FACTS), path="bindings.audio",
     )
     expected = _mapping(expected, "expected_audio_identity")
     result = {}

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

@@ -17,8 +17,6 @@ from subtitles.track import load_subtitle_track
 
 TRACK = 'subtitle_track.json'
 VALIDATION = 'subtitle_track_validation.json'
-VALIDATION_SCHEMA = 1
-PROJECTOR_VERSION = 1
 
 
 def current_bindings(video, selected_audio_stream=0, *, edit_plan_path=None):
@@ -113,8 +111,6 @@ def prepare_subtitle_track(input_video, work_dir, video_duration, *, audio_mode,
                      start=float(Fraction(start['pts'])), end=float(Fraction(end['pts'])))
         entry['frame_projection'] = {'requested_ticks': [cue['start_tick'], cue['end_tick']],
                                      'start': start, 'end': end}
-    loaded['validation_schema'] = VALIDATION_SCHEMA
-    loaded['projector_version'] = PROJECTOR_VERSION
     loaded['binding'] = {
         'input_video': str(Path(input_video).resolve()), 'identities': bindings,
         'inputs': {'track': file_identity(path), 'video': file_identity(input_video),
@@ -129,14 +125,11 @@ def prepare_subtitle_track(input_video, work_dir, video_duration, *, audio_mode,
 
 
 def _load_validation(work):
+    """The record prepare_subtitle_track rewrote earlier in this same assemble run."""
     path = Path(work) / VALIDATION
     if not path.exists():
         raise ValueError('Explicit subtitle track must be prepared against current media before use')
-    loaded = json.loads(path.read_text(encoding='utf-8'))
-    if (type(loaded.get('validation_schema')) is not int or loaded['validation_schema'] != VALIDATION_SCHEMA
-            or type(loaded.get('projector_version')) is not int or loaded['projector_version'] != PROJECTOR_VERSION):
-        raise ValueError('Subtitle validation/projector version changed; prepare again')
-    return loaded
+    return json.loads(path.read_text(encoding='utf-8'))
 
 
 def bound_subtitle_entries(work_dir, video_duration):