video-compose 0.3.0__py3-none-any.whl

video_compose/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from video_compose.api import compose, preview, validate
+
+__all__ = ["__version__", "compose", "validate", "preview"]

video_compose/_codec.py

@@ -0,0 +1,65 @@
+"""
+GPU-accelerated codec selection with automatic h264_nvenc → libx264 fallback.
+
+Usage:
+    from video_compose._codec import codec_params
+
+    cmd = ["ffmpeg", "-y", "-i", "input.mp4", *codec_params(crf=18), "output.mp4"]
+
+Codec selection order:
+    1. VIDEO_COMPOSE_CODEC env var  (e.g. "libx264", "h264_nvenc", "hevc_nvenc")
+    2. h264_nvenc if detected via ffmpeg -encoders
+    3. libx264 as fallback
+"""
+from __future__ import annotations
+
+import functools
+import os
+import subprocess
+
+
+def _probe_nvenc() -> bool:
+    try:
+        r = subprocess.run(
+            ["ffmpeg", "-hide_banner", "-encoders"],
+            capture_output=True, text=True, timeout=5,
+        )
+        return "h264_nvenc" in r.stdout
+    except Exception:
+        return False
+
+
+@functools.lru_cache(maxsize=1)
+def get_codec() -> str:
+    """Return the active codec name (detected once, then cached)."""
+    forced = os.environ.get("VIDEO_COMPOSE_CODEC", "").strip()
+    if forced:
+        return forced
+    if _probe_nvenc():
+        return "h264_nvenc"
+    return "libx264"
+
+
+def codec_params(crf: int = 20, *, profile: str | None = None) -> list[str]:
+    """Return ffmpeg -c:v … quality arguments for the active codec.
+
+    Args:
+        crf:     Quality level (0–51, lower = better). Maps to -crf for libx264
+                 and -cq for h264_nvenc — same perceptual scale.
+        profile: H.264 profile ("high", "main", "baseline"). Applied for both
+                 libx264 and h264_nvenc when specified.
+    """
+    codec = get_codec()
+    is_nvenc = codec == "h264_nvenc"
+
+    params: list[str] = ["-c:v", codec, "-pix_fmt", "yuv420p"]
+
+    if is_nvenc:
+        params += ["-cq", str(crf), "-preset", "p4"]
+    else:
+        params += ["-crf", str(crf)]
+
+    if profile:
+        params += ["-profile:v", profile]
+
+    return params

video_compose/_fonts.py

@@ -0,0 +1,51 @@
+"""
+Font resolution for video-compose.
+
+Maps logical font family names to bundled TTF paths so templates work
+on any system without requiring fonts to be installed.
+
+Bundled fonts take priority; system fonts are used as fallback for
+families not in the bundle (e.g. custom brand fonts).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+_FONTS_DIR = Path(__file__).parent / "fonts"
+
+_BUNDLED: dict[str, dict[str, str]] = {
+    "inter": {
+        "regular":  "Inter-Regular.ttf",
+        "medium":   "Inter-Medium.ttf",
+        "bold":     "Inter-SemiBold.ttf",
+        "semibold": "Inter-SemiBold.ttf",
+        "black":    "Inter-SemiBold.ttf",
+    },
+}
+
+
+def resolve_font_family(family: str, weight: str = "bold") -> str:
+    """Return an absolute path to a bundled TTF, or the original family name.
+
+    If the family is bundled (e.g. "Inter"), returns the absolute path so
+    text-fx loads it directly without a system font lookup.
+
+    If the family is not bundled, returns it unchanged so text-fx attempts
+    its normal matplotlib / filesystem discovery.
+    """
+    key = family.lower().strip()
+    weight_key = weight.lower().strip()
+
+    bundle = _BUNDLED.get(key)
+    if bundle is None:
+        return family
+
+    filename = bundle.get(weight_key) or bundle.get("regular", "")
+    if not filename:
+        return family
+
+    path = _FONTS_DIR / filename
+    if path.exists():
+        return str(path)
+
+    return family

video_compose/api.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ComposeResult:
+    video_path: Path | None = None
+    png_dir: Path | None = None
+    warnings: list[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        return f"ComposeResult(video={self.video_path}, warnings={len(self.warnings)})"
+
+
+def compose(
+    spec: dict | str | Path,
+    output_dir: str | Path | None = None,
+    progress_cb: Callable[[str, float], None] | None = None,
+    export_png: bool = False,
+) -> ComposeResult:
+    """Render a TVCS spec to MP4 and optionally PNG frames.
+
+    Args:
+        spec:        TVCS spec as dict, JSON string, or path to a .json file.
+        output_dir:  Output directory. Defaults to ./video_compose_output/.
+        progress_cb: Optional callback(stage: str, fraction: float).
+        export_png:  If True, also extract PNG frames alongside the MP4.
+
+    Returns:
+        ComposeResult with paths to rendered outputs and any non-fatal warnings.
+
+    Raises:
+        ValueError: If the spec fails structural or semantic validation.
+    """
+    from video_compose.schema.spec import TVCSSpec
+    from video_compose.schema.validator import validate as _validate
+    from video_compose.assembler.assembler import Assembler
+
+    raw = _load_raw(spec)
+    vr = _validate(raw)
+    if vr.has_errors:
+        raise ValueError("Invalid TVCS spec:\n" + "\n".join(vr.errors))
+
+    parsed_spec = TVCSSpec.model_validate(raw)
+
+    out_dir = Path(output_dir) if output_dir else Path("video_compose_output")
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    assembler = Assembler(parsed_spec, output_dir=out_dir, progress_cb=progress_cb)
+    video_path = assembler.run()
+
+    png_dir: Path | None = None
+    if export_png:
+        from video_compose.assembler.png_export import export_frames
+        png_dir = out_dir / "frames"
+        export_frames(video_path, png_dir)
+
+    return ComposeResult(
+        video_path=video_path,
+        png_dir=png_dir,
+        warnings=vr.warnings,
+    )
+
+
+def validate(spec: dict | str | Path):
+    """Validate a TVCS spec without rendering.
+
+    Returns:
+        ValidationResult with .is_valid, .errors, .warnings.
+    """
+    from video_compose.schema.validator import validate as _validate
+    return _validate(_load_raw(spec))
+
+
+def preview(
+    spec: dict | str | Path,
+    segment_id: str,
+    output_path: str | Path | None = None,
+) -> Path:
+    """Render a single segment to a preview MP4.
+
+    Args:
+        spec:         TVCS spec.
+        segment_id:   ID of the segment to render.
+        output_path:  Destination path. Defaults to ./preview_{segment_id}.mp4.
+
+    Returns:
+        Path to the rendered preview MP4.
+    """
+    from video_compose.schema.spec import TVCSSpec
+    from video_compose.assembler.assembler import Assembler
+
+    raw = _load_raw(spec)
+    parsed_spec = TVCSSpec.model_validate(raw)
+    assembler = Assembler(parsed_spec)
+    if output_path is None:
+        output_path = Path(f"preview_{segment_id}.mp4")
+    return assembler.render_segment_preview(segment_id, Path(output_path))
+
+
+def _load_raw(spec: dict | str | Path) -> dict:
+    if isinstance(spec, dict):
+        return spec
+    text = Path(spec).read_text(encoding="utf-8") if isinstance(spec, Path) else str(spec)
+    if text.strip().startswith("{") or text.strip().startswith("["):
+        return json.loads(text)
+    return json.loads(Path(text).read_text(encoding="utf-8"))

video_compose/assembler/__init__.py

@@ -0,0 +1,4 @@
+from video_compose.assembler.assembler import Assembler
+from video_compose.assembler.png_export import export_frames
+
+__all__ = ["Assembler", "export_frames"]

video_compose/assembler/assembler.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import logging
+import tempfile
+from pathlib import Path
+from typing import Callable, Any
+
+logger = logging.getLogger(__name__)
+
+
+class Assembler:
+    """Full render pipeline: segment render → overlays → grade → transitions → concat → audio.
+
+    Pipeline per segment:
+        1. Render segment (via renderers.dispatcher)
+        2. Apply overlays (via overlays.compositor)
+        3. Apply per-segment grade (via grade.apply)
+
+    Then global pipeline:
+        4. Apply transitions between segments (via transition.apply)
+        5. Concatenate all segments
+        6. Apply global theme grade (if any, no per-segment grade yet applied)
+        7. Mix audio (via audio.pipeline)
+    """
+
+    def __init__(
+        self,
+        spec,
+        output_dir: Path | None = None,
+        progress_cb: Callable[[str, float], None] | None = None,
+    ) -> None:
+        self._spec = spec
+        self._output_dir = Path(output_dir) if output_dir else None
+        self._progress_cb = progress_cb or (lambda msg, pct: None)
+
+    def run(self) -> Path:
+        """Execute the full render pipeline. Returns path to the final MP4."""
+        spec = self._spec
+        output = spec.output
+
+        width = output.width if output else 1920
+        height = output.height if output else 1080
+        fps = float(output.fps if output else 30)
+
+        grade_slug_global: str | None = None
+        if spec.theme:
+            grade_slug_global = getattr(spec.theme, "grade", None)
+
+        with tempfile.TemporaryDirectory() as td:
+            work_dir = Path(td)
+
+            from video_compose.data import DataResolver
+            resolver = DataResolver(spec)
+
+            # ── Phase 1: Render each segment ──────────────────────────────────
+            segment_clips: list[Path] = []
+            segment_timing: dict[str, float] = {}
+            current_time = 0.0
+
+            for i, seg in enumerate(spec.segments):
+                self._progress_cb(f"Rendering segment {seg.id}", i / len(spec.segments) * 0.6)
+                logger.info("[%d/%d] Rendering segment %r (type=%s)", i + 1, len(spec.segments), seg.id, seg.type)
+
+                segment_timing[seg.id] = current_time
+
+                # 1a. Resolve data ref
+                data_ref = getattr(seg, "data", None)
+                data = resolver.resolve(data_ref) if data_ref is not None else None
+
+                # 1b. Render the segment content
+                clip_path = work_dir / f"seg_{i:03d}_{seg.id}.mp4"
+                from video_compose.renderers.dispatcher import dispatch
+                dispatch(seg, data, clip_path, width=width, height=height, fps=fps)
+
+                # 1c. Apply overlays
+                overlays = getattr(seg, "overlays", None) or []
+                if overlays:
+                    from video_compose.overlays.compositor import apply_overlays
+                    clip_path = apply_overlays(
+                        clip_path, overlays, seg.duration, width, height, fps
+                    )
+
+                # 1d. Per-segment grade (prefer segment.grade, else global theme grade)
+                grade_slug = getattr(seg, "grade", None) or grade_slug_global
+                if grade_slug:
+                    from video_compose.grade.apply import apply_grade
+                    clip_path = apply_grade(clip_path, grade_slug)
+
+                segment_clips.append(clip_path)
+                current_time += seg.duration
+
+            total_duration = current_time
+
+            # ── Phase 2: Apply transitions ──────────────────────────────────
+            self._progress_cb("Applying transitions", 0.65)
+            clips_with_transitions = self._apply_transitions(segment_clips, spec, work_dir)
+
+            # ── Phase 3: Concatenate ─────────────────────────────────────────
+            self._progress_cb("Concatenating", 0.75)
+            from video_compose.assembler.concat import concat_clips
+            silent_video = concat_clips(clips_with_transitions, work_dir / "assembled_silent.mp4")
+
+            # ── Phase 4: Audio ───────────────────────────────────────────────
+            self._progress_cb("Mixing audio", 0.85)
+            from video_compose.audio.pipeline import AudioPipeline
+
+            if self._output_dir:
+                self._output_dir.mkdir(parents=True, exist_ok=True)
+                final_path = self._output_dir / "output.mp4"
+            else:
+                final_path = work_dir / "final.mp4"
+
+            audio_pipeline = AudioPipeline()
+            final_video = audio_pipeline.run(
+                spec=spec,
+                video_path=silent_video,
+                segment_timing=segment_timing,
+                total_duration=total_duration,
+                work_dir=work_dir,
+                output_path=work_dir / "final_with_audio.mp4",
+            )
+
+            # Copy final to output_dir
+            import shutil
+            shutil.copy2(final_video, final_path)
+
+        self._progress_cb("Done", 1.0)
+        logger.info("Render complete: %s", final_path)
+        return final_path
+
+    def render_segment_preview(self, segment_id: str, output_path: Path | None = None) -> Path:
+        """Render a single segment to a temporary file for preview."""
+        spec = self._spec
+        seg = next((s for s in spec.segments if s.id == segment_id), None)
+        if seg is None:
+            raise ValueError(f"No segment with id {segment_id!r}")
+
+        output = spec.output
+        width = output.width if output else 1920
+        height = output.height if output else 1080
+        fps = float(output.fps if output else 30)
+
+        if output_path is None:
+            import tempfile
+            tf = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
+            output_path = Path(tf.name)
+            tf.close()
+
+        from video_compose.data import DataResolver
+        resolver = DataResolver(spec)
+        data_ref = getattr(seg, "data", None)
+        data = resolver.resolve(data_ref) if data_ref is not None else None
+
+        from video_compose.renderers.dispatcher import dispatch
+        dispatch(seg, data, output_path, width=width, height=height, fps=fps)
+
+        return output_path
+
+    def _apply_transitions(
+        self,
+        clips: list[Path],
+        spec,
+        work_dir: Path,
+    ) -> list[Path]:
+        """Apply transitions between consecutive clips.
+
+        Returns a list of paths — may be shorter than *clips* if transitions
+        merge pairs, or same length if transitions use cut-fx's overlap mode.
+        """
+        if len(clips) <= 1:
+            return clips
+
+        from video_compose.transition.apply import apply_transition
+
+        transitions_block = getattr(spec, "transitions", None)
+        default_ref = transitions_block.default if transitions_block else None
+        overrides_list = (transitions_block.overrides or []) if transitions_block else []
+
+        # Build override map: (from_id, to_id) → TransitionRef
+        override_map: dict[tuple[str, str], Any] = {}
+        for ov in overrides_list:
+            from_id = ov.from_segment
+            to_id = ov.to
+            override_map[(from_id, to_id)] = ov  # use ov as config (has .type and .duration)
+
+        segments = spec.segments
+        result_clips = [clips[0]]
+
+        for i in range(len(clips) - 1):
+            from_id = segments[i].id
+            to_id = segments[i + 1].id
+            transition_config = override_map.get((from_id, to_id), default_ref)
+
+            joined = work_dir / f"joined_{i:03d}_{i+1:03d}.mp4"
+            try:
+                joined_path = apply_transition(result_clips[-1], clips[i + 1], transition_config, joined)
+                # Replace last clip with the joined result
+                result_clips[-1] = joined_path
+            except Exception as exc:
+                logger.warning("Transition %d→%d failed: %s — using hard cut", i, i + 1, exc)
+                result_clips.append(clips[i + 1])
+
+        return result_clips

video_compose/assembler/concat.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import subprocess
+import tempfile
+import os
+from pathlib import Path
+
+
+def concat_clips(clip_paths: list[Path], output: Path) -> Path:
+    """Concatenate a list of clip files into a single MP4 using ffmpeg concat."""
+    if not clip_paths:
+        raise ValueError("concat_clips: no clips to concatenate")
+
+    if len(clip_paths) == 1:
+        return clip_paths[0]
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False, encoding="utf-8") as f:
+        for p in clip_paths:
+            f.write(f"file '{Path(p).as_posix()}'\n")
+        concat_list = f.name
+
+    try:
+        result = subprocess.run(
+            ["ffmpeg", "-y", "-f", "concat", "-safe", "0",
+             "-i", concat_list, "-c", "copy", str(output)],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"ffmpeg concat failed: {result.stderr[:500]}")
+    finally:
+        os.unlink(concat_list)
+
+    return output

video_compose/assembler/encode.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from video_compose._codec import codec_params
+
+
+def remux_mp4(source: Path, output: Path, *, width: int, height: int, fps: float) -> Path:
+    """Re-encode *source* to a clean H.264 MP4 at the specified resolution and fps."""
+    cmd = [
+        "ffmpeg", "-y", "-i", str(source),
+        "-vf", f"scale={width}:{height}",
+        "-r", str(fps),
+        *codec_params(crf=20),
+        "-c:a", "copy",
+        str(output),
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"remux failed: {result.stderr[:500]}")
+    return output

video_compose/assembler/png_export.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def export_frames(video_path: Path, output_dir: Path, fps: float | None = None) -> list[Path]:
+    """Extract all frames from *video_path* as PNG files in *output_dir*.
+
+    Args:
+        video_path: Source MP4.
+        output_dir: Directory to write PNG frames.
+        fps:        If set, extract at this rate; otherwise extract every frame.
+
+    Returns:
+        Sorted list of Path objects for the extracted PNGs.
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    vf_args = []
+    if fps is not None:
+        vf_args = ["-vf", f"fps={fps}"]
+
+    cmd = [
+        "ffmpeg", "-y", "-i", str(video_path),
+        *vf_args,
+        str(output_dir / "frame_%06d.png"),
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"PNG export failed: {result.stderr[:500]}")
+
+    return sorted(output_dir.glob("frame_*.png"))

video_compose/assets/placeholders.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+_ASSETS_DIR = Path(__file__).parent / "placeholders"
+
+# keyword → placeholder filename (checked against lowercase variable name)
+_IMAGE_RULES: list[tuple[tuple[str, ...], str]] = [
+    (("headshot", "portrait", "speaker_photo", "avatar", "profile"), "headshot.png"),
+    (("product", "hero_image", "item_photo"),                        "product_hero.png"),
+    (("real_estate", "property", "house", "exterior", "listing"),   "real_estate.png"),
+    (("team",),                                                       "team_photo.png"),
+    (("landscape", "background_image", "scene", "cover"),           "landscape_motivational.png"),
+]
+
+_AUDIO_RULES: list[tuple[tuple[str, ...], str]] = [
+    (("lofi", "chill", "ambient_track"),  "music_lofi.mp3"),
+    (("cinematic", "dramatic", "epic"),   "music_cinematic.mp3"),
+    # default fallback for any music/audio var
+    (("music", "track", "audio_file", "bed", "bgm", "background_audio", "soundtrack"), "music_corporate.mp3"),
+]
+
+
+def auto_placeholder(var_name: str, var_type: str) -> str | None:
+    """Return an absolute path to a bundled placeholder asset for *var_name*.
+
+    Matches on keyword substrings in the variable name (case-insensitive).
+    Returns None if no match is found.
+
+    Args:
+        var_name: Template variable name (e.g. 'speaker_photo', 'bg_music').
+        var_type: TVCS variable type: 'image_path', 'video_path', 'audio_path', etc.
+
+    Returns:
+        Absolute path string to the placeholder file, or None.
+    """
+    name_lower = var_name.lower()
+
+    if var_type in ("image_path", "video_path"):
+        for keywords, filename in _IMAGE_RULES:
+            if any(kw in name_lower for kw in keywords):
+                p = _ASSETS_DIR / filename
+                return str(p) if p.exists() else None
+        # Generic fallback for any image_path
+        fallback = _ASSETS_DIR / "landscape_motivational.png"
+        return str(fallback) if fallback.exists() else None
+
+    if var_type == "audio_path":
+        for keywords, filename in _AUDIO_RULES:
+            if any(kw in name_lower for kw in keywords):
+                p = _ASSETS_DIR / filename
+                return str(p) if p.exists() else None
+        # Generic fallback for any audio_path
+        fallback = _ASSETS_DIR / "music_corporate.mp3"
+        return str(fallback) if fallback.exists() else None
+
+    return None

video_compose/audio/__init__.py

@@ -0,0 +1,2 @@
+from video_compose.audio.pipeline import AudioPipeline
+__all__ = ['AudioPipeline']