@oh-story/dsh 0.1.8 → 0.1.9

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

@@ -10,7 +10,6 @@ from assemble_constants import (
     VISUAL_OVERLAYS,
     VISUAL_QC,
     _SUPPORTED_VISUAL_OVERLAY_TYPES,
-    _VISUAL_DELIVERY_FORBIDDEN_KEYS,
 )
 from audio_automation import coalesce_duck_windows
 from audio_mix import _seg_place_window
@@ -21,17 +20,24 @@ from source_subtitles import (
     _source_subtitle_mask_policy,
 )
 from subtitle_core import (
+    _measured_subtitle_band,
     _measured_subtitle_safe_area,
     _normalize_subtitle_text,
     _style_for_measured_subtitle_band,
     _subtitle_style_config,
-    _validate_measured_subtitle_coordinate_domain,
 )
 
+_OVERFLOW_KINDS = {
+    "max_lines_exceeded": "line_count",
+    "safe_width_exceeded": "line_width",
+    "safe_height_exceeded": "safe_area",
+}
+
+
 def _visual_text_units(text):
     """Approximate visual text width in em units for deterministic geometry QC."""
     units = 0.0
-    for ch in str(text or ""):
+    for ch in text:
         if ch.isspace():
             units += 0.35
         elif ord(ch) < 128:
@@ -41,51 +47,37 @@ def _visual_text_units(text):
     return units
 
 
-def _subtitle_layout_qc(entries, canvas=None, style=None, safe_area=None):
+def _subtitle_layout_qc(entries, style, safe_area=None):
     """Machine-check subtitle safe-area/multiline/overflow facts for visual_qc.json."""
-    canvas = canvas or {}
-    style = style or _subtitle_style_config(canvas)
-    play_x = int(style.get("play_res_x") or canvas.get("width") or 1280)
-    play_y = int(style.get("play_res_y") or canvas.get("height") or 720)
-    margin_l = int(style.get("margin_l") or 0)
-    margin_r = int(style.get("margin_r") or 0)
-    margin_v = int(style.get("margin_v") or 0)
-    font_size = float(style.get("font_size") or 1)
-    max_lines = int(CONFIG.get("subtitle_max_lines", 2) or 2)
-    usable_w = max(1.0, play_x - margin_l - margin_r)
-    if safe_area:
+    play_x = int(style["play_res_x"])
+    play_y = int(style["play_res_y"])
+    margin_l = int(style["margin_l"])
+    margin_r = int(style["margin_r"])
+    margin_v = int(style["margin_v"])
+    font_size = float(style["font_size"])
+    max_lines = CONFIG["subtitle_max_lines"]
+    if safe_area is None:
         safe_area = {
-            "x": int(safe_area.get("x", margin_l) or 0),
-            "y": int(safe_area.get("y", margin_v) or 0),
-            "width": int(safe_area.get("width", safe_area.get("w", play_x - margin_l - margin_r)) or 1),
-            "height": int(safe_area.get("height", safe_area.get("h", play_y - 2 * margin_v)) or 1),
+            "x": margin_l,
+            "y": margin_v,
+            "width": max(1, play_x - margin_l - margin_r),
+            "height": max(1, play_y - 2 * margin_v),
             "bottom_margin": margin_v,
         }
-        usable_w = max(1.0, float(safe_area["width"]))
-    else:
-        safe_area = {
-        "x": margin_l,
-        "y": margin_v,
-        "width": max(1, play_x - margin_l - margin_r),
-        "height": max(1, play_y - 2 * margin_v),
-        "bottom_margin": margin_v,
-        }
+    usable_w = float(safe_area["width"])
     line_h = font_size * 1.25
     overflow_entries = []
     violations = []
     multi_line_entries = []
     max_observed_lines = 0
     entry_facts = []
-    for i, entry in enumerate(entries or []):
-        raw_text = _normalize_subtitle_text(entry.get("text", ""))
-        lines = [ln for ln in re.split(r"(?:\\N|\n)+", raw_text) if ln != ""]
-        if not lines:
-            lines = [""]
+    for i, entry in enumerate(entries):
+        raw_text = _normalize_subtitle_text(entry["text"])
+        lines = [ln for ln in re.split(r"(?:\\N|\n)+", raw_text) if ln != ""] or [""]
         line_count = len(lines)
         max_observed_lines = max(max_observed_lines, line_count)
-        widths = [_visual_text_units(line) * font_size for line in lines]
-        max_w = max(widths or [0.0])
-        band_h = line_count * line_h + float(style.get("outline", 0)) * 2 + float(style.get("shadow", 0))
+        max_w = max(_visual_text_units(line) * font_size for line in lines)
+        band_h = line_count * line_h + float(style["outline"]) * 2 + float(style["shadow"])
         overflow_reasons = []
         if line_count > max_lines:
             overflow_reasons.append("max_lines_exceeded")
@@ -95,8 +87,8 @@ def _subtitle_layout_qc(entries, canvas=None, style=None, safe_area=None):
             overflow_reasons.append("safe_height_exceeded")
         fact = {
             "index": i,
-            "start": round(float(entry.get("start", 0.0) or 0.0), 3),
-            "end": round(float(entry.get("end", 0.0) or 0.0), 3),
+            "start": round(float(entry["start"]), 3),
+            "end": round(float(entry["end"]), 3),
             "line_count": line_count,
             "max_line_width": round(max_w, 2),
             "safe_width": round(usable_w, 2),
@@ -109,23 +101,20 @@ def _subtitle_layout_qc(entries, canvas=None, style=None, safe_area=None):
             multi_line_entries.append(i)
         if overflow_reasons:
             overflow_entries.append(fact)
-            for reason in overflow_reasons:
-                kind = {
-                    "max_lines_exceeded": "line_count",
-                    "safe_width_exceeded": "line_width",
-                    "safe_height_exceeded": "safe_area",
-                }.get(reason, "safe_area")
-                violations.append({"index": i, "kind": kind, "reason": reason})
+            violations.extend(
+                {"index": i, "kind": _OVERFLOW_KINDS[reason], "reason": reason}
+                for reason in overflow_reasons
+            )
     return {
-        "enabled": bool(CONFIG.get("burn_subtitles", False)),
-        "renderer": "ass" if CONFIG.get("burn_subtitles", False) else "sidecar_srt",
+        "enabled": CONFIG["burn_subtitles"],
+        "renderer": "ass" if CONFIG["burn_subtitles"] else "sidecar_srt",
         "style": {
             "font_size": int(font_size),
-            "max_chars": int(style.get("max_chars") or 0),
+            "max_chars": int(style["max_chars"]),
             "max_lines": max_lines,
             "play_res_x": play_x,
             "play_res_y": play_y,
-            "alignment": int(style.get("alignment") or 0),
+            "alignment": int(style["alignment"]),
             "margin_l": margin_l,
             "margin_r": margin_r,
             "margin_v": margin_v,
@@ -143,45 +132,35 @@ def _subtitle_layout_qc(entries, canvas=None, style=None, safe_area=None):
     }
 
 
-def _load_visual_overlays(work_dir, *, with_source=False):
+def _load_visual_overlays(work_dir):
+    """Return (overlays, source) from the canonical visual_overlays.json handoff."""
     path = Path(work_dir) / VISUAL_OVERLAYS
     if not path.exists():
-        result = ([], {"present": False, "path": str(path), "fingerprint": None})
-        return result if with_source else result[0]
+        return [], {"present": False, "path": str(path), "fingerprint": None}
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
-    except (ValueError, OSError) as exc:
-        result = ([], {
-            "present": True,
-            "path": str(path),
-            "fingerprint": _artifact_fingerprint(path),
-            "load_error": "invalid_json",
-            "load_error_detail": str(exc),
-        })
-        return result if with_source else result[0]
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path}: JSON 无效") from exc
+    if (
+        not isinstance(data, dict)
+        or type(data.get("schema_version")) is not int
+        or data["schema_version"] != 1
+        or not isinstance(data.get("overlays"), list)
+        or not all(isinstance(item, dict) for item in data["overlays"])
+    ):
+        raise ValueError(f"{path}: visual_overlays.json schema 无效")
     source = {
         "present": True,
         "path": str(path),
         "fingerprint": _artifact_fingerprint(path),
-        "schema_version": data.get("schema_version") if isinstance(data, dict) else None,
+        "schema_version": 1,
     }
-    schema_version = data.get("schema_version") if isinstance(data, dict) else None
-    valid_schema_version = (
-        isinstance(schema_version, int)
-        and not isinstance(schema_version, bool)
-        and schema_version == 1
-    )
-    if isinstance(data, dict) and valid_schema_version and isinstance(data.get("overlays"), list):
-        overlays = data["overlays"]
-    else:
-        overlays = []
-        source["load_error"] = "invalid_schema"
-    return (overlays, source) if with_source else overlays
+    return data["overlays"], source
 
 
 def _escape_drawtext_text(text):
     return (
-        str(text or "")
+        text
         .replace("\\", "\\\\")
         .replace(":", "\\:")
         .replace("'", "\\'")
@@ -191,44 +170,30 @@ def _escape_drawtext_text(text):
 
 
 def _overlay_time_window(overlay, video_duration):
-    try:
-        start = float(overlay.get("start", 0.0) or 0.0)
-    except (TypeError, ValueError):
-        start = 0.0
-    try:
-        end = float(overlay.get("end", video_duration) or video_duration)
-    except (TypeError, ValueError):
-        end = float(video_duration or 0.0)
-    end = max(start, end)
-    return start, end
+    start = float(overlay.get("start", 0.0))
+    end = float(overlay.get("end", video_duration))
+    return start, max(start, end)
 
 
 def _overlay_bbox(overlay, canvas, *, default_y):
-    width = int((canvas or {}).get("width") or 1280)
-    height = int((canvas or {}).get("height") or 720)
-    text = str(overlay.get("text") or "")
-    font_size = int(overlay.get("font_size") or max(18, round(height * 0.045)))
+    width = canvas["width"]
+    height = canvas["height"]
+    text = overlay["text"]
+    font_size = int(overlay.get("font_size", max(18, round(height * 0.045))))
     lines = [ln for ln in text.splitlines() if ln.strip()] or [text]
-    max_w = max((_visual_text_units(ln) * font_size for ln in lines), default=0.0)
+    max_w = max(_visual_text_units(ln) * font_size for ln in lines)
     text_h = len(lines) * font_size * 1.25
-    if overlay.get("type") == "top_title":
+    if overlay["type"] == "top_title":
         x = max(0.0, (width - max_w) / 2)
-        y = float(overlay.get("y", default_y) or default_y)
+        y = float(overlay.get("y", default_y))
     else:
-        raw_x = overlay.get("x", 0.08)
-        raw_y = overlay.get("y", 0.25)
-        try:
-            x = float(raw_x)
-            if 0.0 <= x <= 1.0:
-                x *= width
-        except (TypeError, ValueError):
-            x = width * 0.08
-        try:
-            y = float(raw_y)
-            if 0.0 <= y <= 1.0:
-                y *= height
-        except (TypeError, ValueError):
-            y = height * 0.25
+        # Fractions of the canvas in [0, 1] are normalized coordinates; larger values are pixels.
+        x = float(overlay.get("x", 0.08))
+        y = float(overlay.get("y", 0.25))
+        if 0.0 <= x <= 1.0:
+            x *= width
+        if 0.0 <= y <= 1.0:
+            y *= height
     return {
         "x": round(x, 2),
         "y": round(y, 2),
@@ -246,19 +211,15 @@ def _visual_overlay_filters(work_dir, canvas, video_duration):
     Only two semantic renderers are supported: top_title and inline_label_or_callout.
     Unsupported types are QC-blocking and deliberately do not silently render.
     """
-    overlays, source = _load_visual_overlays(work_dir, with_source=True)
-    height = int((canvas or {}).get("height") or 720)
-    default_top_y = max(24, round(height * 0.05))
+    overlays, source = _load_visual_overlays(work_dir)
+    default_top_y = max(24, round(canvas["height"] * 0.05))
     filters = []
     facts = []
     unsupported = []
     overflow = []
     for idx, overlay in enumerate(overlays):
-        if not isinstance(overlay, dict):
-            unsupported.append({"index": idx, "type": None, "reason": "overlay_not_object"})
-            continue
-        typ = str(overlay.get("type") or "").strip()
-        text = str(overlay.get("text") or "").strip()
+        typ = overlay.get("type")
+        text = overlay.get("text", "").strip()
         if typ not in _SUPPORTED_VISUAL_OVERLAY_TYPES:
             unsupported.append({"index": idx, "type": typ, "reason": "unsupported_overlay_type"})
             continue
@@ -297,9 +258,8 @@ def _visual_overlay_filters(work_dir, canvas, video_duration):
         })
     qc = {
         "source": source,
-        "load_error": source.get("load_error"),
         "supported_types": sorted(_SUPPORTED_VISUAL_OVERLAY_TYPES),
-        "present": bool(source.get("present")),
+        "present": source["present"],
         "count": len(overlays),
         "rendered": len(facts),
         "facts": facts,
@@ -309,49 +269,33 @@ def _visual_overlay_filters(work_dir, canvas, video_duration):
     return filters, qc
 
 
-def _visual_qc_has_forbidden_delivery_facts(value):
-    if isinstance(value, dict):
-        for key, child in value.items():
-            if key in _VISUAL_DELIVERY_FORBIDDEN_KEYS:
-                return True
-            if _visual_qc_has_forbidden_delivery_facts(child):
-                return True
-    elif isinstance(value, list):
-        return any(_visual_qc_has_forbidden_delivery_facts(item) for item in value)
-    return False
-
-
 def _build_visual_qc(tts_segments, work_dir, video_duration, canvas, *, overlay_qc=None, mask_filter=None):
     entries = _combined_subtitle_entries(tts_segments, work_dir, video_duration)
     style = _style_for_measured_subtitle_band(_subtitle_style_config(canvas), canvas)
     subtitle_layout = _subtitle_layout_qc(
-        entries, canvas, style, safe_area=_measured_subtitle_safe_area(style, canvas)
+        entries, style, safe_area=_measured_subtitle_safe_area(style, canvas)
     )
     mask = _source_subtitle_mask_policy(work_dir)
-    ratio = None
-    if mask.get("active"):
-        ratio = max(0.0, min(0.5, float(CONFIG.get("source_subtitle_mask_ratio", 0.14) or 0.0)))
     mask.update({
-        "ratio": ratio,
+        "ratio": min(0.5, CONFIG["source_subtitle_mask_ratio"]) if mask["active"] else None,
         "filter": "drawbox" if mask_filter else None,
-        "opacity": float(CONFIG.get("subtitle_mask_opacity", 0.6)),
-        "timing": str(CONFIG.get("source_subtitle_mask_timing", "narration")),
-        "subtitle_y_top": int(CONFIG.get("subtitle_y_top", -1)),
-        "subtitle_y_bot": int(CONFIG.get("subtitle_y_bot", -1)),
+        "opacity": CONFIG["subtitle_mask_opacity"],
+        "timing": CONFIG["source_subtitle_mask_timing"],
+        "subtitle_y_top": CONFIG["subtitle_y_top"],
+        "subtitle_y_bot": CONFIG["subtitle_y_bot"],
     })
-    overlay_qc = overlay_qc or _visual_overlay_filters(work_dir, canvas, video_duration)[1]
+    if overlay_qc is None:
+        overlay_qc = _visual_overlay_filters(work_dir, canvas, video_duration)[1]
     blocking_codes = []
-    if mask.get("blocking"):
+    if mask["blocking"]:
         blocking_codes.append("mask_policy_not_explicit")
-    if subtitle_layout.get("overflow"):
+    if subtitle_layout["overflow"]:
         blocking_codes.append("subtitle_overflow")
-    if overlay_qc.get("load_error"):
-        blocking_codes.append("invalid_visual_overlays_json")
-    if overlay_qc.get("unsupported"):
+    if overlay_qc["unsupported"]:
         blocking_codes.append("unsupported_visual_overlay")
-    if overlay_qc.get("overflow"):
+    if overlay_qc["overflow"]:
         blocking_codes.append("visual_overlay_overflow")
-    qc = {
+    return {
         "schema_version": 1,
         "artifact": VISUAL_QC,
         "verdict": "FAIL" if blocking_codes else "PASS",
@@ -359,36 +303,31 @@ def _build_visual_qc(tts_segments, work_dir, video_duration, canvas, *, overlay_
         "blocking_codes": blocking_codes,
         "geometry": {
             "canvas": {
-                "width": int(canvas.get("width", 1280)),
-                "height": int(canvas.get("height", 720)),
-                "fps": float(canvas.get("fps", 30.0)),
+                "width": canvas["width"],
+                "height": canvas["height"],
+                "fps": canvas["fps"],
             },
             "storage": {
-                "width": int(canvas.get("storage_width", canvas.get("width", 1280))),
-                "height": int(canvas.get("storage_height", canvas.get("height", 720))),
+                "width": canvas["storage_width"],
+                "height": canvas["storage_height"],
             },
-            "rotation": int(canvas.get("rotation", 0) or 0),
-            "sample_aspect_ratio": canvas.get("sample_aspect_ratio", "1:1"),
-            "display_aspect_ratio": canvas.get("display_aspect_ratio"),
+            "rotation": canvas["rotation"],
+            "sample_aspect_ratio": canvas["sample_aspect_ratio"],
+            "display_aspect_ratio": canvas["display_aspect_ratio"],
         },
         "subtitles": subtitle_layout,
         "mask": mask,
         "overlays": overlay_qc,
         "summary": {
-            "subtitle_entries": subtitle_layout.get("entries", 0),
-            "subtitle_overflow": bool(subtitle_layout.get("overflow")),
-            "subtitle_multi_line": bool(subtitle_layout.get("multi_line")),
-            "mask_policy": mask.get("policy"),
-            "mask_active": bool(mask.get("active")),
-            "overlay_rendered": int(overlay_qc.get("rendered", 0) or 0),
-            "overlay_unsupported": len(overlay_qc.get("unsupported") or []),
+            "subtitle_entries": subtitle_layout["entries"],
+            "subtitle_overflow": subtitle_layout["overflow"],
+            "subtitle_multi_line": subtitle_layout["multi_line"],
+            "mask_policy": mask["policy"],
+            "mask_active": mask["active"],
+            "overlay_rendered": overlay_qc["rendered"],
+            "overlay_unsupported": len(overlay_qc["unsupported"]),
         },
     }
-    if _visual_qc_has_forbidden_delivery_facts(qc):
-        qc["verdict"] = "FAIL"
-        qc["blocking"] = True
-        qc["blocking_codes"].append("visual_qc_contains_delivery_fact")
-    return qc
 
 
 def _write_visual_qc(work_dir, qc):
@@ -427,9 +366,7 @@ def _output_downscale_filter(max_h):
     return f"scale=-2:'2*trunc(min(ih,{max_h})/2)':flags=lanczos"
 
 
-def _source_subtitle_mask_filter(
-    canvas=None, work_dir=None, tts_segments=None, video_duration=None
-):
+def _source_subtitle_mask_filter(canvas, work_dir, tts_segments, video_duration):
     """Return source-subtitle drawbox filters, optionally scoped to narration windows.
 
     Many source videos (e.g. 庆余年) ship hardcoded subtitles; without this the recap
@@ -438,71 +375,56 @@ def _source_subtitle_mask_filter(
     remain configurable.
     """
     policy = _source_subtitle_mask_policy(work_dir)
-    if not policy.get("active"):
+    if not policy["active"]:
         return None
-    opacity = max(0.0, min(1.0, float(CONFIG.get("subtitle_mask_opacity", 0.6))))
-
-    _validate_measured_subtitle_coordinate_domain(canvas)
+    opacity = CONFIG["subtitle_mask_opacity"]
+    timing = CONFIG["source_subtitle_mask_timing"]
+    if timing not in {"all", "narration"}:
+        raise ValueError(f"SOURCE_SUBTITLE_MASK_TIMING 必须是 all 或 narration，当前为 {timing!r}")
 
-    canvas_h = int((canvas or {}).get("height", 0) or 0)
-    y_top = int(CONFIG.get("subtitle_y_top", -1))
-    y_bot = int(CONFIG.get("subtitle_y_bot", -1))
-    custom_band = canvas_h > 0 and 0 <= y_top < y_bot <= canvas_h
-    if custom_band:
-        padding = int(CONFIG.get("subtitle_mask_padding", 4) or 0)
+    band = _measured_subtitle_band(canvas)
+    if band is not None:
+        y_top, y_bot = band
+        padding = CONFIG["subtitle_mask_padding"]
         mask_top = max(0, y_top - padding)
-        mask_bot = min(canvas_h, y_bot + padding)
+        mask_bot = min(canvas["height"], y_bot + padding)
         geometry = f"x=0:y={mask_top}:w=iw:h={mask_bot - mask_top}"
     else:
-        ratio = max(0.0, min(0.5, float(CONFIG.get("source_subtitle_mask_ratio", 0.14) or 0.0)))
         # Our subtitle cues are one line. Keep the mask large enough for that line and its
         # margin, but never regress to the old two-line bar that hid ~23% of the image.
         style = _subtitle_style_config(canvas)
-        play_res_y = max(1.0, float(style["play_res_y"]))
+        play_res_y = float(style["play_res_y"])
         line_h = float(style["font_size"]) * 1.25
         pad = 10.0 * play_res_y / SUBTITLE_STYLE_REF_H
         sub_band = (float(style["margin_v"]) + line_h + pad) / play_res_y
-        ratio = min(0.5, max(ratio, sub_band))
-        if ratio <= 0:
-            return None
+        ratio = min(0.5, max(CONFIG["source_subtitle_mask_ratio"], sub_band))
         geometry = f"x=0:y=ih-ih*{ratio:.3f}:w=iw:h=ih*{ratio:.3f}"
 
     base = f"drawbox={geometry}:color=black@{opacity:.2f}:t=fill"
-    timing = str(CONFIG.get("source_subtitle_mask_timing", "narration") or "narration").lower()
-    if timing not in {"all", "narration"}:
-        timing = "narration"
     filters = []
-    if timing == "all" and opacity > 0:
-        filters.append(base)
-    elif timing == "narration" and opacity > 0:
-        windows = []
-        for seg in tts_segments or []:
-            if not isinstance(seg, dict):
-                continue
-            start, end = _seg_place_window(seg)
-            try:
-                start, end = float(start), float(end)
-            except (TypeError, ValueError):
-                continue
-            if end <= start:
-                continue
-            windows.append((start, end, 0.0))
-        # Avoid overlapping drawboxes: stacking two 60%-black masks would darken the overlap
-        # to 84%. Coalescing also keeps long filter chains smaller.
-        filters.extend(
-            f"{base}:enable='between(t,{start:.3f},{end:.3f})'"
-            for start, end, _ in coalesce_duck_windows(windows, bridge=0.001)
-        )
+    if opacity > 0:
+        if timing == "all":
+            filters.append(base)
+        else:
+            windows = [
+                (start, end, 0.0)
+                for start, end in map(_seg_place_window, tts_segments)
+                if end > start
+            ]
+            # Avoid overlapping drawboxes: stacking two 60%-black masks would darken the
+            # overlap to 84%. Coalescing also keeps long filter chains smaller.
+            filters.extend(
+                f"{base}:enable='between(t,{start:.3f},{end:.3f})'"
+                for start, end, _ in coalesce_duck_windows(windows, bridge=0.001)
+            )
 
     # A translucent mask deliberately leaves the source glyphs visible. Whenever we burn a
     # replacement original-dialogue subtitle into a gap, cover that exact window opaquely first;
     # otherwise the source hard-sub and replacement text are stacked on top of each other.
-    if video_duration is not None and not (timing == "all" and opacity >= 1.0 - 1e-9):
-        replacement_entries = _original_gap_subtitle_entries(
-            tts_segments or [], work_dir, video_duration
-        )
+    if not (timing == "all" and opacity >= 1.0 - 1e-9):
         replacement_windows = [
-            (entry["start"], entry["end"], 0.0) for entry in replacement_entries
+            (entry["start"], entry["end"], 0.0)
+            for entry in _original_gap_subtitle_entries(tts_segments, work_dir, video_duration)
         ]
         opaque = f"drawbox={geometry}:color=black@1.00:t=fill"
         filters.extend(