@oh-story/dsh 0.1.11 → 0.1.13

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

@@ -2,6 +2,7 @@
 
 import json
 import math
+import os
 import shlex
 import shutil
 import subprocess
@@ -9,8 +10,7 @@ import sys
 from pathlib import Path
 
 import materials as material_lib
-from doctor import ffmpeg_has_subtitles_filter
-from lib import env_bool, env_int, load_json
+from lib import env_bool, env_int, ffmpeg_has_subtitles_filter, file_identity, load_json, material_id_for
 from recap_source import audio_binding
 
 BUNDLE = Path(__file__).resolve().parents[2]  # the skills/ directory
@@ -23,7 +23,9 @@ MULTI_SOURCE_MANIFEST = "multi_source_manifest.json"
 def _run(skill, script, *cli_args):
     cmd = [sys.executable, str(_entry(skill, script)), *map(str, cli_args)]
     print(f"[video-recap] ▶ {skill}/{script}", flush=True)
-    res = subprocess.run(cmd)
+    # Stage scripts log Chinese; on Windows a piped stdout defaults to cp1252 and the
+    # first log line would crash the child with UnicodeEncodeError.
+    res = subprocess.run(cmd, env={**os.environ, "PYTHONIOENCODING": "utf-8"})
     if res.returncode != 0:
         raise SystemExit(f"{skill}/{script} 失败 (exit {res.returncode})")
 
@@ -60,12 +62,18 @@ def _read_video_duration_or_raise(path):
     return duration
 
 
-def _probe_display_height_or_raise(path, *, require_square_pixels=False):
+# Subtitle Y coordinates are display-canvas rows; a near-square SAR only changes the canvas
+# width (or, rotated, the row scale the renderer converts exactly). Same value as the
+# renderer's and the measuring tool's copies (parity-tested).
+SUBTITLE_BAND_SAR_TOLERANCE = 0.02
+
+
+def _probe_display_height_or_raise(path, *, require_near_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]
+    return _probe_display_size_or_raise(path, require_near_square_pixels=require_near_square_pixels)[1]
 
 
-def _probe_display_size_or_raise(path, *, require_square_pixels=False):
+def _probe_display_size_or_raise(path, *, require_near_square_pixels=False):
     """Return ffmpeg's display-coordinate (width, height), accounting for rotation and SAR."""
     cmd = [
         "ffprobe",
@@ -92,11 +100,14 @@ def _probe_display_size_or_raise(path, *, require_square_pixels=False):
         sar_ratio = float(num) / float(den)
     except (ValueError, ZeroDivisionError):
         sar_ratio = math.nan
-    if require_square_pixels and (
-        not math.isfinite(sar_ratio) or abs(sar_ratio - 1.0) >= 1e-9
+    if sar in {"0:1", "N/A"}:
+        sar_ratio = 1.0  # unspecified SAR: ffmpeg (and the renderer's canvas) treat it as square
+    if require_near_square_pixels and (
+        not math.isfinite(sar_ratio) or abs(sar_ratio - 1.0) > SUBTITLE_BAND_SAR_TOLERANCE + 1e-9
     ):
         raise SystemExit(
-            f"subtitle Y coordinates currently require square-pixel video (SAR 1:1); got {sar}"
+            "subtitle Y coordinates require square or near-square pixels "
+            f"(SAR within {SUBTITLE_BAND_SAR_TOLERANCE:.0%} of 1:1); got {sar}"
         )
     display_width = max(1, round(width * sar_ratio)) if math.isfinite(sar_ratio) else width
     rotation_values = [
@@ -134,14 +145,43 @@ def _run_manifest_payload(video, args):
     return {
         "schema_version": 1,
         "source_video": str(Path(video).resolve()),
-        "source_video_identity": material_lib.file_identity(video),
+        "source_video_identity": file_identity(video),
         "settings": _analysis_settings(args),
         "audio": audio_binding(args),
     }
 
 
+# Settings main() can take from the environment rather than argv, with their no-env value.
+# A resume shell may not carry the same environment, so the resume argv pins them.
+_ENV_FILLED = (
+    ("edit_mode", "full"),
+    ("target_duration", None),
+    ("tts_provider", "auto"),
+    ("voice_ref", None),
+    ("subtitle_y_top", None),
+    ("subtitle_y_bot", None),
+)
+
+
+def _resume_argv(work_dir, args):
+    """The argv that resumes this run: what the user typed (paths made absolute by
+    recap_cli), plus the work dir and any environment-filled setting it did not spell out.
+    Values a --project binding filled in are re-derived from --project on resume."""
+    argv = list(args._argv)
+    explicit = args._explicit_options
+    bound = getattr(args, "_bound_from_project", frozenset())
+    if "--work-dir" not in explicit:
+        argv += ["--work-dir", str(work_dir)]
+    for dest, unset in _ENV_FILLED:
+        flag = "--" + dest.replace("_", "-")
+        value = getattr(args, dest)
+        if flag not in explicit and dest not in bound and value != unset:
+            argv += [flag, str(value)]
+    return argv
+
+
 def _write_run_manifest(work_dir, video, args):
-    payload = _run_manifest_payload(video, args)
+    payload = {**_run_manifest_payload(video, args), "argv": _resume_argv(work_dir, args)}
     (work_dir / RUN_MANIFEST).write_text(
         json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
     )
@@ -151,14 +191,14 @@ def _write_run_manifest(work_dir, video, args):
 def _build_multi_source_records(videos, args):
     records = []
     for video in _coerce_videos(videos):
-        identity = material_lib.file_identity(video)
+        identity = file_identity(video)
         records.append(
             {
                 "source_path": str(video),
                 "source_name": video.name,
                 "source_video_identity": identity,
                 "settings": _analysis_settings(args),
-                "material_id": material_lib.material_id_for(video, identity),
+                "material_id": material_id_for(video, identity),
             }
         )
     records = material_lib.assign_source_ids(records)
@@ -188,7 +228,10 @@ def _multi_run_manifest_payload(videos, args, source_records):
 
 
 def _write_project_run_manifest(work_dir, videos, args, source_records):
-    payload = _multi_run_manifest_payload(videos, args, source_records)
+    payload = {
+        **_multi_run_manifest_payload(videos, args, source_records),
+        "argv": _resume_argv(work_dir, args),
+    }
     (work_dir / RUN_MANIFEST).write_text(
         json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
     )
@@ -240,20 +283,41 @@ def _ffmpeg_present_but_cannot_burn():
     return not ffmpeg_has_subtitles_filter()
 
 
+def _burn_subtitles_explicit(args):
+    """Burn was asked for, not inherited: --burn-subtitles, or a truthy BURN_SUBTITLES."""
+    if args.burn_subtitles is not None:
+        return args.burn_subtitles
+    return "BURN_SUBTITLES" in os.environ and env_bool("BURN_SUBTITLES", True)
+
+
 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. Dub renders through
-    dub.py, which never burns subtitles, so it is exempt."""
+    """Settle subtitle burn-in BEFORE any understanding/VLM/ASR/TTS spend when this ffmpeg
+    lacks libass. An explicit request fails fast here, since otherwise the run only dies at
+    the final assemble `-vf subtitles=` step. The default burn only warns: assemble then
+    delivers the .srt sidecar and records `subtitle_burn_degraded` in visual_qc.json, which
+    final_qc.json carries in metadata.warnings. Dub renders through its own script, 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():
+    if not _ffmpeg_present_but_cannot_burn():
+        return
+    doctor = f"python3 {shlex.quote(str(_entry('video-recap', 'doctor.py')))}"
+    if _burn_subtitles_explicit(args):
         raise SystemExit(
-            "字幕烧录已开启，但当前 ffmpeg 不支持 subtitles/libass 滤镜，整条流程会跑到最后渲染才失败。\n"
-            "  解决其一：(1) 安装带 libass 的 ffmpeg；(2) 加 --no-burn-subtitles 关闭烧录"
-            "（仍输出 .srt 外挂字幕）。\n"
-            f"  自检：python3 {shlex.quote(str(_entry('video-recap', 'doctor.py')))}"
+            "已显式要求烧录字幕（--burn-subtitles 或 BURN_SUBTITLES），但当前 ffmpeg 不支持"
+            " subtitles/libass 滤镜，整条流程会跑到最后渲染才失败。\n"
+            "  解决其一：(1) 安装带 libass 的 ffmpeg；(2) 去掉显式烧录要求，默认运行会改为输出"
+            " .srt 外挂字幕；(3) 加 --no-burn-subtitles。\n"
+            f"  自检：{doctor}"
         )
+    print(
+        "[video-recap] ⚠ 当前 ffmpeg 不支持 subtitles/libass 滤镜：本次成片不烧录字幕。"
+        "有字幕条目时改为在成片旁输出同名 .srt 外挂字幕（final_qc.json 的 metadata.warnings"
+        " 会记录 subtitle_burn_degraded）；没有字幕条目的运行（如 source 音频模式且没有"
+        " user_subtitles.*）不输出 .srt，也不记警告。要烧录字幕请安装带 libass 的 ffmpeg；"
+        f"自检：{doctor}",
+        flush=True,
+    )
 
 
 def _entry(skill, script):

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

@@ -24,8 +24,6 @@ _LOCAL_ADOPTION_OPTIONS = (
 )
 
 _LOCAL_ADOPTION_CONFLICTS = _TTS_OPTIONS | frozenset({
-    "--mimo-qc",
-    "--mimo-qc-refresh",
     "--export-jianying",
     "--jianying-bundle-media",
     "--jianying-no-bundle-media",
@@ -106,7 +104,6 @@ def validate_local_adoption(parser, args):
     args.tts_provider = "auto"
     args.mimo_tts_voice = None
     args.voice_ref = None
-    args.mimo_qc = "off"
 
 
 def load_local_assembly_evidence(work_dir):
@@ -215,8 +212,6 @@ def validate_audio_routing(parser, args):
     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:
@@ -242,37 +237,3 @@ def reject_unsupported_subtitle_track(work_dir, args):
             "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

@@ -1,72 +1,13 @@
-"""Write shift-left, MiMo, and final QC stage reports."""
+"""Write final_qc.json after render and enforce --require-final-qc."""
 
-import json
 from pathlib import Path
 
 import final_qc
-import mimo_qc
-import qc_contract
-
-ASSEMBLY_MANIFEST = "assembly_manifest.json"
-PREFLIGHT_QC = "preflight_qc.json"
-
-
-def _load_preflight_stage_reports(work_dir):
-    path = Path(work_dir) / PREFLIGHT_QC
-    if not path.exists():
-        return {}
-    return json.loads(path.read_text(encoding="utf-8"))["metadata"]["stages"]
-
-
-def _write_shift_left_stage_qc(work_dir, stage, metadata, findings=None):
-    """Write/roll up local shift-left QC for one pipeline stage.
-
-    This is a local contract artifact only: no MiMo/deep eval calls, no repair, and no
-    credential persistence (qc_contract redacts every report it builds).
-    """
-    stage_report = qc_contract.build_report(
-        artifact=PREFLIGHT_QC, stage=stage, findings=findings, metadata=metadata
-    )
-    stage_reports = _load_preflight_stage_reports(work_dir)
-    stage_reports[stage] = stage_report
-    top_metadata = dict(stage_report["metadata"])
-    top_metadata["latest_stage"] = stage
-    top_metadata["stages"] = stage_reports
-    top_report = qc_contract.build_report(
-        artifact=PREFLIGHT_QC,
-        stage=stage,
-        findings=[f for report in stage_reports.values() for f in report["findings"]],
-        metadata=top_metadata,
-    )
-    (Path(work_dir) / PREFLIGHT_QC).write_text(
-        json.dumps(top_report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
-    )
-    return top_report
-
-
-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": 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"] = [
-            p.relative_to(work_dir).as_posix() for p in sorted(tts_dir.iterdir()) if p.is_file()
-        ]
-    return metadata
-
-
-def _post_render_qc_metadata(work_dir, final_output):
-    """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")),
-    }
+from lib import read_json_object
 
 
 def _write_final_qc_reports(work_dir, final_output):
-    """Write report-only final QC artifacts after render.
+    """Write the report-only final_qc.json after render.
 
     final_qc.run converts ffprobe unavailability/failure into deterministic
     blockers; only unexpected schema/write errors propagate.
@@ -75,86 +16,47 @@ def _write_final_qc_reports(work_dir, final_output):
 
 
 def _print_final_qc_pointer(result):
-    """Surface a report-only final_qc/golden_eval FAIL so the shift-left QC is
-    not a silent no-op. Advisory only: it never changes the exit status."""
-    problems = [
-        f"{key} blocker_count={result[key].get('blocker_count', '?')}"
-        for key in ("final_qc", "golden_eval")
-        if result[key].get("ok") is False
-    ]
-    if problems:
+    """Surface a report-only final_qc FAIL so the final QC is not a silent
+    no-op. Advisory only: it never changes the exit status."""
+    summary = result["final_qc"]
+    if summary.get("ok") is False:
         print(
             "[video-recap] ⚠️  最终 QC 未通过（仅报告，不阻断）: "
-            + "; ".join(problems)
-            + "；详见 final_qc.json / golden_eval.json"
+            f"final_qc blocker_count={summary.get('blocker_count', '?')}"
+            "；详见 final_qc.json"
         )
 
 
 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)
+    """Fail closed unless the final_qc summary is a literal blocker-free pass."""
+    print(f"[video-recap] 最终 QC 报告: {Path(work_dir) / 'final_qc.json'}")
+    summary = result.get("final_qc") if isinstance(result, dict) else None
+    blockers = summary.get("blocker_count") if isinstance(summary, dict) else None
+    invalid = not isinstance(summary, dict) or summary.get("ok") is not True or \
+        type(blockers) is not int or blockers != 0
     if invalid:
-        raise SystemExit(
-            "严格最终 QC 未通过或摘要格式无效: " + ", ".join(invalid)
-        )
-
-
-def _mimo_qc_stage_enabled(args, stage):
-    return (
-        args.mimo_qc == "both"
-        or (args.mimo_qc == "pre-assemble" and stage == "pre_assemble")
-        or (args.mimo_qc == "post-render" and stage == "post_render")
-    )
-
-
-def _prepare_mimo_qc(work_dir, args):
-    """Remove an old advisory artifact when this run has MiMo QC disabled."""
-    if args.mimo_qc == "off":
-        mimo_qc.clear_report(work_dir)
-
-
-def _print_mimo_qc_pointer(result, stage):
-    report = result["report"]
-    metadata = report["metadata"]
-    status = metadata["status"]
-    stage_findings = [f for f in report["findings"] if f["stage"] == stage]
-    if status in {"failed", "unavailable"}:
+        raise SystemExit("严格最终 QC 未通过或摘要格式无效: final_qc")
+
+
+def _print_render_warnings(result, work_dir, final_output):
+    """Relay non-blocking render warnings (final_qc metadata.warnings) and the subtitle
+    sidecar, so a degraded run is never reported as a plain success. The sidecar comes from
+    assembly_manifest.json only when that manifest rendered `final_output` (dub never
+    writes one, so a stale manifest from an earlier run must not be quoted)."""
+    codes = (result.get("final_qc") or {}).get("warnings") or []
+    manifest = read_json_object(Path(work_dir) / "assembly_manifest.json") or {}
+    rendered = manifest.get("final_output")
+    same_render = isinstance(rendered, str) and \
+        Path(rendered).resolve() == Path(final_output).resolve()
+    sidecar = manifest.get("subtitle_sidecar") if same_render else None
+    if "subtitle_burn_degraded" in codes:
         print(
-            f"[video-recap] ⚠ MiMo QC {stage}: {status} ({metadata['error']})；建议性检查不可用，继续流水线"
+            "[video-recap] ⚠️  字幕未烧录进画面（当前 ffmpeg 缺 libass）："
+            f"字幕以外挂文件交付 {sidecar}；详见 final_qc.json 的 metadata.warnings"
         )
-        return
-    print(
-        f"[video-recap] ℹ MiMo QC {stage}: {status}, {len(stage_findings)} 条建议；详见 {result['path']}"
-    )
-    for finding in stage_findings[:5]:
-        print(f"[video-recap]   - {finding['message']}")
-
+    elif sidecar:
+        print(f"[video-recap] 外挂字幕: {sidecar}")
+    for code in codes:
+        if code != "subtitle_burn_degraded":
+            print(f"[video-recap] ⚠️  渲染警告: {code}；详见 final_qc.json 的 metadata.warnings")
 
-def _run_mimo_qc_stage(work_dir, args, stage, *, final_output=None):
-    """Run one selected advisory stage and never propagate a failure."""
-    if not _mimo_qc_stage_enabled(args, stage):
-        return None
-    try:
-        result = mimo_qc.run(
-            work_dir,
-            stage=stage,
-            live=True,
-            refresh=args.mimo_qc_refresh,
-            final_output=final_output,
-        )
-    except Exception as exc:
-        print(
-            f"[video-recap] ⚠ MiMo QC {stage}: {type(exc).__name__}；"
-            "建议性检查失败，继续流水线"
-        )
-        return None
-    _print_mimo_qc_pointer(result, stage)
-    return result