@oh-story/dsh 0.1.9 → 0.1.11

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

@@ -2,7 +2,6 @@
 
 import json
 import math
-import os
 import shlex
 import shutil
 import subprocess
@@ -11,7 +10,8 @@ from pathlib import Path
 
 import materials as material_lib
 from doctor import ffmpeg_has_subtitles_filter
-from lib import env_bool, load_json
+from lib import env_bool, env_int, load_json
+from recap_source import audio_binding
 
 BUNDLE = Path(__file__).resolve().parents[2]  # the skills/ directory
 
@@ -29,13 +29,8 @@ def _run(skill, script, *cli_args):
 
 
 def _optional_env_int(name):
-    raw = os.environ.get(name)
-    if raw is None or raw.strip() == "":
-        return None
-    try:
-        value = int(raw)
-    except ValueError as exc:
-        raise ValueError(f"{name} must be an integer; got {raw!r}") from exc
+    """lib.env_int with -1 as the documented "unset" sentinel."""
+    value = env_int(name, None)
     return None if value == -1 else value
 
 
@@ -67,6 +62,11 @@ def _read_video_duration_or_raise(path):
 
 def _probe_display_height_or_raise(path, *, require_square_pixels=False):
     """Return ffmpeg's display-coordinate height, accounting for rotation and SAR."""
+    return _probe_display_size_or_raise(path, require_square_pixels=require_square_pixels)[1]
+
+
+def _probe_display_size_or_raise(path, *, require_square_pixels=False):
+    """Return ffmpeg's display-coordinate (width, height), accounting for rotation and SAR."""
     cmd = [
         "ffprobe",
         "-v",
@@ -107,7 +107,7 @@ def _probe_display_height_or_raise(path, *, require_square_pixels=False):
         (int(round(float(value))) % 360 for value in rotation_values if value not in (None, "")),
         0,
     )
-    return display_width if rotation in {90, 270} else height
+    return (height, display_width) if rotation in {90, 270} else (display_width, height)
 
 
 def _analysis_settings(args):
@@ -124,10 +124,6 @@ def _analysis_settings(args):
     }
 
 
-def _material_settings_fingerprint(args):
-    return material_lib.settings_fingerprint(_analysis_settings(args))
-
-
 def _coerce_videos(video_or_videos):
     if isinstance(video_or_videos, (list, tuple)):
         return [Path(v).resolve() for v in video_or_videos]
@@ -138,8 +134,9 @@ def _run_manifest_payload(video, args):
     return {
         "schema_version": 1,
         "source_video": str(Path(video).resolve()),
-        "source_video_fingerprint": material_lib.file_fingerprint(video),
+        "source_video_identity": material_lib.file_identity(video),
         "settings": _analysis_settings(args),
+        "audio": audio_binding(args),
     }
 
 
@@ -148,19 +145,20 @@ def _write_run_manifest(work_dir, video, args):
     (work_dir / RUN_MANIFEST).write_text(
         json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
     )
+    return payload
 
 
 def _build_multi_source_records(videos, args):
     records = []
     for video in _coerce_videos(videos):
-        fp = material_lib.file_fingerprint(video)
+        identity = material_lib.file_identity(video)
         records.append(
             {
                 "source_path": str(video),
                 "source_name": video.name,
-                "source_video_fingerprint": fp,
-                "settings_fingerprint": _material_settings_fingerprint(args),
-                "material_id": material_lib.material_id_for(video, fp),
+                "source_video_identity": identity,
+                "settings": _analysis_settings(args),
+                "material_id": material_lib.material_id_for(video, identity),
             }
         )
     records = material_lib.assign_source_ids(records)
@@ -177,7 +175,7 @@ def _multi_run_manifest_payload(videos, args, source_records):
             {
                 "source_id": s["source_id"],
                 "source_path": s["source_path"],
-                "source_video_fingerprint": s["source_video_fingerprint"],
+                "source_video_identity": s["source_video_identity"],
                 "source_work_dir": s["source_work_dir"],
                 "material_id": s["material_id"],
             }
@@ -185,6 +183,7 @@ def _multi_run_manifest_payload(videos, args, source_records):
         ],
         "source_videos": [str(v) for v in _coerce_videos(videos)],
         "settings": _analysis_settings(args),
+        "audio": audio_binding(args),
     }
 
 
@@ -204,7 +203,7 @@ def _write_multi_source_manifest(work_dir, source_records):
                 "source_id": s["source_id"],
                 "source_path": s["source_path"],
                 "source_name": s["source_name"],
-                "source_video_fingerprint": s["source_video_fingerprint"],
+                "source_video_identity": s["source_video_identity"],
                 "source_work_dir": s["source_work_dir"],
                 "material_id": s["material_id"],
             }
@@ -244,8 +243,9 @@ def _ffmpeg_present_but_cannot_burn():
 def _preflight_burn_subtitles(args):
     """Fail fast BEFORE any understanding/VLM/ASR/TTS spend when subtitle burn-in is on but
     this ffmpeg can't burn it. Without it the run only dies at the final assemble
-    `-vf subtitles=` step — after the whole expensive pipeline has run."""
-    if not _burn_subtitles_intended(args):
+    `-vf subtitles=` step — after the whole expensive pipeline has run. Dub renders through
+    dub.py, which never burns subtitles, so it is exempt."""
+    if args.edit_mode == "dub" or not _burn_subtitles_intended(args):
         return
     if _ffmpeg_present_but_cannot_burn():
         raise SystemExit(

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

@@ -0,0 +1,278 @@
+"""Validate recap audio ownership without importing another skill."""
+
+import json
+from pathlib import Path
+
+
+AUDIO_MODES = ("narration", "source-mix", "adopted-packet-copy")
+
+_TTS_OPTIONS = frozenset({
+    "--tts-provider",
+    "--mimo-tts-voice",
+    "--voice-ref",
+    "--allow-partial-tts",
+    "--preserve-approved-text",
+    "--review-narration",
+    "--no-review-narration",
+    "--require-narration-review",
+})
+
+_LOCAL_ADOPTION_OPTIONS = (
+    ("tts_meta", "--tts-meta"),
+    ("narration_adoption", "--narration-adoption"),
+    ("audio_mix_adoption", "--audio-mix-adoption"),
+)
+
+_LOCAL_ADOPTION_CONFLICTS = _TTS_OPTIONS | frozenset({
+    "--mimo-qc",
+    "--mimo-qc-refresh",
+    "--export-jianying",
+    "--jianying-bundle-media",
+    "--jianying-no-bundle-media",
+})
+
+
+def uses_narration(args):
+    return args.audio_mode == "narration"
+
+
+def uses_local_adoption(args):
+    return all(getattr(args, field) is not None for field, _ in _LOCAL_ADOPTION_OPTIONS)
+
+
+def needs_voiceover(args):
+    return uses_narration(args) and not uses_local_adoption(args)
+
+
+def audio_binding(args):
+    binding = {
+        "mode": args.audio_mode,
+        "selected_stream_index": args.audio_stream_index,
+    }
+    if uses_local_adoption(args):
+        binding["local_adoption"] = {
+            field: {"path": str(Path(getattr(args, field)).resolve())}
+            for field, _ in _LOCAL_ADOPTION_OPTIONS
+        }
+    return binding
+
+
+def _resolve_local_file(parser, value, option):
+    path = Path(value).expanduser().resolve()
+    if not path.is_file():
+        parser.error(f"{option} does not exist or is not a file: {path}")
+    return str(path)
+
+
+def validate_local_adoption(parser, args):
+    """Validate and resolve the assembly-only local adoption boundary."""
+    supplied = [getattr(args, field) is not None for field, _ in _LOCAL_ADOPTION_OPTIONS]
+    if any(supplied) and not all(supplied):
+        parser.error("--tts-meta, --narration-adoption and --audio-mix-adoption are all-or-none")
+    if not all(supplied):
+        return
+    if args.edit_mode != "full" or args.audio_mode != "narration":
+        parser.error("local audio adoption requires --edit-mode full and --audio-mode narration")
+    if args.audio_stream_index != 0:
+        parser.error("local audio adoption requires --audio-stream-index 0")
+    if len(args.video) != 1:
+        parser.error("local audio adoption requires exactly one input video")
+    if args.work_dir is None:
+        parser.error("local audio adoption requires explicit --work-dir")
+    conflicts = sorted(set(args._explicit_options).intersection(_LOCAL_ADOPTION_CONFLICTS))
+    if conflicts:
+        parser.error("local audio adoption cannot use: " + ", ".join(conflicts))
+    for field, option in _LOCAL_ADOPTION_OPTIONS:
+        setattr(args, field, _resolve_local_file(parser, getattr(args, field), option))
+
+    work_dir = Path(args.work_dir).expanduser().resolve()
+    if work_dir.exists():
+        parser.error("local audio adoption requires a new --work-dir")
+    output_dir = (
+        Path(args.output_dir).expanduser().resolve()
+        if args.output_dir is not None else work_dir.parent
+    )
+    # Pre-run guard only: mirrors the assembler's `recap_<stem>.mp4` naming so an existing
+    # delivery is refused before work starts. The authoritative published path is read back
+    # from the child's assembly_manifest.json after the run.
+    delivery = output_dir / f"recap_{Path(args.video[0]).stem}.mp4"
+    if delivery.exists():
+        parser.error(f"local audio adoption will not overwrite delivery: {delivery}")
+    args.work_dir = str(work_dir)
+    args.output_dir = str(output_dir)
+
+    # Ambient authoring configuration is irrelevant because this route never synthesizes
+    # or reviews narration. Explicit forms were rejected above.
+    args.tts_provider = "auto"
+    args.mimo_tts_voice = None
+    args.voice_ref = None
+    args.mimo_qc = "off"
+
+
+def load_local_assembly_evidence(work_dir):
+    """Load the assembler's binding records for the adopted local bundle."""
+    work_dir = Path(work_dir)
+    try:
+        return {
+            name: json.loads((work_dir / filename).read_text(encoding="utf-8"))
+            for name, filename in (
+                ("assembly", "assembly_manifest.json"),
+                ("narration", "narration_input_binding.json"),
+                ("mix", "audio_mix_binding.json"),
+            )
+        }
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise SystemExit("assembler did not publish readable local adoption evidence") from exc
+
+
+def _same_file(declared, expected):
+    return Path(declared).resolve() == Path(expected).resolve()
+
+
+def verify_local_assembly_evidence(evidence, manifest):
+    """The child bindings must reference the same adoption files and picture recap ran with."""
+    try:
+        local = manifest["audio"]["local_adoption"]
+        narration = evidence["narration"]
+        mix = evidence["mix"]
+        matches = (
+            _same_file(narration["adoption"]["path"], local["narration_adoption"]["path"])
+            and _same_file(narration["adoption"]["tts_meta"]["path"], local["tts_meta"]["path"])
+            and _same_file(mix["adoption"]["path"], local["audio_mix_adoption"]["path"])
+            and _same_file(mix["picture"]["path"], manifest["source_video"])
+        )
+    except (KeyError, TypeError):
+        matches = False
+    if not matches:
+        raise SystemExit("assembler bindings do not match the local adoption manifest")
+
+
+def owned_local_delivery(evidence):
+    """Return a stable ownership token only when all child reports bind the published file."""
+    try:
+        expected = Path(evidence["assembly"]["final_output"]).resolve()
+    except (KeyError, TypeError) as exc:
+        raise SystemExit(
+            "assembly manifest does not declare final_output; cannot own the delivery"
+        ) from exc
+    try:
+        declared = [
+            Path(evidence["narration"]["final_output"]["path"]).resolve(),
+            Path(evidence["mix"]["final_output"]["path"]).resolve(),
+        ]
+    except (KeyError, TypeError):
+        return None
+    if declared != [expected, expected] or not expected.is_file():
+        return None
+    stat = expected.stat()
+    return {"path": expected, "device": stat.st_dev, "inode": stat.st_ino}
+
+
+def remove_owned_local_delivery(token):
+    if token is None:
+        return
+    path = token["path"]
+    if not path.is_file():
+        return
+    stat = path.stat()
+    if (stat.st_dev, stat.st_ino) == (token["device"], token["inode"]):
+        path.unlink()
+
+
+def reject_unbound_narration_workdir(work_dir, args):
+    """Do not reinterpret an unbound narrated work directory as source-owned audio."""
+    work_dir = Path(work_dir)
+    if (
+        not uses_narration(args)
+        and not (work_dir / "recap_run_manifest.json").exists()
+        and (work_dir / "narration.json").exists()
+    ):
+        raise SystemExit(
+            "当前 work_dir 含 narration.json 但缺少可验证的音频运行策略；"
+            "非解说模式请使用新的 --work-dir"
+        )
+
+
+def validate_audio_routing(parser, args):
+    """Reject combinations the current pipeline cannot execute truthfully."""
+    validate_local_adoption(parser, args)
+    mode = args.audio_mode
+    stream = args.audio_stream_index
+    if stream < 0:
+        parser.error("--audio-stream-index must be a non-negative integer")
+    if args.edit_mode == "dub" and mode != "narration":
+        parser.error("--edit-mode dub cannot be combined with a non-narration --audio-mode")
+    # index-tts + MiMo voice/--voice-ref is rejected once, in recap_runner.main, after the
+    # ambient VOICE_REF/MIMO_TTS_VOICE have been folded in.
+    if args.tts_provider == "index-tts" and args.edit_mode == "dub":
+        parser.error("--edit-mode dub does not support --tts-provider index-tts")
+    if mode == "narration":
+        if stream != 0:
+            parser.error("narration currently requires --audio-stream-index 0")
+        return
+
+    conflicts = sorted(set(args._explicit_options).intersection(_TTS_OPTIONS))
+    if conflicts:
+        detail = ", ".join(conflicts)
+        parser.error(f"--audio-mode {mode} cannot use TTS/strict narration options: {detail}")
+    if args.mimo_qc != "off":
+        parser.error(f"--audio-mode {mode} currently requires --mimo-qc off")
+    if args.edit_mode == "cut" and stream != 0:
+        parser.error("cut audio modes currently require --audio-stream-index 0")
+    if args.export_jianying and stream != 0:
+        parser.error("JianYing export currently requires --audio-stream-index 0")
+    # Environment defaults are irrelevant once source audio owns the run. Normalizing
+    # prevents an invalid ambient provider from leaking into later state or continuation.
+    args.tts_provider = "auto"
+
+
+def extend_assemble_args(cli_args, args):
+    mode = args.audio_mode
+    stream = args.audio_stream_index
+    if mode != "narration":
+        cli_args += ["--audio-mode", mode]
+    if stream != 0:
+        cli_args += ["--audio-stream-index", str(stream)]
+    return cli_args
+
+
+def reject_unsupported_subtitle_track(work_dir, args):
+    if args.audio_mode == "source-mix" and (Path(work_dir) / "subtitle_track.json").exists():
+        raise SystemExit(
+            "source-mix 当前不能绑定显式 subtitle_track.json；请使用新的 work_dir，"
+            "或选择 adopted-packet-copy"
+        )
+
+
+def begin_non_narration_qc(work_dir, args, write_stage):
+    """Start a clean run-local QC ledger without reading or deleting old TTS."""
+    (Path(work_dir) / "preflight_qc.json").unlink(missing_ok=True)
+    return write_stage(
+        work_dir,
+        "pre_assemble",
+        metadata={
+            "audio_mode": args.audio_mode,
+            "selected_audio_stream_index": args.audio_stream_index,
+            "tts": "not_applicable",
+            "narration_validation": "not_applicable",
+            "narration_review": "not_applicable",
+            "visual_overlays": "preserved_not_authored_by_this_run",
+        },
+    )
+
+
+def begin_local_adoption_qc(work_dir, write_stage):
+    """Record that authoring was intentionally skipped for adopted local assets."""
+    return write_stage(
+        work_dir,
+        "pre_assemble",
+        metadata={
+            "audio_mode": "narration",
+            "selected_audio_stream_index": 0,
+            "tts": "adopted_local_not_generated",
+            "narration_validation": "not_run",
+            "narration_review": "not_run",
+            "semantic_validation": "video-assemble",
+            "visual_overlays": "not_authored_not_present",
+        },
+    )

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

@@ -45,11 +45,9 @@ def _write_shift_left_stage_qc(work_dir, stage, metadata, findings=None):
 
 
 def _tts_qc_metadata(work_dir):
+    """Called after video-voiceover exited 0, which always writes tts_meta.json."""
     work_dir = Path(work_dir)
-    metadata = {}
-    tts_meta = work_dir / "tts_meta.json"
-    if tts_meta.exists():
-        metadata["tts_meta"] = json.loads(tts_meta.read_text(encoding="utf-8"))
+    metadata = {"tts_meta": json.loads((work_dir / "tts_meta.json").read_text(encoding="utf-8"))}
     tts_dir = work_dir / "tts_segments"
     if tts_dir.is_dir():
         metadata["tts_segments"] = [
@@ -59,14 +57,12 @@ def _tts_qc_metadata(work_dir):
 
 
 def _post_render_qc_metadata(work_dir, final_output):
-    work_dir = Path(work_dir)
-    metadata = {"final_output": str(final_output)}
-    manifest = work_dir / ASSEMBLY_MANIFEST
-    if manifest.exists():
-        metadata["assembly_manifest"] = json.loads(
-            manifest.read_text(encoding="utf-8")
-        )
-    return metadata
+    """Called after video-assemble exited 0, which always writes assembly_manifest.json."""
+    manifest = Path(work_dir) / ASSEMBLY_MANIFEST
+    return {
+        "final_output": str(final_output),
+        "assembly_manifest": json.loads(manifest.read_text(encoding="utf-8")),
+    }
 
 
 def _write_final_qc_reports(work_dir, final_output):
@@ -94,6 +90,23 @@ def _print_final_qc_pointer(result):
         )
 
 
+def _require_final_qc(result, work_dir):
+    """Fail closed unless both final summaries are literal blocker-free passes."""
+    paths = [Path(work_dir) / name for name in ("final_qc.json", "golden_eval.json")]
+    print("[video-recap] 最终 QC 报告: " + "; ".join(map(str, paths)))
+    invalid = []
+    for name in ("final_qc", "golden_eval"):
+        summary = result.get(name) if isinstance(result, dict) else None
+        blockers = summary.get("blocker_count") if isinstance(summary, dict) else None
+        if not isinstance(summary, dict) or summary.get("ok") is not True or \
+                type(blockers) is not int or blockers != 0:
+            invalid.append(name)
+    if invalid:
+        raise SystemExit(
+            "严格最终 QC 未通过或摘要格式无效: " + ", ".join(invalid)
+        )
+
+
 def _mimo_qc_stage_enabled(args, stage):
     return (
         args.mimo_qc == "both"