Upload 25 files

renderer/__init__.py

@@ -0,0 +1,7 @@
+"""CPU-first video rendering engine for Basyx FFmpeg."""
+
+from renderer.core.config import Settings
+from renderer.core.models import RenderRequest, RenderResult
+from renderer.core.render_engine import RenderEngine
+
+__all__ = ["RenderEngine", "RenderRequest", "RenderResult", "Settings"]

renderer/audio/__init__.py

@@ -0,0 +1,3 @@
+from renderer.audio.mixer import AudioMixer
+
+__all__ = ["AudioMixer"]

renderer/audio/mixer.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from renderer.ffmpeg.command import FFmpegCommand
+from renderer.ffmpeg.runner import FFmpegRunner
+
+
+class AudioMixer:
+    def __init__(self, runner: FFmpegRunner) -> None:
+        self.runner = runner
+
+    def ducking_filter(self) -> str:
+        # sidechaincompress lowers background music while voiceover is active.
+        return (
+            "[1:a]volume=0.316[music_quiet];"
+            "[music_quiet][2:a]sidechaincompress=threshold=0.02:ratio=8:attack=30:release=600[ducked];"
+            "[2:a]volume=1.0[voice];"
+            "[ducked][voice]amix=inputs=2:duration=first:dropout_transition=2[aout]"
+        )
+
+    def mix(self, video: Path, music: str | None, voiceover: str | None, output: Path) -> Path:
+        if not music and not voiceover:
+            command = FFmpegCommand().add("-hide_banner").input(video).add("-c", "copy").overwrite().add(output).build()
+            self.runner.run(command)
+            return output
+        if voiceover and music:
+            command = (
+                FFmpegCommand()
+                .add("-hide_banner")
+                .input(video)
+                .input(music)
+                .input(voiceover)
+                .add("-filter_complex", self.ducking_filter())
+                .add("-map", "0:v", "-map", "[aout]", "-c:v", "copy", "-c:a", "aac", "-shortest")
+                .overwrite()
+                .add(output)
+                .build()
+            )
+        else:
+            audio = voiceover or music
+            volume = "1.0" if voiceover else "0.316"
+            command = (
+                FFmpegCommand()
+                .add("-hide_banner")
+                .input(video)
+                .input(audio)
+                .add("-filter_complex", f"[1:a]volume={volume}[aout]")
+                .add("-map", "0:v", "-map", "[aout]", "-c:v", "copy", "-c:a", "aac", "-shortest")
+                .overwrite()
+                .add(output)
+                .build()
+            )
+        self.runner.run(command)
+        return output

renderer/core/__init__.py

@@ -0,0 +1 @@
+"""Core configuration, models, and orchestration."""

renderer/core/config.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Runtime settings tuned for small CPU-only Hugging Face Spaces."""
+
+    base_dir: Path = Path(os.getenv("BASYX_BASE_DIR", "/app"))
+    temp_dir: Path = Path(os.getenv("TEMP_DIR", "/app/temp"))
+    exports_dir: Path = Path(os.getenv("EXPORTS_DIR", "/app/exports"))
+    jobs_dir: Path = Path(os.getenv("JOBS_DIR", "/app/jobs"))
+    metadata_cache: Path = Path(os.getenv("METADATA_CACHE", "/app/temp/metadata_cache.json"))
+    font_path: Path = Path(os.getenv("FONT_PATH", "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf"))
+    output_width: int = int(os.getenv("OUTPUT_WIDTH", "1080"))
+    output_height: int = int(os.getenv("OUTPUT_HEIGHT", "1920"))
+    output_fps: int = int(os.getenv("OUTPUT_FPS", "30"))
+    ffmpeg_timeout_seconds: int = int(os.getenv("FFMPEG_TIMEOUT_SECONDS", "900"))
+    max_retries: int = int(os.getenv("MAX_RETRIES", "3"))
+    max_workers: int = int(os.getenv("MAX_RENDER_WORKERS", "1"))
+    crf: int = int(os.getenv("OUTPUT_CRF", "23"))
+    preset: str = os.getenv("OUTPUT_PRESET", "veryfast")
+
+    def ensure_dirs(self) -> None:
+        for directory in (self.temp_dir, self.exports_dir, self.jobs_dir, self.metadata_cache.parent):
+            directory.mkdir(parents=True, exist_ok=True)

renderer/core/models.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+JobState = Literal["PENDING", "RUNNING", "FAILED", "COMPLETED"]
+
+
+@dataclass
+class Scene:
+    start: float
+    duration: float
+    media: str
+    caption: str = ""
+    transition: str = "fade"
+    background: str = "blur"
+
+
+@dataclass
+class RenderRequest:
+    scenes: list[Scene]
+    template: str = "tiktok_classic"
+    output_name: str = "render.mp4"
+    voiceover: str | None = None
+    background_music: str | None = None
+    subtitle_format: Literal["srt", "ass"] = "ass"
+    normalize: bool = True
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AIReelsRequest:
+    script: str
+    voiceover: str
+    assets: list[str]
+    template: str = "tiktok_classic"
+    output_name: str = "ai_reel.mp4"
+    background_music: str | None = None
+
+
+@dataclass
+class RenderResult:
+    output_path: Path
+    commands: list[list[str]]
+    metrics: dict[str, Any]
+    logs: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AssetMetadata:
+    path: str
+    mime_type: str
+    size_bytes: int
+    mtime: float
+    duration: float = 0.0
+    width: int | None = None
+    height: int | None = None
+    fps: float | None = None
+    bitrate: int | None = None
+    video_codec: str | None = None
+    audio_codec: str | None = None
+    has_audio: bool = False
+    streams: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class JobRecord:
+    job_id: str
+    state: JobState
+    created_at: float
+    updated_at: float
+    output_path: str | None = None
+    failure_reason: str | None = None
+    commands: list[list[str]] = field(default_factory=list)
+    logs: list[str] = field(default_factory=list)
+    metrics: dict[str, Any] = field(default_factory=dict)

renderer/core/render_engine.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import mimetypes
+import shutil
+import time
+from pathlib import Path
+
+from renderer.audio import AudioMixer
+from renderer.core.config import Settings
+from renderer.core.models import AIReelsRequest, RenderRequest, RenderResult
+from renderer.core.utils import cleanup_directory, temp_workdir
+from renderer.exports import ExportManager
+from renderer.ffmpeg.assets import AssetProbe
+from renderer.ffmpeg.command import FFmpegCommand
+from renderer.ffmpeg.normalize import Normalizer
+from renderer.ffmpeg.runner import FFmpegRunner
+from renderer.scenes import Timeline
+from renderer.subtitles import SubtitleGenerator
+from renderer.transitions import TransitionBuilder
+
+
+class RenderEngine:
+    def __init__(self, settings: Settings | None = None, log=None) -> None:
+        self.settings = settings or Settings()
+        self.settings.ensure_dirs()
+        self._commands: list[list[str]] = []
+        self._logs: list[str] = []
+        self.runner = FFmpegRunner(self.settings.ffmpeg_timeout_seconds, log=log, on_command=self._record_command)
+        self.assets = AssetProbe(self.settings.metadata_cache)
+        self.normalizer = Normalizer(self.settings, self.runner)
+        self.subtitles = SubtitleGenerator()
+        self.transitions = TransitionBuilder()
+        self.audio = AudioMixer(self.runner)
+        self.exports = ExportManager(self.settings.exports_dir)
+
+    def render(self, request: RenderRequest, job_id: str) -> RenderResult:
+        self._commands = []
+        self._logs = []
+        started = time.time()
+        timeline = Timeline(request.scenes)
+        with temp_workdir(self.settings.temp_dir, job_id) as work:
+            workdir = Path(work)
+            prepared = self._prepare_scene_media(request, workdir)
+            subtitles = self._write_subtitles(request, timeline, workdir)
+            video = self._compose_video(prepared, request, subtitles, workdir)
+            mixed = self.audio.mix(video, request.background_music, request.voiceover, workdir / "mixed.mp4")
+            output = self.exports.save(mixed, job_id, request.output_name)
+            cleanup_directory(workdir, keep={mixed})
+        metrics = {
+            "render_time_seconds": round(time.time() - started, 3),
+            "output_size_bytes": output.stat().st_size,
+            "scene_count": len(request.scenes),
+        }
+        return RenderResult(output_path=output, commands=list(self._commands), metrics=metrics, logs=list(self._logs))
+
+    def ai_reels(self, request: AIReelsRequest, job_id: str) -> RenderResult:
+        if not request.voiceover:
+            raise ValueError("AI reels v1 requires a provided voiceover path; TTS is pluggable but not bundled.")
+        voice_meta = self.assets.probe(request.voiceover)
+        duration = max(voice_meta.duration, len(request.script.split()) * 0.35, 3.0)
+        per_scene = duration / max(1, len(request.assets))
+        captions = _split_script(request.script, len(request.assets))
+        scenes = [
+            {
+                "start": round(idx * per_scene, 3),
+                "duration": round(per_scene, 3),
+                "media": asset,
+                "caption": captions[idx] if idx < len(captions) else "",
+            }
+            for idx, asset in enumerate(request.assets)
+        ]
+        render_request = RenderRequest(
+            scenes=Timeline.request_from_payload({"scenes": scenes}).scenes,
+            template=request.template,
+            output_name=request.output_name,
+            voiceover=request.voiceover,
+            background_music=request.background_music,
+        )
+        return self.render(render_request, job_id)
+
+    def inspect_asset(self, path: str | Path) -> dict:
+        return self.assets.probe(path).__dict__
+
+    def _prepare_scene_media(self, request: RenderRequest, workdir: Path) -> list[Path]:
+        prepared: list[Path] = []
+        for idx, scene in enumerate(request.scenes):
+            source = Path(scene.media)
+            metadata = self.assets.probe(source)
+            target = workdir / f"scene_{idx:03d}.mp4"
+            mime_type = metadata.mime_type or mimetypes.guess_type(str(source))[0] or ""
+            if mime_type.startswith("image/") or source.suffix.lower() in {".jpg", ".jpeg", ".png", ".webp", ".gif"}:
+                self.normalizer.image_to_video(source, target, scene.duration)
+            elif request.normalize and self.normalizer.needs_normalization(metadata):
+                self.normalizer.normalize(source, target, scene.duration)
+            else:
+                shutil.copy2(source, target)
+            prepared.append(target)
+        return prepared
+
+    def _write_subtitles(self, request: RenderRequest, timeline: Timeline, workdir: Path) -> Path | None:
+        events = self.subtitles.from_scenes(request.scenes, timeline.total_duration)
+        if not events:
+            return None
+        if request.subtitle_format == "srt":
+            return self.subtitles.write_srt(events, workdir / "captions.srt")
+        return self.subtitles.write_ass(events, workdir / "captions.ass", request.template)
+
+    def _compose_video(self, scenes: list[Path], request: RenderRequest, subtitle_path: Path | None, workdir: Path) -> Path:
+        if len(scenes) == 1:
+            composed = workdir / "composed.mp4"
+            shutil.copy2(scenes[0], composed)
+        else:
+            composed = workdir / "composed.mp4"
+            durations = [scene.duration for scene in request.scenes]
+            transitions = [scene.transition for scene in request.scenes]
+            filter_graph, final_stream = self.transitions.xfade_chain(len(scenes), durations, transitions)
+            cmd = FFmpegCommand().add("-hide_banner")
+            for scene in scenes:
+                cmd.input(scene)
+            cmd.add("-filter_complex", filter_graph)
+            cmd.add("-map", final_stream, "-an", "-c:v", "libx264", "-preset", self.settings.preset, "-crf", self.settings.crf)
+            command = cmd.overwrite().add(composed).build()
+            self._run(command)
+        if subtitle_path:
+            subtitled = workdir / "subtitled.mp4"
+            escaped = _ffmpeg_subtitle_path(subtitle_path)
+            command = (
+                FFmpegCommand()
+                .add("-hide_banner")
+                .input(composed)
+                .add("-vf", f"subtitles='{escaped}'", "-c:a", "copy", "-c:v", "libx264", "-preset", self.settings.preset, "-crf", self.settings.crf)
+                .overwrite()
+                .add(subtitled)
+                .build()
+            )
+            self._run(command)
+            return subtitled
+        return composed
+
+    def _run(self, command: list[str]) -> None:
+        result = self.runner.run(command)
+        if result.stderr:
+            self._logs.append(result.stderr[-4000:])
+
+    def _record_command(self, command: list[str]) -> None:
+        self._commands.append(command)
+
+
+def _split_script(script: str, chunks: int) -> list[str]:
+    words = script.split()
+    if chunks <= 0:
+        return []
+    size = max(1, round(len(words) / chunks))
+    return [" ".join(words[i : i + size]) for i in range(0, len(words), size)][:chunks]
+
+
+def _ffmpeg_subtitle_path(path: Path) -> str:
+    return str(path).replace("\\", "/").replace(":", r"\:")

renderer/core/utils.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import tempfile
+import time
+import uuid
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any
+
+
+def new_id(prefix: str = "job") -> str:
+    return f"{prefix}_{uuid.uuid4().hex[:12]}"
+
+
+def safe_filename(name: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("._")
+    return cleaned or "render.mp4"
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    serializable = asdict(data) if is_dataclass(data) else data
+    path.write_text(json.dumps(serializable, indent=2, default=str), encoding="utf-8")
+
+
+def read_json(path: Path, default: Any) -> Any:
+    if not path.exists():
+        return default
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def now() -> float:
+    return time.time()
+
+
+def temp_workdir(root: Path, prefix: str) -> tempfile.TemporaryDirectory[str]:
+    root.mkdir(parents=True, exist_ok=True)
+    return tempfile.TemporaryDirectory(prefix=f"{prefix}_", dir=str(root))
+
+
+def cleanup_directory(path: Path, keep: set[Path] | None = None) -> None:
+    keep = {p.resolve() for p in (keep or set())}
+    if not path.exists():
+        return
+    for child in path.iterdir():
+        if child.resolve() in keep:
+            continue
+        if child.is_dir():
+            shutil.rmtree(child, ignore_errors=True)
+        else:
+            child.unlink(missing_ok=True)

renderer/exports/__init__.py

@@ -0,0 +1,3 @@
+from renderer.exports.manager import ExportManager
+
+__all__ = ["ExportManager"]

renderer/exports/manager.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from renderer.core.utils import safe_filename
+
+
+class ExportManager:
+    def __init__(self, exports_dir: Path) -> None:
+        self.exports_dir = exports_dir
+        self.exports_dir.mkdir(parents=True, exist_ok=True)
+
+    def save(self, source: Path, job_id: str, output_name: str) -> Path:
+        filename = safe_filename(output_name)
+        if not filename.lower().endswith(".mp4"):
+            filename += ".mp4"
+        target = self.exports_dir / f"{job_id}_{filename}"
+        shutil.copy2(source, target)
+        return target

renderer/ffmpeg/__init__.py

@@ -0,0 +1 @@
+"""FFmpeg subprocess and filter graph helpers."""

renderer/ffmpeg/assets.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+import mimetypes
+import subprocess
+from dataclasses import asdict
+from pathlib import Path
+
+from renderer.core.models import AssetMetadata
+from renderer.core.utils import read_json, write_json
+
+
+class AssetProbe:
+    def __init__(self, cache_path: Path) -> None:
+        self.cache_path = cache_path
+        self.cache: dict[str, dict] = read_json(cache_path, {})
+
+    def probe(self, path: str | Path) -> AssetMetadata:
+        media = Path(path)
+        stat = media.stat()
+        key = str(media.resolve())
+        cached = self.cache.get(key)
+        if cached and cached.get("size_bytes") == stat.st_size and cached.get("mtime") == stat.st_mtime:
+            return AssetMetadata(**cached)
+
+        raw = self._ffprobe(media)
+        streams = raw.get("streams", [])
+        fmt = raw.get("format", {})
+        video_stream = next((s for s in streams if s.get("codec_type") == "video"), {})
+        audio_stream = next((s for s in streams if s.get("codec_type") == "audio"), {})
+        metadata = AssetMetadata(
+            path=str(media),
+            mime_type=mimetypes.guess_type(str(media))[0] or "application/octet-stream",
+            size_bytes=stat.st_size,
+            mtime=stat.st_mtime,
+            duration=float(fmt.get("duration") or video_stream.get("duration") or audio_stream.get("duration") or 0),
+            width=_int_or_none(video_stream.get("width")),
+            height=_int_or_none(video_stream.get("height")),
+            fps=_parse_fps(video_stream.get("avg_frame_rate") or video_stream.get("r_frame_rate")),
+            bitrate=_int_or_none(fmt.get("bit_rate")),
+            video_codec=video_stream.get("codec_name"),
+            audio_codec=audio_stream.get("codec_name"),
+            has_audio=bool(audio_stream),
+            streams=streams,
+        )
+        self.cache[key] = asdict(metadata)
+        write_json(self.cache_path, self.cache)
+        return metadata
+
+    @staticmethod
+    def _ffprobe(path: Path) -> dict:
+        command = [
+            "ffprobe",
+            "-v",
+            "error",
+            "-show_format",
+            "-show_streams",
+            "-print_format",
+            "json",
+            str(path),
+        ]
+        result = subprocess.run(command, check=True, capture_output=True, text=True)
+        return json.loads(result.stdout or "{}")
+
+
+def _parse_fps(value: str | None) -> float | None:
+    if not value or value == "0/0":
+        return None
+    if "/" in value:
+        num, den = value.split("/", 1)
+        den_f = float(den)
+        return float(num) / den_f if den_f else None
+    return float(value)
+
+
+def _int_or_none(value: object) -> int | None:
+    if value in (None, ""):
+        return None
+    return int(value)

renderer/ffmpeg/command.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class FFmpegCommand:
+    args: list[str] = field(default_factory=lambda: ["ffmpeg"])
+
+    def add(self, *args: object) -> "FFmpegCommand":
+        self.args.extend(str(arg) for arg in args)
+        return self
+
+    def input(self, path: str | Path, **options: object) -> "FFmpegCommand":
+        for key, value in options.items():
+            self.add(f"-{key}", value)
+        self.add("-i", path)
+        return self
+
+    def overwrite(self) -> "FFmpegCommand":
+        self.add("-y")
+        return self
+
+    def build(self) -> list[str]:
+        return list(self.args)

renderer/ffmpeg/normalize.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from renderer.core.config import Settings
+from renderer.core.models import AssetMetadata
+from renderer.ffmpeg.command import FFmpegCommand
+from renderer.ffmpeg.runner import FFmpegRunner
+
+
+class Normalizer:
+    def __init__(self, settings: Settings, runner: FFmpegRunner) -> None:
+        self.settings = settings
+        self.runner = runner
+
+    def needs_normalization(self, metadata: AssetMetadata) -> bool:
+        return not (
+            metadata.width == self.settings.output_width
+            and metadata.height == self.settings.output_height
+            and round(metadata.fps or 0) == self.settings.output_fps
+            and metadata.video_codec == "h264"
+            and (metadata.audio_codec in ("aac", None))
+        )
+
+    def normalize(self, path: str | Path, output: Path, duration: float | None = None) -> Path:
+        vf = (
+            f"scale={self.settings.output_width}:{self.settings.output_height}:"
+            "force_original_aspect_ratio=increase,"
+            f"crop={self.settings.output_width}:{self.settings.output_height},"
+            f"fps={self.settings.output_fps},format=yuv420p"
+        )
+        cmd = (
+            FFmpegCommand()
+            .add("-hide_banner")
+            .input(path)
+            .add("-vf", vf, "-c:v", "libx264", "-preset", self.settings.preset, "-crf", self.settings.crf)
+            .add("-c:a", "aac", "-b:a", "128k", "-movflags", "+faststart")
+        )
+        if duration:
+            cmd.add("-t", duration)
+        command = cmd.overwrite().add(output).build()
+        self.runner.run(command)
+        return output
+
+    def image_to_video(self, path: str | Path, output: Path, duration: float) -> Path:
+        vf = (
+            f"scale={self.settings.output_width}:{self.settings.output_height}:"
+            "force_original_aspect_ratio=increase,"
+            f"crop={self.settings.output_width}:{self.settings.output_height},"
+            f"fps={self.settings.output_fps},format=yuv420p"
+        )
+        command = (
+            FFmpegCommand()
+            .add("-hide_banner", "-loop", "1", "-t", duration)
+            .input(path)
+            .add("-vf", vf, "-an", "-c:v", "libx264", "-preset", self.settings.preset, "-crf", self.settings.crf)
+            .overwrite()
+            .add(output)
+            .build()
+        )
+        self.runner.run(command)
+        return output

renderer/ffmpeg/runner.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+try:
+    import psutil
+except Exception:  # pragma: no cover - optional runtime dependency fallback
+    psutil = None
+
+
+class FFmpegError(RuntimeError):
+    def __init__(self, message: str, command: list[str], stderr: str = "") -> None:
+        super().__init__(message)
+        self.command = command
+        self.stderr = stderr
+
+
+@dataclass
+class CommandResult:
+    command: list[str]
+    returncode: int
+    duration_seconds: float
+    stdout: str = ""
+    stderr: str = ""
+    metrics: dict[str, float | int] = field(default_factory=dict)
+
+
+class FFmpegRunner:
+    def __init__(
+        self,
+        timeout_seconds: int = 900,
+        log: Callable[[str], None] | None = None,
+        on_command: Callable[[list[str]], None] | None = None,
+    ) -> None:
+        self.timeout_seconds = timeout_seconds
+        self.log = log or (lambda _: None)
+        self.on_command = on_command or (lambda _: None)
+
+    def run(self, command: list[str], cwd: Path | None = None) -> CommandResult:
+        started = time.time()
+        self.on_command(command)
+        self.log("$ " + " ".join(command))
+        process = subprocess.Popen(
+            command,
+            cwd=str(cwd) if cwd else None,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        peak_rss = 0
+        cpu_percent = 0.0
+        proc = psutil.Process(process.pid) if psutil else None
+        try:
+            stdout, stderr = process.communicate(timeout=self.timeout_seconds)
+            if proc:
+                try:
+                    peak_rss = max(peak_rss, proc.memory_info().rss)
+                    cpu_percent = proc.cpu_percent(interval=None)
+                except Exception:
+                    pass
+        except subprocess.TimeoutExpired as exc:
+            self._kill_process(process)
+            stdout, stderr = process.communicate()
+            raise FFmpegError(f"FFmpeg timed out after {self.timeout_seconds}s", command, stderr) from exc
+
+        duration = time.time() - started
+        result = CommandResult(
+            command=command,
+            returncode=process.returncode,
+            duration_seconds=duration,
+            stdout=stdout,
+            stderr=stderr,
+            metrics={"duration_seconds": duration, "peak_rss_bytes": peak_rss, "cpu_percent": cpu_percent},
+        )
+        if process.returncode != 0:
+            raise FFmpegError("FFmpeg failed", command, stderr)
+        return result
+
+    @staticmethod
+    def _kill_process(process: subprocess.Popen[str]) -> None:
+        if psutil:
+            try:
+                parent = psutil.Process(process.pid)
+                for child in parent.children(recursive=True):
+                    child.kill()
+                parent.kill()
+                return
+            except Exception:
+                pass
+        process.kill()

renderer/jobs/__init__.py

@@ -0,0 +1,3 @@
+from renderer.jobs.manager import JobManager
+
+__all__ = ["JobManager"]

renderer/jobs/manager.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import concurrent.futures
+import threading
+from dataclasses import asdict
+from pathlib import Path
+from typing import Callable
+
+from renderer.core.config import Settings
+from renderer.core.models import AIReelsRequest, JobRecord, RenderRequest
+from renderer.core.render_engine import RenderEngine
+from renderer.core.utils import new_id, now, read_json, write_json
+
+
+class JobManager:
+    def __init__(self, settings: Settings | None = None) -> None:
+        self.settings = settings or Settings()
+        self.settings.ensure_dirs()
+        self.executor = concurrent.futures.ThreadPoolExecutor(max_workers=self.settings.max_workers)
+        self.lock = threading.Lock()
+
+    def submit_render(self, request: RenderRequest) -> str:
+        return self._submit(lambda job_id, log: RenderEngine(self.settings, log=log).render(request, job_id))
+
+    def submit_ai_reels(self, request: AIReelsRequest) -> str:
+        return self._submit(lambda job_id, log: RenderEngine(self.settings, log=log).ai_reels(request, job_id))
+
+    def submit_batch(self, requests: list[RenderRequest]) -> list[str]:
+        job_ids: list[str] = []
+        for request in requests:
+            job_ids.append(self.submit_render(request))
+        return job_ids
+
+    def get(self, job_id: str) -> JobRecord:
+        data = read_json(self._record_path(job_id), None)
+        if data is None:
+            raise KeyError(job_id)
+        return JobRecord(**data)
+
+    def _submit(self, handler: Callable[[str, Callable[[str], None]], object]) -> str:
+        job_id = new_id()
+        record = JobRecord(job_id=job_id, state="PENDING", created_at=now(), updated_at=now())
+        self._save(record)
+        self.executor.submit(self._run_with_retries, job_id, handler)
+        return job_id
+
+    def _run_with_retries(self, job_id: str, handler: Callable[[str, Callable[[str], None]], object]) -> None:
+        attempts = 0
+        while attempts < self.settings.max_retries:
+            attempts += 1
+            self._update(job_id, state="RUNNING", metrics={"attempt": attempts})
+            try:
+                result = handler(job_id, lambda message: self.append_log(job_id, message))
+                self._update(
+                    job_id,
+                    state="COMPLETED",
+                    output_path=str(result.output_path),
+                    commands=result.commands,
+                    logs=result.logs,
+                    metrics=result.metrics | {"attempt": attempts},
+                )
+                return
+            except Exception as exc:
+                self.append_log(job_id, f"Attempt {attempts} failed: {exc}")
+                if attempts >= self.settings.max_retries:
+                    self._update(job_id, state="FAILED", failure_reason=str(exc), metrics={"attempt": attempts})
+
+    def append_log(self, job_id: str, message: str) -> None:
+        with self.lock:
+            record = self.get(job_id)
+            record.logs.append(message)
+            record.updated_at = now()
+            self._save(record)
+
+    def _update(self, job_id: str, **changes) -> None:
+        with self.lock:
+            record = self.get(job_id)
+            for key, value in changes.items():
+                if key == "metrics" and record.metrics and isinstance(value, dict):
+                    record.metrics.update(value)
+                else:
+                    setattr(record, key, value)
+            record.updated_at = now()
+            self._save(record)
+
+    def _record_path(self, job_id: str) -> Path:
+        return self.settings.jobs_dir / f"{job_id}.json"
+
+    def _save(self, record: JobRecord) -> None:
+        write_json(self._record_path(record.job_id), asdict(record))

renderer/scenes/__init__.py

@@ -0,0 +1,3 @@
+from renderer.scenes.timeline import Timeline
+
+__all__ = ["Timeline"]

renderer/scenes/timeline.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from renderer.core.models import RenderRequest, Scene
+
+
+class Timeline:
+    def __init__(self, scenes: list[Scene]) -> None:
+        self.scenes = sorted(scenes, key=lambda scene: scene.start)
+        self.validate()
+
+    @classmethod
+    def from_payload(cls, payload: dict) -> "Timeline":
+        return cls([Scene(**scene) for scene in payload.get("scenes", [])])
+
+    @classmethod
+    def request_from_payload(cls, payload: dict) -> RenderRequest:
+        scenes = [Scene(**scene) for scene in payload.get("scenes", [])]
+        return RenderRequest(
+            scenes=scenes,
+            template=payload.get("template", "tiktok_classic"),
+            output_name=payload.get("output_name", "render.mp4"),
+            voiceover=payload.get("voiceover"),
+            background_music=payload.get("background_music"),
+            subtitle_format=payload.get("subtitle_format", "ass"),
+            normalize=payload.get("normalize", True),
+            metadata=payload.get("metadata", {}),
+        )
+
+    @property
+    def total_duration(self) -> float:
+        return max((scene.start + scene.duration for scene in self.scenes), default=0.0)
+
+    def validate(self) -> None:
+        if not self.scenes:
+            raise ValueError("At least one scene is required")
+        for scene in self.scenes:
+            if scene.duration <= 0:
+                raise ValueError("Scene duration must be greater than zero")
+            if scene.start < 0:
+                raise ValueError("Scene start must be non-negative")
+            if not scene.media:
+                raise ValueError("Scene media path is required")

renderer/subtitles/__init__.py

@@ -0,0 +1,3 @@
+from renderer.subtitles.generator import SubtitleEvent, SubtitleGenerator
+
+__all__ = ["SubtitleEvent", "SubtitleGenerator"]

renderer/subtitles/generator.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+from pathlib import Path
+
+from renderer.templates import get_template
+
+
+@dataclass
+class SubtitleEvent:
+    start: float
+    end: float
+    text: str
+
+
+class SubtitleGenerator:
+    def from_scenes(self, scenes: list, total_duration: float | None = None) -> list[SubtitleEvent]:
+        events: list[SubtitleEvent] = []
+        for scene in scenes:
+            if scene.caption:
+                events.append(SubtitleEvent(scene.start, scene.start + scene.duration, scene.caption))
+        if not events and total_duration:
+            events.append(SubtitleEvent(0, total_duration, ""))
+        return events
+
+    def write_srt(self, events: list[SubtitleEvent], output: Path) -> Path:
+        lines: list[str] = []
+        for idx, event in enumerate(events, start=1):
+            lines.extend([str(idx), f"{_srt_time(event.start)} --> {_srt_time(event.end)}", event.text, ""])
+        output.write_text("\n".join(lines), encoding="utf-8")
+        return output
+
+    def write_ass(self, events: list[SubtitleEvent], output: Path, template_key: str) -> Path:
+        template = get_template(template_key)
+        body = [
+            "[Script Info]",
+            "ScriptType: v4.00+",
+            "PlayResX: 1080",
+            "PlayResY: 1920",
+            "",
+            "[V4+ Styles]",
+            "Format: Name,Fontname,Fontsize,PrimaryColour,SecondaryColour,OutlineColour,BackColour,"
+            "Bold,Italic,Underline,StrikeOut,ScaleX,ScaleY,Spacing,Angle,BorderStyle,Outline,Shadow,"
+            "Alignment,MarginL,MarginR,MarginV,Encoding",
+            template.ass_style(),
+            "",
+            "[Events]",
+            "Format: Layer,Start,End,Style,Name,MarginL,MarginR,MarginV,Effect,Text",
+        ]
+        for event in events:
+            text = _ass_escape(event.text)
+            if template.effect == "karaoke":
+                text = _karaoke_text(text, event.end - event.start)
+            elif template.effect == "zoom":
+                text = r"{\t(0,180,\fscx115\fscy115)\t(180,360,\fscx100\fscy100)}" + text
+            elif template.effect == "bounce":
+                text = r"{\t(0,120,\frz-2)\t(120,240,\frz2)\t(240,360,\frz0)}" + text
+            body.append(f"Dialogue: 0,{_ass_time(event.start)},{_ass_time(event.end)},Default,,0,0,0,,{text}")
+        output.write_text("\n".join(body), encoding="utf-8")
+        return output
+
+
+def _karaoke_text(text: str, duration: float) -> str:
+    words = text.split()
+    if not words:
+        return text
+    centiseconds = max(1, int(duration * 100 / len(words)))
+    return "".join(f"{{\\k{centiseconds}}}{word} " for word in words).strip()
+
+
+def _srt_time(seconds: float) -> str:
+    ms = int(round(seconds * 1000))
+    h, rem = divmod(ms, 3600000)
+    m, rem = divmod(rem, 60000)
+    s, ms = divmod(rem, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def _ass_time(seconds: float) -> str:
+    cs = int(round(seconds * 100))
+    h, rem = divmod(cs, 360000)
+    m, rem = divmod(rem, 6000)
+    s, cs = divmod(rem, 100)
+    return f"{h}:{m:02d}:{s:02d}.{cs:02d}"
+
+
+def _ass_escape(text: str) -> str:
+    return html.escape(text).replace("\n", r"\N").replace("{", r"\{").replace("}", r"\}")

renderer/templates/__init__.py

@@ -0,0 +1,3 @@
+from renderer.templates.caption_templates import CaptionTemplate, get_template, list_templates
+
+__all__ = ["CaptionTemplate", "get_template", "list_templates"]

renderer/templates/caption_templates.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CaptionTemplate:
+    key: str
+    label: str
+    font_size: int
+    primary_color: str
+    secondary_color: str
+    outline_color: str = "&H000000"
+    back_color: str = "&H80000000"
+    alignment: int = 2
+    margin_v: int = 180
+    bold: bool = True
+    effect: str = "none"
+
+    def ass_style(self) -> str:
+        bold = -1 if self.bold else 0
+        return (
+            "Style: Default,DejaVu Sans,"
+            f"{self.font_size},{self.primary_color},{self.secondary_color},"
+            f"{self.outline_color},{self.back_color},{bold},0,0,0,100,100,0,0,3,3,1,"
+            f"{self.alignment},80,80,{self.margin_v},1"
+        )
+
+
+TEMPLATES: dict[str, CaptionTemplate] = {
+    "tiktok_classic": CaptionTemplate("tiktok_classic", "TikTok Classic", 64, "&H00FFFFFF", "&H0000FFFF", effect="karaoke"),
+    "tiktok_zoom": CaptionTemplate("tiktok_zoom", "TikTok Zoom", 72, "&H00FFFFFF", "&H0000E5FF", effect="zoom"),
+    "alex_hormozi": CaptionTemplate("alex_hormozi", "Alex Hormozi", 70, "&H0000FFFF", "&H00FFFFFF", effect="bounce"),
+    "modern_minimal": CaptionTemplate("modern_minimal", "Modern Minimal", 52, "&H00FFFFFF", "&H00DDDDDD", margin_v=240),
+    "youtube_shorts": CaptionTemplate("youtube_shorts", "YouTube Shorts", 62, "&H00FFFFFF", "&H000000FF", effect="karaoke"),
+    "podcast_style": CaptionTemplate("podcast_style", "Podcast Style", 48, "&H00F5F5F5", "&H0099CCFF", margin_v=120),
+    "news_style": CaptionTemplate("news_style", "News Style", 46, "&H00FFFFFF", "&H0000FFFF", alignment=2, margin_v=100),
+}
+
+
+def get_template(key: str) -> CaptionTemplate:
+    return TEMPLATES.get(key, TEMPLATES["tiktok_classic"])
+
+
+def list_templates() -> list[str]:
+    return list(TEMPLATES.keys())

renderer/transitions/__init__.py

@@ -0,0 +1,3 @@
+from renderer.transitions.builder import TransitionBuilder
+
+__all__ = ["TransitionBuilder"]

renderer/transitions/builder.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+
+class TransitionBuilder:
+    """Build FFmpeg xfade filters for scene joins."""
+
+    TRANSITIONS = {
+        "fade": "fade",
+        "zoom": "zoomin",
+        "slide": "slideleft",
+        "push": "slideup",
+        "blur": "fade",
+        "whip": "smoothleft",
+        "dissolve": "dissolve",
+    }
+
+    def map_transition(self, name: str) -> str:
+        return self.TRANSITIONS.get(name, "fade")
+
+    def xfade_chain(self, stream_count: int, durations: list[float], transitions: list[str], transition_duration: float = 0.45) -> tuple[str, str]:
+        if stream_count <= 1:
+            return "", "[0:v]"
+        filters: list[str] = []
+        current = "[0:v]"
+        offset = max(0.1, durations[0] - transition_duration)
+        for idx in range(1, stream_count):
+            out = f"[vx{idx}]"
+            transition = self.map_transition(transitions[idx - 1] if idx - 1 < len(transitions) else "fade")
+            filters.append(
+                f"{current}[{idx}:v]xfade=transition={transition}:duration={transition_duration}:offset={offset:.3f}{out}"
+            )
+            current = out
+            if idx < len(durations):
+                offset += max(0.1, durations[idx] - transition_duration)
+        return ";".join(filters), current