@oh-story/dsh 0.1.8 → 0.1.9

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

@@ -7,7 +7,7 @@ from pathlib import Path
 from artifacts import _load_work_json
 from audio_mix import _seg_place_window
 from lib import CONFIG
-from media import _load_cut_timeline_plan
+from media import _plan_clip_spans
 from assemble_constants import (
     _AUTO_ORIGINAL_READ_CPS,
     _MAX_ORIGINAL_READ_CPS,
@@ -37,17 +37,15 @@ def _source_subtitle_mask_policy(work_dir=None):
     legacy flag is represented as ``legacy_implicit`` and blocks the visual gate
     instead of silently masking picture information.
     """
-    burn = bool(CONFIG.get("burn_subtitles", False))
-    raw_policy = str(CONFIG.get("source_subtitle_mask_policy", "") or "").strip().lower()
-    legacy_flag = bool(CONFIG.get("mask_source_subtitles", False))
+    burn = CONFIG["burn_subtitles"]
+    raw_policy = CONFIG["source_subtitle_mask_policy"]
+    legacy_flag = CONFIG["mask_source_subtitles"]
     allowed = {"off", "opt_in", "safe", "forced"}
-    declared = bool(CONFIG.get("source_subtitle_mask_policy_declared", False)) or raw_policy in {"opt_in", "safe", "forced"}
+    declared = CONFIG["source_subtitle_mask_policy_declared"] or raw_policy in {"opt_in", "safe", "forced"}
     implicit = False
     if legacy_flag and not declared:
         raw_policy = "legacy_implicit"
         implicit = True
-    elif not raw_policy:
-        raw_policy = "off"
     elif raw_policy not in allowed:
         implicit = True
     user_subtitles = _has_user_subtitles(work_dir)
@@ -78,7 +76,7 @@ def _source_subtitle_mask_policy(work_dir=None):
         "active": bool(active),
         "scope": (
             "measured_source_subtitle_band"
-            if active and 0 <= int(CONFIG.get("subtitle_y_top", -1)) < int(CONFIG.get("subtitle_y_bot", -1))
+            if active and 0 <= CONFIG["subtitle_y_top"] < CONFIG["subtitle_y_bot"]
             else ("bottom_source_subtitle_band" if active else "none")
         ),
         "trigger": trigger,
@@ -86,107 +84,88 @@ def _source_subtitle_mask_policy(work_dir=None):
         "burn_subtitles": burn,
         "legacy_mask_flag": legacy_flag,
         "user_subtitles_present": user_subtitles,
-        "blocking": bool(implicit),
+        "blocking": implicit,
     }
 
 
 def _load_original_asr(work_dir):
-    """The original speech transcription (asr_result.json), SOURCE-time, cleaned to
-    {start,end,text} with text and a positive span. [] when absent/unparseable."""
-    segs = []
-    for s in _load_work_json(work_dir, "asr_result.json") or []:
-        if not isinstance(s, dict):
-            continue
-        try:
-            start, end = float(s["start"]), float(s["end"])
-        except (KeyError, TypeError, ValueError):
-            continue
-        text = str(s.get("text", "")).strip()
-        if text and end > start:
-            segs.append({"start": start, "end": end, "text": text})
-    return segs
+    """The original speech transcription (asr_result.json), SOURCE-time [{start,end,text}]; [] when absent."""
+    data = _load_work_json(work_dir, "asr_result.json")
+    if data is None:
+        return []
+    return [{"start": float(s["start"]), "end": float(s["end"]), "text": s["text"]} for s in data]
 
 
 def _load_agent_original_subtitles(work_dir):
     """Agent-calibrated original-dialogue subtitles (original_subtitles.json): OUTPUT-time
     [{start,end,text}] the writer authors alongside narration.json — the corrected, gap-aligned
     transcript of what is ACTUALLY said in each original-audio gap (ASR errors/names fixed).
-    None when absent/invalid (then assemble falls back to a conservative auto-ASR mapping)."""
+    None when absent or empty (then assemble falls back to a conservative auto-ASR mapping)."""
     data = _load_work_json(work_dir, "original_subtitles.json")
-    if not isinstance(data, list):
+    if not data:
         return None
-    out = []
-    for s in data:
-        if not isinstance(s, dict):
-            continue
-        try:
-            start, end = float(s["start"]), float(s["end"])
-        except (KeyError, TypeError, ValueError):
-            continue
-        text = str(s.get("text", "")).strip()
-        if text and end > start:
-            out.append({"start": start, "end": end, "text": text})
-    return out or None
+    return [{"start": float(s["start"]), "end": float(s["end"]), "text": s["text"]} for s in data]
 
 
-def _clean_subtitle_segments(raw):
-    """Coerce an iterable of {start,end,text} dicts to validated, positive-span segments."""
+def _user_subtitle_entries(rows, source):
+    """Validate user-authored {start,end,text} rows; a malformed row is an error, not a skip."""
     out = []
-    for s in raw or []:
-        if not isinstance(s, dict):
-            continue
+    for index, row in enumerate(rows, start=1):
         try:
-            start, end = float(s["start"]), float(s["end"])
-        except (KeyError, TypeError, ValueError):
-            continue
-        text = str(s.get("text", "")).strip()
-        if text and end > start:
-            out.append({"start": start, "end": end, "text": text})
+            start, end, text = float(row["start"]), float(row["end"]), row["text"].strip()
+        except (KeyError, TypeError, ValueError, AttributeError) as exc:
+            raise ValueError(f"{source} 第 {index} 条缺少或无法解析 start/end/text: {row!r}") from exc
+        if end <= start or not text:
+            raise ValueError(f"{source} 第 {index} 条无效（需要 end > start 且 text 非空）: {row!r}")
+        out.append({"start": start, "end": end, "text": text})
     return out
 
 
 def _parse_srt_timestamp(value):
-    """Parse an SRT 'HH:MM:SS,mmm' (or ASS 'H:MM:SS.cc') timestamp into seconds, or None."""
-    m = re.match(r"\s*(\d+):(\d{1,2}):(\d{1,2})[.,](\d{1,3})\s*$", str(value))
+    """Parse an SRT 'HH:MM:SS,mmm' (or ASS 'H:MM:SS.cc') timestamp into seconds."""
+    m = re.match(r"\s*(\d+):(\d{1,2}):(\d{1,2})[.,](\d{1,3})\s*$", value)
     if not m:
-        return None
+        raise ValueError(f"无法解析字幕时间戳: {value!r}")
     h, mm, ss, frac = m.groups()
     return int(h) * 3600 + int(mm) * 60 + int(ss) + int(frac) / (10 ** len(frac))
 
 
-def _parse_srt_text(text):
-    """Minimal SRT parser → [{start,end,text}]. Tolerant of blank lines / missing indices."""
+def _parse_srt_text(text, source):
+    """Minimal SRT parser → [{start,end,text}]. Blank lines and missing indices are tolerated;
+    a block without a parseable timing line is an error. Cues with no text are dropped."""
     segs = []
-    for block in re.split(r"\n\s*\n", str(text).replace("\r\n", "\n").replace("\r", "\n")):
+    for block in re.split(r"\n\s*\n", text.replace("\r\n", "\n").replace("\r", "\n")):
         lines = [ln for ln in block.split("\n") if ln.strip()]
         if not lines:
             continue
         if lines[0].strip().isdigit():
             lines = lines[1:]
         if not lines or "-->" not in lines[0]:
-            continue
-        parts = lines[0].split("-->")
-        if len(parts) != 2:
-            continue
-        start, end = _parse_srt_timestamp(parts[0]), _parse_srt_timestamp(parts[1])
+            raise ValueError(f"{source}: 字幕块缺少时间行: {block.strip()!r}")
+        start_text, end_text = lines[0].split("-->", 1)
+        start, end = _parse_srt_timestamp(start_text), _parse_srt_timestamp(end_text)
+        if end <= start:
+            raise ValueError(f"{source}: 字幕结束时间必须晚于开始时间: {lines[0].strip()!r}")
         body = " ".join(lines[1:]).strip()
-        if start is not None and end is not None and end > start and body:
+        if body:
             segs.append({"start": start, "end": end, "text": body})
     return segs
 
 
-def _parse_ass_text(text):
+def _parse_ass_text(text, source):
     """Minimal ASS Dialogue parser → [{start,end,text}] (Start, End are fields 2 and 3)."""
     segs = []
-    for line in str(text).replace("\r\n", "\n").replace("\r", "\n").split("\n"):
+    for line in text.replace("\r\n", "\n").replace("\r", "\n").split("\n"):
         if not line.startswith("Dialogue:"):
             continue
         fields = line[len("Dialogue:"):].split(",", 9)
         if len(fields) < 10:
-            continue
+            raise ValueError(f"{source}: Dialogue 行字段不足: {line!r}")
         start, end = _parse_srt_timestamp(fields[1]), _parse_srt_timestamp(fields[2])
+        if end <= start:
+            raise ValueError(f"{source}: 字幕结束时间必须晚于开始时间: {line!r}")
         body = re.sub(r"\{[^}]*\}", "", fields[9]).replace("\\N", " ").replace("\\n", " ").strip()
-        if start is not None and end is not None and end > start and body:
+        if body:
             segs.append({"start": start, "end": end, "text": body})
     return segs
 
@@ -200,79 +179,39 @@ def _load_user_original_subtitles(work_dir):
         via the cut clip spans, "output" (default) is used directly.
       - user_subtitles.srt / user_subtitles.ass: parsed minimally and defaulted to SOURCE-time,
         so they are remapped to OUTPUT via the cut clip spans.
-    Returns OUTPUT-time [{start,end,text}], or None when absent/malformed (caller falls back)."""
+    Returns OUTPUT-time [{start,end,text}], or None when no user file exists. A malformed
+    file raises: the user asked for these subtitles, so silently falling back is wrong."""
     work = Path(work_dir)
     json_path = work / "user_subtitles.json"
     if json_path.exists():
         try:
             data = json.loads(json_path.read_text(encoding="utf-8"))
-        except (ValueError, OSError):
-            return None
-        if isinstance(data, list):
-            segs, timeline = _clean_subtitle_segments(data), "output"
-        elif isinstance(data, dict):
-            segs = _clean_subtitle_segments(data.get("lines"))
-            timeline = str(data.get("timeline", "output")).lower()
+        except ValueError as exc:
+            raise ValueError(f"{json_path} 不是合法 JSON: {exc}") from exc
+        if isinstance(data, dict):
+            timeline = data.get("timeline", "output")
+            if timeline not in {"source", "output"}:
+                raise ValueError(f"{json_path}: timeline 必须是 source 或 output，当前为 {timeline!r}")
+            rows = data["lines"]
         else:
-            return None
-        if not segs:
-            return None
+            timeline, rows = "output", data
+        segs = _user_subtitle_entries(rows, json_path.name)
         if timeline == "source":
-            segs = _map_asr_to_output(segs, _output_clip_spans(work))
-        return segs or None
+            segs = _map_asr_to_output(segs, _plan_clip_spans(work))
+        return segs
 
     for name in ("user_subtitles.srt", "user_subtitles.ass"):
         path = work / name
         if not path.exists():
             continue
-        try:
-            text = path.read_text(encoding="utf-8")
-        except OSError:
-            return None
         parser = _parse_ass_text if name.endswith(".ass") else _parse_srt_text
-        segs = _clean_subtitle_segments(parser(text))
-        if not segs:
-            return None
+        segs = parser(path.read_text(encoding="utf-8"), name)
         # .srt/.ass default to SOURCE-time → remap onto the output timeline (identity in full mode).
-        segs = _map_asr_to_output(segs, _output_clip_spans(work))
-        return segs or None
+        return _map_asr_to_output(segs, _plan_clip_spans(work))
 
     return None
 
 
-def _output_clip_spans(work_dir):
-    """Cut-mode source→output clip spans using the same freshness logic as video clips."""
-    try:
-        plan = _load_cut_timeline_plan(work_dir)
-    except (OSError, ValueError, json.JSONDecodeError):
-        plan = None
-    if not plan:
-        return None
-    entries = plan.get("clips", plan) if isinstance(plan, dict) else plan
-    if not isinstance(entries, list):
-        return None
-    spans, cursor = [], 0.0
-    for c in entries:
-        if not isinstance(c, dict):
-            continue
-        try:
-            ss = float(c.get("source_start", c.get("start")))
-            se = float(c.get("source_end", c.get("end")))
-        except (TypeError, ValueError):
-            continue
-        if se - ss <= 0:
-            continue
-        out_s, out_e = c.get("output_start"), c.get("output_end")
-        if out_s is None or out_e is None:
-            out_s, out_e = cursor, cursor + (se - ss)
-            cursor += se - ss
-        else:
-            out_s, out_e = float(out_s), float(out_e)
-            cursor = max(cursor, out_e)
-        spans.append({"source_start": ss, "source_end": se, "output_start": out_s, "output_end": out_e})
-    return spans or None
-
-
 def _map_asr_to_output(asr_segs, clip_spans):
     """Map SOURCE-time ASR segments onto the OUTPUT timeline. Full mode (clip_spans None) is
     identity; cut mode intersects each ASR span with each kept clip (a straddling line yields one
@@ -296,8 +235,7 @@ def _map_asr_to_output(asr_segs, clip_spans):
 def _narration_gap_windows(tts_segments, video_duration, min_gap=_MIN_GAP_TO_SUBTITLE):
     """OUTPUT-timeline stretches with NO narration (the original-audio blocks): the complement of
     the merged narration placement windows within [0, video_duration], keeping gaps >= min_gap."""
-    placed = sorted(
-        (_seg_place_window(s) for s in tts_segments if isinstance(s, dict)), key=lambda w: w[0])
+    placed = sorted(map(_seg_place_window, tts_segments), key=lambda w: w[0])
     merged = []
     for s, e in placed:
         if e - s <= 0:
@@ -325,10 +263,9 @@ def _original_gap_subtitle_entries(tts_segments, work_dir, video_duration):
     # 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.
-    mask_covers_gaps = _source_subtitle_mask_covers_gaps(work_dir)
-    if not (CONFIG.get("burn_subtitles", False)
-            and CONFIG.get("subtitle_original_in_gaps", True)
-            and (mask_covers_gaps or _has_user_subtitles(work_dir))):
+    if not (CONFIG["burn_subtitles"]
+            and CONFIG["subtitle_original_in_gaps"]
+            and (_source_subtitle_mask_covers_gaps(work_dir) or _has_user_subtitles(work_dir))):
         return []
     gaps = _narration_gap_windows(tts_segments, video_duration)
     if not gaps:
@@ -338,23 +275,17 @@ def _original_gap_subtitle_entries(tts_segments, work_dir, video_duration):
     # conservative auto-ASR mapping. The user file and the agent file are time-precise (their spans
     # are the real on-screen windows), so they take the interval-clip "precise" path; raw ASR is
     # coarse and stays on the midpoint+over-render-guard fallback path.
+    max_chars = CONFIG["subtitle_max_chars"]
     user = _load_user_original_subtitles(work_dir)
     if user is not None:
-        candidates, precise = user, True
-    else:
-        agent = _load_agent_original_subtitles(work_dir)
-        if agent is not None:
-            candidates, precise = agent, True
-        else:
-            asr = _load_original_asr(work_dir)
-            if not asr:
-                return []
-            candidates, precise = _map_asr_to_output(asr, _output_clip_spans(work_dir)), False
-
-    max_chars = int(CONFIG.get("subtitle_max_chars", 20))
-    if precise:
-        return _precise_gap_entries(candidates, gaps, max_chars)
-    return _fallback_gap_entries(candidates, gaps, max_chars)
+        return _precise_gap_entries(user, gaps, max_chars)
+    agent = _load_agent_original_subtitles(work_dir)
+    if agent is not None:
+        return _precise_gap_entries(agent, gaps, max_chars)
+    asr = _load_original_asr(work_dir)
+    if not asr:
+        return []
+    return _fallback_gap_entries(_map_asr_to_output(asr, _plan_clip_spans(work_dir)), gaps, max_chars)
 
 
 def _precise_gap_entries(candidates, gaps, max_chars):
@@ -364,25 +295,23 @@ def _precise_gap_entries(candidates, gaps, max_chars):
     shorter than _MIN_READABLE_SECONDS are dropped. No over-render guard (the source is trusted)."""
     entries = []
     for seg in candidates:
-        text = str(seg["text"]).strip()
-        if not text:
-            continue
+        text = seg["text"]
         seg_start, seg_end = float(seg["start"]), float(seg["end"])
-        seg_dur = seg_end - seg_start
-        overlaps = []
-        for gs, ge in gaps:
-            cs, ce = max(seg_start, gs), min(seg_end, ge)
-            if ce - cs >= _MIN_READABLE_SECONDS:
-                overlaps.append((cs, ce))
+        overlaps = [
+            (max(seg_start, gs), min(seg_end, ge))
+            for gs, ge in gaps
+            if min(seg_end, ge) - max(seg_start, gs) >= _MIN_READABLE_SECONDS
+        ]
         if not overlaps:
             continue
-        if len(overlaps) == 1 or seg_dur <= 0:
+        if len(overlaps) == 1:
             # the common case (a line authored within one gap): show it whole in that gap
             cs, ce = overlaps[0]
             entries.extend(_bracketed_original_chunks(text, cs, ce, max_chars))
             continue
         # the line straddles a narration block: show each gap only ITS portion of the text
         # (proportional to the time the line overlaps that gap) instead of the whole line twice.
+        seg_dur = seg_end - seg_start
         n = len(text)
         for cs, ce in overlaps:
             lo = max(0, int(round((cs - seg_start) / seg_dur * n)))
@@ -397,7 +326,7 @@ def _split_sentences_keep_delims(text):
     """Split on terminal CJK sentence marks 。！？ keeping each delimiter with its sentence. A
     fragment that is only closing quotes/brackets (e.g. a trailing 」 after a 。 inside a quote) is
     re-attached to the previous sentence so quoted speech is never split off into a bare 」."""
-    parts = [p.strip() for p in re.split(r"(?<=[。！？])", str(text)) if p.strip()]
+    parts = [p.strip() for p in re.split(r"(?<=[。！？])", text) if p.strip()]
     merged = []
     for part in parts:
         if merged and all(ch in _SUBTITLE_CLOSING_QUOTES for ch in part):
@@ -418,11 +347,8 @@ def _fallback_gap_entries(candidates, gaps, max_chars):
     #    its char-proportional midpoint lands in (the only "which gap" signal coarse ASR gives).
     buckets = {}  # gap_index -> [(estimated_onset, sentence_text)]
     for seg in candidates:
-        for sentence in _split_sentences_keep_delims(seg["text"]) or [str(seg["text"]).strip()]:
-            text = sentence.strip()
-            if not text:
-                continue
-            sub = _sentence_subspan(seg, sentence)
+        for text in _split_sentences_keep_delims(seg["text"]):
+            sub = _sentence_subspan(seg, text)
             mid = (sub["start"] + sub["end"]) / 2.0
             gi = next((i for i, (gs, ge) in enumerate(gaps) if gs <= mid < ge), None)
             if gi is None:
@@ -447,8 +373,7 @@ def _fallback_gap_entries(candidates, gaps, max_chars):
             if ce2 - cursor < _MIN_READABLE_SECONDS:
                 break
             max_len = int((ce2 - cursor) * _MAX_ORIGINAL_READ_CPS)
-            shown = text if len(text) <= max_len else text[:max_len]
-            entries.extend(_bracketed_original_chunks(shown, cursor, ce2, max_chars))
+            entries.extend(_bracketed_original_chunks(text[:max_len], cursor, ce2, max_chars))
             cursor = ce2
     return entries
 
@@ -456,22 +381,20 @@ def _fallback_gap_entries(candidates, gaps, max_chars):
 def _sentence_subspan(seg, sentence):
     """The slice of seg's [start,end] window that this sentence occupies, by character proportion.
     Single-sentence lines return the whole span unchanged."""
-    full = str(seg["text"]).strip()
-    if not full or sentence.strip() == full:
-        return {"start": seg["start"], "end": seg["end"]}
-    idx = full.find(sentence.strip())
-    if idx < 0:
+    full = seg["text"].strip()
+    idx = full.find(sentence)
+    if not full or sentence == full or idx < 0:
         return {"start": seg["start"], "end": seg["end"]}
     span = seg["end"] - seg["start"]
     s = seg["start"] + span * (idx / len(full))
-    e = seg["start"] + span * ((idx + len(sentence.strip())) / len(full))
+    e = seg["start"] + span * ((idx + len(sentence)) / len(full))
     return {"start": s, "end": e}
 
 
 def _combined_subtitle_entries(narration, work_dir, video_duration):
     """Narration subtitle entries plus original-dialogue entries in the gaps, sorted by start.
     Original entries are confined to narration gaps, so they never overlap narration entries."""
-    entries = list(_subtitle_entries(narration))
+    entries = _subtitle_entries(narration)
     entries.extend(_original_gap_subtitle_entries(narration, work_dir, video_duration))
     entries.sort(key=lambda x: (x["start"], x["end"]))
     return entries
@@ -479,8 +402,6 @@ def _combined_subtitle_entries(narration, work_dir, video_duration):
 
 def _source_subtitle_mask_covers_gaps(work_dir=None):
     """Whether the effective source mask hides hardcoded subtitles outside narration."""
-    if not _source_subtitle_mask_policy(work_dir).get("active"):
+    if not _source_subtitle_mask_policy(work_dir)["active"]:
         return False
-    opacity = max(0.0, min(1.0, float(CONFIG.get("subtitle_mask_opacity", 0.6))))
-    timing = str(CONFIG.get("source_subtitle_mask_timing", "narration") or "narration").lower()
-    return opacity >= 1.0 - 1e-9 and timing == "all"
+    return CONFIG["subtitle_mask_opacity"] >= 1.0 - 1e-9 and CONFIG["source_subtitle_mask_timing"] == "all"