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

video_editor/schemas/project-profile.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "video-edit-cli/project-profile.schema.json",
+  "title": "External project profile (YAML, validated as JSON)",
+  "type": "object",
+  "required": ["schema_version", "profiles"],
+  "properties": {
+    "schema_version": {"type": "string"},
+    "profiles": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": ["canvas"],
+        "properties": {
+          "canvas": {
+            "type": "object",
+            "required": ["width", "height"],
+            "properties": {
+              "width": {"type": "integer", "minimum": 16},
+              "height": {"type": "integer", "minimum": 16},
+              "frame_rate": {"type": ["number", "null"]}
+            }
+          },
+          "video_codec": {
+            "type": "object",
+            "properties": {
+              "name": {"type": "string"},
+              "crf": {"type": ["integer", "null"]},
+              "preset": {"type": ["string", "null"]}
+            }
+          },
+          "audio_codec": {
+            "type": "object",
+            "properties": {
+              "name": {"type": "string"},
+              "bitrate": {"type": ["string", "null"]}
+            }
+          },
+          "loudness": {
+            "type": "object",
+            "properties": {
+              "integrated_lufs": {"type": "number"},
+              "true_peak_dbtp": {"type": "number"},
+              "lra": {"type": "number"}
+            }
+          },
+          "subtitles": {
+            "type": "object",
+            "properties": {
+              "mode": {"enum": ["mux", "burn", "none"]}
+            }
+          }
+        }
+      }
+    },
+    "music": {
+      "type": ["object", "null"],
+      "required": ["path"],
+      "properties": {
+        "path": {"type": "string"},
+        "gain_db": {"type": "number"},
+        "ducking": {
+          "type": "object",
+          "properties": {
+            "threshold": {"type": "number"},
+            "ratio": {"type": "number"}
+          }
+        }
+      }
+    },
+    "assets": {
+      "type": ["object", "null"],
+      "additionalProperties": {"type": "string"}
+    },
+    "fonts": {
+      "type": ["object", "null"],
+      "additionalProperties": {"type": "string"}
+    },
+    "camera_aliases": {
+      "type": ["object", "null"],
+      "additionalProperties": {"type": "string"}
+    },
+    "subtitle_style": {"type": ["object", "null"]}
+  }
+}

video_editor/schemas/result.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "video-edit-cli/result.schema.json",
+  "title": "Command result envelope",
+  "type": "object",
+  "required": ["ok", "command", "schema_version"],
+  "properties": {
+    "ok": {"type": "boolean"},
+    "command": {"type": "string"},
+    "schema_version": {"type": "string"},
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "kind"],
+        "properties": {
+          "path": {"type": "string"},
+          "kind": {"type": "string"}
+        }
+      }
+    },
+    "data": {"type": "object"},
+    "error": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": {"type": "string"},
+        "message": {"type": "string"}
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"ok": {"const": true}}},
+      "then": {"required": ["artifacts", "data"]}
+    },
+    {
+      "if": {"properties": {"ok": {"const": false}}},
+      "then": {"required": ["error"]}
+    }
+  ]
+}

video_editor/schemas/transcript.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "video-edit-cli/transcript.schema.json",
+  "title": "Authoritative word-level transcript",
+  "type": "object",
+  "required": ["schema_version", "source", "language", "backend", "model", "segments"],
+  "properties": {
+    "schema_version": {"type": "string"},
+    "source": {
+      "type": "object",
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": {"type": "string"},
+        "sha256": {"type": "string"},
+        "source_id": {"type": ["string", "null"]}
+      }
+    },
+    "language": {"type": ["string", "null"]},
+    "backend": {"type": "string"},
+    "model": {"type": ["string", "null"]},
+    "created_at": {"type": "string"},
+    "segments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["start", "end", "text", "words"],
+        "properties": {
+          "start": {"type": "number", "minimum": 0},
+          "end": {"type": "number", "minimum": 0},
+          "text": {"type": "string"},
+          "speaker": {"type": ["string", "null"]},
+          "words": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["text", "start", "end"],
+              "properties": {
+                "text": {"type": "string"},
+                "start": {"type": "number", "minimum": 0},
+                "end": {"type": "number", "minimum": 0},
+                "confidence": {"type": ["number", "null"]}
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

video_editor/schemas/workspace.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "video-edit-cli/workspace.schema.json",
+  "title": "Editing workspace manifest",
+  "type": "object",
+  "required": ["schema_version", "workspace_id", "created_at", "sources", "artifacts"],
+  "properties": {
+    "schema_version": {"type": "string"},
+    "workspace_id": {"type": "string"},
+    "created_at": {"type": "string"},
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "path", "sha256", "registered_at"],
+        "properties": {
+          "id": {"type": "string"},
+          "path": {"type": "string"},
+          "sha256": {"type": "string"},
+          "role": {"type": ["string", "null"]},
+          "registered_at": {"type": "string"}
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "kind", "command", "created_at"],
+        "properties": {
+          "path": {"type": "string"},
+          "kind": {"type": "string"},
+          "command": {"type": "string"},
+          "created_at": {"type": "string"}
+        }
+      }
+    }
+  }
+}

video_editor/subtitles.py

@@ -0,0 +1,137 @@
+"""Subtitles derived from transcripts mapped through an edited timeline."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from video_editor import ffmpeg
+from video_editor.errors import InvalidInputError, ToolFailureError
+
+
+def _fmt_srt(seconds: float) -> str:
+    ms = round(seconds * 1000)
+    h, rem = divmod(ms, 3_600_000)
+    m, rem = divmod(rem, 60_000)
+    s, ms = divmod(rem, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def _fmt_vtt(seconds: float) -> str:
+    return _fmt_srt(seconds).replace(",", ".")
+
+
+def map_cues(
+    transcripts: dict[str, dict[str, Any]], segments: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    """Map transcript segments through kept ranges into output-time cues.
+
+    `transcripts` is keyed by plan source id. Words outside kept ranges are
+    dropped; partially kept transcript segments are clamped.
+    """
+    cues: list[dict[str, Any]] = []
+    for segment in segments:
+        transcript = transcripts.get(segment["source"])
+        if transcript is None:
+            continue
+        kept_in, kept_out = segment["in"], segment["out"]
+        offset = segment["output_start"] - kept_in
+        for ts in transcript["segments"]:
+            words = [
+                w for w in ts["words"] if kept_in <= w["start"] and w["end"] <= kept_out
+            ]
+            if not words:
+                continue
+            cues.append(
+                {
+                    "start": round(words[0]["start"] + offset, 3),
+                    "end": round(words[-1]["end"] + offset, 3),
+                    "text": " ".join(w["text"] for w in words).strip(),
+                }
+            )
+    cues.sort(key=lambda cue: cue["start"])
+    return cues
+
+
+def write_srt(cues: list[dict[str, Any]], output: Path) -> None:
+    lines = []
+    for i, cue in enumerate(cues, start=1):
+        lines.append(str(i))
+        lines.append(f"{_fmt_srt(cue['start'])} --> {_fmt_srt(cue['end'])}")
+        lines.append(cue["text"])
+        lines.append("")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text("\n".join(lines))
+
+
+def write_vtt(cues: list[dict[str, Any]], output: Path) -> None:
+    lines = ["WEBVTT", ""]
+    for cue in cues:
+        lines.append(f"{_fmt_vtt(cue['start'])} --> {_fmt_vtt(cue['end'])}")
+        lines.append(cue["text"])
+        lines.append("")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text("\n".join(lines))
+
+
+def parse_srt_last_end(path: Path) -> float:
+    """Last cue end time in seconds, for output validation."""
+    import re
+
+    text = path.read_text()
+    times = re.findall(r"(\d\d):(\d\d):(\d\d)[,.](\d\d\d)", text)
+    if not times:
+        raise InvalidInputError(f"no cue timestamps found in {path}")
+    h, m, s, ms = times[-1]
+    return int(h) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000
+
+
+def render_subtitles(
+    video: Path, subtitle_file: Path, output: Path, mode: str
+) -> list[str]:
+    """Attach subtitles to a video: mux a subtitle track, or burn if supported."""
+    if not video.is_file():
+        raise InvalidInputError(f"video not found: {video}")
+    if not subtitle_file.is_file():
+        raise InvalidInputError(f"subtitle file not found: {subtitle_file}")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if mode == "mux":
+        codec = (
+            "mov_text" if output.suffix.lower() in (".mp4", ".m4v", ".mov") else "srt"
+        )
+        args = [
+            "-i",
+            str(video),
+            "-i",
+            str(subtitle_file),
+            "-map",
+            "0",
+            "-map",
+            "1:0",
+            "-c",
+            "copy",
+            "-c:s",
+            codec,
+            str(output),
+        ]
+        ffmpeg.run_ffmpeg(args)
+        return args
+    if mode == "burn":
+        filters = ffmpeg.run("ffmpeg", ["-hide_banner", "-filters"]).stdout
+        if " subtitles " not in filters:
+            raise ToolFailureError(
+                "this ffmpeg build has no 'subtitles' filter (libass); "
+                "use --mode mux or install a full ffmpeg build"
+            )
+        args = [
+            "-i",
+            str(video),
+            "-vf",
+            f"subtitles={subtitle_file}",
+            "-c:a",
+            "copy",
+            str(output),
+        ]
+        ffmpeg.run_ffmpeg(args)
+        return args
+    raise InvalidInputError(f"unknown subtitles render mode '{mode}' (mux|burn)")

video_editor/sync.py

@@ -0,0 +1,149 @@
+"""Audio-based synchronization between separately recorded sources.
+
+`analyze` estimates the offset by cross-correlating low-rate loudness
+envelopes — pure evidence, it never rewrites sources. `apply` creates an
+aligned derivative or a mapping file from an explicitly approved offset.
+"""
+
+from __future__ import annotations
+
+import array
+import json
+import math
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from video_editor import ffmpeg
+from video_editor.errors import InvalidInputError, ToolFailureError
+from video_editor.provenance import utc_now
+
+ENVELOPE_HZ = 100
+SAMPLE_RATE = 8000
+
+
+def _envelope(path: Path) -> list[float]:
+    """RMS envelope at ENVELOPE_HZ from mono 8 kHz PCM."""
+    if not path.is_file():
+        raise InvalidInputError(f"input file not found: {path}")
+    binary = ffmpeg.binary_path("ffmpeg")
+    proc = subprocess.run(
+        [
+            binary,
+            "-hide_banner",
+            "-nostdin",
+            "-i",
+            str(path),
+            "-map",
+            "0:a:0",
+            "-ac",
+            "1",
+            "-ar",
+            str(SAMPLE_RATE),
+            "-f",
+            "s16le",
+            "-",
+        ],
+        capture_output=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        raise ToolFailureError(
+            f"ffmpeg failed extracting audio from {path}: "
+            + proc.stderr.decode(errors="replace").strip().splitlines()[-1]
+        )
+    samples = array.array("h")
+    samples.frombytes(proc.stdout[: len(proc.stdout) // 2 * 2])
+    window = SAMPLE_RATE // ENVELOPE_HZ
+    envelope = []
+    for i in range(0, len(samples) - window, window):
+        acc = 0.0
+        for j in range(i, i + window):
+            value = samples[j] / 32768.0
+            acc += value * value
+        envelope.append(math.sqrt(acc / window))
+    return envelope
+
+
+def _normalize(env: list[float]) -> list[float]:
+    mean = sum(env) / len(env)
+    centered = [v - mean for v in env]
+    norm = math.sqrt(sum(v * v for v in centered)) or 1.0
+    return [v / norm for v in centered]
+
+
+def analyze(reference: Path, other: Path, max_offset: float = 30.0) -> dict[str, Any]:
+    """Estimated offset in seconds such that `other` content = reference + offset."""
+    env_ref = _normalize(_envelope(reference))
+    env_other = _normalize(_envelope(other))
+    if len(env_ref) < ENVELOPE_HZ or len(env_other) < ENVELOPE_HZ:
+        raise InvalidInputError("sources are too short to synchronize (<1s of audio)")
+
+    max_lag = int(max_offset * ENVELOPE_HZ)
+    scores: list[tuple[float, int]] = []
+    for lag in range(-max_lag, max_lag + 1):
+        acc = 0.0
+        for i, value in enumerate(env_ref):
+            j = i + lag
+            if 0 <= j < len(env_other):
+                acc += value * env_other[j]
+        scores.append((acc, lag))
+    scores.sort(reverse=True)
+    best_score, best_lag = scores[0]
+    runner_up = next(
+        (score for score, lag in scores[1:] if abs(lag - best_lag) > ENVELOPE_HZ // 5),
+        0.0,
+    )
+    confidence = best_score / runner_up if runner_up > 0 else float("inf")
+    return {
+        "reference": str(reference),
+        "other": str(other),
+        "offset_seconds": round(best_lag / ENVELOPE_HZ, 3),
+        "peak_correlation": round(best_score, 4),
+        "confidence_ratio": round(confidence, 3) if math.isfinite(confidence) else None,
+        "candidates": [
+            {"offset_seconds": lag / ENVELOPE_HZ, "correlation": round(score, 4)}
+            for score, lag in scores[:5]
+        ],
+        "note": "offset is where reference content appears in the other source; "
+        "trim that many seconds from the other source to align",
+    }
+
+
+def apply(source: Path, offset: float, output: Path) -> dict[str, Any]:
+    """Create an aligned derivative (or a .json mapping) from an approved offset."""
+    if not source.is_file():
+        raise InvalidInputError(f"input file not found: {source}")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if output.suffix.lower() == ".json":
+        mapping = {
+            "kind": "sync-mapping",
+            "created_at": utc_now(),
+            "source": str(source),
+            "offset_seconds": offset,
+            "aligned_time": "source_time - offset",
+        }
+        output.write_text(json.dumps(mapping, indent=2) + "\n")
+        return {"mode": "metadata", "output": str(output), "offset_seconds": offset}
+    if offset < 0:
+        raise InvalidInputError(
+            "negative offset: swap arguments so the trimmed source is the later one, "
+            "or write a .json mapping instead"
+        )
+    args = [
+        "-ss",
+        f"{offset:.6f}",
+        "-i",
+        str(source),
+        "-c:v",
+        "libx264",
+        "-preset",
+        "veryfast",
+        "-crf",
+        "18",
+        "-c:a",
+        "pcm_s24le" if output.suffix.lower() == ".mov" else "aac",
+        str(output),
+    ]
+    ffmpeg.run_ffmpeg(args)
+    return {"mode": "trim", "output": str(output), "offset_seconds": offset}

video_editor/transcription/__init__.py

@@ -0,0 +1 @@
+"""Local transcription backends behind a replaceable interface."""

video_editor/transcription/base.py

@@ -0,0 +1,73 @@
+"""Transcription backend interface.
+
+A backend turns one media file into raw segments; `transcribe_to_document`
+wraps the result in the authoritative transcript JSON document. Backends are
+isolated behind this interface so the initial mlx-whisper backend can be
+replaced without touching callers.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol
+
+from video_editor import SCHEMA_VERSION, schemas
+from video_editor.errors import InvalidInputError
+from video_editor.provenance import sha256_file, utc_now
+
+
+class TranscriptionBackend(Protocol):
+    name: str
+
+    def transcribe(
+        self, media: Path, model: str | None, language: str | None
+    ) -> dict[str, Any]:
+        """Return {"language": str|None, "model": str|None, "segments": [...]}.
+
+        Each segment: {"start", "end", "text", "words": [{"text", "start",
+        "end", "confidence"?}], "speaker"?}.
+        """
+        ...
+
+
+def get_backend(name: str, fixture: Path | None = None) -> TranscriptionBackend:
+    if name == "mlx-whisper":
+        from video_editor.transcription.mlx_whisper import MlxWhisperBackend
+
+        return MlxWhisperBackend()
+    if name == "fixture":
+        from video_editor.transcription.fixture import FixtureBackend
+
+        if fixture is None:
+            raise InvalidInputError(
+                "--fixture <raw.json> is required with --backend fixture"
+            )
+        return FixtureBackend(fixture)
+    raise InvalidInputError(f"unknown transcription backend '{name}'")
+
+
+def transcribe_to_document(
+    backend: TranscriptionBackend,
+    media: Path,
+    model: str | None,
+    language: str | None,
+    source_id: str | None = None,
+) -> dict[str, Any]:
+    if not media.is_file():
+        raise InvalidInputError(f"input file not found: {media}")
+    raw = backend.transcribe(media, model, language)
+    document: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "source": {
+            "path": str(media.resolve()),
+            "sha256": sha256_file(media),
+            "source_id": source_id,
+        },
+        "language": raw.get("language"),
+        "backend": backend.name,
+        "model": raw.get("model"),
+        "created_at": utc_now(),
+        "segments": raw["segments"],
+    }
+    schemas.validate(document, "transcript.schema.json")
+    return document

video_editor/transcription/fixture.py

@@ -0,0 +1,33 @@
+"""Deterministic backend that replays a prepared raw-transcription JSON file.
+
+Used by automated tests and available for development so no command depends on
+model weights. The fixture file holds exactly what a real backend would return:
+{"language": ..., "model": ..., "segments": [...]}.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from video_editor.errors import InvalidInputError
+
+
+class FixtureBackend:
+    name = "fixture"
+
+    def __init__(self, fixture: Path) -> None:
+        self._fixture = fixture
+
+    def transcribe(
+        self, media: Path, model: str | None, language: str | None
+    ) -> dict[str, Any]:
+        if not self._fixture.is_file():
+            raise InvalidInputError(f"fixture transcript not found: {self._fixture}")
+        raw: dict[str, Any] = json.loads(self._fixture.read_text())
+        if "segments" not in raw:
+            raise InvalidInputError(
+                f"fixture transcript {self._fixture} has no 'segments' key"
+            )
+        return raw

video_editor/transcription/mlx_whisper.py

@@ -0,0 +1,68 @@
+"""mlx-whisper backend: local word-level transcription on Apple Silicon.
+
+The `mlx-whisper` dependency is an optional extra (`video-edit-cli[mlx]`); its
+absence fails cleanly without affecting other commands. Integration tests that
+run real inference are opt-in via the `integration` pytest marker.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from video_editor.errors import VideoEditorError
+
+DEFAULT_MODEL = "mlx-community/whisper-large-v3-turbo"
+
+
+class MlxWhisperBackend:
+    name = "mlx-whisper"
+
+    def transcribe(
+        self, media: Path, model: str | None, language: str | None
+    ) -> dict[str, Any]:
+        import importlib
+
+        try:
+            mlx_whisper = importlib.import_module("mlx_whisper")
+        except ImportError as exc:
+            raise VideoEditorError(
+                "missing-dependency",
+                "the mlx-whisper backend requires the optional 'mlx' extra; "
+                "install with `uv sync --extra mlx` (Apple Silicon only)",
+                exit_code=5,
+            ) from exc
+
+        model_name = model or DEFAULT_MODEL
+        raw = mlx_whisper.transcribe(
+            str(media),
+            path_or_hf_repo=model_name,
+            word_timestamps=True,
+            language=language,
+        )
+        segments = []
+        for segment in raw.get("segments", []):
+            words = [
+                {
+                    "text": str(word["word"]).strip(),
+                    "start": float(word["start"]),
+                    "end": float(word["end"]),
+                    "confidence": float(word["probability"])
+                    if word.get("probability") is not None
+                    else None,
+                }
+                for word in segment.get("words", [])
+            ]
+            segments.append(
+                {
+                    "start": float(segment["start"]),
+                    "end": float(segment["end"]),
+                    "text": str(segment["text"]).strip(),
+                    "words": words,
+                }
+            )
+        return {
+            "language": raw.get("language"),
+            "model": model_name,
+            "segments": segments,
+        }