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

video_editor/errors.py

@@ -0,0 +1,33 @@
+"""Structured errors with stable codes for the CLI contract."""
+
+from __future__ import annotations
+
+
+class VideoEditorError(Exception):
+    """Failure with a stable machine-readable code and actionable message."""
+
+    def __init__(self, code: str, message: str, *, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.exit_code = exit_code
+
+
+class MissingBinaryError(VideoEditorError):
+    def __init__(self, binary: str) -> None:
+        super().__init__(
+            "missing-binary",
+            f"required external binary '{binary}' was not found on PATH; "
+            f"install FFmpeg (e.g. `brew install ffmpeg`) and retry",
+            exit_code=3,
+        )
+
+
+class InvalidInputError(VideoEditorError):
+    def __init__(self, message: str) -> None:
+        super().__init__("invalid-input", message, exit_code=2)
+
+
+class ToolFailureError(VideoEditorError):
+    def __init__(self, message: str) -> None:
+        super().__init__("tool-failure", message, exit_code=4)

video_editor/ffmpeg.py

@@ -0,0 +1,48 @@
+"""Locate and run the required external FFmpeg binaries."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from typing import Any
+
+from video_editor.errors import MissingBinaryError, ToolFailureError
+
+
+def binary_path(name: str) -> str:
+    path = shutil.which(name)
+    if path is None:
+        raise MissingBinaryError(name)
+    return path
+
+
+def run(binary: str, args: list[str]) -> subprocess.CompletedProcess[str]:
+    """Run ffmpeg/ffprobe non-interactively; raise ToolFailureError on non-zero exit."""
+    path = binary_path(binary)
+    cmd = [path, *args]
+    proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    if proc.returncode != 0:
+        tail = proc.stderr.strip().splitlines()[-8:]
+        raise ToolFailureError(
+            f"{binary} exited with {proc.returncode}: " + " | ".join(tail)
+        )
+    return proc
+
+
+def run_ffmpeg(args: list[str]) -> subprocess.CompletedProcess[str]:
+    return run("ffmpeg", ["-hide_banner", "-nostdin", "-y", *args])
+
+
+def ffprobe_json(args: list[str]) -> dict[str, Any]:
+    proc = run("ffprobe", ["-v", "error", "-of", "json", *args])
+    try:
+        result: dict[str, Any] = json.loads(proc.stdout)
+    except json.JSONDecodeError as exc:
+        raise ToolFailureError(f"ffprobe produced invalid JSON: {exc}") from exc
+    return result
+
+
+def version(binary: str) -> str:
+    proc = run(binary, ["-version"])
+    return proc.stdout.splitlines()[0] if proc.stdout else "unknown"

video_editor/inspection.py

@@ -0,0 +1,168 @@
+"""Derived inspection artifacts: audio, proxies, frames, filmstrips, waveforms, previews.
+
+Every function writes new files, never touches inputs, and returns the ffmpeg
+argument lists it ran so callers can record provenance.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from video_editor import ffmpeg, media
+from video_editor.errors import InvalidInputError
+
+
+def _prepare_output(output: Path) -> None:
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+
+def extract_audio(source: Path, output: Path) -> list[str]:
+    """Extract the first audio stream as lossless PCM WAV at its native sample rate."""
+    info = media.probe(source)
+    if not any(s["type"] == "audio" for s in info["streams"]):
+        raise InvalidInputError(f"no audio stream in {source}")
+    if output.suffix.lower() != ".wav":
+        raise InvalidInputError("audio extract output must be a .wav path")
+    _prepare_output(output)
+    args = ["-i", str(source), "-vn", "-map", "0:a:0", "-c:a", "pcm_s24le", str(output)]
+    ffmpeg.run_ffmpeg(args)
+    return args
+
+
+def create_proxy(source: Path, output: Path, height: int = 360) -> list[str]:
+    """Create a low-cost H.264 proxy for inspection."""
+    info = media.probe(source)
+    if not any(s["type"] == "video" for s in info["streams"]):
+        raise InvalidInputError(f"no video stream in {source}")
+    _prepare_output(output)
+    args = [
+        "-i",
+        str(source),
+        "-vf",
+        f"scale=-2:{height}",
+        "-c:v",
+        "libx264",
+        "-preset",
+        "veryfast",
+        "-crf",
+        "28",
+        "-c:a",
+        "aac",
+        "-b:a",
+        "96k",
+        str(output),
+    ]
+    ffmpeg.run_ffmpeg(args)
+    return args
+
+
+def extract_frame(source: Path, time: float, output: Path) -> list[str]:
+    """Extract a single frame at the requested source time."""
+    duration = media.duration_of(source)
+    if time < 0 or time >= duration:
+        raise InvalidInputError(
+            f"time {time}s is outside media duration {duration:.3f}s"
+        )
+    _prepare_output(output)
+    args = ["-ss", f"{time:.3f}", "-i", str(source), "-frames:v", "1", str(output)]
+    ffmpeg.run_ffmpeg(args)
+    return args
+
+
+def create_filmstrip(
+    source: Path,
+    start: float,
+    end: float,
+    output: Path,
+    columns: int = 6,
+    frames: int = 12,
+) -> tuple[list[str], list[float]]:
+    """Create a contact sheet of `frames` evenly sampled frames from [start, end).
+
+    Returns the ffmpeg args and the source times of the sampled tiles
+    (row-major order), so callers can map tiles back to timestamps.
+    """
+    media.require_range(source, start, end)
+    if frames < 1 or columns < 1:
+        raise InvalidInputError("frames and columns must be >= 1")
+    _prepare_output(output)
+    span = end - start
+    fps = frames / span
+    rows = -((-frames) // columns)
+    times = [round(start + i / fps, 3) for i in range(frames)]
+    args = [
+        "-ss",
+        f"{start:.3f}",
+        "-t",
+        f"{span:.3f}",
+        "-i",
+        str(source),
+        "-vf",
+        f"fps={fps:.6f},scale=320:-2,tile={columns}x{rows}",
+        "-frames:v",
+        "1",
+        str(output),
+    ]
+    ffmpeg.run_ffmpeg(args)
+    return args, times
+
+
+def create_waveform(
+    source: Path,
+    start: float,
+    end: float,
+    output: Path,
+    width: int = 1600,
+    height: int = 300,
+) -> list[str]:
+    """Render a waveform image for the requested audio range."""
+    media.require_range(source, start, end)
+    _prepare_output(output)
+    span = end - start
+    args = [
+        "-ss",
+        f"{start:.3f}",
+        "-t",
+        f"{span:.3f}",
+        "-i",
+        str(source),
+        "-filter_complex",
+        f"[0:a:0]showwavespic=s={width}x{height}:split_channels=1[w]",
+        "-map",
+        "[w]",
+        "-frames:v",
+        "1",
+        str(output),
+    ]
+    ffmpeg.run_ffmpeg(args)
+    return args
+
+
+def create_preview(source: Path, start: float, end: float, output: Path) -> list[str]:
+    """Render a short low-cost preview of a range without altering any plan."""
+    media.require_range(source, start, end)
+    _prepare_output(output)
+    span = end - start
+    info = media.probe(source)
+    has_video = any(s["type"] == "video" for s in info["streams"])
+    args = ["-ss", f"{start:.3f}", "-t", f"{span:.3f}", "-i", str(source)]
+    if has_video:
+        args += [
+            "-vf",
+            "scale=-2:360",
+            "-c:v",
+            "libx264",
+            "-preset",
+            "veryfast",
+            "-crf",
+            "28",
+            "-c:a",
+            "aac",
+            "-b:a",
+            "96k",
+        ]
+    else:
+        args += ["-c:a", "aac", "-b:a", "128k"]
+    args.append(str(output))
+    ffmpeg.run_ffmpeg(args)
+    return args

video_editor/media.py

@@ -0,0 +1,92 @@
+"""Normalized media inspection built on ffprobe."""
+
+from __future__ import annotations
+
+from fractions import Fraction
+from pathlib import Path
+from typing import Any
+
+from video_editor import ffmpeg
+from video_editor.errors import InvalidInputError
+
+
+def _parse_rate(rate: str | None) -> float | None:
+    if not rate or rate in ("0/0", "N/A"):
+        return None
+    try:
+        return float(Fraction(rate))
+    except (ValueError, ZeroDivisionError):
+        return None
+
+
+def _float(value: Any) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def probe(path: Path) -> dict[str, Any]:
+    """Return normalized container and per-stream metadata for one media file."""
+    if not path.is_file():
+        raise InvalidInputError(f"input file not found: {path}")
+    raw = ffmpeg.ffprobe_json(["-show_format", "-show_streams", str(path)])
+    fmt = raw.get("format", {})
+    streams: list[dict[str, Any]] = []
+    for stream in raw.get("streams", []):
+        kind = stream.get("codec_type")
+        normalized: dict[str, Any] = {
+            "index": stream.get("index"),
+            "type": kind,
+            "codec": stream.get("codec_name"),
+            "duration_seconds": _float(stream.get("duration")),
+        }
+        if kind == "video":
+            normalized.update(
+                {
+                    "width": stream.get("width"),
+                    "height": stream.get("height"),
+                    "frame_rate": _parse_rate(stream.get("r_frame_rate")),
+                    "pixel_format": stream.get("pix_fmt"),
+                }
+            )
+        elif kind == "audio":
+            normalized.update(
+                {
+                    "sample_rate": int(stream["sample_rate"])
+                    if stream.get("sample_rate")
+                    else None,
+                    "channels": stream.get("channels"),
+                    "channel_layout": stream.get("channel_layout"),
+                }
+            )
+        streams.append(normalized)
+    return {
+        "path": str(path.resolve()),
+        "container": fmt.get("format_name"),
+        "duration_seconds": _float(fmt.get("duration")),
+        "size_bytes": int(fmt["size"]) if fmt.get("size") else None,
+        "bit_rate": int(fmt["bit_rate"]) if fmt.get("bit_rate") else None,
+        "streams": streams,
+    }
+
+
+def duration_of(path: Path) -> float:
+    info = probe(path)
+    duration = info["duration_seconds"]
+    if duration is None:
+        raise InvalidInputError(f"could not determine duration of {path}")
+    return float(duration)
+
+
+def require_range(path: Path, start: float, end: float) -> None:
+    """Validate that [start, end) is a sane range within the media duration."""
+    if start < 0 or end <= start:
+        raise InvalidInputError(
+            f"invalid range [{start}, {end}): start must be >= 0 and end > start"
+        )
+    duration = duration_of(path)
+    if start >= duration:
+        raise InvalidInputError(
+            f"range start {start}s is beyond media duration {duration:.3f}s"
+        )

video_editor/plans.py

@@ -0,0 +1,90 @@
+"""Edit-plan loading and validation.
+
+A plan is an ordered keep-list: each timeline clip keeps [in, out) of a source,
+with an editorial reason. Validation is structural (schema) plus semantic
+(references, ranges against real media, ordering/overlap per source).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from video_editor import media, schemas
+from video_editor.errors import InvalidInputError
+
+
+def load(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        raise InvalidInputError(f"plan file not found: {path}")
+    try:
+        plan: dict[str, Any] = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise InvalidInputError(f"plan {path} is not valid JSON: {exc}") from exc
+    return plan
+
+
+def validate(plan: dict[str, Any]) -> dict[str, Any]:
+    """Validate a plan; return summary data (durations, boundaries)."""
+    schemas.validate(plan, "edit-plan.schema.json")
+
+    errors: list[str] = []
+    sources: dict[str, Path] = {}
+    durations: dict[str, float] = {}
+    for record in plan["sources"]:
+        if record["id"] in sources:
+            errors.append(f"duplicate source id '{record['id']}'")
+            continue
+        source_path = Path(record["path"])
+        sources[record["id"]] = source_path
+        if not source_path.is_file():
+            errors.append(f"source '{record['id']}' file not found: {source_path}")
+
+    if errors:
+        raise InvalidInputError("invalid plan: " + "; ".join(errors))
+
+    for source_id, source_path in sources.items():
+        durations[source_id] = media.duration_of(source_path)
+
+    last_out: dict[str, float] = {}
+    output_time = 0.0
+    boundaries: list[float] = []
+    for index, clip in enumerate(plan["timeline"]):
+        label = f"timeline[{index}]"
+        source_id = clip["source"]
+        if source_id not in sources:
+            errors.append(f"{label}: unknown source '{source_id}'")
+            continue
+        video_source = clip.get("video_source")
+        if video_source is not None and video_source not in sources:
+            errors.append(f"{label}: unknown video_source '{video_source}'")
+        clip_in, clip_out = clip["in"], clip["out"]
+        if clip_in >= clip_out:
+            errors.append(f"{label}: in ({clip_in}) must be < out ({clip_out})")
+            continue
+        duration = durations[source_id]
+        if clip_out > duration + 0.05:
+            errors.append(
+                f"{label}: out ({clip_out}) exceeds source '{source_id}' "
+                f"duration ({duration:.3f})"
+            )
+            continue
+        if source_id in last_out and clip_in < last_out[source_id]:
+            errors.append(
+                f"{label}: overlaps or reorders earlier clip on source "
+                f"'{source_id}' (in {clip_in} < previous out {last_out[source_id]})"
+            )
+        last_out[source_id] = max(last_out.get(source_id, 0.0), clip_out)
+        output_time += clip_out - clip_in
+        boundaries.append(round(output_time, 6))
+
+    if errors:
+        raise InvalidInputError("invalid plan: " + "; ".join(errors))
+
+    return {
+        "plan_id": plan["plan_id"],
+        "clip_count": len(plan["timeline"]),
+        "output_duration": round(output_time, 6),
+        "boundaries": boundaries[:-1],
+    }

video_editor/profiles.py

@@ -0,0 +1,58 @@
+"""External project profiles: explicit YAML passed by path, never discovered.
+
+Project identity (canvases, codecs, loudness targets, assets, music, fonts,
+camera aliases) lives here, outside the skill and the package defaults.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from video_editor import schemas
+from video_editor.errors import InvalidInputError
+
+
+def load(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        raise InvalidInputError(f"project profile not found: {path}")
+    try:
+        document = yaml.safe_load(path.read_text())
+    except yaml.YAMLError as exc:
+        raise InvalidInputError(
+            f"project profile {path} is not valid YAML: {exc}"
+        ) from exc
+    if not isinstance(document, dict):
+        raise InvalidInputError(f"project profile {path} must be a YAML mapping")
+    schemas.validate(document, "project-profile.schema.json")
+
+    base = path.parent
+    music = document.get("music")
+    if music:
+        music_path = (base / music["path"]).resolve()
+        if not music_path.is_file():
+            raise InvalidInputError(f"profile music file not found: {music_path}")
+        music["path"] = str(music_path)
+    for section in ("assets", "fonts"):
+        mapping = document.get(section) or {}
+        for key, rel in mapping.items():
+            resolved = (base / rel).resolve()
+            if not resolved.is_file():
+                raise InvalidInputError(
+                    f"profile {section[:-1]} '{key}' file not found: {resolved}"
+                )
+            mapping[key] = str(resolved)
+    return document
+
+
+def named_profile(document: dict[str, Any], name: str) -> dict[str, Any]:
+    profiles = document["profiles"]
+    if name not in profiles:
+        known = ", ".join(sorted(profiles))
+        raise InvalidInputError(
+            f"unknown render profile '{name}' (profile declares: {known})"
+        )
+    profile: dict[str, Any] = profiles[name]
+    return profile

video_editor/provenance.py

@@ -0,0 +1,49 @@
+"""Provenance sidecars: enough recorded detail to reproduce any derived artifact."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from video_editor import SCHEMA_VERSION
+from video_editor import ffmpeg
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def write_sidecar(
+    output: Path,
+    command: str,
+    inputs: list[Path],
+    parameters: dict[str, Any],
+    tool_commands: list[list[str]] | None = None,
+) -> Path:
+    """Write `<output>.provenance.json` describing how `output` was produced."""
+    record = {
+        "schema_version": SCHEMA_VERSION,
+        "command": command,
+        "created_at": utc_now(),
+        "inputs": [
+            {"path": str(p), "sha256": sha256_file(p)} for p in inputs if p.is_file()
+        ],
+        "parameters": parameters,
+        "tools": {name: ffmpeg.version(name) for name in ("ffmpeg", "ffprobe")},
+        "tool_commands": tool_commands or [],
+        "output": {"path": str(output), "sha256": sha256_file(output)},
+    }
+    sidecar = output.with_name(output.name + ".provenance.json")
+    sidecar.write_text(json.dumps(record, indent=2) + "\n")
+    return sidecar

video_editor/reframe.py

@@ -0,0 +1,119 @@
+"""Explicit crop/reframe previews and vertical plan derivation.
+
+The agent decides where to look; these helpers only execute explicit
+instructions — `derive_short_plan` never chooses the highlight.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from pathlib import Path
+from typing import Any
+
+from video_editor import SCHEMA_VERSION, ffmpeg, media
+from video_editor.errors import InvalidInputError
+
+
+def parse_crop(text: str) -> dict[str, int]:
+    match = re.fullmatch(r"(\d+):(\d+):(\d+):(\d+)", text)
+    if not match:
+        raise InvalidInputError(f"crop must be x:y:width:height, got '{text}'")
+    x, y, width, height = (int(g) for g in match.groups())
+    return {"x": x, "y": y, "width": width, "height": height}
+
+
+def parse_canvas(text: str) -> dict[str, int]:
+    match = re.fullmatch(r"(\d+)x(\d+)", text)
+    if not match:
+        raise InvalidInputError(f"canvas must be WIDTHxHEIGHT, got '{text}'")
+    return {"width": int(match.group(1)), "height": int(match.group(2))}
+
+
+def preview_reframe(
+    source: Path,
+    start: float,
+    end: float,
+    crop: dict[str, int],
+    canvas: dict[str, int],
+    output: Path,
+) -> list[str]:
+    """Render a short preview of one explicit crop scaled onto a canvas."""
+    media.require_range(source, start, end)
+    info = media.probe(source)
+    video = next((s for s in info["streams"] if s["type"] == "video"), None)
+    if video is None:
+        raise InvalidInputError(f"no video stream in {source}")
+    if (
+        crop["x"] + crop["width"] > video["width"]
+        or crop["y"] + crop["height"] > video["height"]
+    ):
+        raise InvalidInputError(
+            f"crop {crop} exceeds source frame {video['width']}x{video['height']}"
+        )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    span = end - start
+    args = [
+        "-ss",
+        f"{start:.3f}",
+        "-t",
+        f"{span:.3f}",
+        "-i",
+        str(source),
+        "-vf",
+        (
+            f"crop={crop['width']}:{crop['height']}:{crop['x']}:{crop['y']},"
+            f"scale={canvas['width']}:{canvas['height']}:force_original_aspect_ratio=decrease,"
+            f"pad={canvas['width']}:{canvas['height']}:(ow-iw)/2:(oh-ih)/2,setsar=1"
+        ),
+        "-c:v",
+        "libx264",
+        "-preset",
+        "veryfast",
+        "-crf",
+        "26",
+        "-c:a",
+        "aac",
+        "-b:a",
+        "96k",
+        str(output),
+    ]
+    ffmpeg.run_ffmpeg(args)
+    return args
+
+
+def derive_short_plan(
+    source_path: Path,
+    source_id: str,
+    start: float,
+    end: float,
+    canvas: dict[str, int],
+    reason: str,
+    crop: dict[str, int] | None = None,
+    parent_plan: str | None = None,
+    created_by: str | None = None,
+) -> dict[str, Any]:
+    """New editable vertical plan for one explicit, agent-chosen source range."""
+    media.require_range(source_path, start, end)
+    duration = media.duration_of(source_path)
+    if end > duration + 0.05:
+        raise InvalidInputError(
+            f"range end {end}s exceeds source duration {duration:.3f}s"
+        )
+    clip: dict[str, Any] = {
+        "source": source_id,
+        "in": start,
+        "out": end,
+        "reason": reason,
+    }
+    if crop:
+        clip["crop"] = crop
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "plan_id": f"short-{uuid.uuid4().hex[:8]}",
+        "created_by": created_by,
+        "parent_plan": parent_plan,
+        "output_canvas": {**canvas, "frame_rate": None},
+        "sources": [{"id": source_id, "path": str(source_path.resolve())}],
+        "timeline": [clip],
+    }