@oh-story/dsh 0.1.10 → 0.1.12

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

@@ -1,20 +1,11 @@
-"""Normalize cut plans and maintain render-cache provenance."""
-
-import hashlib
+"""Normalize cut plans and maintain the render-cache sidecar."""
 
 import json
-import os
-
 import re
 
-
 from pathlib import Path
 
-from lib import CONFIG, get_video_duration, log
-
-EDITED_SOURCE_RENDER_ALGORITHM_VERSION = "edited-source-render-v3"
-
-GEOMETRY_RENDER_ALGORITHM_VERSION = "geometry-weighted-orientation-area-fps-v2"
+from lib import CONFIG, file_identity, get_video_duration, log
 
 
 def parse_duration_seconds(value):
@@ -101,111 +92,42 @@ def load_clip_plan(path):
     return json.loads(Path(path).read_text(encoding="utf-8"))
 
 
-def _stable_json_dumps(value):
-    return json.dumps(
-        value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str
-    )
-
-
-def value_fingerprint(value):
-    """Return a stable fingerprint for JSON-serializable non-secret values."""
-    return hashlib.md5(_stable_json_dumps(value).encode("utf-8")).hexdigest()
-
-
-def cut_plan_fingerprint(validated_plan):
-    """Hash the exact normalized clip plan that determines edited_source.mp4 bytes."""
-    payload = dict(validated_plan)
-    # Provenance for raw-plan freshness is not part of the edited media bytes.
-    payload.pop("raw_plan_fingerprint", None)
-    # QC is observability derived from the media plan, not an input range decision.
-    payload.pop("qc", None)
-    return value_fingerprint(payload)
-
-
-_FILE_FINGERPRINT_MEMO = {}
-
-
-def _file_identity(path):
-    """(device, inode, size, mtime_ns) — changes whenever the bytes could have changed."""
-    st = os.stat(os.fspath(path))
-    return (st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns)
-
-
-def file_fingerprint(path, chunk_size=1024 * 1024):
-    """Return a full-content fingerprint for cache-correct identity checks.
-
-    The digest covers CONTENT only — never the path or mtime — so a copied video or
-    artifact is still recognised as the same asset, while any byte change invalidates
-    the cache even if timestamps, size, head, or tail bytes are misleading.
-
-    Identity metadata is used ONLY to memoize within a single process. One understanding
-    run fingerprints the same source video 8-10 times and the whole extracted frame set
-    2-3 times; on a 40-minute video at fps=1 that is gigabytes of redundant reads before
-    any real work starts. A file rewritten in place gets a new (size, mtime_ns) and is
-    re-hashed, so the memo can never serve a stale digest.
-    """
-    key = _file_identity(path)
-    memoized = _FILE_FINGERPRINT_MEMO.get(key)
-    if memoized is not None:
-        return memoized
-    h = hashlib.sha256()
-    with open(os.fspath(path), "rb") as f:
-        for chunk in iter(lambda: f.read(chunk_size), b""):
-            h.update(chunk)
-    digest = h.hexdigest()
-    _FILE_FINGERPRINT_MEMO[key] = digest
-    return digest
-
-
 def _edited_source_meta_path(output_path):
     return Path(str(output_path) + ".meta.json")
 
 
 def _load_edited_source_meta(output_path):
+    """None when never rendered; a sidecar this skill wrote but cannot parse raises."""
     meta_path = _edited_source_meta_path(output_path)
     if not meta_path.exists():
         return None
-    try:
-        meta = json.loads(meta_path.read_text(encoding="utf-8"))
-    except (OSError, ValueError):
-        return None
-    return meta if isinstance(meta, dict) else None
+    return json.loads(meta_path.read_text(encoding="utf-8"))
 
 
-def _source_fingerprints_for_plan(validated_plan, input_video=None):
-    """Fingerprint every media file that can affect edited_source.mp4 bytes."""
+def _source_identities_for_plan(validated_plan, input_video=None):
+    """{path: {size, mtime_ns}} for every media file that can affect edited_source.mp4."""
     # Single-source plans carry no per-clip source_path; the CLI video is the only input.
     paths = {clip["source_path"] for clip in validated_plan["clips"] if "source_path" in clip}
     if not paths and input_video is not None:
         paths.add(str(input_video))
-    return {str(Path(path)): file_fingerprint(path) for path in sorted(paths)}
+    return {str(Path(path)): file_identity(path) for path in sorted(paths)}
 
 
 def edited_source_render_cache_payload():
     """Render-affecting settings that invalidate edited_source.mp4 cache reuse.
 
-    Keep this payload limited to inputs/algorithms that can change rendered media bytes.
+    Keep this payload limited to inputs that can change rendered media bytes.
     Observational QC produced after validation/render is intentionally excluded.
     """
-    return {
-        "render_algorithm_version": EDITED_SOURCE_RENDER_ALGORITHM_VERSION,
-        "geometry_render_algorithm_version": GEOMETRY_RENDER_ALGORITHM_VERSION,
-        "clip_join_audio_fade_ms": round(CONFIG["clip_join_audio_fade_ms"], 3),
-    }
-
-
-def edited_source_render_fingerprint():
-    return value_fingerprint(edited_source_render_cache_payload())
+    return {"clip_join_audio_fade_ms": round(CONFIG["clip_join_audio_fade_ms"], 3)}
 
 
 def _write_edited_source_meta(output_path, validated_plan, input_video=None):
     meta = {
-        "schema_version": 2,
-        "clip_plan_fingerprint": cut_plan_fingerprint(validated_plan),
-        "render_fingerprint": edited_source_render_fingerprint(),
+        "schema_version": 3,
+        "plan": validated_plan["clips"],
         "render_cache": edited_source_render_cache_payload(),
-        "source_fingerprints": _source_fingerprints_for_plan(validated_plan, input_video),
-        "edited_source_fingerprint": file_fingerprint(output_path),
+        "sources": _source_identities_for_plan(validated_plan, input_video),
         "total_duration": validated_plan["total_duration"],
         "clip_count": len(validated_plan["clips"]),
     }
@@ -215,25 +137,18 @@ def _write_edited_source_meta(output_path, validated_plan, input_video=None):
 
 
 def should_reuse_edited_source(output_path, validated_plan, input_video=None):
-    """Return True only when edited_source.mp4 matches source media and cut params."""
+    """True only when a non-empty edited_source.mp4 matches the plan, settings and sources."""
     output_path = Path(output_path)
-    if not output_path.exists():
+    if not output_path.exists() or output_path.stat().st_size == 0:
         return False
     meta = _load_edited_source_meta(output_path)
-    if meta is None:
-        return False
-    if (
-        meta.get("clip_plan_fingerprint") != cut_plan_fingerprint(validated_plan)
-        or meta.get("render_fingerprint") != edited_source_render_fingerprint()
-        or meta.get("source_fingerprints")
-        != _source_fingerprints_for_plan(validated_plan, input_video)
-    ):
-        return False
-    try:
-        output_fingerprint = file_fingerprint(output_path)
-    except OSError:
-        return False
-    return meta.get("edited_source_fingerprint") == output_fingerprint
+    if not isinstance(meta, dict) or meta.get("schema_version") != 3:
+        return False  # never rendered, or a sidecar from an older schema: re-render
+    return (
+        meta["plan"] == validated_plan["clips"]
+        and meta["render_cache"] == edited_source_render_cache_payload()
+        and meta["sources"] == _source_identities_for_plan(validated_plan, input_video)
+    )
 
 
 def _manifest_source_entries(sources_manifest):

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

@@ -5,10 +5,10 @@ import json
 
 from pathlib import Path
 
-from lib import CONFIG, get_video_duration, log, run_cmd
+from lib import CONFIG, filter_file_args, get_video_duration, log, run_cmd
 
 from cut_contract import _write_edited_source_meta
-from media_geometry import _has_audio_stream, _select_output_geometry
+from media_geometry import _has_audio_stream
 from sentence_boundaries import _continuous_source_join
 
 
@@ -129,10 +129,20 @@ def write_cut_delivery_qc(work_dir, validated_plan):
 
 
 def build_edited_source_video(input_video, validated_plan, work_dir, output_path=None):
-    """Build `edited_source.mp4` by concatenating validated source ranges."""
+    """Build `edited_source.mp4` by concatenating validated source ranges.
+
+    `validated_plan["qc"]["output_geometry"]` is required: the caller (cut_cli, or any
+    public user of this API) selects the canvas with `_select_output_geometry` first, so the
+    same geometry is recorded in clip_plan_validated.json and used for the render."""
     work_dir = Path(work_dir)
     output_path = Path(output_path or work_dir / "edited_source.mp4")
     clips = validated_plan["clips"]
+    qc = validated_plan["qc"]
+    if "output_geometry" not in qc:
+        raise KeyError(
+            "validated_plan['qc']['output_geometry'] is required: select the canvas with "
+            "media_geometry._select_output_geometry before build_edited_source_video"
+        )
 
     source_paths = []
     for clip in clips:
@@ -142,12 +152,7 @@ def build_edited_source_video(input_video, validated_plan, work_dir, output_path
     source_index = {path: idx for idx, path in enumerate(source_paths)}
     audio_by_input = {path: _has_audio_stream(path) for path in source_paths}
     join_fade_ms = CONFIG["clip_join_audio_fade_ms"]
-    qc = validated_plan.setdefault("qc", {})
     qc["join_fade_ms"] = round(join_fade_ms, 3)
-    if "output_geometry" not in qc:
-        _, _, _, geometry_qc = _select_output_geometry(source_paths, clips)
-        qc["output_geometry"] = geometry_qc
-        qc["output_geometry_reason"] = geometry_qc["reason"]
 
     parts = []
     concat_inputs = []
@@ -250,7 +255,7 @@ def build_edited_source_video(input_video, validated_plan, work_dir, output_path
     if len(filter_complex.encode("utf-8")) > 7000:
         filter_script = work_dir / "edit_filter_complex.txt"
         filter_script.write_text(filter_complex, encoding="utf-8")
-        filter_args = ["-filter_complex_script", str(filter_script)]
+        filter_args = filter_file_args("filter_complex", filter_script)
     else:
         filter_args = ["-filter_complex", filter_complex]
 

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

@@ -1,7 +1,10 @@
 """Self-contained utilities for the video-cut skill (no cross-skill imports)."""
+import functools
 import math
 import os
+import shutil
 import subprocess
+import tempfile
 
 
 def log(msg):
@@ -56,6 +59,12 @@ CONFIG = {
 }
 
 
+def file_identity(path):
+    """{size, mtime_ns} — the cache identity of an input file (no content read)."""
+    st = os.stat(os.fspath(path))
+    return {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
+
+
 def run_cmd(cmd, **kwargs):
     """Run a command list and return the CompletedProcess (stdout/stderr captured)."""
     display = " ".join(
@@ -65,6 +74,36 @@ def run_cmd(cmd, **kwargs):
     return subprocess.run(cmd, capture_output=True, text=True, **kwargs)
 
 
+# ffmpeg 7 added `-/option path` to read any option's value from a file; ffmpeg 9 removed the
+# older `-filter_complex_script` / `-filter_script` spellings, which are all ffmpeg <= 6 knows.
+_LEGACY_FILTER_FILE_OPTIONS = {
+    "filter_complex": "-filter_complex_script",
+    "filter:v:0": "-filter_script:v:0",
+}
+
+
+@functools.lru_cache(maxsize=None)
+def _ffmpeg_reads_option_files():
+    """Whether the ffmpeg on PATH accepts `-/option path` (asked once per process)."""
+    if shutil.which("ffmpeg") is None:
+        return False
+    with tempfile.TemporaryDirectory() as tmp:
+        graph = os.path.join(tmp, "probe_filter.txt")
+        with open(graph, "w", encoding="utf-8") as fh:
+            fh.write("null")
+        result = subprocess.run(["ffmpeg", "-hide_banner", "-/filter_complex", graph],
+                                stdin=subprocess.DEVNULL, capture_output=True, text=True,
+                                timeout=20)
+    return "Unrecognized option" not in result.stderr
+
+
+def filter_file_args(option, path):
+    """ffmpeg arguments that load `option`'s filtergraph from `path`, spelled for this ffmpeg."""
+    if _ffmpeg_reads_option_files():
+        return [f"-/{option}", str(path)]
+    return [_LEGACY_FILTER_FILE_OPTIONS[option], str(path)]
+
+
 def get_video_duration(video_path):
     """Return media duration in seconds via ffprobe."""
     cmd = ["ffprobe", "-v", "error", "-show_entries", "format=duration",

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

@@ -1,157 +1,4 @@
-"""Map source-time narration onto the edited output timeline."""
-
-from lib import log
-
-
-def source_time_to_output_time(source_time, clips):
-    """Map a source timestamp into the post-concat output timeline (None when cut away)."""
-    for clip in clips:
-        start = clip["source_start"]
-        end = clip["source_end"]
-        if start <= source_time <= end:
-            mapped = clip["output_start"] + (source_time - start)
-            return round(max(clip["output_start"], min(mapped, clip["output_end"])), 3)
-    return None
-
-
-def _clips_for_midpoint(start, end, clips):
-    mid = (start + end) / 2
-    return [clip for clip in clips if clip["source_start"] <= mid <= clip["source_end"]]
-
-
-def map_narration_to_clips(narration, validated_plan, min_duration=0.3):
-    """Convert source-time narration segments to edited-output timeline segments."""
-    clips = validated_plan["clips"]
-    mapped = []
-    for raw in narration:
-        source_start = raw["start"]
-        source_end = raw["end"]
-        if raw.get("source_clip_id") is not None:
-            requested_clip_id = int(raw["source_clip_id"])
-            clip = next((c for c in clips if c["clip_id"] == requested_clip_id), None)
-            if clip and not (
-                clip["source_start"] <= (source_start + source_end) / 2 <= clip["source_end"]
-            ):
-                clip = None
-        else:
-            matches = _clips_for_midpoint(source_start, source_end, clips)
-            if len(matches) > 1:
-                log(
-                    f"  丢弃重复片段中未标 source_clip_id 的解说: {source_start:.1f}-{source_end:.1f}s"
-                )
-                continue
-            clip = matches[0] if matches else None
-        if not clip:
-            log(f"  丢弃未落入剪辑片段的解说: {source_start:.1f}-{source_end:.1f}s")
-            continue
-        clipped_source_start = max(source_start, clip["source_start"])
-        clipped_source_end = min(source_end, clip["source_end"])
-        if clipped_source_end - clipped_source_start < min_duration:
-            log(f"  丢弃过短映射解说: {source_start:.1f}-{source_end:.1f}s")
-            continue
-        item = dict(raw)
-        item["source_start"] = round(clipped_source_start, 3)
-        item["source_end"] = round(clipped_source_end, 3)
-        item["source_clip_id"] = clip["clip_id"]
-        item["start"] = source_time_to_output_time(clipped_source_start, [clip])
-        item["end"] = source_time_to_output_time(clipped_source_end, [clip])
-        # Tag beats trimmed to a clip edge: their TEXT was written for a longer span and may
-        # now describe footage that was cut away (a stale-text desync the lint surfaces).
-        item["clamped"] = bool(
-            clipped_source_start > source_start + 1e-3
-            or clipped_source_end < source_end - 1e-3
-        )
-        mapped.append(item)
-
-    mapped.sort(key=lambda seg: seg["start"])
-    return mapped
-
-
-def lint_mapped_narration(
-    mapped,
-    original_count,
-    output_duration,
-    *,
-    min_spm=6.0,
-    max_gap_seconds=12.0,
-    drop_ratio_limit=0.3,
-):
-    """Advisory re-lint of narration AFTER it is mapped onto the cut OUTPUT timeline.
-
-    The mapper silently drops beats whose midpoint is outside every kept clip and clamps
-    boundary-crossers, so a narration authored against the full source can pass the
-    source-time validate yet leave the cut sparse or describing footage the viewer never
-    sees. This surfaces that on the real output timeline (narration_mapped_lint.json) and
-    returns a `blocking` verdict (heavy drop / too sparse / long gap) that the cut stage
-    enforces unless --allow-sparse-cut. Clamped beats are always blocking because their TTS
-    sentence would be cut at a clip edge; sparse-cut intent never authorizes speech truncation.
-    """
-    mapped = sorted(mapped, key=lambda s: s["start"])
-    mapped_count = len(mapped)
-    dropped = max(0, original_count - mapped_count)
-    drop_ratio = dropped / original_count if original_count else 0.0
-    spm = mapped_count / (output_duration / 60) if output_duration > 0 else 0.0
-    gaps = [b["start"] - a["end"] for a, b in zip(mapped, mapped[1:])]
-    max_gap = max(gaps) if gaps else 0.0
-    covered = sum(max(0.0, b["end"] - b["start"]) for b in mapped)
-    coverage = covered / output_duration if output_duration > 0 else 0.0
-
-    warnings = []
-    if drop_ratio >= drop_ratio_limit:
-        warnings.append(
-            {
-                "code": "many_beats_dropped",
-                "message": "大量解说段落落在保留片段之外被丢弃——请按保留的片段写解说，而不是整段原片。",
-                "dropped": dropped,
-                "original": original_count,
-                "drop_ratio": round(drop_ratio, 2),
-            }
-        )
-    if mapped_count >= 2 and spm and spm < min_spm:
-        warnings.append(
-            {
-                "code": "low_density_output",
-                "message": "映射后的解说在成片里偏稀疏——在保留片段内补充解说 beat。",
-                "segments_per_minute": round(spm, 2),
-                "min_segments_per_minute": min_spm,
-            }
-        )
-    if max_gap > max_gap_seconds:
-        warnings.append(
-            {
-                "code": "long_gap_output",
-                "message": "成片里有一长段没有解说。",
-                "max_gap_seconds": round(max_gap, 2),
-                "max_gap_limit_seconds": max_gap_seconds,
-            }
-        )
-    clamped = [b for b in mapped if b["clamped"]]
-    if clamped:
-        warnings.append(
-            {
-                "code": "clamped_beats",
-                "message": "有解说段被裁到片段边界，旁白句子会被截断——必须移动片段边界或重写整句。",
-                "count": len(clamped),
-            }
-        )
-    blocking_codes = {
-        "many_beats_dropped",
-        "low_density_output",
-        "long_gap_output",
-        "clamped_beats",
-    }
-    return {
-        "mapped_count": mapped_count,
-        "dropped": dropped,
-        "drop_ratio": round(drop_ratio, 2),
-        "output_duration": round(output_duration, 2),
-        "segments_per_minute": round(spm, 2),
-        "max_gap_seconds": round(max_gap, 2),
-        "coverage": round(coverage, 2),
-        "clamped_count": len(clamped),
-        "warnings": warnings,
-        "blocking": any(w["code"] in blocking_codes for w in warnings),
-    }
+"""Cut QC bookkeeping for clip_plan_validated.json."""
 
 
 def update_cut_qc(plan, *, allow_duration_drift=False, duration_drift_allowed_by=None):
@@ -169,7 +16,7 @@ def update_cut_qc(plan, *, allow_duration_drift=False, duration_drift_allowed_by
             "total_duration": round(total, 3),
         }
     else:
-        ratio = total / target if target > 0 else 0.0
+        ratio = total / target  # parse_duration_seconds guarantees target > 0
         if ratio < 0.85:
             target_status = "under"
         elif ratio > 1.15: