@oh-story/dsh 0.1.12 → 0.1.13

package/lib/video-recap/skills/video-cut/scripts/cut_cli.py

@@ -2,6 +2,7 @@
 
 import json
 import math
+import os
 
 
 from pathlib import Path
@@ -10,6 +11,7 @@ from lib import CONFIG, get_video_duration, log
 import shot_review
 
 from cut_contract import (
+    SOURCES_MANIFEST_SHAPE,
     _write_edited_source_meta,
     load_clip_plan,
     normalize_clip_plan,
@@ -17,25 +19,46 @@ from cut_contract import (
     parse_duration_seconds,
     should_reuse_edited_source,
 )
-from cut_render import (
-    build_edited_source_video,
-    update_delivery_qc,
-    write_cut_delivery_qc,
-)
+from cut_render import build_edited_source_video
+from frame_grid import record_frame_grid, source_frame_grids
 from media_geometry import _has_audio_stream, _select_output_geometry
 from narrative_selection import check_required_evidence
-from narration_mapping import update_cut_qc
-from sentence_boundaries import (
-    _combine_boundary_windows,
-    _load_sentence_boundary_windows,
-    _load_silence_for_source,
-    _load_source_speech_spans,
-    enforce_clip_sentence_boundaries,
-    snap_clip_ends_to_lines,
-    snap_clip_starts_to_lines,
-    snap_clips_off_shot_changes,
-    snap_multi_source_clips,
-)
+from cut_qc import update_cut_qc
+from sentence_boundaries import snap_multi_source_clips, snap_source_clips
+
+
+def _write_validated_plan(path, plan, raw_plan_paths):
+    """Write clip_plan_validated.json unless the file already holds exactly this plan.
+
+    Downstream output-clock evidence binds to this file's {size, mtime_ns}, so a resumed
+    run that re-validates an unchanged plan must leave it alone. The file is still
+    rewritten when any raw plan is newer, so "validated older than raw = stale" holds."""
+    text = json.dumps(plan, ensure_ascii=False, indent=2)
+    if path.exists() and path.read_text(encoding="utf-8") == text:
+        written = path.stat().st_mtime_ns
+        if all(not raw.exists() or raw.stat().st_mtime_ns <= written for raw in raw_plan_paths):
+            return
+    path.write_text(text, encoding="utf-8")
+
+
+def _required_ranges_by_source(raw_plan, source_paths):
+    """{plan source path: [(start, end)]} of declared required-evidence nodes.
+
+    Only a hint for frame snapping; check_required_evidence validates the contract itself.
+    """
+    nodes = raw_plan.get("required_evidence") if isinstance(raw_plan, dict) else None
+    nodes = nodes.get("nodes") if isinstance(nodes, dict) else None
+    by_realpath = {os.path.realpath(path): path for path in source_paths}
+    ranges = {}
+    for node in nodes if isinstance(nodes, list) else []:
+        try:
+            path = by_realpath.get(os.path.realpath(node["source"]))
+            start, end = float(node["start"]), float(node["end"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        if path is not None:
+            ranges.setdefault(path, []).append((start, end))
+    return ranges
 
 
 def main():
@@ -58,19 +81,13 @@ def main():
     parser.add_argument(
         "--sources-manifest",
         default=None,
-        help="multi-source manifest json mapping source_id values to source media",
+        help=f"multi-source manifest json: {SOURCES_MANIFEST_SHAPE}",
     )
     parser.add_argument(
         "--target-duration",
         default=None,
         help="target output duration, e.g. 10m / 600 / 00:10:00",
     )
-    parser.add_argument(
-        "--clip-padding",
-        type=float,
-        default=None,
-        help="seconds to pad each clip on both ends (default: CLIP_PADDING env, else 0)",
-    )
     parser.add_argument(
         "--allow-overlap",
         action="store_true",
@@ -79,8 +96,8 @@ def main():
     parser.add_argument(
         "--normalize-only",
         action="store_true",
-        help="only normalize the clip plan -> clip_plan_validated.json (no render); "
-        "lets validate lint the SAME padded/pruned plan the render uses",
+        help="normalize, snap and QC the clip plan, write clip_plan_validated.json, then exit "
+        "without rendering",
     )
     parser.add_argument(
         "--review-shots", action="store_true",
@@ -110,13 +127,6 @@ def main():
     ):
         parser.error("--shot-roi requires --review-shots, nonnegative X/Y and positive WIDTH/HEIGHT")
 
-    # CLIP_PADDING is declared in every skill's CONFIG, but video-cut is the only place that
-    # implements padding — and it used to read the CLI flag alone, so setting the env var did
-    # nothing at all while `clip_padding_source: "env"` reported otherwise. CLI still wins.
-    clip_padding = (
-        args.clip_padding if args.clip_padding is not None else CONFIG["clip_padding"]
-    )
-
     work_dir = Path(args.work_dir)
     work_dir.mkdir(parents=True, exist_ok=True)
     clip_plan_path = (
@@ -132,90 +142,68 @@ def main():
         if args.sources_manifest
         else None
     )
-    if sources_manifest is not None:
-        validated_plan = normalize_multi_source_clip_plan(
+    # Visual shot-change cleanup runs first; the sentence/quiet pass is the final authority,
+    # so a prettier edit point never moves a boundary back inside a spoken sentence.
+    snap_options = {
+        "line_max_extend": CONFIG["clip_snap_max_extend"],
+        "scene_margin": CONFIG["scene_cut_snap_margin"],
+        "scene_threshold": CONFIG["scene_cut_detect_threshold"],
+        "start_max_prepend": CONFIG["clip_start_snap_max_prepend"],
+        "start_max_trim": CONFIG["clip_start_snap_max_trim"],
+        "do_line_snap": CONFIG["snap_clip_line_end"],
+        "do_scene_snap": CONFIG["scene_cut_snap"],
+    }
+    if sources_manifest is None:
+        video_duration = get_video_duration(args.video)
+        validated_plan = normalize_clip_plan(
             raw_plan,
-            sources_manifest,
+            video_duration,
             target_duration=target_seconds,
-            clip_padding=clip_padding,
             allow_overlap=args.allow_overlap,
         )
-        video_duration = None
     else:
-        video_duration = get_video_duration(args.video)
-        validated_plan = normalize_clip_plan(
+        validated_plan = normalize_multi_source_clip_plan(
             raw_plan,
-            video_duration,
+            sources_manifest,
             target_duration=target_seconds,
-            clip_padding=clip_padding,
             allow_overlap=args.allow_overlap,
         )
-
-    # Keep boundaries off the original footage's hard cuts (avoids 闪烁 at the edit point).
-    # This visual-only pass runs FIRST. The sentence/quiet pass below is the final authority:
-    # a prettier edit point must never move the final boundary back inside a spoken sentence.
-    if sources_manifest is None and CONFIG["scene_cut_snap"]:
-        validated_plan = snap_clips_off_shot_changes(
-            validated_plan,
-            args.video,
-            margin=CONFIG["scene_cut_snap_margin"],
-            threshold=CONFIG["scene_cut_detect_threshold"],
+    # The canvas (and so the output frame rate) is chosen before snapping because the
+    # frame-grid pass snaps clip lengths to whole output frames; the same geometry is
+    # recorded in clip_plan_validated.json and used for the render.
+    # Single-source clips carry no source_path; the CLI video is the only input.
+    source_paths = list(
+        dict.fromkeys(
+            clip["source_path"] for clip in validated_plan["clips"] if "source_path" in clip
         )
-
+    ) or [str(args.video)]
+    _, _, _, geometry_qc = _select_output_geometry(source_paths, validated_plan["clips"])
+    frame_grids = source_frame_grids(geometry_qc)
+    for path, ranges in _required_ranges_by_source(raw_plan, source_paths).items():
+        frame_grids[path]["keep_ranges"] = ranges
     if sources_manifest is None:
-        safe_boundaries = _combine_boundary_windows(
-            _load_silence_for_source(work_dir, None),
-            _load_sentence_boundary_windows(work_dir),
+        validated_plan = snap_source_clips(
+            validated_plan, args.video, video_duration, work_dir,
+            frame_grid=frame_grids[str(args.video)], **snap_options,
         )
-        if CONFIG["snap_clip_line_end"]:
-            validated_plan = snap_clip_starts_to_lines(
-                validated_plan,
-                safe_boundaries,
-                video_duration,
-                CONFIG["clip_start_snap_max_prepend"],
-                max_trim=CONFIG["clip_start_snap_max_trim"],
-            )
-            validated_plan = snap_clip_ends_to_lines(
-                validated_plan,
-                safe_boundaries,
-                video_duration,
-                CONFIG["clip_snap_max_extend"],
-            )
-        validated_plan = enforce_clip_sentence_boundaries(
-            validated_plan,
-            safe_boundaries,
-            _load_source_speech_spans(work_dir),
-            video_duration,
-        )
-
-    # Multi-source: snap each clip against ITS OWN source's pauses/shot-changes (single-source
-    # snaps above can't, since silence_periods.json and args.video are per-project, not per-source).
-    if sources_manifest is not None:
+    else:
+        # Each clip snaps against ITS OWN source's pauses, shot changes and frame grid.
         validated_plan = snap_multi_source_clips(
-            validated_plan,
-            validated_plan["sources"],
-            work_dir,
-            line_max_extend=CONFIG["clip_snap_max_extend"],
-            scene_margin=CONFIG["scene_cut_snap_margin"],
-            scene_threshold=CONFIG["scene_cut_detect_threshold"],
-            do_line_snap=CONFIG["snap_clip_line_end"],
-            do_scene_snap=CONFIG["scene_cut_snap"],
-            start_max_prepend=CONFIG["clip_start_snap_max_prepend"],
-            start_max_trim=CONFIG["clip_start_snap_max_trim"],
+            validated_plan, validated_plan["sources"], work_dir,
+            frame_grids={
+                sid: frame_grids[source["source_path"]]
+                for sid, source in validated_plan["sources"].items()
+                if source["source_path"] in frame_grids
+            },
+            **snap_options,
         )
 
     validated_plan.setdefault("qc", {})["join_fade_ms"] = round(
         CONFIG["clip_join_audio_fade_ms"], 3
     )
-    # Single-source clips carry no source_path; the CLI video is the only input.
-    source_paths = list(
-        dict.fromkeys(
-            clip["source_path"] for clip in validated_plan["clips"] if "source_path" in clip
-        )
-    ) or [str(args.video)]
-    _, _, _, geometry_qc = _select_output_geometry(source_paths, validated_plan["clips"])
     validated_plan["qc"]["output_geometry"] = geometry_qc
     validated_plan["qc"]["output_geometry_reason"] = geometry_qc["reason"]
+    record_frame_grid(validated_plan, geometry_qc)
     update_cut_qc(
         validated_plan,
         allow_duration_drift=bool(args.allow_duration_drift),
@@ -223,8 +211,6 @@ def main():
     )
     if isinstance(raw_plan, dict) and 'required_evidence' in raw_plan:
         # Re-evaluate the final snapped ranges even when the media cache can be reused.
-        # A prior rendered receipt must not survive a failed revision preflight.
-        (work_dir / 'cut_delivery_qc.json').unlink(missing_ok=True)
         contract = raw_plan['required_evidence']
         plan_sources = {str(Path(path).resolve()): path for path in source_paths}
         source_audio = {}
@@ -240,14 +226,16 @@ def main():
         validated_plan['qc']['required_evidence'] = {**report, 'contract': contract}
         if report['selection_status'] == 'BLOCK':
             validated_plan['qc'].setdefault('blocking', []).extend(report['findings'])
-    update_delivery_qc(
-        validated_plan,
-        source_paths=source_paths,
-        output_path=work_dir / "edited_source.mp4",
-    )
-    (work_dir / "clip_plan_validated.json").write_text(
-        json.dumps(validated_plan, ensure_ascii=False, indent=2), encoding="utf-8"
+    plan_path = work_dir / "clip_plan_validated.json"
+    raw_plan_paths = {clip_plan_path, work_dir / "clip_plan.json"}
+    edited_source_path = work_dir / "edited_source.mp4"
+    reuse = (
+        not validated_plan["qc"].get("blocking")
+        and not args.normalize_only
+        and should_reuse_edited_source(edited_source_path, validated_plan, args.video)
     )
+    if not reuse:
+        _write_validated_plan(plan_path, validated_plan, raw_plan_paths)
     if validated_plan["qc"].get("blocking"):
         raise SystemExit(
             "clip_plan QC blocking: fix required source evidence, unsafe sentence boundaries or target-duration drift. "
@@ -255,9 +243,6 @@ def main():
             "sentence truncation is never allowed. See clip_plan_validated.json['qc']."
         )
     if args.normalize_only:
-        # normalize-only produces planned delivery facts in clip_plan_validated.json, but no
-        # rendered/reused media exists in this run, so remove any stale final delivery artifact.
-        (work_dir / "cut_delivery_qc.json").unlink(missing_ok=True)
         print(
             json.dumps(
                 {
@@ -270,27 +255,14 @@ def main():
         )
         return
 
-    edited_source_path = work_dir / "edited_source.mp4"
-    if should_reuse_edited_source(edited_source_path, validated_plan, args.video):
+    if reuse:
         log(f"复用剪辑源视频: {edited_source_path}")
-        update_delivery_qc(
-            validated_plan,
-            source_paths=source_paths,
-            output_path=edited_source_path,
-            rendered=True,
-        )
-        write_cut_delivery_qc(work_dir, validated_plan)
         _write_edited_source_meta(edited_source_path, validated_plan, args.video)
-        (work_dir / "clip_plan_validated.json").write_text(
-            json.dumps(validated_plan, ensure_ascii=False, indent=2), encoding="utf-8"
-        )
     else:
         build_edited_source_video(
             args.video, validated_plan, work_dir, edited_source_path
         )
-        (work_dir / "clip_plan_validated.json").write_text(
-            json.dumps(validated_plan, ensure_ascii=False, indent=2), encoding="utf-8"
-        )
+    _write_validated_plan(plan_path, validated_plan, raw_plan_paths)
 
     if args.review_shots:
         review_options = {"plan_path": work_dir / "clip_plan_validated.json"}