@oh-story/dsh 0.1.9 → 0.1.11

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

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Compose caller-rendered RGBA pixels over a frozen H264/CFR/AAC base.
+
+This operation validates pixels and declared inputs. It does not generate or
+interpret titles, dialogue, brands, typography, or release approval.
+"""
+
+import argparse
+from fractions import Fraction
+import json
+from pathlib import Path
+import subprocess
+
+from adoption.frozen_audio import probe_audio_packets, verify_adopted_audio
+from pair_media import probe_picture, validate_pair_timing
+from adoption.strict_inputs import (
+    canonical_fraction, require_declared_path, require_fields, require_integer, run_logged,
+    without_digests, write_json_atomic,
+)
+
+
+PATTERN = "frame_%06d.png"
+ENCODING = {
+    "video_codec": "libx264", "preset": "fast", "crf": 18,
+    "pixel_format": "yuv420p", "color": "bt709_tv", "audio_codec": "copy",
+}
+
+
+def _fields(value, required):
+    value = without_digests(value, "compose plan")
+    require_fields(value, required, "compose plan")
+    return value
+
+
+def _local_file(value, label):
+    _fields(value, ["path"])
+    return {"path": str(require_declared_path(value, label))}
+
+
+def _sequence_paths(directory, pattern, start, end):
+    if pattern != PATTERN:
+        raise ValueError(f"Only the literal simple pattern {PATTERN!r} is supported")
+    directory = Path(directory).resolve()
+    if not directory.is_dir():
+        raise FileNotFoundError(f"Sequence directory missing: {directory}")
+    expected = [directory / (pattern % index) for index in range(start, end)]
+    actual = sorted(directory.iterdir(), key=lambda item: item.name)
+    if [item.name for item in actual] != [item.name for item in expected]:
+        raise ValueError("Sequence requires exact contiguous files with no missing or extra entries")
+    if not all(path.is_file() for path in expected):
+        raise FileNotFoundError("Sequence frame missing or not a file")
+    return directory, expected
+
+
+def _probe_image(path):
+    result = subprocess.run(
+        ["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_streams",
+         "-show_entries", "stream=codec_name,width,height,pix_fmt", "-of", "json", str(path)],
+        capture_output=True, text=True, timeout=600,
+    )
+    if result.returncode or result.stderr.strip():
+        raise ValueError(f"Image probe failed: {result.stderr.strip()}")
+    streams = json.loads(result.stdout).get("streams", [])
+    if len(streams) != 1 or streams[0].get("codec_name") != "png":
+        raise ValueError("Foreground assets must be PNG images")
+    return streams[0]
+
+
+def _validate_rgba(path, width, height):
+    image = _probe_image(path)
+    if (image.get("width"), image.get("height")) != (width, height):
+        raise ValueError("PNG must exactly match the full output canvas")
+    if image.get("pix_fmt") != "rgba":
+        raise ValueError("PNG must contain an actual RGBA pixel format")
+
+
+def _sequence(value, required, *, local_count, width, height):
+    value = _fields(value, required)
+    directory = value["directory"]
+    if not isinstance(directory, str) or not directory or "://" in directory:
+        raise ValueError("Sequence requires a local directory")
+    if value["pattern"] != PATTERN:
+        raise ValueError(f"Only the literal simple pattern {PATTERN!r} is supported")
+    resolved, paths = _sequence_paths(directory, value["pattern"], 0, local_count)
+    for path in paths:
+        _validate_rgba(path, width, height)
+    return {**value, "directory": str(resolved), "frame_count": len(paths)}, paths
+
+
+def validate_endcard(value, *, foreground_end, total_frames, width, height):
+    """Validate the exact endcard union and return normalized data and bound paths."""
+    if not isinstance(value, dict) or value.get("kind") not in {"none", "still", "sequence"}:
+        raise ValueError("Endcard kind must be none, still, or sequence")
+    value = without_digests(value, "endcard")
+    if value["kind"] == "none":
+        _fields(value, ["kind"])
+        if foreground_end != total_frames:
+            raise ValueError("No endcard requires foreground to cover the full frame clock")
+        return {"kind": "none"}, []
+    if value["kind"] == "still":
+        required = ["kind", "path", "start_frame", "end_frame"]
+    else:
+        required = ["kind", "directory", "pattern", "start_frame", "end_frame"]
+    _fields(value, required)
+    end_start = require_integer(value["start_frame"], "endcard start_frame")
+    end_end = require_integer(value["end_frame"], "endcard end_frame", minimum=1)
+    if end_start >= end_end:
+        raise ValueError("Endcard interval must be non-empty")
+    if end_start != foreground_end or end_end != total_frames:
+        raise ValueError("Foreground and endcard must exactly partition the base frame clock")
+    if value["kind"] == "still":
+        asset = _local_file({"path": value["path"]}, "endcard")
+        _validate_rgba(asset["path"], width, height)
+        return {**value, **asset}, [Path(asset["path"])]
+    return _sequence(
+        value, required, local_count=end_end - end_start, width=width, height=height,
+    )
+
+
+def validate_plan(plan_path):
+    plan_path = Path(plan_path).resolve()
+    plan = json.loads(plan_path.read_bytes())
+    _fields(plan, ["artifact", "schema_version", "base", "video", "foreground",
+                   "endcard", "producer_receipt"])
+    plan = {**plan, "video": _fields(plan["video"], ["fps", "width", "height", "total_frames"])}
+    if plan["artifact"] != "foreground_compose_plan" or type(plan["schema_version"]) is not int \
+            or plan["schema_version"] != 1:
+        raise ValueError("Unsupported foreground_compose_plan schema")
+    base = _local_file(plan["base"], "base")
+    receipt = _local_file(plan["producer_receipt"], "producer_receipt")
+    fps = canonical_fraction(plan["video"]["fps"], "video fps")
+    width = require_integer(plan["video"]["width"], "video width", minimum=1)
+    height = require_integer(plan["video"]["height"], "video height", minimum=1)
+    total = require_integer(plan["video"]["total_frames"], "video total_frames", minimum=1)
+    _fields(plan["foreground"], ["directory", "pattern", "start_frame", "end_frame"])
+    foreground_start = require_integer(plan["foreground"]["start_frame"], "foreground start_frame")
+    foreground_end = require_integer(plan["foreground"]["end_frame"], "foreground end_frame", minimum=1)
+    if foreground_start != 0 or foreground_end > total:
+        raise ValueError("Foreground must start at frame 0 and not exceed the frame clock")
+    foreground, foreground_paths = _sequence(
+        plan["foreground"], ["directory", "pattern", "start_frame", "end_frame"],
+        local_count=foreground_end, width=width, height=height,
+    )
+    normalized_endcard, endcard_paths = validate_endcard(
+        plan["endcard"], foreground_end=foreground_end, total_frames=total,
+        width=width, height=height,
+    )
+    picture = probe_picture(base["path"])
+    decoder = picture["decoder"]
+    required_color = {"codec_name": "h264", "pix_fmt": "yuv420p", "color_range": "tv",
+                      "color_space": "bt709", "color_transfer": "bt709",
+                      "color_primaries": "bt709"}
+    if any(decoder.get(key) != value for key, value in required_color.items()):
+        raise ValueError("Base must be H264 yuv420p with explicit BT.709 TV color metadata")
+    if (decoder.get("width"), decoder.get("height"), picture["frame_count"],
+            Fraction(picture["fps"])) != (width, height, total, fps):
+        raise ValueError("Declared fps/canvas/count does not match the actual base")
+    audio = probe_audio_packets(base["path"], 0)
+    validate_pair_timing(picture, audio)
+    return {
+        "plan_path": plan_path, "base": base,
+        "video": {"fps": str(fps), "width": width, "height": height, "total_frames": total},
+        "foreground": foreground, "foreground_paths": foreground_paths,
+        "endcard": normalized_endcard, "endcard_paths": endcard_paths,
+        "producer_receipt": receipt, "picture": picture, "audio": audio,
+    }
+
+
+def _run_ffmpeg(command, directory):
+    run_logged(command, directory, "compose", timeout=600)
+
+
+def _verify_output(path, validated):
+    output_picture = probe_picture(path)
+    expected = validated["picture"]
+    for key in ("frame_pts", "frame_count", "fps", "duration", "start"):
+        if output_picture[key] != expected[key]:
+            raise ValueError(f"Output picture {key} differs from the base")
+    decoder_keys = ("codec_name", "width", "height", "pix_fmt", "sample_aspect_ratio",
+                    "field_order", "color_range", "color_space", "color_transfer",
+                    "color_primaries", "chroma_location")
+    if {key: output_picture["decoder"].get(key) for key in decoder_keys} != \
+            {key: expected["decoder"].get(key) for key in decoder_keys}:
+        raise ValueError("Output codec/canvas/color metadata differs from the base")
+    proof = verify_adopted_audio(validated["base"]["path"], path, 0, 0)
+    if validate_pair_timing(output_picture, proof["output"]) != \
+            validate_pair_timing(expected, validated["audio"]):
+        raise ValueError("Output audio interval changed")
+    result = subprocess.run(
+        ["ffmpeg", "-v", "error", "-xerror", "-threads", "2", "-i", str(path),
+         "-map", "0:v:0", "-map", "0:a:0", "-f", "null", "-"],
+        capture_output=True, text=True, timeout=600,
+    )
+    if result.returncode or result.stderr.strip():
+        raise ValueError("Foreground output full decode failed")
+    return output_picture, proof
+
+
+def run_compose(plan_path, output_dir, *, plan_only=False):
+    directory = Path(output_dir).resolve()
+    directory.mkdir(parents=True, exist_ok=False)
+    report_path = directory / "foreground_run.json"
+    staged = directory / "foreground.rendering.mp4"
+    output = directory / "foreground.mp4"
+    report = {"artifact": "foreground_compose_run", "schema_version": 1,
+              "status": "PREPARING", "direct_listening": "NOT_CHECKED",
+              "normal_speed_review": "NOT_CHECKED", "release_approved": False,
+              "encoding": ENCODING}
+    write_json_atomic(report_path, report)
+    try:
+        value = validate_plan(plan_path)
+        report.update(
+            plan={"path": str(value["plan_path"])},
+            base=value["base"], video=value["video"], foreground=value["foreground"],
+            endcard=value["endcard"],
+            producer_receipt={**value["producer_receipt"],
+                              "semantic_validation": "DECLARED_NOT_CHECKED"},
+        )
+        if plan_only:
+            report["status"] = "PLANNED"
+            write_json_atomic(report_path, report)
+            return report
+        fps = value["video"]["fps"]
+        command = ["ffmpeg", "-nostdin", "-v", "error", "-n", "-copyts",
+                   "-i", value["base"]["path"], "-framerate", fps, "-start_number", "0",
+                   "-i", str(Path(value["foreground"]["directory"]) / PATTERN)]
+        if value["endcard"]["kind"] == "none":
+            filters = (
+                "[0:v]format=rgb24[base];[1:v]format=rgba,setpts=PTS-STARTPTS[fg];"
+                "[base][fg]overlay=0:0:eof_action=pass:format=rgb,"
+                "scale=in_range=pc:out_range=tv:"
+                "in_color_matrix=bt709:out_color_matrix=bt709,format=yuv420p,"
+                f"trim=end_frame={value['video']['total_frames']}[outv]"
+            )
+        elif value["endcard"]["kind"] == "still":
+            command += ["-loop", "1", "-framerate", fps, "-i", value["endcard"]["path"]]
+        else:
+            command += ["-framerate", fps, "-start_number", "0", "-i",
+                        str(Path(value["endcard"]["directory"]) / PATTERN)]
+        if value["endcard"]["kind"] != "none":
+            end_start = value["endcard"]["start_frame"]
+            end_offset = Fraction(end_start, 1) / Fraction(fps)
+            filters = (
+                f"[0:v]format=rgb24[base];[1:v]format=rgba,setpts=PTS-STARTPTS[fg];"
+                f"[2:v]format=rgba,setpts=PTS-STARTPTS+{end_offset.numerator}/"
+                f"{end_offset.denominator}/TB[end];"
+                f"[base][fg]overlay=0:0:eof_action=pass:format=rgb:"
+                f"enable='lt(n,{end_start})'[body];"
+                f"[body][end]overlay=0:0:eof_action=repeat:format=rgb:"
+                f"enable='gte(n,{end_start})',scale=in_range=pc:out_range=tv:"
+                "in_color_matrix=bt709:out_color_matrix=bt709,format=yuv420p,"
+                f"trim=end_frame={value['video']['total_frames']}[outv]"
+            )
+        command += ["-filter_complex", filters, "-map", "[outv]", "-map", "0:a:0",
+                    "-c:v", ENCODING["video_codec"], "-preset", ENCODING["preset"],
+                    "-crf", str(ENCODING["crf"]), "-threads", "2",
+                    "-pix_fmt", ENCODING["pixel_format"],
+                    "-color_range", "tv", "-colorspace", "bt709", "-color_primaries", "bt709",
+                    "-color_trc", "bt709", "-c:a", "copy", "-movie_timescale",
+                    str(value["audio"]["sample_rate"]), "-movflags", "+faststart",
+                    str(staged)]
+        _run_ffmpeg(command, directory)
+        output_picture, audio_proof = _verify_output(staged, value)
+        write_json_atomic(directory / "picture_identity.json", output_picture)
+        write_json_atomic(directory / "adopted_audio_identity.json", audio_proof)
+        report["output"] = {"path": str(output),
+                            "full_decode": "PASS", "frame_clock": "EXACT",
+                            "audio_packet_identity": "EXACT"}
+        staged.rename(output)
+        report["status"] = "FOREGROUND_RENDERED"
+        write_json_atomic(report_path, report)
+        return report
+    except Exception as exc:
+        staged.unlink(missing_ok=True)
+        output.unlink(missing_ok=True)
+        report.pop("output", None)
+        report.update(status="FAILED", error=f"{type(exc).__name__}: {exc}")
+        write_json_atomic(report_path, report)
+        raise
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("plan")
+    parser.add_argument("--output-dir", required=True)
+    parser.add_argument("--plan-only", action="store_true")
+    args = parser.parse_args()
+    report = run_compose(args.plan, args.output_dir, plan_only=args.plan_only)
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -20,20 +20,19 @@ are implemented locally and no upstream executable code, resource package,
 adapter binary, or credential is included. See ACKNOWLEDGEMENTS / 致谢.
 """
 
-import copy
 import json
 import os
 import subprocess
 import tempfile
 import uuid
 
-from jianying_builders import build_timeline_track as _build_timeline_track
-from jianying_model import DraftBuildContext as _DraftBuildContext
-from jianying_schema import draft_content_skeleton as _draft_content_skeleton
-from jianying_schema import meta_info as _meta_info
-from jianying_schema import us
-from jianying_timeline_contract import normalize_timeline as _normalize_timeline
-from jianying_writer import write_draft as _write_draft
+from jianying.builders import build_timeline_track as _build_timeline_track
+from jianying.model import DraftBuildContext as _DraftBuildContext
+from jianying.schema import draft_content_skeleton as _draft_content_skeleton
+from jianying.schema import meta_info as _meta_info
+from jianying.schema import us
+from jianying.timeline_contract import normalize_timeline as _normalize_timeline
+from jianying.writer import write_draft as _write_draft
 
 __all__ = ["us", "build_draft", "export_timeline_to_jianying", "main"]
 
@@ -43,46 +42,51 @@ def _default_id():
 
 
 def _probe_media(path):
-    """Return (duration_us, width, height) via ffprobe; zeros on any failure."""
-    try:
-        r = subprocess.run(
-            [
-                "ffprobe",
-                "-v",
-                "error",
-                "-of",
-                "json",
-                "-show_entries",
-                "format=duration:stream=width,height,codec_type",
-                str(path),
-            ],
-            capture_output=True,
-            text=True,
-            timeout=30,
-        )
-        data = json.loads(r.stdout or "{}")
-        dur_us = us(float(data.get("format", {}).get("duration") or 0))
-        width = height = 0
-        for stream in data.get("streams", []):
-            if stream.get("codec_type") == "video":
-                width, height = (
-                    int(stream.get("width") or 0),
-                    int(stream.get("height") or 0),
-                )
-                break
-        return dur_us, width, height
-    except (OSError, ValueError, json.JSONDecodeError, subprocess.TimeoutExpired):
-        return 0, 0, 0
+    """Return (duration_us, width, height) via ffprobe.
+
+    A probe failure raises: a draft that silently carries a zero or guessed media
+    duration is worse than a failed optional export. Still images legitimately
+    report no duration (0).
+    """
+    result = subprocess.run(
+        [
+            "ffprobe",
+            "-v",
+            "error",
+            "-of",
+            "json",
+            "-show_entries",
+            "format=duration:stream=width,height,codec_type",
+            str(path),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if result.returncode:
+        raise RuntimeError(f"ffprobe failed for JianYing media {path}: {result.stderr.strip()}")
+    data = json.loads(result.stdout)
+    duration = data["format"].get("duration")
+    width = height = 0
+    for stream in data.get("streams", []):
+        if stream.get("codec_type") == "video":
+            width, height = int(stream["width"]), int(stream["height"])
+            break
+    return (us(float(duration)) if duration is not None else 0), width, height
 
 
 def build_draft(timeline, new_id=None, probe=None):
     """Build the 剪映 draft_content dict and companion meta from a timeline."""
-    timeline = _normalize_timeline(timeline)
+    return _build_normalized_draft(_normalize_timeline(timeline), new_id, probe)
+
+
+def _build_normalized_draft(timeline, new_id=None, probe=None):
+    """`timeline` has already passed jianying.timeline_contract.normalize_timeline."""
     new_id = new_id or _default_id
     probe = probe or _probe_media
     ctx = _DraftBuildContext.from_timeline(timeline, new_id, probe)
 
-    for timeline_track in timeline.get("tracks", []):
+    for timeline_track in timeline["tracks"]:
         _build_timeline_track(ctx, timeline_track)
     ctx.finalize_tracks()
 
@@ -141,29 +145,20 @@ def _generate_reversed_media(source_path, output_path):
     )
 
 
-def _prepare_reverse_sources(timeline, temporary_dir):
-    prepared = copy.deepcopy(timeline)
+def _prepare_reverse_sources(clips, temporary_dir):
+    """Generate a reversed copy for each clip and record it as the clip's reverse_path."""
     generated = []
-    for track in prepared.get("tracks", []):
-        if not isinstance(track, dict) or track.get("kind") != "video":
-            continue
-        for clip in track.get("clips", []):
-            if (
-                not isinstance(clip, dict)
-                or not clip.get("reverse")
-                or clip.get("reverse_path")
-            ):
-                continue
-            source_path = clip.get("source_path")
-            if not isinstance(source_path, str) or not os.path.isfile(source_path):
-                raise ValueError(f"reverse source does not exist: {source_path}")
-            output_path = os.path.join(
-                temporary_dir, f"reversed-{uuid.uuid4().hex}.mp4"
-            )
-            _generate_reversed_media(source_path, output_path)
-            clip["reverse_path"] = output_path
-            generated.append(source_path)
-    return prepared, generated
+    for clip in clips:
+        source_path = clip["source_path"]
+        if not os.path.isfile(source_path):
+            raise ValueError(f"reverse source does not exist: {source_path}")
+        output_path = os.path.join(
+            temporary_dir, f"reversed-{uuid.uuid4().hex}.mp4"
+        )
+        _generate_reversed_media(source_path, output_path)
+        clip["reverse_path"] = output_path
+        generated.append(source_path)
+    return generated
 
 
 def export_timeline_to_jianying(
@@ -175,21 +170,19 @@ def export_timeline_to_jianying(
     portable. Pass bundle_media=False only when external absolute paths are
     intentionally required.
     """
-    needs_generated_reverse = any(
-        isinstance(track, dict)
-        and track.get("kind") == "video"
-        and any(
-            isinstance(clip, dict)
-            and clip.get("reverse")
-            and not clip.get("reverse_path")
-            for clip in track.get("clips", [])
-        )
-        for track in timeline.get("tracks", [])
-    )
-    if needs_generated_reverse and not bundle_media:
+    # Validate once at the boundary; everything below trusts the normalized copy.
+    timeline = _normalize_timeline(timeline)
+    reverse_clips = [
+        clip
+        for track in timeline["tracks"]
+        if track["kind"] == "video"
+        for clip in track["clips"]
+        if clip.get("reverse") and "reverse_path" not in clip
+    ]
+    if reverse_clips and not bundle_media:
         raise ValueError("automatic reverse generation requires media bundling")
-    if not needs_generated_reverse:
-        content, meta, notes = build_draft(timeline, new_id=new_id, probe=probe)
+    if not reverse_clips:
+        content, meta, notes = _build_normalized_draft(timeline, new_id=new_id, probe=probe)
         return _write_draft(
             content,
             meta,
@@ -203,8 +196,8 @@ def export_timeline_to_jianying(
     with tempfile.TemporaryDirectory(
         prefix="jianying-reverse-", dir=out_dir
     ) as temporary_dir:
-        prepared, generated = _prepare_reverse_sources(timeline, temporary_dir)
-        content, meta, notes = build_draft(prepared, new_id=new_id, probe=probe)
+        generated = _prepare_reverse_sources(reverse_clips, temporary_dir)
+        content, meta, notes = _build_normalized_draft(timeline, new_id=new_id, probe=probe)
         notes.extend(f"已生成倒放素材: {source}" for source in generated)
         return _write_draft(
             content,

package/lib/video-recap/skills/video-assemble/scripts/jianying/__init__.py

@@ -0,0 +1 @@
+"""Jianying (剪映) draft export subpackage."""