video-edit-cli 0.1.0__py3-none-any.whl

video_editor/rendering.py

@@ -0,0 +1,328 @@
+"""Compile validated edit plans into deterministic FFmpeg renders.
+
+Each render writes the output plus a `<output>.manifest.json` recording the
+plan, cut boundaries with their source mapping, and provenance — enough for
+`cuts list` / `cut inspect` to enumerate and review every boundary.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import tempfile
+
+from video_editor import SCHEMA_VERSION, ffmpeg, plans, profiles
+from video_editor.audio.analysis import measure_loudness
+from video_editor.provenance import sha256_file, utc_now
+
+PREVIEW_HEIGHT = 360
+PREVIEW_FPS = 30
+
+
+def _clip_segments(plan: dict[str, Any]) -> list[dict[str, Any]]:
+    """Output-timeline segments: clip + output_start/output_end."""
+    segments = []
+    cursor = 0.0
+    for index, clip in enumerate(plan["timeline"]):
+        duration = clip["out"] - clip["in"]
+        segments.append(
+            {
+                "index": index,
+                "source": clip["source"],
+                "video_source": clip.get("video_source"),
+                "in": clip["in"],
+                "out": clip["out"],
+                "reason": clip["reason"],
+                "output_start": round(cursor, 6),
+                "output_end": round(cursor + duration, 6),
+            }
+        )
+        cursor += duration
+    return segments
+
+
+def _concat_args(
+    plan: dict[str, Any],
+    sources: dict[str, str],
+    video_filter: str,
+    fps: float,
+) -> list[str]:
+    """Input args + filter_complex for the per-clip trim/normalize/concat graph."""
+    args: list[str] = []
+    filters: list[str] = []
+    concat_inputs: list[str] = []
+    input_index = 0
+    for i, clip in enumerate(plan["timeline"]):
+        span = clip["out"] - clip["in"]
+        args += [
+            "-ss",
+            f"{clip['in']:.6f}",
+            "-t",
+            f"{span:.6f}",
+            "-i",
+            str(sources[clip["source"]]),
+        ]
+        audio_index = input_index
+        input_index += 1
+        video_id = clip.get("video_source")
+        if video_id and video_id != clip["source"]:
+            args += [
+                "-ss",
+                f"{clip['in']:.6f}",
+                "-t",
+                f"{span:.6f}",
+                "-i",
+                str(sources[video_id]),
+            ]
+            video_index = input_index
+            input_index += 1
+        else:
+            video_index = audio_index
+        crop = clip.get("crop")
+        crop_filter = (
+            f"crop={crop['width']}:{crop['height']}:{crop['x']}:{crop['y']},"
+            if crop
+            else ""
+        )
+        gain = clip.get("gain_db")
+        gain_filter = f",volume={gain}dB" if gain else ""
+        filters.append(
+            f"[{video_index}:v]{crop_filter}{video_filter},setsar=1,fps={fps},"
+            f"format=yuv420p[v{i}]"
+        )
+        filters.append(
+            f"[{audio_index}:a]aresample=48000,"
+            f"aformat=channel_layouts=stereo{gain_filter}[a{i}]"
+        )
+        concat_inputs.append(f"[v{i}][a{i}]")
+    n = len(plan["timeline"])
+    filter_complex = (
+        ";".join(filters)
+        + ";"
+        + "".join(concat_inputs)
+        + f"concat=n={n}:v=1:a=1[outv][outa]"
+    )
+    return [
+        *args,
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        "[outv]",
+        "-map",
+        "[outa]",
+    ]
+
+
+def _write_manifest(
+    kind: str,
+    plan: dict[str, Any],
+    summary: dict[str, Any],
+    sources: dict[str, str],
+    output: Path,
+    tool_commands: list[list[str]],
+    profile_info: dict[str, Any],
+) -> tuple[Path, dict[str, Any]]:
+    manifest = {
+        "schema_version": SCHEMA_VERSION,
+        "kind": kind,
+        "created_at": utc_now(),
+        "plan": plan,
+        "summary": summary,
+        "segments": _clip_segments(plan),
+        "sources": [
+            {"id": sid, "path": str(path), "sha256": sha256_file(Path(path))}
+            for sid, path in sources.items()
+        ],
+        "tools": {name: ffmpeg.version(name) for name in ("ffmpeg", "ffprobe")},
+        "tool_commands": tool_commands,
+        "output": {"path": str(output), "sha256": sha256_file(output)},
+        "profile": profile_info,
+    }
+    manifest_path = output.with_name(output.name + ".manifest.json")
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n")
+    return manifest_path, manifest
+
+
+def render_master(
+    plan: dict[str, Any],
+    output: Path,
+    profile_document: dict[str, Any],
+    profile_name: str,
+) -> tuple[Path, dict[str, Any]]:
+    """Render a validated plan with a named external profile (canvas, codecs,
+    music/ducking, loudness), via a lossless-audio intermediate."""
+    summary = plans.validate(plan)
+    profile = profiles.named_profile(profile_document, profile_name)
+    sources = {record["id"]: record["path"] for record in plan["sources"]}
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    canvas = profile["canvas"]
+    width, height = canvas["width"], canvas["height"]
+    fps = canvas.get("frame_rate") or 30
+    vcodec = profile.get("video_codec") or {}
+    acodec = profile.get("audio_codec") or {}
+    loudness_target = profile.get("loudness") or {}
+    commands: list[list[str]] = []
+
+    video_filter = (
+        f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
+        f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2"
+    )
+    with tempfile.TemporaryDirectory(prefix="video-edit-cli-master-") as tmp:
+        intermediate = Path(tmp) / "intermediate.mov"
+        args = _concat_args(plan, sources, video_filter, fps) + [
+            "-c:v",
+            "libx264",
+            "-preset",
+            "veryfast",
+            "-crf",
+            "14",
+            "-c:a",
+            "pcm_s24le",
+            str(intermediate),
+        ]
+        ffmpeg.run_ffmpeg(args)
+        commands.append(["ffmpeg", *args])
+
+        mixed = Path(tmp) / "mixed.wav"
+        music = profile_document.get("music")
+        duration = summary["output_duration"]
+        if music:
+            ducking = music.get("ducking") or {}
+            threshold = ducking.get("threshold", 0.02)
+            ratio = ducking.get("ratio", 8)
+            gain = music.get("gain_db", -18)
+            mix_args = [
+                "-i",
+                str(intermediate),
+                "-stream_loop",
+                "-1",
+                "-i",
+                str(music["path"]),
+                "-filter_complex",
+                (
+                    f"[1:a]atrim=0:{duration:.6f},aresample=48000,"
+                    f"aformat=channel_layouts=stereo,volume={gain}dB[m];"
+                    f"[0:a]asplit=2[key][dry];"
+                    f"[m][key]sidechaincompress=threshold={threshold}:ratio={ratio}:"
+                    f"attack=5:release=250[duck];"
+                    f"[dry][duck]amix=inputs=2:duration=first:normalize=0[aout]"
+                ),
+                "-map",
+                "[aout]",
+                "-c:a",
+                "pcm_s24le",
+                str(mixed),
+            ]
+        else:
+            mix_args = ["-i", str(intermediate), "-vn", "-c:a", "pcm_s24le", str(mixed)]
+        ffmpeg.run_ffmpeg(mix_args)
+        commands.append(["ffmpeg", *mix_args])
+
+        target_i = loudness_target.get("integrated_lufs", -16.0)
+        target_tp = loudness_target.get("true_peak_dbtp", -1.5)
+        target_lra = loudness_target.get("lra", 11.0)
+        measured = measure_loudness(mixed, target_i, target_tp, target_lra)["raw"]
+        loudnorm = (
+            f"loudnorm=I={target_i}:TP={target_tp}:LRA={target_lra}:"
+            f"measured_I={measured['input_i']}:measured_TP={measured['input_tp']}:"
+            f"measured_LRA={measured['input_lra']}:"
+            f"measured_thresh={measured['input_thresh']}:"
+            f"offset={measured['target_offset']}:linear=true"
+        )
+        final_args = [
+            "-i",
+            str(intermediate),
+            "-i",
+            str(mixed),
+            "-map",
+            "0:v",
+            "-map",
+            "1:a",
+            "-af",
+            loudnorm,
+            "-c:v",
+            vcodec.get("name", "libx264"),
+            "-preset",
+            str(vcodec.get("preset", "medium")),
+            "-crf",
+            str(vcodec.get("crf", 20)),
+            "-c:a",
+            acodec.get("name", "aac"),
+            "-b:a",
+            acodec.get("bitrate", "192k"),
+            "-ar",
+            "48000",
+            str(output),
+        ]
+        ffmpeg.run_ffmpeg(final_args)
+        commands.append(["ffmpeg", *final_args])
+
+    return _write_manifest(
+        "render-master",
+        plan,
+        summary,
+        sources,
+        output,
+        commands,
+        {
+            "name": profile_name,
+            "canvas": canvas,
+            "loudness": loudness_target,
+            "music": bool(profile_document.get("music")),
+        },
+    )
+
+
+def render_preview(
+    plan: dict[str, Any], output: Path, height: int = PREVIEW_HEIGHT
+) -> tuple[Path, dict[str, Any]]:
+    """Render a low-cost rough cut of a validated plan; returns (manifest_path, manifest)."""
+    summary = plans.validate(plan)
+    sources = {record["id"]: record["path"] for record in plan["sources"]}
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    canvas = plan.get("output_canvas")
+    if canvas:
+        # A plan-declared canvas (e.g. a vertical short) wins over the preview
+        # height so the preview shows the real framing.
+        video_filter = (
+            f"scale={canvas['width']}:{canvas['height']}:"
+            f"force_original_aspect_ratio=decrease,"
+            f"pad={canvas['width']}:{canvas['height']}:(ow-iw)/2:(oh-ih)/2"
+        )
+        fps = canvas.get("frame_rate") or PREVIEW_FPS
+    else:
+        # Concat requires identical frame sizes, so normalize every clip to one
+        # 16:9 letterboxed preview canvas even when sources differ.
+        width = int(height * 16 / 9) // 2 * 2
+        video_filter = (
+            f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
+            f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2"
+        )
+        fps = PREVIEW_FPS
+    args = _concat_args(plan, sources, video_filter, fps) + [
+        "-c:v",
+        "libx264",
+        "-preset",
+        "veryfast",
+        "-crf",
+        "26",
+        "-c:a",
+        "aac",
+        "-b:a",
+        "128k",
+        str(output),
+    ]
+    ffmpeg.run_ffmpeg(args)
+    return _write_manifest(
+        "render-preview",
+        plan,
+        summary,
+        sources,
+        output,
+        [["ffmpeg", *args]],
+        {"height": height, "fps": fps, "canvas": canvas, "codec": "h264/aac"},
+    )

video_editor/result.py

@@ -0,0 +1,42 @@
+"""Command result envelope: one JSON object on stdout per command."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from video_editor import SCHEMA_VERSION
+
+
+def artifact(path: Path | str, kind: str) -> dict[str, str]:
+    return {"path": str(path), "kind": kind}
+
+
+def emit_success(
+    command: str,
+    data: dict[str, Any],
+    artifacts: list[dict[str, str]] | None = None,
+) -> None:
+    envelope = {
+        "ok": True,
+        "command": command,
+        "schema_version": SCHEMA_VERSION,
+        "artifacts": artifacts or [],
+        "data": data,
+    }
+    json.dump(envelope, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def emit_error(command: str, code: str, message: str) -> None:
+    envelope = {
+        "ok": False,
+        "command": command,
+        "schema_version": SCHEMA_VERSION,
+        "error": {"code": code, "message": message},
+    }
+    json.dump(envelope, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    print(f"error [{code}]: {message}", file=sys.stderr)

video_editor/review.py

@@ -0,0 +1,169 @@
+"""Cut review: enumerate render boundaries and gather evidence around each one.
+
+Works from a render manifest (written by rendering). Continuity checks are
+deterministic signals (black frames, silence gaps, words clipped by the cut);
+they guide review but the agent judges the evidence.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from video_editor import ffmpeg, inspection
+from video_editor.errors import InvalidInputError
+from video_editor.transcription import views as transcript_views
+
+
+def load_manifest(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        raise InvalidInputError(f"render manifest not found: {path}")
+    manifest: dict[str, Any] = json.loads(path.read_text())
+    if "segments" not in manifest or "output" not in manifest:
+        raise InvalidInputError(f"{path} is not a render manifest")
+    return manifest
+
+
+def list_cuts(manifest: dict[str, Any]) -> list[dict[str, Any]]:
+    """Each cut joins segment i (before) and segment i+1 (after)."""
+    segments = manifest["segments"]
+    cuts = []
+    for i in range(len(segments) - 1):
+        before, after = segments[i], segments[i + 1]
+        cuts.append(
+            {
+                "cut_index": i,
+                "output_time": before["output_end"],
+                "before": {
+                    "segment_index": before["index"],
+                    "source": before["source"],
+                    "source_out": before["out"],
+                    "reason": before["reason"],
+                },
+                "after": {
+                    "segment_index": after["index"],
+                    "source": after["source"],
+                    "source_in": after["in"],
+                    "reason": after["reason"],
+                },
+            }
+        )
+    return cuts
+
+
+def _detect(render: Path, start: float, end: float, filters: dict[str, str]) -> str:
+    """Run detection filters over a render range and return ffmpeg's stderr log."""
+    span = end - start
+    args = ["-ss", f"{start:.3f}", "-t", f"{span:.3f}", "-i", str(render)]
+    if "video" in filters:
+        args += ["-vf", filters["video"]]
+    if "audio" in filters:
+        args += ["-af", filters["audio"]]
+    args += ["-f", "null", "-"]
+    proc = ffmpeg.run("ffmpeg", ["-hide_banner", "-nostdin", "-y", *args])
+    return proc.stderr
+
+
+def _clipped_word(
+    transcript: dict[str, Any] | None, source_time: float
+) -> dict[str, Any] | None:
+    """Word whose span straddles `source_time` in the source transcript."""
+    if transcript is None:
+        return None
+    for segment in transcript["segments"]:
+        for word in segment["words"]:
+            if word["start"] < source_time < word["end"]:
+                return {
+                    "text": word["text"],
+                    "start": word["start"],
+                    "end": word["end"],
+                }
+    return None
+
+
+def inspect_cut(
+    manifest: dict[str, Any],
+    cut_index: int,
+    output_dir: Path,
+    window: float = 2.0,
+    transcript_path: Path | None = None,
+) -> dict[str, Any]:
+    cuts = list_cuts(manifest)
+    if not 0 <= cut_index < len(cuts):
+        raise InvalidInputError(
+            f"cut index {cut_index} out of range (render has {len(cuts)} cuts)"
+        )
+    cut = cuts[cut_index]
+    render = Path(manifest["output"]["path"])
+    if not render.is_file():
+        raise InvalidInputError(f"rendered output not found: {render}")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    boundary = cut["output_time"]
+    total = manifest["segments"][-1]["output_end"]
+    start = max(0.0, boundary - window)
+    end = min(total, boundary + window)
+
+    prefix = output_dir / f"cut-{cut_index}"
+    artifacts: dict[str, str] = {}
+
+    _, _times = inspection.create_filmstrip(
+        render, start, end, Path(f"{prefix}-filmstrip.png"), columns=6, frames=12
+    )
+    artifacts["filmstrip"] = f"{prefix}-filmstrip.png"
+    inspection.create_waveform(render, start, end, Path(f"{prefix}-waveform.png"))
+    artifacts["waveform"] = f"{prefix}-waveform.png"
+    inspection.create_preview(render, start, end, Path(f"{prefix}-preview.mp4"))
+    artifacts["preview"] = f"{prefix}-preview.mp4"
+    frame_offset = min(0.04, total - boundary)
+    inspection.extract_frame(
+        render, max(0.0, boundary - 0.04), Path(f"{prefix}-frame-before.png")
+    )
+    artifacts["frame_before"] = f"{prefix}-frame-before.png"
+    inspection.extract_frame(
+        render,
+        min(total - 0.001, boundary + frame_offset),
+        Path(f"{prefix}-frame-after.png"),
+    )
+    artifacts["frame_after"] = f"{prefix}-frame-after.png"
+
+    log = _detect(
+        render,
+        start,
+        end,
+        {"video": "blackdetect=d=0.1", "audio": "silencedetect=n=-45dB:d=0.4"},
+    )
+    black_events = re.findall(r"black_start:(\d+\.?\d*)", log)
+    silence_events = re.findall(r"silence_start: (-?\d+\.?\d*)", log)
+
+    transcript = (
+        transcript_views.load_transcript(transcript_path) if transcript_path else None
+    )
+    clipped_before = _clipped_word(transcript, cut["before"]["source_out"])
+    clipped_after = _clipped_word(transcript, cut["after"]["source_in"])
+
+    checks = {
+        "black_frames_near_cut": [float(t) + start for t in black_events],
+        "silence_near_cut": [float(t) + start for t in silence_events],
+        "clipped_word_before": clipped_before,
+        "clipped_word_after": clipped_after,
+    }
+    passed = (
+        not checks["black_frames_near_cut"]
+        and clipped_before is None
+        and clipped_after is None
+    )
+
+    report = {
+        "cut": cut,
+        "window": {"start": start, "end": end},
+        "artifacts": artifacts,
+        "checks": checks,
+        "passed": passed,
+    }
+    report_path = Path(f"{prefix}-report.json")
+    report_path.write_text(json.dumps(report, indent=2) + "\n")
+    report["report_path"] = str(report_path)
+    return report

video_editor/schemas/__init__.py

@@ -0,0 +1,29 @@
+"""JSON schemas validated at command boundaries."""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib import resources
+from typing import Any
+
+import jsonschema
+
+from video_editor.errors import InvalidInputError
+
+
+@cache
+def load(name: str) -> dict[str, Any]:
+    text = resources.files("video_editor.schemas").joinpath(name).read_text()
+    schema: dict[str, Any] = json.loads(text)
+    return schema
+
+
+def validate(instance: Any, schema_name: str) -> None:
+    try:
+        jsonschema.validate(instance, load(schema_name))
+    except jsonschema.ValidationError as exc:
+        location = "/".join(str(p) for p in exc.absolute_path) or "<root>"
+        raise InvalidInputError(
+            f"schema validation failed against {schema_name} at {location}: {exc.message}"
+        ) from exc

video_editor/schemas/edit-plan.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "video-edit-cli/edit-plan.schema.json",
+  "title": "Agent-authored edit plan",
+  "type": "object",
+  "required": ["schema_version", "plan_id", "sources", "timeline"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {"type": "string"},
+    "plan_id": {"type": "string"},
+    "workspace": {"type": ["string", "null"]},
+    "target_profile": {"type": ["string", "null"]},
+    "created_by": {"type": ["string", "null"]},
+    "parent_plan": {"type": ["string", "null"]},
+    "notes": {"type": ["string", "null"]},
+    "output_canvas": {
+      "type": ["object", "null"],
+      "required": ["width", "height"],
+      "additionalProperties": false,
+      "properties": {
+        "width": {"type": "integer", "minimum": 16},
+        "height": {"type": "integer", "minimum": 16},
+        "frame_rate": {"type": ["number", "null"]}
+      }
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "path"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {"type": "string"},
+          "path": {"type": "string"},
+          "role": {"type": ["string", "null"]}
+        }
+      }
+    },
+    "timeline": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["source", "in", "out", "reason"],
+        "additionalProperties": false,
+        "properties": {
+          "source": {"type": "string"},
+          "in": {"type": "number", "minimum": 0},
+          "out": {"type": "number", "exclusiveMinimum": 0},
+          "reason": {"type": "string", "minLength": 1},
+          "video_source": {"type": ["string", "null"]},
+          "crop": {
+            "type": ["object", "null"],
+            "required": ["x", "y", "width", "height"],
+            "additionalProperties": false,
+            "properties": {
+              "x": {"type": "integer", "minimum": 0},
+              "y": {"type": "integer", "minimum": 0},
+              "width": {"type": "integer", "minimum": 16},
+              "height": {"type": "integer", "minimum": 16}
+            }
+          },
+          "gain_db": {"type": ["number", "null"]}
+        }
+      }
+    }
+  }
+}