Upload 205 files

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+services/ktts/assets/edu_note.wav filter=lfs diff=lfs merge=lfs -text
+services/ktts/assets/fun_fact.wav filter=lfs diff=lfs merge=lfs -text
+services/ktts/assets/thanks.wav filter=lfs diff=lfs merge=lfs -text
+services/ktts/gradio_demo.png filter=lfs diff=lfs merge=lfs -text

services/ffmpeg_automation/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

services/ffmpeg_automation/Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.10-slim
+
+# Install system binaries and fonts
+RUN apt-get update && apt-get install -y \
+    ffmpeg \
+    wget \
+    libmagic1 \
+    fonts-dejavu-core \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Create temp dir and set permissions for HF user
+RUN mkdir -p /app/temp && chmod 777 /app/temp
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -U yt-dlp && \
+    pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Set permissions for the entire app dir to avoid runtime write issues
+RUN chmod -R 777 /app
+
+ENV PYTHONUNBUFFERED=1
+ENV TEMP_DIR=/app/temp
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

services/ffmpeg_automation/README.md

@@ -0,0 +1,217 @@
+---
+title: Ffmpeg
+emoji: 👀
+colorFrom: green
+colorTo: yellow
+sdk: docker
+pinned: false
+license: mit
+---
+
+# Basyx FFmpeg Automation Hub
+
+FastAPI + Gradio app for common FFmpeg media tasks. It can run directly in
+Docker/Hugging Face Spaces and exposes both a browser UI and HTTP API.
+
+## Features
+
+- Task-specific Gradio controls for video, audio, subtitle, image, and social presets.
+- File and URL inputs, including `yt-dlp` downloads.
+- Input validation with `python-magic`, upload size limits, and temp-file cleanup.
+- Synchronous execution at `/execute/{task_id}`.
+- Background jobs at `/jobs/{task_id}` with `/status/{job_id}` and `/download/{job_id}`.
+- Recent output history at `/history` with per-item download URLs.
+- Configurable FFmpeg options: CRF, preset, resolution, audio bitrate, trim times,
+  aspect ratio, GIF settings, watermark settings, speed, frame rate, and text styling.
+- Persistent SQLite job/history state.
+- FFmpeg execution timeout, production readiness checks, and URL download limits.
+- Faceless short-video automation for quote cards, story slides, image narration,
+  b-roll narration, and vertical montage generation.
+- TikTok/Reels mini-series packaging with numbered episodes, recap cards, and
+  ZIP exports containing publish-order manifests.
+
+## Tasks
+
+Call `GET /tasks` to list the current task registry with file requirements.
+
+Current tasks:
+
+- `normalize`
+- `extract_audio`
+- `resize_916`
+- `add_subtitles`
+- `burn_lyrics`
+- `text_overlay`
+- `merge_music`
+- `thumbnail`
+- `watermark`
+- `compress`
+- `batch_compress`
+- `make_gif`
+- `tiktok_lyrics`
+- `tiktok_pro_reframer`
+- `reels_blur_fit`
+- `reels_safe_caption`
+- `reels_hook_title`
+- `reels_progress_bar`
+- `reels_loop`
+- `reels_subtitle_safe`
+- `reels_reaction_stack`
+- `reels_audio_duck`
+- `faceless_quote_card`
+- `faceless_story_pages`
+- `faceless_image_narration`
+- `faceless_video_narration`
+- `faceless_broll_montage`
+- `series_split_pack`
+- `series_episode_badge`
+- `series_batch_pack`
+- `series_recap_card`
+- `concat`
+- `slideshow`
+- `trim`
+- `crop_aspect`
+- `waveform`
+- `extract_frames`
+- `add_intro_outro`
+- `speed`
+- `remove_audio`
+- `replace_audio`
+
+## API Examples
+
+Run a task immediately and download the returned file:
+
+```bash
+curl -X POST \
+  -F "files=@input.mp4" \
+  -F "resolution=720p" \
+  -F "crf=28" \
+  http://localhost:7860/execute/compress \
+  --output compressed.mp4
+```
+
+Run a background job:
+
+```bash
+curl -X POST \
+  -F "files=@input.mp4" \
+  -F "text=Launch caption" \
+  http://localhost:7860/jobs/text_overlay
+```
+
+Check the job:
+
+```bash
+curl http://localhost:7860/status/<job_id>
+```
+
+Download a completed background job:
+
+```bash
+curl http://localhost:7860/download/<job_id> --output result.mp4
+```
+
+Use a URL input:
+
+```bash
+curl -X POST \
+  -F "url=https://example.com/video.mp4" \
+  http://localhost:7860/execute/thumbnail \
+  --output thumbnail.jpg
+```
+
+## n8n Inputs
+
+Use `POST /n8n/execute/{task_id}` for immediate file output or
+`POST /n8n/jobs/{task_id}` for background jobs. These endpoints accept common
+n8n HTTP Request node payload styles:
+
+- multipart form-data with any binary field name
+- form-data URL fields: `url`, `urls`, `file_url`, `source_url`, `download_url`
+- JSON base64 files in `files`, `binary`, or `data`
+- JSON URL lists
+- raw binary body for single-file tasks, with optional `X-Filename` header
+
+Multipart binary from n8n:
+
+```bash
+curl -X POST \
+  -F "myBinary=@input.mp4" \
+  -F "text=Episode 1" \
+  http://localhost:7860/n8n/execute/series_episode_badge \
+  --output episode.mp4
+```
+
+JSON base64:
+
+```json
+{
+  "text": "Episode title",
+  "files": [
+    {
+      "fileName": "input.mp4",
+      "mimeType": "video/mp4",
+      "data": "<base64>"
+    }
+  ]
+}
+```
+
+JSON URLs:
+
+```json
+{
+  "urls": ["https://example.com/input.mp4"],
+  "text": "Mini series title",
+  "duration": "60"
+}
+```
+
+Raw binary:
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/octet-stream" \
+  -H "X-Filename: input.mp4" \
+  --data-binary @input.mp4 \
+  http://localhost:7860/n8n/execute/reels_blur_fit \
+  --output output.mp4
+```
+
+## Configuration
+
+Environment variables:
+
+- `TEMP_DIR`: working directory for uploads and outputs. Default: `temp`.
+- `STATE_DB_PATH`: SQLite path for job/history state. Default: `TEMP_DIR/state.sqlite3`.
+- `FONT_PATH`: font used by FFmpeg `drawtext`. Default:
+  `/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf`.
+- `MAX_UPLOAD_MB`: max upload size per file. Default: `500`.
+- `MAX_URL_DOWNLOAD_MB`: max URL download size. Default: same as `MAX_UPLOAD_MB`.
+- `ALLOW_URL_INPUTS`: enable/disable URL downloads. Default: `true`.
+- `FFMPEG_TIMEOUT_SECONDS`: max runtime for an FFmpeg command. Default: `1800`.
+- `FILE_TTL_SECONDS`: temp file lifetime. Default: `3600`.
+- `HISTORY_LIMIT`: number of recent output records to keep. Default: `50`.
+
+## Production Checks
+
+- `GET /healthz`: process health and dependency check details.
+- `GET /readyz`: returns `503` if required runtime dependencies are missing.
+
+Required runtime dependencies:
+
+- `ffmpeg`
+- `ffprobe`
+- writable `TEMP_DIR`
+- writable SQLite state database
+- readable `FONT_PATH`
+
+## Local Run
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+The app listens on `http://localhost:7860`.

services/ffmpeg_automation/app.py

@@ -0,0 +1,2215 @@
+import base64
+import binascii
+import os
+import shutil
+import sqlite3
+import subprocess
+import textwrap
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Optional
+
+import gradio as gr
+import magic
+import uvicorn
+import yt_dlp
+from fastapi import BackgroundTasks, FastAPI, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import FileResponse
+
+app = FastAPI(title="Basyx FFmpeg Automation Hub")
+
+TEMP_DIR = os.getenv("TEMP_DIR", "temp")
+FONT_PATH = os.getenv(
+    "FONT_PATH", "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf"
+)
+MAX_UPLOAD_MB = int(os.getenv("MAX_UPLOAD_MB", "500"))
+MAX_UPLOAD_BYTES = MAX_UPLOAD_MB * 1024 * 1024
+FILE_TTL_SECONDS = int(os.getenv("FILE_TTL_SECONDS", "3600"))
+HISTORY_LIMIT = int(os.getenv("HISTORY_LIMIT", "50"))
+FFMPEG_TIMEOUT_SECONDS = int(os.getenv("FFMPEG_TIMEOUT_SECONDS", "1800"))
+MAX_URL_DOWNLOAD_MB = int(os.getenv("MAX_URL_DOWNLOAD_MB", str(MAX_UPLOAD_MB)))
+MAX_URL_DOWNLOAD_BYTES = MAX_URL_DOWNLOAD_MB * 1024 * 1024
+ALLOW_URL_INPUTS = os.getenv("ALLOW_URL_INPUTS", "true").lower() in {"1", "true", "yes"}
+STATE_DB_PATH = os.getenv("STATE_DB_PATH", os.path.join(TEMP_DIR, "state.sqlite3"))
+OPTION_FIELDS = [
+    "text",
+    "start_time",
+    "end_time",
+    "duration",
+    "aspect_ratio",
+    "resolution",
+    "crf",
+    "preset",
+    "audio_bitrate",
+    "volume",
+    "position",
+    "opacity",
+    "fps",
+    "width",
+    "speed",
+    "timestamp",
+    "image_duration",
+    "frame_rate",
+    "font_size",
+    "wave_color",
+]
+
+os.makedirs(TEMP_DIR, exist_ok=True)
+
+
+@dataclass(frozen=True)
+class TaskDefinition:
+    label: str
+    description: str
+    category: str
+    output_ext: str
+    min_files: int
+    max_files: Optional[int]
+    accepted_types: List[str]
+    builder: Optional[Callable[[List[str], Dict[str, str], str], List[str]]] = None
+    runner: Optional[Callable[[List[str], Dict[str, str], str], str]] = None
+    file_types: Optional[List[List[str]]] = None
+
+
+JOBS: Dict[str, Dict[str, object]] = {}
+HISTORY: List[Dict[str, object]] = []
+STATE_LOCK = threading.Lock()
+
+
+def db_connect():
+    connection = sqlite3.connect(STATE_DB_PATH, timeout=30)
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+def init_state_store() -> None:
+    with db_connect() as connection:
+        connection.execute(
+            """
+            CREATE TABLE IF NOT EXISTS jobs (
+                job_id TEXT PRIMARY KEY,
+                task_id TEXT NOT NULL,
+                status TEXT NOT NULL,
+                message TEXT NOT NULL,
+                output TEXT,
+                created_at INTEGER NOT NULL,
+                updated_at INTEGER NOT NULL
+            )
+            """
+        )
+        connection.execute(
+            """
+            CREATE TABLE IF NOT EXISTS history (
+                history_id TEXT PRIMARY KEY,
+                job_id TEXT NOT NULL,
+                task_id TEXT NOT NULL,
+                task TEXT NOT NULL,
+                output TEXT NOT NULL,
+                filename TEXT NOT NULL,
+                size INTEGER NOT NULL,
+                created_at INTEGER NOT NULL
+            )
+            """
+        )
+        connection.execute(
+            "CREATE INDEX IF NOT EXISTS idx_history_created_at ON history(created_at DESC)"
+        )
+
+
+def load_state_store() -> None:
+    with STATE_LOCK, db_connect() as connection:
+        JOBS.clear()
+        for row in connection.execute("SELECT * FROM jobs ORDER BY created_at DESC"):
+            JOBS[row["job_id"]] = dict(row)
+        HISTORY.clear()
+        for row in connection.execute(
+            "SELECT * FROM history ORDER BY created_at DESC LIMIT ?", (HISTORY_LIMIT,)
+        ):
+            item = dict(row)
+            item["download_url"] = f"/history/{item['history_id']}/download"
+            HISTORY.append(item)
+
+
+def persist_job(job: Dict[str, object]) -> None:
+    now = int(time.time())
+    with db_connect() as connection:
+        connection.execute(
+            """
+            INSERT INTO jobs (job_id, task_id, status, message, output, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(job_id) DO UPDATE SET
+                status=excluded.status,
+                message=excluded.message,
+                output=excluded.output,
+                updated_at=excluded.updated_at
+            """,
+            (
+                str(job["job_id"]),
+                str(job["task_id"]),
+                str(job["status"]),
+                str(job["message"]),
+                str(job.get("output") or ""),
+                int(job.get("created_at") or now),
+                now,
+            ),
+        )
+
+
+def persist_history(item: Dict[str, object]) -> None:
+    with db_connect() as connection:
+        connection.execute(
+            """
+            INSERT OR REPLACE INTO history
+            (history_id, job_id, task_id, task, output, filename, size, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                str(item["history_id"]),
+                str(item["job_id"]),
+                str(item["task_id"]),
+                str(item["task"]),
+                str(item["output"]),
+                str(item["filename"]),
+                int(item["size"]),
+                int(item["created_at"]),
+            ),
+        )
+        stale_ids = [
+            row["history_id"]
+            for row in connection.execute(
+                """
+                SELECT history_id FROM history
+                ORDER BY created_at DESC
+                LIMIT -1 OFFSET ?
+                """,
+                (HISTORY_LIMIT,),
+            )
+        ]
+        if stale_ids:
+            connection.executemany(
+                "DELETE FROM history WHERE history_id = ?",
+                [(history_id,) for history_id in stale_ids],
+            )
+
+
+init_state_store()
+load_state_store()
+
+
+def ffmpeg_escape(value: str) -> str:
+    return (
+        value.replace("\\", "\\\\")
+        .replace(":", "\\:")
+        .replace("'", "\\'")
+        .replace("\n", "\\n")
+        .replace("%", "\\%")
+    )
+
+
+def filter_path(path: str) -> str:
+    return ffmpeg_escape(os.path.abspath(path))
+
+
+def ffconcat_path(path: str) -> str:
+    return os.path.abspath(path).replace("\\", "\\\\").replace("'", "\\'")
+
+
+def drawtext_file_path(path: str) -> str:
+    return filter_path(path)
+
+
+def remove_file_quietly(path: str) -> None:
+    try:
+        os.remove(path)
+    except FileNotFoundError:
+        return
+    except OSError:
+        return
+
+
+def clamp_int(value: str, default: int, minimum: int, maximum: int) -> int:
+    try:
+        parsed = int(float(value))
+    except (TypeError, ValueError):
+        parsed = default
+    return max(minimum, min(maximum, parsed))
+
+
+def clamp_float(value: str, default: float, minimum: float, maximum: float) -> float:
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError):
+        parsed = default
+    return max(minimum, min(maximum, parsed))
+
+
+def dimensions(preset: str) -> tuple[int, int]:
+    presets = {
+        "9:16": (1080, 1920),
+        "16:9": (1920, 1080),
+        "1:1": (1080, 1080),
+        "4:5": (1080, 1350),
+    }
+    return presets.get(preset, presets["9:16"])
+
+
+def scaled_crop_filter(preset: str) -> str:
+    width, height = dimensions(preset)
+    return (
+        f"scale={width}:{height}:force_original_aspect_ratio=increase,"
+        f"crop={width}:{height}"
+    )
+
+
+def output_scale_filter(size: str) -> str:
+    sizes = {"480p": 480, "720p": 720, "1080p": 1080}
+    height = sizes.get(size, 720)
+    return f"scale=-2:{height}"
+
+
+def write_wrapped_text_file(text: str, width: int = 24, max_lines: Optional[int] = None) -> str:
+    cleaned = " ".join((text or "").split())
+    if not cleaned:
+        cleaned = "Your faceless video"
+    lines = textwrap.wrap(cleaned, width=width, break_long_words=False)
+    if max_lines:
+        lines = lines[:max_lines]
+    path = os.path.abspath(os.path.join(TEMP_DIR, f"text_{uuid.uuid4().hex[:8]}.txt"))
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write("\n".join(lines))
+    return path
+
+
+def split_story_pages(text: str, words_per_page: int = 22) -> List[str]:
+    words = (text or "").split()
+    if not words:
+        words = ["Add", "story", "text", "to", "generate", "faceless", "video", "slides."]
+    pages = [
+        " ".join(words[index : index + words_per_page])
+        for index in range(0, len(words), words_per_page)
+    ]
+    return pages[:20]
+
+
+def production_checks() -> Dict[str, Dict[str, object]]:
+    checks = {
+        "ffmpeg": {"ok": shutil.which("ffmpeg") is not None},
+        "ffprobe": {"ok": shutil.which("ffprobe") is not None},
+        "font": {"ok": os.path.exists(FONT_PATH), "path": FONT_PATH},
+        "temp_dir": {
+            "ok": os.path.isdir(TEMP_DIR) and os.access(TEMP_DIR, os.W_OK),
+            "path": TEMP_DIR,
+        },
+        "state_db": {
+            "ok": os.path.exists(STATE_DB_PATH) and os.access(STATE_DB_PATH, os.W_OK),
+            "path": STATE_DB_PATH,
+        },
+    }
+    checks["url_inputs"] = {"ok": True, "enabled": ALLOW_URL_INPUTS}
+    return checks
+
+
+def production_ready() -> bool:
+    required = ["ffmpeg", "ffprobe", "font", "temp_dir", "state_db"]
+    checks = production_checks()
+    return all(bool(checks[name]["ok"]) for name in required)
+
+
+def add_video_quality(cmd: List[str], opts: Dict[str, str]) -> List[str]:
+    crf = str(clamp_int(opts.get("crf", "23"), 23, 12, 35))
+    preset = opts.get("preset") or "fast"
+    if preset not in {"ultrafast", "veryfast", "fast", "medium", "slow"}:
+        preset = "fast"
+    return cmd + ["-c:v", "libx264", "-preset", preset, "-crf", crf, "-c:a", "aac"]
+
+
+def run_command(cmd: List[str]) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(
+            cmd,
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=FFMPEG_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise HTTPException(
+            status_code=504,
+            detail=f"FFmpeg timed out after {FFMPEG_TIMEOUT_SECONDS} seconds.",
+        ) from exc
+
+
+def media_duration_seconds(path: str) -> float:
+    result = run_command(
+        [
+            "ffprobe",
+            "-v",
+            "error",
+            "-show_entries",
+            "format=duration",
+            "-of",
+            "default=noprint_wrappers=1:nokey=1",
+            path,
+        ]
+    )
+    try:
+        duration = float(result.stdout.strip())
+    except ValueError as exc:
+        raise HTTPException(status_code=500, detail="Could not read media duration.") from exc
+    if duration <= 0:
+        raise HTTPException(status_code=500, detail="Media duration is not usable.")
+    return duration
+
+
+def build_normalize(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    cmd = ["ffmpeg", "-i", paths[0]]
+    return add_video_quality(cmd, opts) + ["-y", out]
+
+
+def build_extract_audio(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    bitrate = str(clamp_int(opts.get("audio_bitrate", "192"), 192, 64, 320))
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-vn",
+        "-acodec",
+        "libmp3lame",
+        "-ar",
+        "44100",
+        "-ac",
+        "2",
+        "-b:a",
+        f"{bitrate}k",
+        "-y",
+        out,
+    ]
+
+
+def build_resize(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    vf = scaled_crop_filter(opts.get("aspect_ratio", "9:16"))
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_subtitles(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    subtitle_filter = f"subtitles='{filter_path(paths[1])}'"
+    return ["ffmpeg", "-i", paths[0], "-vf", subtitle_filter, "-c:a", "copy", "-y", out]
+
+
+def build_burn_lyrics(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    style = (
+        "Fontname=DejaVu Sans,Fontsize=24,PrimaryColour=&H00FFFF,"
+        "OutlineColour=&H000000,BorderStyle=3,Outline=1,Shadow=1,Alignment=2"
+    )
+    vf = f"subtitles='{filter_path(paths[1])}':force_style='{style}'"
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_text_overlay(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    text = ffmpeg_escape(opts.get("text", ""))
+    font_size = clamp_int(opts.get("font_size", "60"), 60, 18, 160)
+    vf = (
+        f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{text}':"
+        f"fontcolor=white:fontsize={font_size}:box=1:boxcolor=black@0.45:"
+        "boxborderw=16:x=(w-text_w)/2:y=h-200"
+    )
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_merge_music(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    volume = clamp_float(opts.get("volume", "0.3"), 0.3, 0.0, 2.0)
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-i",
+        paths[1],
+        "-filter_complex",
+        f"[1:a]volume={volume}[a1]",
+        "-map",
+        "0:v",
+        "-map",
+        "[a1]",
+        "-c:v",
+        "copy",
+        "-shortest",
+        "-y",
+        out,
+    ]
+
+
+def build_thumbnail(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    timestamp = opts.get("timestamp") or "00:00:02"
+    return ["ffmpeg", "-i", paths[0], "-ss", timestamp, "-vframes", "1", "-y", out]
+
+
+def build_watermark(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    positions = {
+        "bottom-right": "W-w-20:H-h-20",
+        "bottom-left": "20:H-h-20",
+        "top-right": "W-w-20:20",
+        "top-left": "20:20",
+        "center": "(W-w)/2:(H-h)/2",
+    }
+    position = positions.get(opts.get("position"), positions["bottom-right"])
+    opacity = clamp_float(opts.get("opacity", "1"), 1, 0.1, 1.0)
+    overlay = f"[1:v]format=rgba,colorchannelmixer=aa={opacity}[wm];[0:v][wm]overlay={position}"
+    return ["ffmpeg", "-i", paths[0], "-i", paths[1], "-filter_complex", overlay, "-y", out]
+
+
+def build_compress(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    vf = output_scale_filter(opts.get("resolution", "720p"))
+    cmd = ["ffmpeg", "-i", paths[0], "-vf", vf]
+    return add_video_quality(cmd, opts) + ["-y", out]
+
+
+def build_gif(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    duration = str(clamp_int(opts.get("duration", "5"), 5, 1, 60))
+    fps = str(clamp_int(opts.get("fps", "10"), 10, 5, 30))
+    width = str(clamp_int(opts.get("width", "480"), 480, 240, 1080))
+    vf = f"fps={fps},scale={width}:-1:flags=lanczos"
+    return ["ffmpeg", "-i", paths[0], "-t", duration, "-vf", vf, "-y", out]
+
+
+def build_tiktok_lyrics(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    text = ffmpeg_escape(opts.get("text", ""))
+    duration = str(clamp_int(opts.get("duration", "15"), 15, 1, 180))
+    vf = (
+        scaled_crop_filter("9:16")
+        + ","
+        + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{text}':"
+        "fontcolor=white:fontsize=50:box=1:boxcolor=black@0.5:"
+        "boxborderw=20:line_spacing=15:x=(w-text_w)/2:y=(h-text_h)/2"
+    )
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-t", duration, "-y", out]
+
+
+def build_tiktok_pro(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    text = ffmpeg_escape(opts.get("text", ""))
+    vf = (
+        scaled_crop_filter("9:16")
+        + ","
+        + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{text}':"
+        "fontcolor=white:fontsize=48:box=1:boxcolor=black@0.4:"
+        "boxborderw=14:x=(w-text_w)/2:y=h-200,"
+        "eq=contrast=1.15:brightness=0.04"
+    )
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_reels_blur_fit(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    filter_complex = (
+        "[0:v]scale=1080:1920:force_original_aspect_ratio=increase,"
+        "crop=1080:1920,gblur=sigma=24,eq=brightness=-0.08[bg];"
+        "[0:v]scale=1080:1920:force_original_aspect_ratio=decrease[fg];"
+        "[bg][fg]overlay=(W-w)/2:(H-h)/2,setsar=1[v]"
+    )
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        "[v]",
+        "-map",
+        "0:a?",
+        "-c:v",
+        "libx264",
+        "-preset",
+        opts.get("preset") or "fast",
+        "-crf",
+        str(clamp_int(opts.get("crf", "23"), 23, 12, 35)),
+        "-c:a",
+        "aac",
+        "-y",
+        out,
+    ]
+
+
+def build_reels_safe_caption(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    text = ffmpeg_escape(opts.get("text", ""))
+    font_size = clamp_int(opts.get("font_size", "58"), 58, 24, 140)
+    vf = (
+        scaled_crop_filter("9:16")
+        + ","
+        + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{text}':"
+        f"fontcolor=white:fontsize={font_size}:line_spacing=10:"
+        "box=1:boxcolor=black@0.55:boxborderw=22:"
+        "x=(w-text_w)/2:y=h-430"
+    )
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_reels_hook_title(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    text = ffmpeg_escape(opts.get("text", ""))
+    font_size = clamp_int(opts.get("font_size", "64"), 64, 28, 150)
+    vf = (
+        scaled_crop_filter("9:16")
+        + ",drawbox=x=0:y=95:w=iw:h=210:color=black@0.62:t=fill,"
+        + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{text}':"
+        f"fontcolor=white:fontsize={font_size}:line_spacing=8:"
+        "x=(w-text_w)/2:y=145"
+    )
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_reels_progress_bar(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    duration = clamp_float(opts.get("duration", "30"), 30, 1, 180)
+    vf = (
+        scaled_crop_filter("9:16")
+        + ",drawbox=x=0:y=0:w=iw:h=10:color=black@0.35:t=fill,"
+        + f"drawbox=x=0:y=0:w='min(iw,iw*t/{duration:.3f})':h=10:"
+        "color=white@0.95:t=fill"
+    )
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-t", f"{duration:.3f}", "-y", out]
+
+
+def build_reels_loop(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    duration = clamp_float(opts.get("duration", "15"), 15, 1, 180)
+    return [
+        "ffmpeg",
+        "-stream_loop",
+        "-1",
+        "-i",
+        paths[0],
+        "-t",
+        f"{duration:.3f}",
+        "-vf",
+        scaled_crop_filter("9:16"),
+        "-c:v",
+        "libx264",
+        "-preset",
+        opts.get("preset") or "fast",
+        "-crf",
+        str(clamp_int(opts.get("crf", "23"), 23, 12, 35)),
+        "-c:a",
+        "aac",
+        "-y",
+        out,
+    ]
+
+
+def build_reels_subtitle_safe(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    vf = (
+        scaled_crop_filter("9:16")
+        + ",subtitles='"
+        + filter_path(paths[1])
+        + "':force_style='Fontname=DejaVu Sans,Fontsize=28,"
+        + "PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,"
+        + "BorderStyle=3,Outline=1,Shadow=0,Alignment=2,MarginV=250'"
+    )
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_reels_reaction_stack(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    filter_complex = (
+        "[0:v]scale=1080:960:force_original_aspect_ratio=increase,"
+        "crop=1080:960,setsar=1[top];"
+        "[1:v]scale=1080:960:force_original_aspect_ratio=increase,"
+        "crop=1080:960,setsar=1[bottom];"
+        "[top][bottom]vstack=inputs=2[v]"
+    )
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-i",
+        paths[1],
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        "[v]",
+        "-map",
+        "0:a?",
+        "-shortest",
+        "-c:v",
+        "libx264",
+        "-preset",
+        opts.get("preset") or "fast",
+        "-crf",
+        str(clamp_int(opts.get("crf", "23"), 23, 12, 35)),
+        "-c:a",
+        "aac",
+        "-y",
+        out,
+    ]
+
+
+def build_reels_audio_duck(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    music_volume = clamp_float(opts.get("volume", "0.18"), 0.18, 0.0, 1.0)
+    filter_complex = (
+        f"[1:a]volume={music_volume}[music];"
+        "[0:a][music]amix=inputs=2:duration=first:dropout_transition=2[a]"
+    )
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-i",
+        paths[1],
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        "0:v",
+        "-map",
+        "[a]",
+        "-c:v",
+        "copy",
+        "-c:a",
+        "aac",
+        "-shortest",
+        "-y",
+        out,
+    ]
+
+
+def build_faceless_quote_card(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    duration = clamp_float(opts.get("duration", "12"), 12, 3, 180)
+    font_size = clamp_int(opts.get("font_size", "68"), 68, 28, 140)
+    text_path = write_wrapped_text_file(opts.get("text", ""), width=22, max_lines=9)
+    vf = (
+        "drawbox=x=0:y=0:w=iw:h=ih:color=0x111827@1:t=fill,"
+        "drawbox=x=70:y=190:w=940:h=1540:color=0x0f766e@0.22:t=fill,"
+        f"drawtext=fontfile='{filter_path(FONT_PATH)}':"
+        f"textfile='{drawtext_file_path(text_path)}':fontcolor=white:"
+        f"fontsize={font_size}:line_spacing=14:x=(w-text_w)/2:y=(h-text_h)/2"
+    )
+    return [
+        "ffmpeg",
+        "-f",
+        "lavfi",
+        "-i",
+        f"color=c=0x111827:s=1080x1920:r=30:d={duration:.3f}",
+        "-f",
+        "lavfi",
+        "-i",
+        "anullsrc=channel_layout=stereo:sample_rate=44100",
+        "-vf",
+        vf,
+        "-map",
+        "0:v",
+        "-map",
+        "1:a",
+        "-t",
+        f"{duration:.3f}",
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-c:a",
+        "aac",
+        "-shortest",
+        "-y",
+        out,
+    ]
+
+
+def build_faceless_image_narration(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    text_path = write_wrapped_text_file(opts.get("text", ""), width=24, max_lines=6)
+    font_size = clamp_int(opts.get("font_size", "54"), 54, 24, 110)
+    vf = (
+        "scale=1200:-1,zoompan=z='min(zoom+0.0009,1.12)':"
+        "d=1800:s=1080x1920:fps=30,"
+        f"drawtext=fontfile='{filter_path(FONT_PATH)}':"
+        f"textfile='{drawtext_file_path(text_path)}':fontcolor=white:"
+        f"fontsize={font_size}:line_spacing=10:box=1:boxcolor=black@0.52:"
+        "boxborderw=22:x=(w-text_w)/2:y=h-520"
+    )
+    return [
+        "ffmpeg",
+        "-loop",
+        "1",
+        "-i",
+        paths[0],
+        "-i",
+        paths[1],
+        "-vf",
+        vf,
+        "-map",
+        "0:v",
+        "-map",
+        "1:a",
+        "-c:v",
+        "libx264",
+        "-preset",
+        opts.get("preset") or "fast",
+        "-crf",
+        str(clamp_int(opts.get("crf", "23"), 23, 12, 35)),
+        "-c:a",
+        "aac",
+        "-shortest",
+        "-pix_fmt",
+        "yuv420p",
+        "-y",
+        out,
+    ]
+
+
+def build_faceless_video_narration(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    text_path = write_wrapped_text_file(opts.get("text", ""), width=24, max_lines=6)
+    font_size = clamp_int(opts.get("font_size", "52"), 52, 24, 110)
+    filter_complex = (
+        "[0:v]scale=1080:1920:force_original_aspect_ratio=increase,"
+        "crop=1080:1920,setsar=1,"
+        f"drawtext=fontfile='{filter_path(FONT_PATH)}':"
+        f"textfile='{drawtext_file_path(text_path)}':fontcolor=white:"
+        f"fontsize={font_size}:line_spacing=10:box=1:boxcolor=black@0.5:"
+        "boxborderw=20:x=(w-text_w)/2:y=h-500[v]"
+    )
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-i",
+        paths[1],
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        "[v]",
+        "-map",
+        "1:a",
+        "-c:v",
+        "libx264",
+        "-preset",
+        opts.get("preset") or "fast",
+        "-crf",
+        str(clamp_int(opts.get("crf", "23"), 23, 12, 35)),
+        "-c:a",
+        "aac",
+        "-shortest",
+        "-y",
+        out,
+    ]
+
+
+def run_faceless_story_pages(paths: List[str], options: Dict[str, str], out: str) -> str:
+    pages = split_story_pages(options.get("text", ""), words_per_page=24)
+    seconds = clamp_float(options.get("image_duration", "3"), 3, 1, 12)
+    work_dir = os.path.join(TEMP_DIR, f"story_{uuid.uuid4().hex[:8]}")
+    os.makedirs(work_dir, exist_ok=True)
+    list_path = os.path.join(work_dir, "concat.txt")
+    try:
+        with open(list_path, "w", encoding="utf-8") as concat_file:
+            for index, page in enumerate(pages, start=1):
+                clip_path = os.path.join(work_dir, f"page_{index:03d}.mp4")
+                text_path = write_wrapped_text_file(page, width=24, max_lines=8)
+                vf = (
+                    "drawbox=x=0:y=0:w=iw:h=ih:color=0x0f172a@1:t=fill,"
+                    f"drawtext=fontfile='{filter_path(FONT_PATH)}':"
+                    f"textfile='{drawtext_file_path(text_path)}':fontcolor=white:"
+                    "fontsize=62:line_spacing=12:x=(w-text_w)/2:y=(h-text_h)/2,"
+                    f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{index}/{len(pages)}':"
+                    "fontcolor=white@0.62:fontsize=34:x=(w-text_w)/2:y=h-150"
+                )
+                cmd = [
+                    "ffmpeg",
+                    "-f",
+                    "lavfi",
+                    "-i",
+                    f"color=c=0x0f172a:s=1080x1920:r=30:d={seconds:.3f}",
+                    "-f",
+                    "lavfi",
+                    "-i",
+                    "anullsrc=channel_layout=stereo:sample_rate=44100",
+                    "-vf",
+                    vf,
+                    "-map",
+                    "0:v",
+                    "-map",
+                    "1:a",
+                    "-t",
+                    f"{seconds:.3f}",
+                    "-c:v",
+                    "libx264",
+                    "-pix_fmt",
+                    "yuv420p",
+                    "-c:a",
+                    "aac",
+                    "-y",
+                    clip_path,
+                ]
+                run_command(cmd)
+                concat_file.write(f"file '{ffconcat_path(clip_path)}'\n")
+        run_command(["ffmpeg", "-f", "concat", "-safe", "0", "-i", list_path, "-c", "copy", "-y", out])
+        return out
+    finally:
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+
+def run_faceless_broll_montage(paths: List[str], options: Dict[str, str], out: str) -> str:
+    clip_seconds = clamp_float(options.get("image_duration", "2.5"), 2.5, 1, 8)
+    max_clips = clamp_int(options.get("duration", "12"), 12, 1, 60)
+    work_dir = os.path.join(TEMP_DIR, f"broll_{uuid.uuid4().hex[:8]}")
+    os.makedirs(work_dir, exist_ok=True)
+    list_path = os.path.join(work_dir, "concat.txt")
+    try:
+        with open(list_path, "w", encoding="utf-8") as concat_file:
+            for index, path in enumerate(paths[:max_clips], start=1):
+                clip_path = os.path.join(work_dir, f"clip_{index:03d}.mp4")
+                cmd = [
+                    "ffmpeg",
+                    "-i",
+                    path,
+                    "-t",
+                    f"{clip_seconds:.3f}",
+                    "-vf",
+                    scaled_crop_filter("9:16") + ",setsar=1",
+                    "-an",
+                    "-c:v",
+                    "libx264",
+                    "-preset",
+                    options.get("preset") or "fast",
+                    "-crf",
+                    str(clamp_int(options.get("crf", "23"), 23, 12, 35)),
+                    "-pix_fmt",
+                    "yuv420p",
+                    "-y",
+                    clip_path,
+                ]
+                run_command(cmd)
+                concat_file.write(f"file '{ffconcat_path(clip_path)}'\n")
+        run_command(["ffmpeg", "-f", "concat", "-safe", "0", "-i", list_path, "-c", "copy", "-y", out])
+        return out
+    finally:
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+
+def build_series_episode_badge(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    title = ffmpeg_escape(opts.get("text", "Mini Series"))
+    font_size = clamp_int(opts.get("font_size", "48"), 48, 24, 110)
+    vf = (
+        scaled_crop_filter("9:16")
+        + ",drawbox=x=36:y=86:w=360:h=92:color=black@0.68:t=fill,"
+        + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{title}':"
+        f"fontcolor=white:fontsize={font_size}:x=60:y=106,"
+        + "drawbox=x=36:y=h-238:w=1008:h=116:color=black@0.44:t=fill"
+    )
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_series_recap_card(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    duration = clamp_float(opts.get("duration", "5"), 5, 2, 30)
+    text_path = write_wrapped_text_file(opts.get("text", "Previously in this series"), width=22, max_lines=7)
+    vf = (
+        "drawbox=x=0:y=0:w=iw:h=ih:color=0x111827@1:t=fill,"
+        "drawbox=x=70:y=260:w=940:h=1180:color=0x7c2d12@0.32:t=fill,"
+        f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='PREVIOUSLY':"
+        "fontcolor=white@0.72:fontsize=46:x=(w-text_w)/2:y=350,"
+        f"drawtext=fontfile='{filter_path(FONT_PATH)}':textfile='{drawtext_file_path(text_path)}':"
+        "fontcolor=white:fontsize=68:line_spacing=14:x=(w-text_w)/2:y=(h-text_h)/2"
+    )
+    return [
+        "ffmpeg",
+        "-f",
+        "lavfi",
+        "-i",
+        f"color=c=0x111827:s=1080x1920:r=30:d={duration:.3f}",
+        "-f",
+        "lavfi",
+        "-i",
+        "anullsrc=channel_layout=stereo:sample_rate=44100",
+        "-vf",
+        vf,
+        "-map",
+        "0:v",
+        "-map",
+        "1:a",
+        "-t",
+        f"{duration:.3f}",
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-c:a",
+        "aac",
+        "-shortest",
+        "-y",
+        out,
+    ]
+
+
+def run_series_split_pack(paths: List[str], options: Dict[str, str], out: str) -> str:
+    segment_seconds = clamp_float(options.get("duration", "60"), 60, 15, 180)
+    title = options.get("text", "Mini Series")
+    duration = media_duration_seconds(paths[0])
+    episode_count = min(100, int((duration + segment_seconds - 0.001) // segment_seconds))
+    work_dir = os.path.join(TEMP_DIR, f"series_{uuid.uuid4().hex[:8]}")
+    os.makedirs(work_dir, exist_ok=True)
+    manifest_path = os.path.join(work_dir, "manifest.txt")
+    try:
+        with open(manifest_path, "w", encoding="utf-8") as manifest:
+            manifest.write(f"series_title={title}\n")
+            manifest.write(f"episode_count={episode_count}\n")
+            manifest.write(f"episode_seconds={segment_seconds:.3f}\n\n")
+            for episode in range(1, episode_count + 1):
+                start = (episode - 1) * segment_seconds
+                remaining = max(0.1, duration - start)
+                clip_duration = min(segment_seconds, remaining)
+                episode_out = os.path.join(work_dir, f"episode_{episode:03d}_of_{episode_count:03d}.mp4")
+                label = ffmpeg_escape(f"PART {episode}/{episode_count}")
+                caption = ffmpeg_escape(title)
+                vf = (
+                    scaled_crop_filter("9:16")
+                    + ",drawbox=x=36:y=86:w=390:h=92:color=black@0.68:t=fill,"
+                    + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{label}':"
+                    "fontcolor=white:fontsize=46:x=58:y=108,"
+                    + "drawbox=x=36:y=h-238:w=1008:h=116:color=black@0.48:t=fill,"
+                    + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{caption}':"
+                    "fontcolor=white:fontsize=42:x=(w-text_w)/2:y=h-205"
+                )
+                cmd = [
+                    "ffmpeg",
+                    "-ss",
+                    f"{start:.3f}",
+                    "-i",
+                    paths[0],
+                    "-t",
+                    f"{clip_duration:.3f}",
+                    "-vf",
+                    vf,
+                    "-c:v",
+                    "libx264",
+                    "-preset",
+                    options.get("preset") or "fast",
+                    "-crf",
+                    str(clamp_int(options.get("crf", "23"), 23, 12, 35)),
+                    "-c:a",
+                    "aac",
+                    "-y",
+                    episode_out,
+                ]
+                run_command(cmd)
+                manifest.write(f"{episode_out}\n")
+        shutil.make_archive(out[:-4], "zip", work_dir)
+        return out
+    finally:
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+
+def run_series_batch_pack(paths: List[str], options: Dict[str, str], out: str) -> str:
+    title = options.get("text", "Mini Series")
+    work_dir = os.path.join(TEMP_DIR, f"series_batch_{uuid.uuid4().hex[:8]}")
+    os.makedirs(work_dir, exist_ok=True)
+    manifest_path = os.path.join(work_dir, "manifest.txt")
+    try:
+        with open(manifest_path, "w", encoding="utf-8") as manifest:
+            manifest.write(f"series_title={title}\n")
+            manifest.write(f"episode_count={len(paths)}\n\n")
+            for episode, path in enumerate(paths, start=1):
+                episode_out = os.path.join(work_dir, f"episode_{episode:03d}_of_{len(paths):03d}.mp4")
+                label = ffmpeg_escape(f"PART {episode}/{len(paths)}")
+                caption = ffmpeg_escape(title)
+                vf = (
+                    scaled_crop_filter("9:16")
+                    + ",drawbox=x=36:y=86:w=390:h=92:color=black@0.68:t=fill,"
+                    + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{label}':"
+                    "fontcolor=white:fontsize=46:x=58:y=108,"
+                    + "drawbox=x=36:y=h-238:w=1008:h=116:color=black@0.48:t=fill,"
+                    + f"drawtext=fontfile='{filter_path(FONT_PATH)}':text='{caption}':"
+                    "fontcolor=white:fontsize=42:x=(w-text_w)/2:y=h-205"
+                )
+                cmd = [
+                    "ffmpeg",
+                    "-i",
+                    path,
+                    "-vf",
+                    vf,
+                    "-c:v",
+                    "libx264",
+                    "-preset",
+                    options.get("preset") or "fast",
+                    "-crf",
+                    str(clamp_int(options.get("crf", "23"), 23, 12, 35)),
+                    "-c:a",
+                    "aac",
+                    "-y",
+                    episode_out,
+                ]
+                run_command(cmd)
+                manifest.write(f"{episode_out}\n")
+        shutil.make_archive(out[:-4], "zip", work_dir)
+        return out
+    finally:
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+
+def build_concat(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    job_id = uuid.uuid4().hex[:8]
+    list_path = os.path.join(TEMP_DIR, f"list_{job_id}.txt")
+    with open(list_path, "w", encoding="utf-8") as handle:
+        for path in paths:
+            quoted = ffconcat_path(path)
+            handle.write(f"file '{quoted}'\n")
+    return ["ffmpeg", "-f", "concat", "-safe", "0", "-i", list_path, "-c", "copy", "-y", out]
+
+
+def build_slideshow(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    duration = str(clamp_int(opts.get("image_duration", "3"), 3, 1, 15))
+    job_id = uuid.uuid4().hex[:8]
+    list_path = os.path.join(TEMP_DIR, f"slides_{job_id}.txt")
+    with open(list_path, "w", encoding="utf-8") as handle:
+        for path in paths:
+            quoted = ffconcat_path(path)
+            handle.write(f"file '{quoted}'\nduration {duration}\n")
+        quoted = ffconcat_path(paths[-1])
+        handle.write(f"file '{quoted}'\n")
+    return [
+        "ffmpeg",
+        "-f",
+        "concat",
+        "-safe",
+        "0",
+        "-i",
+        list_path,
+        "-vsync",
+        "vfr",
+        "-pix_fmt",
+        "yuv420p",
+        "-y",
+        out,
+    ]
+
+
+def build_trim(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    start = opts.get("start_time") or "00:00:00"
+    end = opts.get("end_time") or ""
+    cmd = ["ffmpeg", "-ss", start, "-i", paths[0]]
+    if end:
+        cmd += ["-to", end]
+    return cmd + ["-c", "copy", "-y", out]
+
+
+def build_crop(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    vf = scaled_crop_filter(opts.get("aspect_ratio", "1:1"))
+    return ["ffmpeg", "-i", paths[0], "-vf", vf, "-c:a", "copy", "-y", out]
+
+
+def build_waveform(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    color = opts.get("wave_color") or "00e5ff"
+    if not all(ch in "0123456789abcdefABCDEF" for ch in color) or len(color) != 6:
+        color = "00e5ff"
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-filter_complex",
+        f"[0:a]showwaves=s=1280x720:mode=line:colors=#{color}[v]",
+        "-map",
+        "[v]",
+        "-map",
+        "0:a",
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-c:a",
+        "aac",
+        "-shortest",
+        "-y",
+        out,
+    ]
+
+
+def build_extract_frames(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    fps = str(clamp_float(opts.get("frame_rate", "1"), 1, 0.1, 30))
+    pattern = out.replace(".zip", "_%04d.jpg")
+    return ["ffmpeg", "-i", paths[0], "-vf", f"fps={fps}", "-y", pattern]
+
+
+def build_add_intro_outro(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    clips = paths[:]
+    return build_concat(clips, opts, out)
+
+
+def build_speed(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    speed = clamp_float(opts.get("speed", "1.25"), 1.25, 0.25, 4.0)
+    setpts = 1 / speed
+    atempo_parts = []
+    remaining = speed
+    while remaining > 2.0:
+        atempo_parts.append("atempo=2.0")
+        remaining /= 2.0
+    while remaining < 0.5:
+        atempo_parts.append("atempo=0.5")
+        remaining /= 0.5
+    atempo_parts.append(f"atempo={remaining:.4f}")
+    filter_complex = f"[0:v]setpts={setpts:.6f}*PTS[v];[0:a]{','.join(atempo_parts)}[a]"
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        "[v]",
+        "-map",
+        "[a]",
+        "-y",
+        out,
+    ]
+
+
+def build_remove_audio(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    return ["ffmpeg", "-i", paths[0], "-c:v", "copy", "-an", "-y", out]
+
+
+def build_replace_audio(paths: List[str], opts: Dict[str, str], out: str) -> List[str]:
+    return [
+        "ffmpeg",
+        "-i",
+        paths[0],
+        "-i",
+        paths[1],
+        "-map",
+        "0:v",
+        "-map",
+        "1:a",
+        "-c:v",
+        "copy",
+        "-c:a",
+        "aac",
+        "-shortest",
+        "-y",
+        out,
+    ]
+
+
+def run_batch_compress(paths: List[str], options: Dict[str, str], out: str) -> str:
+    archive_dir = os.path.join(TEMP_DIR, f"batch_{uuid.uuid4().hex[:8]}")
+    os.makedirs(archive_dir, exist_ok=True)
+    try:
+        for index, path in enumerate(paths, start=1):
+            name, _ext = os.path.splitext(os.path.basename(path))
+            item_out = os.path.join(archive_dir, f"{index:02d}_{name}_compressed.mp4")
+            cmd = build_compress([path], options, item_out)
+            run_command(cmd)
+        shutil.make_archive(out[:-4], "zip", archive_dir)
+        return out
+    finally:
+        shutil.rmtree(archive_dir, ignore_errors=True)
+
+
+TASKS: Dict[str, TaskDefinition] = {
+    "normalize": TaskDefinition("Normalize MP4", "Convert to H.264/AAC MP4.", "Video", "mp4", 1, 1, ["video"], build_normalize),
+    "extract_audio": TaskDefinition("Extract Audio", "Export MP3 audio from a video.", "Audio", "mp3", 1, 1, ["video", "audio"], build_extract_audio),
+    "resize_916": TaskDefinition("Resize 9:16", "Crop video for vertical platforms.", "Social", "mp4", 1, 1, ["video"], build_resize),
+    "add_subtitles": TaskDefinition("Add Subtitles", "Burn an SRT/ASS subtitle file into video.", "Subtitles", "mp4", 2, 2, ["video", "text"], build_subtitles, file_types=[["video"], ["text"]]),
+    "burn_lyrics": TaskDefinition("Burn Lyrics", "Burn styled lyric subtitles into video.", "Subtitles", "mp4", 2, 2, ["video", "text"], build_burn_lyrics, file_types=[["video"], ["text"]]),
+    "text_overlay": TaskDefinition("Text Overlay", "Add caption text to video.", "Social", "mp4", 1, 1, ["video"], build_text_overlay),
+    "merge_music": TaskDefinition("Merge Music", "Add background music to video.", "Audio", "mp4", 2, 2, ["video", "audio"], build_merge_music, file_types=[["video"], ["audio"]]),
+    "thumbnail": TaskDefinition("Thumbnail", "Export one JPG frame.", "Image", "jpg", 1, 1, ["video"], build_thumbnail),
+    "watermark": TaskDefinition("Watermark", "Overlay a logo/image on video.", "Branding", "mp4", 2, 2, ["video", "image"], build_watermark, file_types=[["video"], ["image"]]),
+    "compress": TaskDefinition("Compress", "Reduce video size using CRF and scale.", "Video", "mp4", 1, 1, ["video"], build_compress),
+    "batch_compress": TaskDefinition("Batch Compress", "Compress multiple videos and return a ZIP.", "Video", "zip", 1, None, ["video"], runner=run_batch_compress),
+    "make_gif": TaskDefinition("Make GIF", "Create a short GIF clip.", "Image", "gif", 1, 1, ["video"], build_gif),
+    "tiktok_lyrics": TaskDefinition("TikTok Lyrics", "Vertical lyric clip with boxed center text.", "Social", "mp4", 1, 1, ["video"], build_tiktok_lyrics),
+    "tiktok_pro_reframer": TaskDefinition("TikTok Pro Reframer", "Vertical crop, text, and contrast pass.", "Social", "mp4", 1, 1, ["video"], build_tiktok_pro),
+    "reels_blur_fit": TaskDefinition("Reels Blur Fit", "Fit any video into 9:16 with a blurred background.", "Social", "mp4", 1, 1, ["video"], build_reels_blur_fit),
+    "reels_safe_caption": TaskDefinition("Reels Safe Caption", "Add lower-third caption text inside Reels and Shorts safe zones.", "Social", "mp4", 1, 1, ["video"], build_reels_safe_caption),
+    "reels_hook_title": TaskDefinition("Reels Hook Title", "Add a bold top hook/title banner to a vertical clip.", "Social", "mp4", 1, 1, ["video"], build_reels_hook_title),
+    "reels_progress_bar": TaskDefinition("Reels Progress Bar", "Add a top progress bar and optional duration trim.", "Social", "mp4", 1, 1, ["video"], build_reels_progress_bar),
+    "reels_loop": TaskDefinition("Reels Loop", "Loop a clip to a target vertical Shorts/Reels duration.", "Social", "mp4", 1, 1, ["video"], build_reels_loop),
+    "reels_subtitle_safe": TaskDefinition("Reels Subtitle Safe", "Burn subtitles with mobile-safe lower margins.", "Social", "mp4", 2, 2, ["video", "text"], build_reels_subtitle_safe, file_types=[["video"], ["text"]]),
+    "reels_reaction_stack": TaskDefinition("Reels Reaction Stack", "Stack two videos vertically for reaction-style Shorts.", "Social", "mp4", 2, 2, ["video"], build_reels_reaction_stack),
+    "reels_audio_duck": TaskDefinition("Reels Audio Duck", "Mix background music under the original video audio.", "Social", "mp4", 2, 2, ["video", "audio"], build_reels_audio_duck, file_types=[["video"], ["audio"]]),
+    "faceless_quote_card": TaskDefinition("Faceless Quote Card", "Generate a vertical text-only quote short from caption text.", "Faceless", "mp4", 0, 0, [], build_faceless_quote_card),
+    "faceless_story_pages": TaskDefinition("Faceless Story Pages", "Split long text into timed vertical story slides.", "Faceless", "mp4", 0, 0, [], runner=run_faceless_story_pages),
+    "faceless_image_narration": TaskDefinition("Faceless Image Narration", "Create a Ken Burns image short with narration audio and caption text.", "Faceless", "mp4", 2, 2, ["image", "audio"], build_faceless_image_narration, file_types=[["image"], ["audio"]]),
+    "faceless_video_narration": TaskDefinition("Faceless Video Narration", "Create a vertical b-roll short with narration audio and caption text.", "Faceless", "mp4", 2, 2, ["video", "audio"], build_faceless_video_narration, file_types=[["video"], ["audio"]]),
+    "faceless_broll_montage": TaskDefinition("Faceless B-roll Montage", "Create a silent vertical montage from multiple b-roll videos.", "Faceless", "mp4", 2, None, ["video"], runner=run_faceless_broll_montage),
+    "series_split_pack": TaskDefinition("Mini Series Split Pack", "Split one long video into numbered vertical TikTok/Reels episodes and return a ZIP.", "Series", "zip", 1, 1, ["video"], runner=run_series_split_pack),
+    "series_episode_badge": TaskDefinition("Mini Series Episode Badge", "Add a series title and episode-safe badge area to one vertical clip.", "Series", "mp4", 1, 1, ["video"], build_series_episode_badge),
+    "series_batch_pack": TaskDefinition("Mini Series Batch Pack", "Number multiple clips as a TikTok/Reels mini-series and return a ZIP.", "Series", "zip", 2, None, ["video"], runner=run_series_batch_pack),
+    "series_recap_card": TaskDefinition("Mini Series Recap Card", "Generate a short text-only recap card for the next episode.", "Series", "mp4", 0, 0, [], build_series_recap_card),
+    "concat": TaskDefinition("Concat Videos", "Join clips in upload order.", "Video", "mp4", 2, None, ["video"], build_concat),
+    "slideshow": TaskDefinition("Slideshow", "Create a video from images.", "Image", "mp4", 2, None, ["image"], build_slideshow),
+    "trim": TaskDefinition("Trim", "Cut a clip by start/end time.", "Video", "mp4", 1, 1, ["video", "audio"], build_trim),
+    "crop_aspect": TaskDefinition("Crop Aspect", "Crop to 1:1, 4:5, 16:9, or 9:16.", "Video", "mp4", 1, 1, ["video"], build_crop),
+    "waveform": TaskDefinition("Waveform Video", "Create a waveform video from audio.", "Audio", "mp4", 1, 1, ["audio", "video"], build_waveform),
+    "extract_frames": TaskDefinition("Extract Frames", "Export JPG frames and return a ZIP.", "Image", "zip", 1, 1, ["video"], build_extract_frames),
+    "add_intro_outro": TaskDefinition("Add Intro/Outro", "Join intro, main clip, and outro.", "Video", "mp4", 2, 3, ["video"], build_add_intro_outro),
+    "speed": TaskDefinition("Speed Change", "Speed up or slow down video and audio.", "Video", "mp4", 1, 1, ["video"], build_speed),
+    "remove_audio": TaskDefinition("Remove Audio", "Export video without audio.", "Audio", "mp4", 1, 1, ["video"], build_remove_audio),
+    "replace_audio": TaskDefinition("Replace Audio", "Replace video audio with another file.", "Audio", "mp4", 2, 2, ["video", "audio"], build_replace_audio, file_types=[["video"], ["audio"]]),
+}
+
+
+def cleanup_worker():
+    while True:
+        now = time.time()
+        expired_outputs = []
+        for name in os.listdir(TEMP_DIR):
+            path = os.path.join(TEMP_DIR, name)
+            try:
+                if os.path.abspath(path) == os.path.abspath(STATE_DB_PATH):
+                    continue
+                if os.path.isfile(path) and now - os.path.getmtime(path) > FILE_TTL_SECONDS:
+                    expired_outputs.append(os.path.abspath(path))
+                    remove_file_quietly(path)
+            except OSError:
+                continue
+        if expired_outputs:
+            with db_connect() as connection:
+                connection.executemany(
+                    "DELETE FROM history WHERE output = ?",
+                    [(path,) for path in expired_outputs],
+                )
+            load_state_store()
+        time.sleep(600)
+
+
+threading.Thread(target=cleanup_worker, daemon=True).start()
+
+
+def file_category(path: str) -> str:
+    try:
+        mime_type = magic.from_file(path, mime=True) or ""
+    except Exception:
+        mime_type = ""
+    if mime_type.startswith("video/"):
+        return "video"
+    if mime_type.startswith("audio/"):
+        return "audio"
+    if mime_type.startswith("image/"):
+        return "image"
+    if mime_type in {"text/plain", "application/x-subrip"} or path.lower().endswith(
+        (".srt", ".ass", ".vtt")
+    ):
+        return "text"
+    return "unknown"
+
+
+def validate_files(task_id: str, paths: List[str]) -> None:
+    task = get_task(task_id)
+    if len(paths) < task.min_files:
+        raise HTTPException(
+            status_code=400,
+            detail=f"{task.label} requires at least {task.min_files} file(s).",
+        )
+    if task.max_files is not None and len(paths) > task.max_files:
+        raise HTTPException(
+            status_code=400,
+            detail=f"{task.label} accepts at most {task.max_files} file(s).",
+        )
+    for index, path in enumerate(paths):
+        if not os.path.exists(path):
+            raise HTTPException(status_code=400, detail=f"Input not found: {path}")
+        if os.path.getsize(path) > MAX_UPLOAD_BYTES:
+            raise HTTPException(
+                status_code=413,
+                detail=f"{os.path.basename(path)} exceeds {MAX_UPLOAD_MB} MB.",
+            )
+        category = file_category(path)
+        expected_types = (
+            task.file_types[index]
+            if task.file_types and index < len(task.file_types)
+            else task.accepted_types
+        )
+        if category not in expected_types:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"{os.path.basename(path)} is {category}; "
+                    f"{task.label} expects {', '.join(expected_types)}."
+                ),
+            )
+
+
+def get_task(task_id: str) -> TaskDefinition:
+    task = TASKS.get(task_id)
+    if not task:
+        raise HTTPException(status_code=404, detail=f"Unknown task: {task_id}")
+    return task
+
+
+def output_path(task_id: str, ext: str, job_id: Optional[str] = None) -> str:
+    safe_job_id = job_id or uuid.uuid4().hex[:8]
+    return os.path.abspath(os.path.join(TEMP_DIR, f"{task_id}_{safe_job_id}.{ext}"))
+
+
+def zip_frames(pattern_prefix: str, zip_path: str) -> str:
+    frame_dir = os.path.dirname(pattern_prefix)
+    prefix = os.path.basename(pattern_prefix).split("_%04d")[0]
+    archive_base = zip_path[:-4]
+    frame_paths = [
+        os.path.join(frame_dir, name)
+        for name in os.listdir(frame_dir)
+        if name.startswith(prefix) and name.endswith(".jpg")
+    ]
+    if not frame_paths:
+        raise HTTPException(status_code=500, detail="No frames were generated.")
+    temp_archive_dir = os.path.join(TEMP_DIR, f"frames_{uuid.uuid4().hex[:8]}")
+    os.makedirs(temp_archive_dir, exist_ok=True)
+    try:
+        for frame_path in frame_paths:
+            shutil.copy2(frame_path, os.path.join(temp_archive_dir, os.path.basename(frame_path)))
+        shutil.make_archive(archive_base, "zip", temp_archive_dir)
+    finally:
+        shutil.rmtree(temp_archive_dir, ignore_errors=True)
+    return zip_path
+
+
+def run_ffmpeg(task_id: str, paths: List[str], options: Optional[Dict[str, str]] = None) -> str:
+    task = get_task(task_id)
+    opts = options or {}
+    validate_files(task_id, paths)
+    job_id = uuid.uuid4().hex[:8]
+    out = output_path(task_id, task.output_ext, job_id)
+    if task.runner:
+        try:
+            return task.runner(paths, opts, out)
+        except subprocess.CalledProcessError as exc:
+            stderr = exc.stderr.strip()[-2000:] or "FFmpeg failed without stderr."
+            raise HTTPException(status_code=500, detail=stderr)
+    if not task.builder:
+        raise HTTPException(status_code=500, detail=f"{task_id} is not executable.")
+    cmd = task.builder(paths, opts, out)
+    try:
+        run_command(cmd)
+        if task_id == "extract_frames":
+            out = zip_frames(out.replace(".zip", "_%04d.jpg"), out)
+        return out
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.strip()[-2000:] or "FFmpeg failed without stderr."
+        raise HTTPException(status_code=500, detail=stderr)
+
+
+def record_history(job_id: str, task_id: str, output: str) -> None:
+    task = get_task(task_id)
+    history_id = uuid.uuid4().hex[:12]
+    item = {
+        "history_id": history_id,
+        "job_id": job_id,
+        "task_id": task_id,
+        "task": task.label,
+        "output": output,
+        "filename": os.path.basename(output),
+        "size": os.path.getsize(output) if os.path.exists(output) else 0,
+        "created_at": int(time.time()),
+        "download_url": f"/history/{history_id}/download",
+    }
+    with STATE_LOCK:
+        HISTORY.insert(0, item)
+        del HISTORY[HISTORY_LIMIT:]
+    persist_history(item)
+
+
+def update_job(job_id: str, **updates: object) -> None:
+    with STATE_LOCK:
+        job = JOBS.get(job_id)
+        if not job:
+            return
+        job.update(updates)
+        snapshot = dict(job)
+    persist_job(snapshot)
+
+
+def execute_job(job_id: str, task_id: str, paths: List[str], options: Dict[str, str]) -> None:
+    update_job(job_id, status="running", message="Running FFmpeg")
+    try:
+        output = run_ffmpeg(task_id, paths, options)
+        record_history(job_id, task_id, output)
+        update_job(job_id, status="complete", message="Complete", output=output)
+    except HTTPException as exc:
+        update_job(job_id, status="failed", message=exc.detail)
+    except Exception as exc:
+        update_job(job_id, status="failed", message=str(exc))
+
+
+async def save_uploads(files: Optional[List[UploadFile]]) -> List[str]:
+    saved = []
+    if not files:
+        return saved
+    for upload in files:
+        filename = os.path.basename(upload.filename or "upload.bin")
+        path = os.path.join(TEMP_DIR, f"{uuid.uuid4().hex}_{filename}")
+        size = 0
+        with open(path, "wb") as handle:
+            while chunk := await upload.read(1024 * 1024):
+                size += len(chunk)
+                if size > MAX_UPLOAD_BYTES:
+                    handle.close()
+                    remove_file_quietly(path)
+                    raise HTTPException(
+                        status_code=413,
+                        detail=f"{filename} exceeds {MAX_UPLOAD_MB} MB.",
+                    )
+                handle.write(chunk)
+        saved.append(path)
+    return saved
+
+
+def safe_upload_name(filename: str, fallback: str = "upload.bin") -> str:
+    cleaned = os.path.basename(filename or fallback).strip()
+    return cleaned or fallback
+
+
+def save_bytes_file(content: bytes, filename: str) -> str:
+    if len(content) > MAX_UPLOAD_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"{safe_upload_name(filename)} exceeds {MAX_UPLOAD_MB} MB.",
+        )
+    path = os.path.abspath(
+        os.path.join(TEMP_DIR, f"{uuid.uuid4().hex}_{safe_upload_name(filename)}")
+    )
+    with open(path, "wb") as handle:
+        handle.write(content)
+    return path
+
+
+def decode_base64_content(value: str) -> bytes:
+    if "," in value and value.lstrip().startswith("data:"):
+        value = value.split(",", 1)[1]
+    try:
+        return base64.b64decode(value, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise HTTPException(status_code=400, detail="Invalid base64 file content.") from exc
+
+
+def collect_base64_files(payload: object) -> List[str]:
+    saved = []
+
+    def walk(value: object, inherited_name: str = "n8n-upload.bin") -> None:
+        if isinstance(value, list):
+            for item in value:
+                walk(item, inherited_name)
+            return
+        if not isinstance(value, dict):
+            return
+
+        filename = str(
+            value.get("fileName")
+            or value.get("filename")
+            or value.get("name")
+            or inherited_name
+        )
+        content = (
+            value.get("content_base64")
+            or value.get("base64")
+            or value.get("content")
+            or value.get("data")
+        )
+        if isinstance(content, str) and (
+            value.get("mimeType")
+            or value.get("mime_type")
+            or value.get("fileName")
+            or value.get("filename")
+            or value.get("base64")
+            or value.get("content_base64")
+        ):
+            saved.append(save_bytes_file(decode_base64_content(content), filename))
+            return
+
+        for key, nested in value.items():
+            walk(nested, str(key))
+
+    walk(payload)
+    return saved
+
+
+def split_url_values(value: object) -> List[str]:
+    if not value:
+        return list()
+    if isinstance(value, list):
+        urls = []
+        for item in value:
+            urls.extend(split_url_values(item))
+        return urls
+    if not isinstance(value, str):
+        return list()
+    chunks = value.replace(",", "\n").splitlines()
+    return [chunk.strip() for chunk in chunks if chunk.strip()]
+
+
+def options_from_mapping(values: Dict[str, object]) -> Dict[str, str]:
+    nested_options = values.get("options")
+    merged = dict(values)
+    if isinstance(nested_options, dict):
+        merged.update(nested_options)
+    return {
+        field: "" if merged.get(field) is None else str(merged.get(field, ""))
+        for field in OPTION_FIELDS
+    }
+
+
+async def collect_n8n_inputs(request: Request) -> tuple[List[str], Dict[str, str]]:
+    content_type = request.headers.get("content-type", "").lower()
+    saved: List[str] = []
+    values: Dict[str, object] = {}
+
+    if "multipart/form-data" in content_type:
+        form = await request.form()
+        uploads = []
+        urls = []
+        for key, value in form.multi_items():
+            if hasattr(value, "filename") and hasattr(value, "read"):
+                uploads.append(value)
+            else:
+                values[key] = value
+                if key in {"url", "urls", "file_url", "source_url", "download_url"}:
+                    urls.extend(split_url_values(value))
+        saved.extend(await save_uploads(uploads))
+        for url in urls:
+            saved.append(download_url(url))
+        return saved, options_from_mapping(values)
+
+    if "application/json" in content_type:
+        payload = await request.json()
+        if not isinstance(payload, dict):
+            raise HTTPException(status_code=400, detail="JSON body must be an object.")
+        values.update(payload)
+        for key in ("url", "urls", "file_url", "source_url", "download_url"):
+            for url in split_url_values(payload.get(key)):
+                saved.append(download_url(url))
+        saved.extend(collect_base64_files(payload.get("files", [])))
+        saved.extend(collect_base64_files(payload.get("binary", {})))
+        saved.extend(collect_base64_files(payload.get("data", {})))
+        if not saved:
+            saved.extend(collect_base64_files(payload))
+        return saved, options_from_mapping(values)
+
+    body = await request.body()
+    if body:
+        filename = (
+            request.headers.get("x-filename")
+            or request.headers.get("x-file-name")
+            or "n8n-upload.bin"
+        )
+        saved.append(save_bytes_file(body, filename))
+    return saved, options_from_mapping(dict(request.query_params))
+
+
+def download_url(url: str) -> str:
+    if not ALLOW_URL_INPUTS:
+        raise HTTPException(status_code=403, detail="URL inputs are disabled.")
+    outtmpl = os.path.join(TEMP_DIR, f"{uuid.uuid4().hex}.%(ext)s")
+    ydl_opts = {
+        "outtmpl": outtmpl,
+        "format": "bestvideo+bestaudio/best",
+        "max_filesize": MAX_URL_DOWNLOAD_BYTES,
+        "noplaylist": True,
+        "quiet": True,
+        "no_warnings": True,
+    }
+    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+        info = ydl.extract_info(url, download=True)
+        path = ydl.prepare_filename(info)
+    if not os.path.exists(path):
+        raise HTTPException(status_code=502, detail="URL download did not produce a file.")
+    if os.path.getsize(path) > MAX_URL_DOWNLOAD_BYTES:
+        remove_file_quietly(path)
+        raise HTTPException(
+            status_code=413,
+            detail=f"Downloaded media exceeds {MAX_URL_DOWNLOAD_MB} MB.",
+        )
+    return path
+
+
+def options_from_form(
+    text: str,
+    start_time: str,
+    end_time: str,
+    duration: str,
+    aspect_ratio: str,
+    resolution: str,
+    crf: str,
+    preset: str,
+    audio_bitrate: str,
+    volume: str,
+    position: str,
+    opacity: str,
+    fps: str,
+    width: str,
+    speed: str,
+    timestamp: str,
+    image_duration: str,
+    frame_rate: str,
+    font_size: str,
+    wave_color: str,
+) -> Dict[str, str]:
+    return {
+        "text": text or "",
+        "start_time": start_time or "",
+        "end_time": end_time or "",
+        "duration": duration or "",
+        "aspect_ratio": aspect_ratio or "",
+        "resolution": resolution or "",
+        "crf": crf or "",
+        "preset": preset or "",
+        "audio_bitrate": audio_bitrate or "",
+        "volume": volume or "",
+        "position": position or "",
+        "opacity": opacity or "",
+        "fps": fps or "",
+        "width": width or "",
+        "speed": speed or "",
+        "timestamp": timestamp or "",
+        "image_duration": image_duration or "",
+        "frame_rate": frame_rate or "",
+        "font_size": font_size or "",
+        "wave_color": wave_color or "",
+    }
+
+
+@app.get("/healthz")
+def healthz():
+    return {"status": "ok", "checks": production_checks()}
+
+
+@app.get("/readyz")
+def readyz():
+    checks = production_checks()
+    if not production_ready():
+        raise HTTPException(status_code=503, detail={"status": "not_ready", "checks": checks})
+    return {"status": "ready", "checks": checks}
+
+
+@app.get("/tasks")
+def list_tasks():
+    return {
+        task_id: {
+            "label": task.label,
+            "description": task.description,
+            "category": task.category,
+            "output_ext": task.output_ext,
+            "min_files": task.min_files,
+            "max_files": task.max_files,
+            "accepted_types": task.accepted_types,
+            "file_types": task.file_types,
+        }
+        for task_id, task in TASKS.items()
+    }
+
+
+@app.post("/n8n/execute/{task_id}")
+async def n8n_execute(task_id: str, request: Request):
+    task = get_task(task_id)
+    saved, options = await collect_n8n_inputs(request)
+    if not saved and task.min_files > 0:
+        raise HTTPException(status_code=400, detail="No n8n binary, base64 file, raw body, or URL input provided.")
+    output = run_ffmpeg(task_id, saved, options)
+    record_history(uuid.uuid4().hex[:8], task_id, output)
+    return FileResponse(output, filename=os.path.basename(output))
+
+
+@app.post("/n8n/jobs/{task_id}")
+async def n8n_create_job(task_id: str, request: Request, background_tasks: BackgroundTasks):
+    task = get_task(task_id)
+    saved, options = await collect_n8n_inputs(request)
+    if not saved and task.min_files > 0:
+        raise HTTPException(status_code=400, detail="No n8n binary, base64 file, raw body, or URL input provided.")
+    job_id = uuid.uuid4().hex[:12]
+    job = {
+        "job_id": job_id,
+        "task_id": task_id,
+        "status": "queued",
+        "message": "Queued",
+        "output": None,
+        "created_at": int(time.time()),
+    }
+    with STATE_LOCK:
+        JOBS[job_id] = job
+    persist_job(job)
+    background_tasks.add_task(execute_job, job_id, task_id, saved, options)
+    return {"job_id": job_id, "status_url": f"/status/{job_id}"}
+
+
+@app.post("/execute/{task_id}")
+async def api_call(
+    task_id: str,
+    files: List[UploadFile] = File(None),
+    url: Optional[str] = Form(None),
+    text: str = Form(""),
+    start_time: str = Form(""),
+    end_time: str = Form(""),
+    duration: str = Form(""),
+    aspect_ratio: str = Form(""),
+    resolution: str = Form(""),
+    crf: str = Form(""),
+    preset: str = Form(""),
+    audio_bitrate: str = Form(""),
+    volume: str = Form(""),
+    position: str = Form(""),
+    opacity: str = Form(""),
+    fps: str = Form(""),
+    width: str = Form(""),
+    speed: str = Form(""),
+    timestamp: str = Form(""),
+    image_duration: str = Form(""),
+    frame_rate: str = Form(""),
+    font_size: str = Form(""),
+    wave_color: str = Form(""),
+):
+    task = get_task(task_id)
+    saved = []
+    if url:
+        saved.append(download_url(url))
+    saved.extend(await save_uploads(files))
+    if not saved and task.min_files > 0:
+        raise HTTPException(status_code=400, detail="No input provided")
+    options = options_from_form(
+        text,
+        start_time,
+        end_time,
+        duration,
+        aspect_ratio,
+        resolution,
+        crf,
+        preset,
+        audio_bitrate,
+        volume,
+        position,
+        opacity,
+        fps,
+        width,
+        speed,
+        timestamp,
+        image_duration,
+        frame_rate,
+        font_size,
+        wave_color,
+    )
+    output = run_ffmpeg(task_id, saved, options)
+    record_history(uuid.uuid4().hex[:8], task_id, output)
+    return FileResponse(output, filename=os.path.basename(output))
+
+
+@app.post("/jobs/{task_id}")
+async def create_job(
+    task_id: str,
+    background_tasks: BackgroundTasks,
+    files: List[UploadFile] = File(None),
+    url: Optional[str] = Form(None),
+    text: str = Form(""),
+    start_time: str = Form(""),
+    end_time: str = Form(""),
+    duration: str = Form(""),
+    aspect_ratio: str = Form(""),
+    resolution: str = Form(""),
+    crf: str = Form(""),
+    preset: str = Form(""),
+    audio_bitrate: str = Form(""),
+    volume: str = Form(""),
+    position: str = Form(""),
+    opacity: str = Form(""),
+    fps: str = Form(""),
+    width: str = Form(""),
+    speed: str = Form(""),
+    timestamp: str = Form(""),
+    image_duration: str = Form(""),
+    frame_rate: str = Form(""),
+    font_size: str = Form(""),
+    wave_color: str = Form(""),
+):
+    task = get_task(task_id)
+    saved = []
+    if url:
+        saved.append(download_url(url))
+    saved.extend(await save_uploads(files))
+    if not saved and task.min_files > 0:
+        raise HTTPException(status_code=400, detail="No input provided")
+    options = options_from_form(
+        text,
+        start_time,
+        end_time,
+        duration,
+        aspect_ratio,
+        resolution,
+        crf,
+        preset,
+        audio_bitrate,
+        volume,
+        position,
+        opacity,
+        fps,
+        width,
+        speed,
+        timestamp,
+        image_duration,
+        frame_rate,
+        font_size,
+        wave_color,
+    )
+    job_id = uuid.uuid4().hex[:12]
+    job = {
+        "job_id": job_id,
+        "task_id": task_id,
+        "status": "queued",
+        "message": "Queued",
+        "output": None,
+        "created_at": int(time.time()),
+    }
+    with STATE_LOCK:
+        JOBS[job_id] = job
+    persist_job(job)
+    background_tasks.add_task(execute_job, job_id, task_id, saved, options)
+    return {"job_id": job_id, "status_url": f"/status/{job_id}"}
+
+
+@app.get("/status/{job_id}")
+def job_status(job_id: str):
+    with STATE_LOCK:
+        job = JOBS.get(job_id)
+        if not job:
+            raise HTTPException(status_code=404, detail="Job not found")
+        data = dict(job)
+    if data.get("output"):
+        data["download_url"] = f"/download/{job_id}"
+    return data
+
+
+@app.get("/download/{job_id}")
+def download_job(job_id: str):
+    with STATE_LOCK:
+        job = JOBS.get(job_id)
+        if not job:
+            raise HTTPException(status_code=404, detail="Job not found")
+        output = job.get("output")
+    if not output or not os.path.exists(str(output)):
+        raise HTTPException(status_code=404, detail="Output not available")
+    return FileResponse(str(output), filename=os.path.basename(str(output)))
+
+
+@app.get("/history")
+def history():
+    with STATE_LOCK:
+        return [
+            {key: value for key, value in item.items() if key != "output"}
+            for item in HISTORY
+        ]
+
+
+@app.get("/history/{history_id}/download")
+def download_history_item(history_id: str):
+    with STATE_LOCK:
+        item = next(
+            (entry for entry in HISTORY if entry.get("history_id") == history_id), None
+        )
+    if not item:
+        raise HTTPException(status_code=404, detail="History item not found")
+    output = str(item["output"])
+    if not os.path.exists(output):
+        raise HTTPException(status_code=404, detail="Output expired")
+    return FileResponse(output, filename=os.path.basename(output))
+
+
+def task_choices() -> List[str]:
+    return [f"{task.label} ({task_id})" for task_id, task in TASKS.items()]
+
+
+def selected_task_id(choice: str) -> str:
+    if not choice:
+        return "normalize"
+    if "(" in choice and choice.endswith(")"):
+        return choice.rsplit("(", 1)[1][:-1]
+    return choice if choice in TASKS else "normalize"
+
+
+def describe_task(choice: str) -> str:
+    task_id = selected_task_id(choice)
+    task = get_task(task_id)
+    max_files = "unlimited" if task.max_files is None else str(task.max_files)
+    return (
+        f"{task.description}\n\n"
+        f"Files: {task.min_files}-{max_files}. "
+        f"Accepted: {', '.join(task.accepted_types)}. "
+        f"Output: .{task.output_ext}"
+    )
+
+
+def option_visibility(choice: str):
+    task_id = selected_task_id(choice)
+    text_tasks = {
+        "text_overlay",
+        "tiktok_lyrics",
+        "tiktok_pro_reframer",
+        "reels_safe_caption",
+        "reels_hook_title",
+        "faceless_quote_card",
+        "faceless_story_pages",
+        "faceless_image_narration",
+        "faceless_video_narration",
+        "series_split_pack",
+        "series_episode_badge",
+        "series_batch_pack",
+        "series_recap_card",
+    }
+    duration_tasks = {
+        "make_gif",
+        "tiktok_lyrics",
+        "reels_progress_bar",
+        "reels_loop",
+        "faceless_quote_card",
+        "faceless_broll_montage",
+        "series_split_pack",
+        "series_recap_card",
+    }
+    quality_tasks = {
+        "normalize",
+        "compress",
+        "batch_compress",
+        "reels_blur_fit",
+        "reels_loop",
+        "reels_reaction_stack",
+        "faceless_image_narration",
+        "faceless_video_narration",
+        "faceless_broll_montage",
+        "series_split_pack",
+        "series_batch_pack",
+    }
+    audio_tasks = {"extract_audio", "merge_music", "reels_audio_duck"}
+    font_tasks = {
+        "text_overlay",
+        "tiktok_lyrics",
+        "tiktok_pro_reframer",
+        "reels_safe_caption",
+        "reels_hook_title",
+        "faceless_quote_card",
+        "faceless_story_pages",
+        "faceless_image_narration",
+        "faceless_video_narration",
+        "series_episode_badge",
+        "series_recap_card",
+    }
+    visible = {
+        "text": task_id in text_tasks,
+        "trim": task_id == "trim",
+        "duration": task_id in duration_tasks,
+        "timestamp": task_id == "thumbnail",
+        "aspect": task_id in {"resize_916", "crop_aspect"},
+        "resolution": task_id == "compress",
+        "quality": task_id in quality_tasks,
+        "audio": task_id in audio_tasks,
+        "watermark": task_id == "watermark",
+        "gif": task_id == "make_gif",
+        "speed": task_id == "speed",
+        "slideshow": task_id in {"slideshow", "faceless_story_pages", "faceless_broll_montage"},
+        "frames": task_id == "extract_frames",
+        "font": task_id in font_tasks,
+        "wave": task_id == "waveform",
+    }
+    return [
+        describe_task(choice),
+        gr.update(visible=visible["text"]),
+        gr.update(visible=visible["trim"]),
+        gr.update(visible=visible["duration"]),
+        gr.update(visible=visible["timestamp"]),
+        gr.update(visible=visible["aspect"]),
+        gr.update(visible=visible["resolution"]),
+        gr.update(visible=visible["quality"]),
+        gr.update(visible=visible["audio"]),
+        gr.update(visible=visible["watermark"]),
+        gr.update(visible=visible["gif"]),
+        gr.update(visible=visible["speed"]),
+        gr.update(visible=visible["slideshow"]),
+        gr.update(visible=visible["frames"]),
+        gr.update(visible=visible["font"]),
+        gr.update(visible=visible["wave"]),
+    ]
+
+
+def ui_handler(
+    files,
+    url,
+    task_choice,
+    text,
+    start_time,
+    end_time,
+    duration,
+    aspect_ratio,
+    resolution,
+    crf,
+    preset,
+    audio_bitrate,
+    volume,
+    position,
+    opacity,
+    fps,
+    width,
+    speed,
+    timestamp,
+    image_duration,
+    frame_rate,
+    font_size,
+    wave_color,
+):
+    task_id = selected_task_id(task_choice)
+    task = get_task(task_id)
+    paths = []
+    if url:
+        paths.append(download_url(url))
+    if files:
+        paths.extend([file.name for file in files])
+    if not paths and task.min_files > 0:
+        raise gr.Error("Upload files or provide a URL.")
+    options = options_from_form(
+        text,
+        start_time,
+        end_time,
+        duration,
+        aspect_ratio,
+        resolution,
+        crf,
+        preset,
+        audio_bitrate,
+        volume,
+        position,
+        opacity,
+        fps,
+        width,
+        speed,
+        timestamp,
+        image_duration,
+        frame_rate,
+        font_size,
+        wave_color,
+    )
+    try:
+        output = run_ffmpeg(task_id, paths, options)
+        record_history(uuid.uuid4().hex[:8], task_id, output)
+        return output, history_table()
+    except HTTPException as exc:
+        raise gr.Error(str(exc.detail))
+
+
+def history_table():
+    with STATE_LOCK:
+        rows = [
+            [
+                item["task"],
+                item["filename"],
+                item["size"],
+                time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(item["created_at"])),
+            ]
+            for item in HISTORY[:10]
+        ]
+    return rows
+
+
+with gr.Blocks(title="Basyx FFmpeg Automation Hub") as ui:
+    gr.Markdown("# Basyx FFmpeg Automation Hub")
+    gr.Markdown("Upload media, choose a task, tune the options, and download the output.")
+    with gr.Row():
+        with gr.Column(scale=1):
+            task_input = gr.Dropdown(
+                choices=task_choices(),
+                value=task_choices()[0],
+                label="Task",
+            )
+            task_info = gr.Textbox(
+                label="Task requirements", value=describe_task(task_choices()[0]), lines=4
+            )
+            file_input = gr.File(label="Files", file_count="multiple")
+            url_input = gr.Textbox(label="Media URL")
+        with gr.Column(scale=1):
+            text_input = gr.Textbox(label="Text / Caption / Lyrics", lines=3, visible=False)
+            with gr.Row(visible=False) as trim_row:
+                start_input = gr.Textbox(label="Start", value="00:00:00")
+                end_input = gr.Textbox(label="End")
+            with gr.Row(visible=False) as duration_row:
+                duration_input = gr.Number(label="Duration seconds", value=5, precision=0)
+            with gr.Row(visible=False) as timestamp_row:
+                timestamp_input = gr.Textbox(label="Thumbnail timestamp", value="00:00:02")
+            with gr.Row(visible=False) as aspect_row:
+                aspect_input = gr.Dropdown(["9:16", "16:9", "1:1", "4:5"], label="Aspect", value="9:16")
+            with gr.Row(visible=False) as resolution_row:
+                resolution_input = gr.Dropdown(["480p", "720p", "1080p"], label="Resolution", value="720p")
+            with gr.Row(visible=True) as quality_row:
+                crf_input = gr.Slider(12, 35, value=23, step=1, label="CRF")
+                preset_input = gr.Dropdown(
+                    ["ultrafast", "veryfast", "fast", "medium", "slow"],
+                    label="Preset",
+                    value="fast",
+                )
+            with gr.Row(visible=False) as audio_row:
+                audio_bitrate_input = gr.Slider(64, 320, value=192, step=16, label="Audio kbps")
+                volume_input = gr.Slider(0, 2, value=0.3, step=0.05, label="Music volume")
+            with gr.Row(visible=False) as watermark_row:
+                position_input = gr.Dropdown(
+                    ["bottom-right", "bottom-left", "top-right", "top-left", "center"],
+                    label="Watermark position",
+                    value="bottom-right",
+                )
+                opacity_input = gr.Slider(0.1, 1, value=1, step=0.05, label="Watermark opacity")
+            with gr.Row(visible=False) as gif_row:
+                fps_input = gr.Slider(5, 30, value=10, step=1, label="GIF FPS")
+                width_input = gr.Slider(240, 1080, value=480, step=20, label="GIF width")
+            with gr.Row(visible=False) as speed_row:
+                speed_input = gr.Slider(0.25, 4, value=1.25, step=0.05, label="Speed")
+            with gr.Row(visible=False) as slideshow_row:
+                image_duration_input = gr.Slider(1, 15, value=3, step=1, label="Slide seconds")
+            with gr.Row(visible=False) as frames_row:
+                frame_rate_input = gr.Slider(0.1, 30, value=1, step=0.1, label="Frame FPS")
+            with gr.Row(visible=False) as font_row:
+                font_size_input = gr.Slider(18, 160, value=60, step=1, label="Font size")
+            wave_color_input = gr.Textbox(label="Wave color hex", value="00e5ff", visible=False)
+    run_button = gr.Button("Run")
+    output_file = gr.File(label="Output")
+    history_output = gr.Dataframe(
+        headers=["Task", "Filename", "Bytes", "Created"],
+        datatype=["str", "str", "number", "str"],
+        label="Recent outputs",
+        value=history_table,
+    )
+
+    task_input.change(
+        option_visibility,
+        inputs=task_input,
+        outputs=[
+            task_info,
+            text_input,
+            trim_row,
+            duration_row,
+            timestamp_row,
+            aspect_row,
+            resolution_row,
+            quality_row,
+            audio_row,
+            watermark_row,
+            gif_row,
+            speed_row,
+            slideshow_row,
+            frames_row,
+            font_row,
+            wave_color_input,
+        ],
+    )
+    run_button.click(
+        ui_handler,
+        inputs=[
+            file_input,
+            url_input,
+            task_input,
+            text_input,
+            start_input,
+            end_input,
+            duration_input,
+            aspect_input,
+            resolution_input,
+            crf_input,
+            preset_input,
+            audio_bitrate_input,
+            volume_input,
+            position_input,
+            opacity_input,
+            fps_input,
+            width_input,
+            speed_input,
+            timestamp_input,
+            image_duration_input,
+            frame_rate_input,
+            font_size_input,
+            wave_color_input,
+        ],
+        outputs=[output_file, history_output],
+    )
+
+app = gr.mount_gradio_app(app, ui, path="/")
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860)

services/ffmpeg_automation/requirements.txt

@@ -0,0 +1,6 @@
+fastapi
+uvicorn
+gradio
+python-multipart
+python-magic
+yt-dlp

services/ktts/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

services/ktts/.gitignore

@@ -0,0 +1,171 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc

services/ktts/Dockerfile

@@ -0,0 +1,22 @@
+# Base image with Python and essential libraries
+FROM python:3.8-slim
+
+# Install system-level dependencies
+RUN apt-get update && \
+    apt-get install -y espeak && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Set the working directory
+WORKDIR /app
+
+# Copy your files into the container
+COPY . .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Expose the port
+EXPOSE 7860
+
+# Run your app
+CMD ["python", "app.py"]

services/ktts/README.md

@@ -0,0 +1,9 @@
+---
+title: "Kokoro-82M TTS ONNX"
+emoji: "💡"
+colorFrom: "blue"
+colorTo: "green"
+sdk: "docker"
+app_file: app.py
+pinned: false
+---

services/ktts/README_git.md

@@ -0,0 +1,94 @@
+# Kokoro-82M ONNX Runtime Inference
+
+![Downloads](https://img.shields.io/github/downloads/yakhyo/kokoro-82m-onnx/total)
+[![GitHub Repo stars](https://img.shields.io/github/stars/yakhyo/kokoro-82m-onnx)](https://github.com/yakhyo/kokoro-82m-onnx/stargazers)
+[![GitHub Repository](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/yakhyo/kokoro-82m-onnx)
+
+This repository contains minimal code and resources for inference using the **Kokoro-82M** model. The repository supports inference using **ONNX Runtime**.
+
+<table>
+  <tr>
+    <td>Machine learning models rely on large datasets and complex algorithms to identify patterns and make predictions.</td>
+    <td>Did you know that honey never spoils? Archaeologists have found pots of honey in ancient Egyptian tombs that are over 3,000 years old and still edible!</td>
+  </tr>
+  <tr>
+    <td align="center">
+       <video controls autoplay loop src="https://github.com/user-attachments/assets/a8e9bfb7-777a-4b44-901c-c79c39c02c6f" ></video>
+    </td>
+    <td align="center">
+      <video controls autoplay loop src="https://github.com/user-attachments/assets/358723ad-c0ab-44a3-90cc-64d89c042c9a" ></video>
+    </td>
+  </tr>
+</table>
+
+## Features
+
+- **ONNX Runtime Inference**: Kokoro-82M (v0_19) Minimal ONNX Runtime Inference code. It supports `en-us` and `en-gb`.
+
+---
+
+## Installation
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/yakhyo/kokoro-82m.git
+   cd kokoro-82m
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Install `espeak` for text-to-speech functionality:
+   Linux:
+   ```bash
+   apt-get install espeak -y
+   ```
+
+---
+
+## Usage
+
+### Download ONNX Model
+
+[click to download](https://github.com/yakhyo/kokoro-82m/releases/download/v0.0.1/kokoro-v0_19.onnx)
+
+### Jupyter Notebook Inference Example
+
+Run inference using the jupyter notebook:
+
+[example.ipynb](example.ipynb)
+
+### CLI Inference
+
+Specify input text and model weights in `inference.py` then run:
+
+```bash
+python inference.py
+```
+
+### Gradio App
+
+Run below start Gradio App
+```bash
+python app.py
+```
+<div>
+  <img src="gradio_demo.png", width="100%>
+</div>
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+Model weights licensed under the [Apache 2.0](#license)
+
+---
+
+## Acknowledgments
+
+- https://huggingface.co/hexgrad/Kokoro-82M

services/ktts/app.py

@@ -0,0 +1,130 @@
+import os
+from pathlib import Path
+import gradio as gr
+import tempfile
+import soundfile as sf
+from models import Tokenizer, Kokoro
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse
+import uvicorn
+
+# --- EXISTING LOGIC (UNCHANGED) ---
+
+BASE_DIR = Path(__file__).resolve().parent
+tokenizer_cache = None
+kokoro_cache = {}
+model_status = "not_loaded"
+model_error = None
+
+def get_style_vector_choices(directory="voices"):
+    directory_path = BASE_DIR / directory
+    return [file.name for file in directory_path.iterdir() if file.suffix == ".pt"]
+
+def get_onnx_models(directory="weights"):
+    directory_path = BASE_DIR / directory
+    return [file.name for file in directory_path.iterdir() if file.suffix == ".onnx"]
+
+def local_tts(
+        text: str,
+        model_path: str,
+        style_vector: str,
+        output_file_format: str = "wav",
+        speed: float = 1.0
+):
+    global tokenizer_cache, model_status, model_error
+
+    if len(text) > 0:
+        try:
+            style_vector_path = str(BASE_DIR / "voices" / style_vector)
+            model_path_full = str(BASE_DIR / "weights" / model_path)
+            cache_key = (model_path_full, style_vector_path)
+
+            if tokenizer_cache is None:
+                tokenizer_cache = Tokenizer()
+
+            if cache_key not in kokoro_cache:
+                model_status = "loading"
+                model_error = None
+                kokoro_cache[cache_key] = Kokoro(model_path_full, style_vector_path, tokenizer=tokenizer_cache, lang='en-us')
+                model_status = "ready"
+
+            inference = kokoro_cache[cache_key]
+
+            audio, sample_rate = inference.generate_audio(text, speed=speed)
+
+            with tempfile.NamedTemporaryFile(suffix=f".{output_file_format}", delete=False) as temp_file:
+                sf.write(temp_file.name, audio, sample_rate)
+                temp_file_path = temp_file.name
+
+            return temp_file_path
+
+        except Exception as e:
+            model_status = "failed"
+            model_error = str(e)
+            raise gr.Error(f"An error occurred during TTS inference: {str(e)}")
+    else:
+        raise gr.Error("Input text cannot be empty.")
+
+style_vector_choices = get_style_vector_choices()
+onnx_models_choices = get_onnx_models()
+
+sample_outputs = [
+    ("Educational Note", "Machine learning models rely on large datasets and complex algorithms to identify patterns and make predictions.", str(BASE_DIR / "assets" / "edu_note.wav")),
+    ("Fun Fact", "Did you know that honey never spoils? Archaeologists have found pots of honey in ancient Egyptian tombs that are over 3,000 years old and still edible!", str(BASE_DIR / "assets" / "fun_fact.wav")),
+    ("Thanks", "Thank you for listening to this audio. It was generated by the Kokoro TTS model.", str(BASE_DIR / "assets" / "thanks.wav"))
+]
+
+example_texts = [
+    ["Machine learning models rely on large datasets and complex algorithms to identify patterns and make predictions."],
+    ["Did you know that honey never spoils? Archaeologists have found pots of honey in ancient Egyptian tombs that are over 3,000 years old and still edible!"],
+    ["Thank you for listening to this audio. It was generated by the Kokoro TTS model."]
+]
+
+# --- GRADIO INTERFACE (UNCHANGED) ---
+
+with gr.Blocks() as demo:
+    gr.Markdown("## <center> Kokoro TTS ONNX Inference | [GitHub Link](https://github.com/yakhyo/kokoro-onnx) </center>")
+    with gr.Row(variant="panel"):
+        model_path = gr.Dropdown(choices=onnx_models_choices, label="ONNX Model Path", value=onnx_models_choices[0])
+        style_vector = gr.Dropdown(choices=style_vector_choices, label="Style Vector", value=style_vector_choices[0])
+        output_file_format = gr.Dropdown(choices=["wav", "mp3"], label="Output Format", value="wav")
+        speed = gr.Slider(minimum=0.5, maximum=2.0, value=1.0, step=0.1, label="Speed")
+
+    text = gr.Textbox(label="Input Text", placeholder="Enter text to convert to speech.")
+    btn = gr.Button("Generate Speech")
+    output_audio = gr.Audio(label="Generated Audio", type="filepath")
+
+    btn.click(fn=local_tts, inputs=[text, model_path, style_vector, output_file_format, speed], outputs=output_audio)
+
+    gr.Examples(examples=example_texts, inputs=[text], label="Click an example to populate the input text")
+    gr.Markdown("### Sample Texts and Audio")
+    for topic, sample_text, sample_audio in sample_outputs:
+        with gr.Row():
+            gr.Textbox(value=sample_text, label=topic, interactive=False)
+            gr.Audio(value=sample_audio, label="Example Audio", type="filepath", interactive=False)
+
+# --- FASTAPI WRAPPER & STARTUP ---
+
+app = FastAPI()
+
+@app.post("/v1/audio/speech")
+async def api_speech(request: Request):
+    """
+    OpenAI-compatible /v1/audio/speech endpoint for automation.
+    Expects JSON: {"input": "text", "voice": "voice_file.pt", "model": "model_file.onnx"}
+    """
+    data = await request.json()
+    input_text = data.get("input", "")
+    m_path = data.get("model", onnx_models_choices[0])
+    s_vec = data.get("voice", style_vector_choices[0])
+    spd = float(data.get("speed", 1.0))
+    
+    file_path = local_tts(input_text, m_path, s_vec, speed=spd)
+    return FileResponse(file_path, media_type="audio/wav")
+
+# Mount Gradio into the FastAPI app
+app = gr.mount_gradio_app(app, demo, path="/")
+
+if __name__ == "__main__":
+    # Runs on port 7860 as expected by the Dockerfile/Hugging Face
+    uvicorn.run(app, host="0.0.0.0", port=7860)

services/ktts/assets/edu_note.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:880362273fe0348d8e73e9cf99cbe58573ccaac1e51628e92d4a362c8199d399
+size 416444

services/ktts/assets/fun_fact.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:245b8db3fc90671b02baa477ce0c2d08754b225ae95a853687191ad126de562e
+size 496844

services/ktts/assets/thanks.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d04843d86bff241ff659cf6c6931641797411dbf3b1532eee83914058bbc5a64
+size 288044

services/ktts/inference.py

@@ -0,0 +1,25 @@
+import soundfile as sf
+
+from models import Tokenizer, Kokoro
+
+
+def main():
+    model_path = "weights/kokoro-v0_19.onnx"
+    style_vector_path = "voices/af.pt"
+    output_filename = "test_out.wav"
+    tokenizer = Tokenizer()
+
+    text = (
+        "This approach ensures the entire text is processed without exceeding the token limit and outputs seamless audio for the full input. Let me know if you need further assistance!"
+    )
+
+    inference = Kokoro(model_path, style_vector_path, tokenizer=tokenizer, lang='en-us')
+    audio, sample_rate = inference.generate_audio(text, speed=1.0)
+
+    # Save the audio to a file
+    sf.write(output_filename, audio, sample_rate)
+    print(f"Audio saved to {output_filename}")
+
+
+if __name__ == "__main__":
+    main()

services/ktts/models/__init__.py

@@ -0,0 +1,2 @@
+from .kokoro import Kokoro
+from .tokenizer import Tokenizer

services/ktts/models/kokoro.py

@@ -0,0 +1,125 @@
+import torch
+import numpy as np
+import onnxruntime as ort
+
+TOKEN_LIMIT = 510
+SAMPLE_RATE = 24_000
+
+
+class Kokoro:
+    def __init__(self, model_path: str, style_vector_path: str, tokenizer, lang: str = 'en-us') -> None:
+        """
+        Initializes the ONNXInference class.
+
+        Args:
+            model_path (str): Path to the ONNX model file.
+            style_vector_path (str): Path to the style vector file.
+            lang (str): Language code for the tokenizer.
+        """
+        self.sess = ort.InferenceSession(model_path)
+        self.style_vector_path = style_vector_path
+        self.tokenizer = tokenizer
+        self.lang = lang
+
+    def preprocess(self, text):
+        """
+        Converts input text to tokenized numerical IDs and loads the style vector.
+
+        Args:
+            text (str): Input text to preprocess.
+
+        Returns:
+            tuple: Tokenized input and corresponding style vector.
+        """
+        # Convert text to phonemes and tokenize
+        phonemes = self.tokenizer.phonemize(text, lang=self.lang)
+        tokenized_phonemes = self.tokenizer.tokenize(phonemes)
+
+        if not tokenized_phonemes:
+            raise ValueError("No tokens found after tokenization")
+
+        style_vector = torch.load(self.style_vector_path, weights_only=True)
+
+        if len(tokenized_phonemes) > TOKEN_LIMIT:
+            token_chunks = self.split_into_chunks(tokenized_phonemes)
+
+            tokens_list = []
+            styles_list = []
+
+            for chunk in token_chunks:
+                token_chunk = [[0, *chunk, 0]]
+                style_chunk = style_vector[len(chunk)].numpy()
+
+                tokens_list.append(token_chunk)
+                styles_list.append(style_chunk)
+
+            return tokens_list, styles_list
+
+        style_vector = style_vector[len(tokenized_phonemes)].numpy()
+        tokenized_phonemes = [[0, *tokenized_phonemes, 0]]
+
+        return tokenized_phonemes, style_vector
+
+    @staticmethod
+    def split_into_chunks(tokens):
+        """
+        Splits a list of tokens into chunks of size TOKEN_LIMIT.
+
+        Args:
+            tokens (list): List of tokens to split.
+
+        Returns:
+            list: List of token chunks.
+        """
+        tokens_chunks = []
+        for i in range(0, len(tokens), TOKEN_LIMIT):
+            tokens_chunks.append(tokens[i:i+TOKEN_LIMIT])
+        return tokens_chunks
+
+    def infer(self, tokens, style_vector, speed=1.0):
+        """
+        Runs inference using the ONNX model.
+
+        Args:
+            tokens (list): Tokenized input for the model.
+            style_vector (numpy.ndarray): Style vector for the model.
+            speed (float): Speed parameter for inference.
+
+        Returns:
+            numpy.ndarray: Generated audio data.
+        """
+        # Perform inference
+        audio = self.sess.run(
+            None,
+            {
+                'tokens': tokens,
+                'style': style_vector,
+                'speed': np.array([speed], dtype=np.float32),
+            }
+        )[0]
+        return audio
+
+    def generate_audio(self, text,  speed=1.0):
+        """
+        Full pipeline: preprocess, infer, and save the generated audio.
+
+        Args:
+            text (str): Input text to generate audio from.
+            speed (float): Speed parameter for inference.
+        """
+        # Preprocess text
+        tokenized_data, styles_data = self.preprocess(text)
+
+        audio_segments = []
+        if len(tokenized_data) > 1:  # list of token chunks
+            for token_chunk, style_chunk in zip(tokenized_data, styles_data):
+                audio = self.infer(token_chunk, style_chunk, speed=speed)
+                audio_segments.append(audio)
+        else:  # single token less than input limit
+            # Run inference
+            audio = self.infer(tokenized_data, styles_data, speed=speed)
+            audio_segments.append(audio)
+
+        full_audio = np.concatenate(audio_segments)
+
+        return full_audio, SAMPLE_RATE

services/ktts/models/tokenizer.py

@@ -0,0 +1,238 @@
+import re
+from phonemizer import backend
+from typing import List
+
+
+class Tokenizer:
+    def __init__(self):
+        self.VOCAB = self._get_vocab()
+        self.phonemizers = {
+            'en-us': backend.EspeakBackend(language='en-us', preserve_punctuation=True, with_stress=True),
+            'en-gb': backend.EspeakBackend(language='en-gb', preserve_punctuation=True, with_stress=True),
+        }
+
+    @staticmethod
+    def _get_vocab():
+        """
+        Generates a mapping of symbols to integer indices for tokenization.
+
+        Returns:
+            dict: A dictionary where keys are symbols and values are unique integer indices.
+        """
+        # Define the symbols
+        _pad = "$"
+        _punctuation = ';:,.!?¡¿—…"«»“” '
+        _letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+        _letters_ipa = (
+            "ɑɐɒæɓʙβɔɕçɗɖðʤəɘɚɛɜɝɞɟʄɡɠɢʛɦɧħɥʜɨɪʝɭɬɫɮʟɱɯɰŋɳɲɴøɵɸθœɶʘɹɺɾɻʀʁɽʂʃʈʧʉʊʋⱱʌɣɤʍχʎʏʑʐʒʔʡʕʢǀǁǂǃˈˌːˑʼʴʰʱʲʷˠˤ˞↓↑→↗↘'̩'ᵻ"
+        )
+        symbols = [_pad] + list(_punctuation) + list(_letters) + list(_letters_ipa)
+
+        # Create a dictionary mapping each symbol to its index
+        return {symbol: index for index, symbol in enumerate(symbols)}
+
+    @staticmethod
+    def split_num(num: re.Match) -> str:
+        """
+        Processes numeric strings, formatting them as time, years, or other representations.
+
+        Args:
+            num (re.Match): A regex match object representing the numeric string.
+
+        Returns:
+            str: A formatted string based on the numeric input.
+        """
+        num = num.group()
+
+        # Handle time (e.g., "12:30")
+        if ':' in num:
+            hours, minutes = map(int, num.split(':'))
+            if minutes == 0:
+                return f"{hours} o'clock"
+            elif minutes < 10:
+                return f'{hours} oh {minutes}'
+            return f'{hours} {minutes}'
+
+        # Handle years or general numeric cases
+        year = int(num[:4])
+        if year < 1100 or year % 1000 < 10:
+            return num
+
+        left, right = num[:2], int(num[2:4])
+        suffix = 's' if num.endswith('s') else ''
+
+        # Format years
+        if 100 <= year % 1000 <= 999:
+            if right == 0:
+                return f'{left} hundred{suffix}'
+            elif right < 10:
+                return f'{left} oh {right}{suffix}'
+        return f'{left} {right}{suffix}'
+
+    @staticmethod
+    def flip_money(match: re.Match) -> str:
+        """
+        Converts monetary values to a textual representation.
+
+        Args:
+            m (re.Match): A regex match object representing the monetary value.
+
+        Returns:
+            str: A formatted string describing the monetary value.
+        """
+        m = m.group()
+        currency = 'dollar' if m[0] == '$' else 'pound'
+
+        # Handle whole amounts (e.g., "$10", "£20")
+        if '.' not in m:
+            singular = '' if m[1:] == '1' else 's'
+            return f'{m[1:]} {currency}{singular}'
+
+        # Handle amounts with decimals (e.g., "$10.50", "£5.25")
+        whole, cents = m[1:].split('.')
+        singular = '' if whole == '1' else 's'
+        cents = int(cents.ljust(2, '0'))  # Ensure 2 decimal places
+        coins = f"cent{'' if cents == 1 else 's'}" if m[0] == '$' else ('penny' if cents == 1 else 'pence')
+        return f'{whole} {currency}{singular} and {cents} {coins}'
+
+    @staticmethod
+    def point_num(match):
+        whole, fractional = match.group().split('.')
+        return ' point '.join([whole, ' '.join(fractional)])
+
+    def normalize_text(self, text: str) -> str:
+        """
+        Normalizes input text by replacing special characters, punctuation, and applying custom transformations.
+
+        Args:
+            text (str): Input text to normalize.
+
+        Returns:
+            str: Normalized text.
+        """
+        # Replace specific characters with standardized versions
+        replacements = {
+            chr(8216): "'",  # Left single quotation mark
+            chr(8217): "'",  # Right single quotation mark
+            '«': chr(8220),  # Left double angle quotation mark to left double quotation mark
+            '»': chr(8221),  # Right double angle quotation mark to right double quotation mark
+            chr(8220): '"',  # Left double quotation mark
+            chr(8221): '"',  # Right double quotation mark
+            '(': '«',        # Replace parentheses with angle quotation marks
+            ')': '»'
+        }
+        for old, new in replacements.items():
+            text = text.replace(old, new)
+
+        # Replace punctuation and add spaces
+        punctuation_replacements = {
+            '、': ',',
+            '。': '.',
+            '！': '!',
+            '，': ',',
+            '：': ':',
+            '；': ';',
+            '？': '?',
+        }
+        for old, new in punctuation_replacements.items():
+            text = text.replace(old, new + ' ')
+
+        # Apply regex-based replacements
+        text = re.sub(r'[^\S\n]', ' ', text)
+        text = re.sub(r'  +', ' ', text)
+        text = re.sub(r'(?<=\n) +(?=\n)', '', text)
+
+        # Expand abbreviations and handle special cases
+        abbreviation_patterns = [
+            (r'\bD[Rr]\.(?= [A-Z])', 'Doctor'),
+            (r'\b(?:Mr\.|MR\.(?= [A-Z]))', 'Mister'),
+            (r'\b(?:Ms\.|MS\.(?= [A-Z]))', 'Miss'),
+            (r'\b(?:Mrs\.|MRS\.(?= [A-Z]))', 'Mrs'),
+            (r'\betc\.(?! [A-Z])', 'etc'),
+            (r'(?i)\b(y)eah?\b', r"\1e'a"),
+        ]
+        for pattern, replacement in abbreviation_patterns:
+            text = re.sub(pattern, replacement, text)
+
+        # Handle numbers and monetary values
+        text = re.sub(r'\d*\.\d+|\b\d{4}s?\b|(?<!:)\b(?:[1-9]|1[0-2]):[0-5]\d\b(?!:)', self.split_num, text)
+        text = re.sub(r'(?<=\d),(?=\d)', '', text)  # Remove commas from numbers
+        text = re.sub(
+            r'(?i)[$£]\d+(?:\.\d+)?(?: hundred| thousand| (?:[bm]|tr)illion)*\b|[$£]\d+\.\d\d?\b',
+            self.flip_money,
+            text
+        )
+        text = re.sub(r'\d*\.\d+', self.point_num, text)
+        text = re.sub(r'(?<=\d)-(?=\d)', ' to ', text)
+
+        # Handle possessives and specific letter cases
+        text = re.sub(r'(?<=\d)S', ' S', text)
+        text = re.sub(r"(?<=[BCDFGHJ-NP-TV-Z])'?s\b", "'S", text)
+        text = re.sub(r"(?<=X')S\b", 's', text)
+
+        # Handle abbreviations with dots
+        text = re.sub(r'(?:[A-Za-z]\.){2,} [a-z]', lambda m: m.group().replace('.', '-'), text)
+        text = re.sub(r'(?i)(?<=[A-Z])\.(?=[A-Z])', '-', text)
+
+        return text.strip()
+
+    def tokenize(self, phonemes: str) -> List[int]:
+        """
+        Tokenizes a given string into a list of indices based on VOCAB.
+
+        Args:
+            text (str): Input string to tokenize.
+
+        Returns:
+            list: A list of integer indices corresponding to the characters in the input string.
+        """
+        return [self.VOCAB[x] for x in phonemes if x in self.VOCAB]
+
+    def phonemize(self, text: str, lang: str = 'en-us', normalize: bool = True) -> str:
+        """
+        Converts text to phonemes using the specified language phonemizer and applies normalization.
+
+        Args:
+            text (str): Input text to be phonemized.
+            lang (str): Language identifier ('en-us' or 'en-gb') for selecting the phonemizer.
+            normalize (bool): Whether to normalize the text before phonemization.
+
+        Returns:
+            str: A processed string of phonemes.
+        """
+        # Normalize text if required
+        if normalize:
+            text = self.normalize_text(text)
+
+        # Generate phonemes using the specified phonemizer
+        if lang not in self.phonemizers:
+            print(f"Language '{lang}' not supported. Defaulting to 'en-us'.")
+            lang = 'en-us'
+
+        phonemes = self.phonemizers[lang].phonemize([text])
+        phonemes = phonemes[0] if phonemes else ''
+
+        # Apply custom phoneme replacements
+        replacements = {
+            'kəkˈoːɹoʊ': 'kˈoʊkəɹoʊ',
+            'kəkˈɔːɹəʊ': 'kˈəʊkəɹəʊ',
+            'ʲ': 'j',
+            'r': 'ɹ',
+            'x': 'k',
+            'ɬ': 'l',
+        }
+        for old, new in replacements.items():
+            phonemes = phonemes.replace(old, new)
+
+        # Apply regex-based replacements
+        phonemes = re.sub(r'(?<=[a-zɹː])(?=hˈʌndɹɪd)', ' ', phonemes)
+        phonemes = re.sub(r' z(?=[;:,.!?¡¿—…"«»“” ]|$)', 'z', phonemes)
+
+        # Additional language-specific rules
+        if lang == 'a':
+            phonemes = re.sub(r'(?<=nˈaɪn)ti(?!ː)', 'di', phonemes)
+
+        # Filter out characters not in VOCAB
+        phonemes = ''.join(filter(lambda p: p in self.VOCAB, phonemes))
+
+        return phonemes.strip()

services/ktts/requirements.txt

@@ -0,0 +1,9 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch
+torchvision
+gradio
+phonemizer
+soundfile
+onnxruntime
+fastapi
+uvicorn

services/ktts/voices/af.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:03d6457d8d31306c7c4e7afc5040b446e6cb556b40fd80d07fbdbc8dc75d300c
+size 131

services/ktts/voices/af_bella.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:04339167efe7fe6dedf2eedfcdd357bbe3f4451619fcb67c0feea0708da0bb31
+size 131

services/ktts/voices/af_nicole.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4ca02cd41d325f5445b14805a3ec6985cae55a21cec91635f8c2038a5b288383
+size 131

services/ktts/voices/af_sarah.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2a6f3c43e3645896c7f0d57968f23d5ef5860b764bd4abb6d75076a1e7fda2e9
+size 131

services/ktts/voices/af_sky.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ab87dbbf5b86022f6c01aed43cb4bcd221fcb95241c1d1e67e27dde2978a59c5
+size 131

services/ktts/voices/am_adam.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd49625a3f7fba1b2ca0cd84b817bc0531fdc94bd256953c3636e8afb09df2f4
+size 131

services/ktts/voices/am_michael.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bba4bc7701cefde36070eaf65d20a689dae85282efc79c8d5770933a56c2ff76
+size 131

services/ktts/voices/bf_emma.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d5c84df49c195eb467a7a2e3f5f5e25624808f751db021fd5776495e1b9bb585
+size 131

services/ktts/voices/bf_isabella.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc23980551bb88178169bbdcfe3f10d69fc8b8ded9fdb0ec1123a3294b95266d
+size 131

services/ktts/voices/bm_george.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:27dff07c3aaf98f311475d2d3212f377325ab49b0ff566100424a3301252bbb2
+size 131

services/ktts/voices/bm_lewis.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c9d076bfb89ada363657fea4d40d67f4174929dc771fdc245547397714fd33dc
+size 131

services/ktts/weights/kokoro-quant.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6fa3c2d4e9dabfb2929b555c425c1c56f8333d46c47de8668de365a3d158de83
+size 134

services/ktts/weights/kokoro-v0_19.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d6bd36e46e7e6e1f118d2ae1a8ff807a24c06cdae309f3c4f34230ad9eb37652
+size 134

services/musicgen/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

services/musicgen/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# System deps
+RUN apt-get update && apt-get install -y \
+    git \
+    ffmpeg \
+    libsndfile1 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+
+RUN pip install --upgrade pip
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

services/musicgen/README.md

@@ -0,0 +1,10 @@
+---
+title: MusicGen
+emoji: 📚
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+pinned: false
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

services/musicgen/app.py

@@ -0,0 +1,74 @@
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+import gradio as gr
+from generate import generate_music
+
+# ======================
+# FASTAPI BACKEND
+# ======================
+
+api = FastAPI(title="AI Background Music Generator")
+
+@api.get("/health")
+def health():
+    return {"status": "running"}
+
+@api.post("/generate")
+async def api_generate(prompt: str, duration: int = 10):
+    file_path = generate_music(prompt, duration)
+
+    return FileResponse(
+        path=file_path,
+        media_type="audio/wav",
+        filename="music.wav"
+    )
+
+# ======================
+# GRADIO UI
+# ======================
+
+def ui_generate(prompt, duration):
+    audio = generate_music(prompt, duration)
+    return audio
+
+
+with gr.Blocks(
+    title="AI Background Music Generator",
+    theme=gr.themes.Soft()
+) as demo:
+
+    gr.Markdown("""
+# 🎵 AI Background Music Generator
+Generate royalty-free background music instantly.
+""")
+
+    prompt = gr.Textbox(
+        label="Music Description",
+        placeholder="Soft cinematic nasheed style..."
+    )
+
+    duration = gr.Slider(
+        minimum=5,
+        maximum=60,
+        value=10,
+        step=1,
+        label="Duration (seconds)"
+    )
+
+    btn = gr.Button("Generate")
+
+    output = gr.Audio(type="filepath")
+
+    btn.click(
+        fn=ui_generate,
+        inputs=[prompt, duration],
+        outputs=output
+    )
+
+
+# ======================
+# IMPORTANT FIX
+# ======================
+# Mount GRADIO as ROOT APP
+
+app = gr.mount_gradio_app(api, demo, path="/")

services/musicgen/generate.py

@@ -0,0 +1,58 @@
+import torch
+from transformers import AutoProcessor, MusicgenForConditionalGeneration
+import soundfile as sf
+import uuid
+
+MODEL_NAME = "facebook/musicgen-small"
+
+processor = None
+model = None
+device = "cuda" if torch.cuda.is_available() else "cpu"
+model_status = "not_loaded"
+model_error = None
+
+
+def _get_model():
+    global processor, model, model_status, model_error
+
+    if processor is None or model is None:
+        try:
+            model_status = "loading"
+            model_error = None
+            print("Loading MusicGen model...")
+            processor = AutoProcessor.from_pretrained(MODEL_NAME)
+            model = MusicgenForConditionalGeneration.from_pretrained(MODEL_NAME)
+            model.to(device)
+            model_status = "ready"
+        except Exception as exc:
+            model_status = "failed"
+            model_error = str(exc)
+            raise
+
+    return processor, model
+
+def generate_music(prompt, duration):
+    processor, model = _get_model()
+
+    inputs = processor(
+        text=[prompt],
+        padding=True,
+        return_tensors="pt"
+    ).to(device)
+
+    audio_values = model.generate(
+        **inputs,
+        max_new_tokens=int(duration * 50)
+    )
+
+    filename = f"/tmp/{uuid.uuid4()}.wav"
+
+    sampling_rate = model.config.audio_encoder.sampling_rate
+
+    sf.write(
+        filename,
+        audio_values[0, 0].cpu().numpy(),
+        sampling_rate
+    )
+
+    return filename

services/musicgen/requirements.txt

@@ -0,0 +1,10 @@
+fastapi
+uvicorn
+gradio
+torch
+torchaudio
+transformers
+accelerate
+soundfile
+scipy
+numpy

services/musicgen/storage.py

@@ -0,0 +1,24 @@
+import os
+from huggingface_hub import HfApi
+
+HF_TOKEN = os.getenv("HF_TOKEN")
+REPO_ID = "basyx/music-storage"
+
+api = HfApi()
+
+def upload_audio(filepath):
+
+    if not HF_TOKEN:
+        return None
+
+    filename = os.path.basename(filepath)
+
+    api.upload_file(
+        path_or_fileobj=filepath,
+        path_in_repo=filename,
+        repo_id=REPO_ID,
+        repo_type="dataset",
+        token=HF_TOKEN
+    )
+
+    return f"https://huggingface.co/datasets/{REPO_ID}/resolve/main/{filename}"

services/musicgen/styles.py

@@ -0,0 +1,21 @@
+STYLES = {
+
+    "nasheed": """
+Islamic vocal style nasheed,
+spiritual atmosphere,
+no musical instruments,
+warm emotional tone
+""",
+
+    "cinematic": """
+epic cinematic orchestral background,
+film score mood,
+emotional and inspirational
+""",
+
+    "lofi": """
+lofi chill background music,
+soft ambience,
+relaxed study atmosphere
+"""
+}

services/render_engine/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

services/render_engine/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+
+temp/
+exports/
+jobs/
+models/
+storage/
+
+.env
+.env.*
+!.env.example
+
+node_modules/
+.next/
+out/
+dist/
+coverage/
+*.tsbuildinfo
+
+frontend/node_modules/
+frontend/.next/
+frontend/out/
+frontend/.vercel/
+frontend/.env
+frontend/.env.*
+!frontend/.env.example
+

services/render_engine/Dockerfile

@@ -0,0 +1,40 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    TEMP_DIR=/app/temp \
+    EXPORTS_DIR=/app/exports \
+    JOBS_DIR=/app/jobs \
+    STORAGE_DIR=/app/storage \
+    AVA2LON_BASE_DIR=/app \
+    BASYX_BASE_DIR=/app \
+    MAX_RENDER_WORKERS=1 \
+    FFMPEG_TIMEOUT_SECONDS=900 \
+    DOWNLOAD_TIMEOUT_SECONDS=60 \
+    MAX_DOWNLOAD_BYTES=524288000 \
+    ALLOW_PRIVATE_ASSET_URLS=false \
+    WHISPER_MODEL_SIZE=tiny \
+    WHISPER_COMPUTE_TYPE=int8 \
+    WHISPER_DEVICE=cpu \
+    WHISPER_MODEL_DIR=/app/models \
+    MAX_RETRIES=3 \
+    JOB_RETENTION_SECONDS=86400
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    fonts-dejavu-core \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p /app/temp /app/exports /app/jobs /app/models /app/storage \
+    && chmod -R 777 /app/temp /app/exports /app/jobs /app/models /app/storage
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

services/render_engine/README.md

@@ -0,0 +1,365 @@
+---
+title: Basyx FFmpeg Rendering Engine
+emoji: 🎬
+colorFrom: green
+colorTo: yellow
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# Basyx FFmpeg Rendering Engine
+
+Basyx FFmpeg is a CPU-first rendering backend for short-form video automation. It is designed for Hugging Face Docker Spaces running on 2-8 CPU cores with 8-16 GB RAM and no GPU. The engine uses FFmpeg and FFprobe subprocess pipelines and never loads complete videos into Python memory.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    API["FastAPI REST API"] --> Jobs["Job Manager"]
+    Dashboard["Gradio Operator Dashboard"] --> Jobs
+    Jobs --> Engine["Render Engine"]
+    Engine --> Assets["Asset Probe + Metadata Cache"]
+    Engine --> Ingest["Remote URL + Upload Ingestion"]
+    Engine --> Normalize["Normalization"]
+    Engine --> Scenes["Scene Timeline"]
+    Engine --> Subtitles["SRT / ASS Subtitle Engine"]
+    Engine --> Transitions["Transition Filter Builder"]
+    Engine --> Audio["Voiceover + Ducking Mixer"]
+    Engine --> Exports["Export Manager"]
+    Ingest --> FFmpeg["FFmpeg / FFprobe"]
+    Normalize --> FFmpeg
+    Scenes --> FFmpeg
+    Subtitles --> FFmpeg
+    Transitions --> FFmpeg
+    Audio --> FFmpeg
+```
+
+Package layout:
+
+```text
+renderer/
+  core/          settings, models, ingestion, orchestration
+  ffmpeg/        command builder, runner, probing, normalization
+  subtitles/     SRT and ASS generation
+  transitions/   xfade graph generation
+  audio/         voiceover and music ducking
+  scenes/        timeline validation
+  templates/     caption templates
+  exports/       final deliverables
+  jobs/          durable job records and retries
+```
+
+## REST API
+
+All API endpoints are served at the Space root. Asset fields may be absolute container paths or public `http`/`https` URLs. Remote assets are downloaded into a job-local temp directory with timeout and size limits before rendering.
+
+### `POST /render`
+
+Submit one render job.
+
+```json
+{
+  "template": "tiktok_classic",
+  "output_name": "campaign_clip.mp4",
+  "voiceover": "https://cdn.example.com/voiceover.wav",
+  "background_music": "https://cdn.example.com/music.mp3",
+  "subtitle_format": "ass",
+  "auto_subtitles": true,
+  "subtitle_language": "en",
+  "whisper_model_size": "tiny",
+  "preset": "tiktok_9_16_fast",
+  "callback_url": "https://n8n.example.com/webhook/render-complete",
+  "export_target": "local",
+  "audio_normalize": true,
+  "preview": false,
+  "normalize": true,
+  "scenes": [
+    {
+      "start": 0,
+      "duration": 5,
+      "media": "https://cdn.example.com/scene1.mp4",
+      "caption": "Launch faster with automated rendering",
+      "transition": "fade"
+    }
+  ]
+}
+```
+
+Response:
+
+```json
+{
+  "job_id": "job_abc123",
+  "status_url": "/status/job_abc123",
+  "download_url": "/download/job_abc123?token=..."
+}
+```
+
+### `GET /presets`
+
+Returns available render presets and caption templates. Presets let n8n submit compact requests such as `tiktok_9_16_fast`, `youtube_shorts_hd`, `podcast_square`, `reels_with_subtitles`, and `draft_preview`.
+
+### `POST /render/ai-reels`
+
+Submit a single-call AI Reels job using an existing voiceover and asset list. TTS is intentionally provider-pluggable in v1; the production path requires a supplied voiceover.
+
+```json
+{
+  "script": "Launch faster with automated rendering.",
+  "voiceover": "https://cdn.example.com/voiceover.wav",
+  "assets": ["https://cdn.example.com/scene1.jpg", "https://cdn.example.com/scene2.mp4"],
+  "template": "youtube_shorts",
+  "output_name": "ai_reel.mp4"
+}
+```
+
+### `POST /render/batch`
+
+Submit multiple render jobs. The worker pool defaults to one active render to avoid RAM exhaustion.
+
+```json
+{
+  "jobs": [
+    {
+      "template": "modern_minimal",
+      "output_name": "clip_a.mp4",
+      "scenes": [{"start": 0, "duration": 3, "media": "https://cdn.example.com/a.mp4"}]
+    }
+  ]
+}
+```
+
+### `POST /scene-builder`
+
+Build a timeline from a script and asset list.
+
+```json
+{
+  "script": "One script can be split across several short scenes.",
+  "assets": ["https://cdn.example.com/a.mp4", "https://cdn.example.com/b.jpg"],
+  "duration": 8,
+  "transition": "fade"
+}
+```
+
+### `POST /assets/upload`
+
+Upload files from automation tools such as n8n and receive staged paths that can be used in `/render`.
+
+Multipart form field:
+
+- `files`: one or more images, videos, GIFs, or audio files.
+
+Response:
+
+```json
+{
+  "assets": [
+    {
+      "filename": "clip.mp4",
+      "path": "/app/temp/uploads/abc/clip.mp4",
+      "reference": "upload://clip.mp4"
+    }
+  ]
+}
+```
+
+### `POST /render/upload`
+
+Submit a render job and files in one multipart request.
+
+Multipart fields:
+
+- `request_json`: render payload JSON.
+- `files`: uploaded files referenced by `upload://filename`.
+
+Example `request_json`:
+
+```json
+{
+  "template": "tiktok_classic",
+  "output_name": "n8n_clip.mp4",
+  "scenes": [
+    {
+      "start": 0,
+      "duration": 5,
+      "media": "upload://clip.mp4",
+      "caption": "Rendered from n8n"
+    }
+  ],
+  "voiceover": "upload://voice.wav"
+}
+```
+
+### `POST /render/ai-reels/upload`
+
+Multipart AI Reels endpoint. Use `upload://filename` inside `voiceover`, `background_music`, and `assets`.
+
+### `POST /transcribe`
+
+Transcribe local or remote audio/video with faster-whisper.
+
+```json
+{
+  "audio": "https://cdn.example.com/voiceover.wav",
+  "model_size": "tiny",
+  "language": "en",
+  "task": "transcribe",
+  "word_timestamps": true,
+  "vad_filter": true
+}
+```
+
+Response includes `text`, detected `language`, segment timings, and optional word timings. Use this endpoint from n8n when you want subtitles before rendering.
+
+### `POST /transcribe/upload`
+
+Multipart faster-whisper endpoint for direct n8n file uploads.
+
+Multipart fields:
+
+- `file`: audio or video file.
+- `model_size`: optional Whisper model, default `WHISPER_MODEL_SIZE`.
+- `language`: optional ISO language code.
+- `word_timestamps`: optional boolean, default `true`.
+
+### `POST /subtitles`
+
+Generate SRT or ASS files from timed events.
+
+```json
+{
+  "format": "ass",
+  "template": "tiktok_zoom",
+  "events": [
+    {"start": 0, "end": 1.2, "text": "Hello world"}
+  ]
+}
+```
+
+### `GET /status/{job_id}`
+
+Returns job state, logs, FFmpeg commands, metrics, output path, and failure reason.
+
+States: `PENDING`, `RUNNING`, `FAILED`, `COMPLETED`.
+
+### `GET /download/{job_id}`
+
+Returns the completed MP4 deliverable. Downloads require the signed token returned by render submission. If the job is still running, the endpoint returns `409`.
+
+### `POST /cancel/{job_id}`
+
+Requests job cancellation. Pending jobs are marked `CANCELLED`; running jobs are marked `CANCEL_REQUESTED` and stop before the next guarded execution point.
+
+### `POST /admin/cleanup`
+
+Deletes expired job records, old exports, and staged upload folders. Default retention is controlled by `JOB_RETENTION_SECONDS`.
+
+### `POST /inspect`
+
+Probe one local asset path and return MIME type, duration, codecs, bitrate, resolution, FPS, stream list, and cache metadata.
+
+## n8n Workflow Integration
+
+Recommended URL-based flow:
+
+1. Use an HTTP Request node with `POST https://YOUR-SPACE.hf.space/render`.
+2. Pass public file URLs from S3, Supabase Storage, Cloudinary, Google Drive direct-download links, or another CDN in `scenes[].media`, `voiceover`, and `background_music`.
+3. Set `auto_subtitles` to `true` when you want faster-whisper captions generated from `voiceover`.
+4. Add `callback_url` to receive a POST when the job completes or fails.
+5. Poll `GET https://YOUR-SPACE.hf.space/status/{{$json.job_id}}` only if you do not use callbacks.
+6. Download the final MP4 from the signed `download_url`.
+
+Multipart flow:
+
+1. Use an HTTP Request node set to multipart form-data.
+2. Send `request_json` as a text field.
+3. Attach files under the `files` field.
+4. Reference those files in JSON as `upload://exact-filename.ext`.
+
+Security defaults:
+
+- Only `http` and `https` remote assets are accepted.
+- Private, localhost, link-local, and multicast hosts are blocked by default.
+- Set `ALLOW_PRIVATE_ASSET_URLS=true` only for trusted self-hosted deployments.
+- `MAX_DOWNLOAD_BYTES` limits remote downloads and multipart upload totals.
+- `WHISPER_MODEL_SIZE=tiny` and `WHISPER_COMPUTE_TYPE=int8` are the recommended CPU defaults.
+- `BASYX_SIGNING_SECRET` should be set as a Space secret before public deployment.
+
+## Operator Dashboard
+
+The dashboard is available at `/dashboard`. It provides production operator tools for render submission, batch submission, AI Reels submission, job status, logs, downloads, and asset inspection.
+
+## Caption Templates
+
+Built-in templates:
+
+- `tiktok_classic`
+- `tiktok_zoom`
+- `alex_hormozi`
+- `modern_minimal`
+- `youtube_shorts`
+- `podcast_style`
+- `news_style`
+
+Templates are selected per request and do not require code changes.
+
+## CPU And RAM Tuning
+
+- Keep `MAX_RENDER_WORKERS=1` for 8 GB RAM deployments.
+- Use `OUTPUT_PRESET=veryfast` or `ultrafast` for faster CPU rendering.
+- Use `OUTPUT_CRF=23-28` to balance quality and file size.
+- Keep source assets near the target duration to reduce normalization work.
+- Prefer pre-trimmed voiceovers and assets for batch workloads.
+- Start with `WHISPER_MODEL_SIZE=tiny` or `base` on free/CPU Spaces.
+- Use `preview=true` for low-resolution draft renders.
+- Use `audio_normalize=true` for voiceover or podcast-style content.
+
+## Reliability
+
+- FFmpeg subprocesses are killed after `FFMPEG_TIMEOUT_SECONDS`.
+- Remote asset downloads are killed after `DOWNLOAD_TIMEOUT_SECONDS`.
+- Remote and multipart input size is capped by `MAX_DOWNLOAD_BYTES`.
+- faster-whisper models are loaded lazily and cached under `WHISPER_MODEL_DIR`.
+- Webhook callbacks are best-effort and callback failures are written to job logs.
+- `export_target=local` copies completed renders to `STORAGE_DIR`.
+- `export_target=https://...` uploads the completed MP4 with HTTP `PUT`, which works with presigned URLs from S3, Supabase Storage, and similar providers.
+- Jobs retry up to `MAX_RETRIES`.
+- Intermediate files are created under `TEMP_DIR` and removed after export.
+- Job records retain command history, logs, render time, output size, and failure reasons.
+
+## Docker Deployment
+
+Build locally:
+
+```bash
+docker build -t basyx-ffmpeg .
+docker run --rm -p 7860:7860 basyx-ffmpeg
+```
+
+Open:
+
+- API: `http://localhost:7860/health`
+- Dashboard: `http://localhost:7860/dashboard`
+
+## Hugging Face Spaces Deployment
+
+Create a Docker Space, push this repository, and keep the README metadata above. The container listens on port `7860`, and the Space exposes the FastAPI service plus the dashboard.
+
+## Testing
+
+Run:
+
+```bash
+pytest --cov=renderer --cov-report=term-missing
+```
+
+Integration tests use mocked FFmpeg/FFprobe where possible and small generated media where necessary.
+
+## Known v1 Limits
+
+- Bundled TTS is not included. The AI Reels endpoint requires a supplied voiceover and keeps narration generation behind a provider interface for future integration.
+- Advanced caption animation is implemented through ASS effects and FFmpeg-compatible filter behavior, not GPU animation layers.
+- Batch rendering is intentionally sequential by default for constrained CPU/RAM Spaces.

services/render_engine/api.py

@@ -0,0 +1,1314 @@
+from __future__ import annotations
+
+import json
+import shutil
+import uuid
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from fastapi import Depends, FastAPI, File, Form, Header, HTTPException, Query, UploadFile
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+
+from renderer.core.config import Settings
+from renderer.core.ingest import stage_upload
+from renderer.core.models import AIReelsRequest, RenderRequest, Scene
+from renderer.core.security import verify_download_token
+from renderer.core.utils import safe_filename
+from renderer.jobs import JobManager
+from renderer.platform import PlatformProcessor, supported_toolkit_tasks
+from renderer.scenes import Timeline
+from renderer.studio import (
+    ProjectStore,
+    StudioTaskProcessor,
+    add_effect,
+    add_filter,
+    add_keyframe,
+    add_transition,
+    capability_catalog,
+)
+from renderer import RenderEngine
+from renderer.subtitles import SubtitleEvent, SubtitleGenerator
+from renderer.templates import (
+    apply_creative_style,
+    apply_preset,
+    creative_style_metadata,
+    get_creative_style,
+    list_creative_styles,
+    list_platform_profiles,
+    list_presets,
+    list_scene_effects,
+    list_templates,
+    platform_profile_metadata,
+    scene_effect_metadata,
+)
+from renderer.transitions import TransitionBuilder
+
+settings = Settings()
+settings.ensure_dirs()
+job_manager = JobManager(settings)
+project_manager = ProjectStore(settings)
+api = FastAPI(title="Ava2lon Studio AI", version="2.0.0")
+
+API_KEY_HEADER = "X-API-Key"
+
+
+def _verify_api_key(api_key: str | None = Header(default=None, alias=API_KEY_HEADER)) -> None:
+    configured = getattr(settings, "api_key", "")
+    if configured and api_key != configured:
+        raise HTTPException(status_code=401, detail="Invalid or missing API key")
+
+def _submission_response(job_id: str) -> dict[str, str]:
+    download_url = f"/download/{job_id}"
+    try:
+        record = job_manager.get(job_id)
+    except KeyError:
+        token = None
+    else:
+        token = record.download_token
+    if token:
+        download_url = f"{download_url}?token={token}"
+    return {"job_id": job_id, "status_url": f"/status/{job_id}", "download_url": download_url}
+
+
+class ScenePayload(BaseModel):
+    start: float = Field(ge=0)
+    duration: float = Field(gt=0)
+    media: str
+    caption: str = ""
+    transition: str = "fade"
+    background: str = "blur"
+    layout: str = "fill"
+    effect: str | None = None
+
+
+class RenderPayload(BaseModel):
+    scenes: list[ScenePayload]
+    template: str = "tiktok_classic"
+    preset: str | None = None
+    creative_style: str | None = None
+    platform: str | None = None
+    output_name: str = "render.mp4"
+    voiceover: str | None = None
+    background_music: str | None = None
+    music_volume: float = Field(default=0.316, ge=0, le=2)
+    music_fade_in: float = Field(default=0.0, ge=0)
+    music_fade_out: float = Field(default=0.0, ge=0)
+    music_loop: bool = True
+    music_start: float = Field(default=0.0, ge=0)
+    music_ducking: bool = True
+    voice_volume: float = Field(default=1.0, ge=0, le=2)
+    subtitle_format: str = "ass"
+    auto_subtitles: bool = False
+    subtitle_language: str | None = None
+    whisper_model_size: str | None = None
+    preview: bool = False
+    audio_normalize: bool = False
+    watermark: str | None = None
+    watermark_position: str = "bottom-right"
+    intro: str | None = None
+    outro: str | None = None
+    callback_url: str | None = None
+    export_target: str | None = None
+    priority: int = 0
+    scheduled_at: float | None = None
+    normalize: bool = True
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AIReelsPayload(BaseModel):
+    script: str
+    voiceover: str
+    assets: list[str]
+    template: str = "tiktok_classic"
+    creative_style: str | None = None
+    platform: str | None = None
+    output_name: str = "ai_reel.mp4"
+    background_music: str | None = None
+    music_volume: float = Field(default=0.316, ge=0, le=2)
+    music_fade_in: float = Field(default=0.0, ge=0)
+    music_fade_out: float = Field(default=0.0, ge=0)
+    music_loop: bool = True
+    music_start: float = Field(default=0.0, ge=0)
+    music_ducking: bool = True
+    voice_volume: float = Field(default=1.0, ge=0, le=2)
+
+
+class BatchPayload(BaseModel):
+    jobs: list[RenderPayload]
+
+
+class UploadedAsset(BaseModel):
+    filename: str
+    path: str
+    reference: str
+    kind: str = "other"
+    metadata: dict[str, Any] | None = None
+
+
+class TranscribePayload(BaseModel):
+    audio: str
+    model_size: str | None = None
+    language: str | None = None
+    task: str = "transcribe"
+    beam_size: int = Field(default=5, ge=1, le=10)
+    vad_filter: bool = True
+    word_timestamps: bool = True
+
+
+class SubtitlePayload(BaseModel):
+    events: list[dict[str, Any]]
+    format: str = "srt"
+    template: str = "tiktok_classic"
+
+
+class SceneBuildPayload(BaseModel):
+    script: str
+    assets: list[str]
+    duration: float | None = None
+    transition: str = "fade"
+    creative_style: str | None = None
+
+
+class IngestSourcePayload(BaseModel):
+    url: str
+    type: str | None = None
+    name: str | None = None
+
+
+class IngestPayload(BaseModel):
+    sources: list[IngestSourcePayload]
+    callback_url: str | None = None
+
+
+class AnalyzePayload(BaseModel):
+    media: str
+    transcript: str = ""
+    platform: str | None = None
+    callback_url: str | None = None
+
+
+class ClipsPayload(BaseModel):
+    media: str
+    clips: list[dict[str, Any]] | None = None
+    callback_url: str | None = None
+
+
+class ToolkitPayload(BaseModel):
+    task: str
+    input: str | None = None
+    media: str | None = None
+    output_name: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+    callback_url: str | None = None
+    export_target: str | None = None
+    model_config = {"extra": "allow"}
+
+
+class ThumbnailPayload(BaseModel):
+    media: str
+    text: str = ""
+    timestamp: float | None = None
+    template: str = "bold"
+    callback_url: str | None = None
+
+
+class MetadataPayload(BaseModel):
+    topic: str = ""
+    transcript: str = ""
+    platform: str | None = None
+    callback_url: str | None = None
+
+
+class PublishPayload(BaseModel):
+    media: str | None = None
+    asset: str | None = None
+    title: str | None = None
+    description: str | None = None
+    platforms: list[str] = Field(default_factory=list)
+    platform: str | None = None
+    scheduled_at: str | None = None
+    draft: bool = True
+    callback_url: str | None = None
+
+
+class ProjectPayload(BaseModel):
+    name: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    export_settings: dict[str, Any] = Field(default_factory=dict)
+    template: dict[str, Any] | None = None
+
+
+class ProjectSavePayload(BaseModel):
+    project_id: str | None = None
+    project: dict[str, Any]
+
+
+class ProjectAssetPayload(BaseModel):
+    project_id: str
+    asset: dict[str, Any]
+
+
+class TimelineAddPayload(BaseModel):
+    project_id: str
+    track_type: str = "video"
+    track_id: str | None = None
+    item: dict[str, Any] = Field(default_factory=dict)
+
+
+class TimelineOperationPayload(BaseModel):
+    project_id: str
+    operation: str = "drag"
+    item_id: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+class EffectApplyPayload(BaseModel):
+    project_id: str | None = None
+    target_id: str | None = None
+    item_id: str | None = None
+    effect: str
+    params: dict[str, Any] = Field(default_factory=dict)
+    callback_url: str | None = None
+
+
+class FilterApplyPayload(BaseModel):
+    project_id: str | None = None
+    target_id: str | None = None
+    item_id: str | None = None
+    filter: str
+    params: dict[str, Any] = Field(default_factory=dict)
+    lut: str | None = None
+    callback_url: str | None = None
+
+
+class TransitionAddPayload(BaseModel):
+    project_id: str | None = None
+    from_item_id: str | None = None
+    to_item_id: str | None = None
+    target_id: str | None = None
+    transition: str
+    duration: float = Field(default=0.45, gt=0)
+    params: dict[str, Any] = Field(default_factory=dict)
+    callback_url: str | None = None
+
+
+class KeyframePayload(BaseModel):
+    project_id: str
+    target_id: str
+    property: str
+    time: float = Field(ge=0)
+    value: Any
+    easing: str = "linear"
+
+
+class GenerationPayload(BaseModel):
+    prompt: str | None = None
+    text: str | None = None
+    media: str | None = None
+    provider: str | None = None
+    callback_url: str | None = None
+    export_target: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+    model_config = {"extra": "allow"}
+
+
+class CaptionGeneratePayload(BaseModel):
+    media: str | None = None
+    audio: str | None = None
+    text: str | None = None
+    transcript: str | None = None
+    events: list[dict[str, Any]] | None = None
+    template: str = "capcut"
+    language: str | None = None
+    engine: str = "whisper"
+    word_timestamps: bool = True
+    emoji_insertion: bool = False
+    speaker_detection: bool = False
+    karaoke: bool = True
+    animated: bool = True
+    callback_url: str | None = None
+    model_config = {"extra": "allow"}
+
+
+class AIToolPayload(BaseModel):
+    project_id: str | None = None
+    media: str | None = None
+    transcript: str | None = None
+    text: str | None = None
+    platform: str | None = None
+    callback_url: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+    model_config = {"extra": "allow"}
+
+
+class ProjectRenderPayload(BaseModel):
+    output_name: str = "project_render.mp4"
+    template: str | None = None
+    preset: str | None = None
+    creative_style: str | None = None
+    platform: str | None = None
+    callback_url: str | None = None
+    export_target: str | None = None
+    preview: bool = False
+    normalize: bool = True
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+@api.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@api.get("/monitor")
+def monitor() -> dict[str, Any]:
+    return _monitor_payload()
+
+
+@api.get("/queue")
+def queue() -> dict[str, Any]:
+    return job_manager.summary()
+
+
+@api.get("/workers")
+def workers() -> dict[str, Any]:
+    return {
+        "max_workers": settings.max_workers,
+        "ffmpeg_timeout_seconds": settings.ffmpeg_timeout_seconds,
+        "whisper_device": settings.whisper_device,
+        "whisper_model_size": settings.whisper_model_size,
+        "toolkit_tasks": supported_toolkit_tasks(),
+    }
+
+
+@api.get("/presets")
+def presets() -> dict[str, Any]:
+    return {
+        "presets": list_presets(),
+        "caption_templates": list_templates(),
+        "platforms": list_platform_profiles(),
+        "creative_styles": list_creative_styles(),
+        "scene_effects": list_scene_effects(),
+        "transitions": TransitionBuilder().list_transitions(),
+        "creative_style_metadata": creative_style_metadata(),
+        "scene_effect_metadata": scene_effect_metadata(),
+        "toolkit_tasks": supported_toolkit_tasks(),
+    }
+
+
+@api.get("/platforms")
+def platforms() -> dict[str, dict[str, Any]]:
+    return {"platforms": platform_profile_metadata()}
+
+
+@api.get("/toolkit/tasks")
+def toolkit_tasks() -> dict[str, list[str]]:
+    return {"tasks": supported_toolkit_tasks()}
+
+
+@api.get("/capabilities")
+def capabilities() -> dict[str, Any]:
+    catalog = capability_catalog()
+    catalog["runtime"] = {
+        "toolkit_tasks": supported_toolkit_tasks(),
+        "caption_templates": list_templates(),
+        "creative_styles": list_creative_styles(),
+        "scene_effects": list_scene_effects(),
+        "platforms": list_platform_profiles(),
+        "transitions": TransitionBuilder().list_transitions(),
+    }
+    return catalog
+
+
+@api.get("/effects")
+def effects() -> dict[str, Any]:
+    catalog = capability_catalog()
+    return {"effects": catalog["effects"], "scene_effects": scene_effect_metadata()}
+
+
+@api.get("/filters")
+def filters() -> dict[str, Any]:
+    return {"filters": capability_catalog()["filters"]}
+
+
+@api.get("/transitions")
+def transitions() -> dict[str, Any]:
+    return {"families": capability_catalog()["transitions"], "ffmpeg": TransitionBuilder().list_transitions()}
+
+
+@api.get("/templates/catalog")
+def templates_catalog() -> dict[str, Any]:
+    return {
+        "categories": capability_catalog()["templates"],
+        "caption_templates": list_templates(),
+        "render_presets": list_presets(),
+        "creative_styles": creative_style_metadata(),
+    }
+
+
+@api.get("/projects")
+def list_projects() -> dict[str, list[dict[str, Any]]]:
+    return {"projects": project_manager.list()}
+
+
+@api.post("/projects", dependencies=[Depends(_verify_api_key)])
+def create_project(payload: ProjectPayload) -> dict[str, Any]:
+    project = project_manager.create(payload.name, metadata=payload.metadata, template=payload.template)
+    if payload.export_settings:
+        project["export_settings"].update(payload.export_settings)
+        project = project_manager.save(project["id"], project)
+    return {"project": project}
+
+
+@api.post("/project/create", dependencies=[Depends(_verify_api_key)])
+def project_create(payload: ProjectPayload) -> dict[str, Any]:
+    return create_project(payload)
+
+
+@api.get("/project/{project_id}")
+def project_get(project_id: str) -> dict[str, Any]:
+    try:
+        return {"project": project_manager.get(project_id)}
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Project not found") from exc
+
+
+@api.post("/project/save", dependencies=[Depends(_verify_api_key)])
+def project_save(payload: ProjectSavePayload) -> dict[str, Any]:
+    project_id = payload.project_id or str(payload.project.get("id") or safe_filename(payload.project.get("name", "project")))
+    return {"project": project_manager.save(project_id, payload.project)}
+
+
+@api.post("/project/assets/add", dependencies=[Depends(_verify_api_key)])
+def project_asset_add(payload: ProjectAssetPayload) -> dict[str, Any]:
+    try:
+        return {"project": project_manager.add_asset(payload.project_id, payload.asset)}
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Project not found") from exc
+
+
+@api.post("/timeline/add", dependencies=[Depends(_verify_api_key)])
+def timeline_add(payload: TimelineAddPayload) -> dict[str, Any]:
+    try:
+        project = project_manager.add_to_timeline(payload.project_id, payload.item, payload.track_type, payload.track_id)
+        return {"project": project}
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Project not found") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@api.post("/timeline/operation", dependencies=[Depends(_verify_api_key)])
+def timeline_operation(payload: TimelineOperationPayload) -> dict[str, Any]:
+    try:
+        project = project_manager.timeline_operation(payload.project_id, payload.operation, payload.item_id, payload.params)
+        return {"project": project}
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Timeline item or project not found") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@api.post("/timeline/split", dependencies=[Depends(_verify_api_key)])
+def timeline_split(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "split"
+    return timeline_operation(payload)
+
+
+@api.post("/timeline/trim", dependencies=[Depends(_verify_api_key)])
+def timeline_trim(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "trim"
+    return timeline_operation(payload)
+
+
+@api.post("/timeline/ripple-delete", dependencies=[Depends(_verify_api_key)])
+def timeline_ripple_delete(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "ripple_delete"
+    return timeline_operation(payload)
+
+
+@api.post("/timeline/insert", dependencies=[Depends(_verify_api_key)])
+def timeline_insert(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "insert"
+    return timeline_operation(payload)
+
+
+@api.post("/timeline/replace", dependencies=[Depends(_verify_api_key)])
+def timeline_replace(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "replace"
+    return timeline_operation(payload)
+
+
+@api.post("/timeline/group", dependencies=[Depends(_verify_api_key)])
+def timeline_group(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "group"
+    return timeline_operation(payload)
+
+
+@api.post("/timeline/lock", dependencies=[Depends(_verify_api_key)])
+def timeline_lock(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "lock"
+    return timeline_operation(payload)
+
+
+@api.post("/timeline/hide", dependencies=[Depends(_verify_api_key)])
+def timeline_hide(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "hide"
+    return timeline_operation(payload)
+
+
+@api.post("/timeline/duplicate", dependencies=[Depends(_verify_api_key)])
+def timeline_duplicate(payload: TimelineOperationPayload) -> dict[str, Any]:
+    payload.operation = "duplicate"
+    return timeline_operation(payload)
+
+
+@api.post("/effect/apply", dependencies=[Depends(_verify_api_key)])
+def effect_apply(payload: EffectApplyPayload) -> dict[str, Any]:
+    target_id = payload.target_id or payload.item_id
+    if payload.project_id and target_id:
+        try:
+            project = project_manager.get(payload.project_id)
+            record = add_effect(project, target_id, payload.effect, payload.params)
+            project = project_manager.save(payload.project_id, project)
+            return {"effect": record, "project": project}
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail="Project or target item not found") from exc
+    data = {"task": payload.effect, "input": target_id, "params": payload.params, "callback_url": payload.callback_url}
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).ai_tool("auto_edit", data, task_id),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/filter/apply", dependencies=[Depends(_verify_api_key)])
+def filter_apply(payload: FilterApplyPayload) -> dict[str, Any]:
+    target_id = payload.target_id or payload.item_id
+    params = dict(payload.params)
+    if payload.lut:
+        params["lut"] = payload.lut
+    if payload.project_id and target_id:
+        try:
+            project = project_manager.get(payload.project_id)
+            record = add_filter(project, target_id, payload.filter, params)
+            project = project_manager.save(payload.project_id, project)
+            return {"filter": record, "project": project}
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail="Project or target item not found") from exc
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).ai_tool("auto_color_match", payload.model_dump(), task_id),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/transition/add", dependencies=[Depends(_verify_api_key)])
+def transition_add(payload: TransitionAddPayload) -> dict[str, Any]:
+    if payload.project_id and payload.from_item_id and payload.to_item_id:
+        try:
+            project = project_manager.get(payload.project_id)
+            record = add_transition(project, payload.from_item_id, payload.to_item_id, payload.transition, payload.duration)
+            project = project_manager.save(payload.project_id, project)
+            return {"transition": record, "project": project}
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail="Project not found") from exc
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).ai_tool("auto_edit", payload.model_dump(), task_id),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/keyframe/add", dependencies=[Depends(_verify_api_key)])
+def keyframe_add(payload: KeyframePayload) -> dict[str, Any]:
+    try:
+        project = project_manager.get(payload.project_id)
+        record = add_keyframe(project, payload.target_id, payload.property, payload.time, payload.value, payload.easing)
+        project = project_manager.save(payload.project_id, project)
+        return {"keyframe": record, "project": project}
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Project or target item not found") from exc
+
+
+@api.post("/caption/generate", dependencies=[Depends(_verify_api_key)])
+def caption_generate(payload: CaptionGeneratePayload) -> dict[str, str]:
+    data = payload.model_dump()
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).caption_generate(data, task_id),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/music/generate", dependencies=[Depends(_verify_api_key)])
+def music_generate(payload: GenerationPayload) -> dict[str, str]:
+    data = _generation_data(payload)
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).music_generate(data, task_id),
+        callback_url=payload.callback_url,
+        export_target=payload.export_target,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/voice/generate", dependencies=[Depends(_verify_api_key)])
+def voice_generate(payload: GenerationPayload) -> dict[str, str]:
+    data = _generation_data(payload)
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).voice_generate(data, task_id),
+        callback_url=payload.callback_url,
+        export_target=payload.export_target,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/image/generate", dependencies=[Depends(_verify_api_key)])
+def image_generate(payload: GenerationPayload) -> dict[str, str]:
+    data = _generation_data(payload)
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).image_generate(data, task_id),
+        callback_url=payload.callback_url,
+        export_target=payload.export_target,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/video/generate", dependencies=[Depends(_verify_api_key)])
+def video_generate(payload: GenerationPayload) -> dict[str, str]:
+    data = _generation_data(payload)
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).video_generate(data, task_id),
+        callback_url=payload.callback_url,
+        export_target=payload.export_target,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/ai/{tool}", dependencies=[Depends(_verify_api_key)])
+def ai_tool(tool: str, payload: AIToolPayload) -> dict[str, str]:
+    data = payload.model_dump()
+    if payload.model_extra:
+        data.update(payload.model_extra)
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).ai_tool(tool, data, task_id),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/assistant/{tool}", dependencies=[Depends(_verify_api_key)])
+def assistant_tool(tool: str, payload: AIToolPayload) -> dict[str, str]:
+    data = payload.model_dump()
+    if payload.model_extra:
+        data.update(payload.model_extra)
+    job_id = job_manager.submit_task(
+        lambda task_id, log: StudioTaskProcessor(settings, log=log).assistant_tool(tool, data, task_id),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/render")
+def render(payload: RenderPayload | AIReelsPayload) -> dict[str, str]:
+    if isinstance(payload, AIReelsPayload):
+        job_id = job_manager.submit_ai_reels(_ai_reels_request(payload))
+    else:
+        job_id = job_manager.submit_render(_render_request(payload))
+    return _submission_response(job_id)
+
+
+
+@api.post("/render/ai-reels")
+def render_ai_reels(payload: AIReelsPayload) -> dict[str, str]:
+    job_id = job_manager.submit_ai_reels(_ai_reels_request(payload))
+    return _submission_response(job_id)
+
+
+@api.post("/render/batch")
+def render_batch(payload: BatchPayload) -> dict[str, list[str]]:
+    job_ids = job_manager.submit_batch([_render_request(job) for job in payload.jobs])
+    return {"job_ids": job_ids}
+
+
+@api.post("/automation/batch", dependencies=[Depends(_verify_api_key)])
+def automation_batch(payload: BatchPayload) -> dict[str, list[str]]:
+    return render_batch(payload)
+
+
+@api.post("/project/{project_id}/render", dependencies=[Depends(_verify_api_key)])
+def project_render(project_id: str, payload: ProjectRenderPayload) -> dict[str, str]:
+    try:
+        project = project_manager.get(project_id)
+        request = _project_render_request(project, payload)
+        job_id = job_manager.submit_render(request)
+        return _submission_response(job_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Project not found") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@api.post("/render/upload")
+async def render_upload(request_json: str = Form(...), files: list[UploadFile] = File(default=[])) -> dict[str, str]:
+    uploads = await _stage_uploads(files)
+    payload_data = _replace_upload_refs(json.loads(request_json), uploads)
+    payload = RenderPayload.model_validate(payload_data)
+    job_id = job_manager.submit_render(_render_request(payload))
+    return _submission_response(job_id)
+
+
+@api.post("/render/ai-reels/upload")
+async def render_ai_reels_upload(request_json: str = Form(...), files: list[UploadFile] = File(default=[])) -> dict[str, str]:
+    uploads = await _stage_uploads(files)
+    payload_data = _replace_upload_refs(json.loads(request_json), uploads)
+    payload = AIReelsPayload.model_validate(payload_data)
+    job_id = job_manager.submit_ai_reels(_ai_reels_request(payload))
+    return _submission_response(job_id)
+
+
+@api.post("/assets/upload")
+async def upload_assets(files: list[UploadFile] = File(...)) -> dict[str, list[UploadedAsset]]:
+    uploads = await _stage_uploads(files)
+    assets = [
+        UploadedAsset(filename=filename, path=path, reference=f"upload://{filename}", kind=_asset_kind(filename)) for filename, path in uploads.items()
+    ]
+    return {"assets": [asset.model_dump() for asset in assets]}
+
+
+@api.post("/upload")
+async def upload(files: list[UploadFile] = File(...), expand_zip: bool = Form(default=True)) -> dict[str, list[UploadedAsset]]:
+    uploads = await _stage_uploads(files)
+    expanded: dict[str, str] = {}
+    for filename, path in uploads.items():
+        if expand_zip and filename.lower().endswith(".zip"):
+            expanded.update(_extract_zip(Path(path)))
+        else:
+            expanded[filename] = path
+    assets = [
+        UploadedAsset(filename=filename, path=path, reference=f"upload://{filename}", kind=_asset_kind(filename))
+        for filename, path in expanded.items()
+    ]
+    return {"assets": [asset.model_dump() for asset in assets]}
+
+
+@api.post("/ingest", dependencies=[Depends(_verify_api_key)])
+def ingest(payload: IngestPayload) -> dict[str, str]:
+    job_id = job_manager.submit_task(
+        lambda task_id, log: PlatformProcessor(settings, log=log).ingest_sources([source.model_dump() for source in payload.sources], task_id),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/analyze", dependencies=[Depends(_verify_api_key)])
+def analyze(payload: AnalyzePayload) -> dict[str, str]:
+    job_id = job_manager.submit_task(
+        lambda task_id, log: PlatformProcessor(settings, log=log).analyze(
+            payload.media,
+            task_id,
+            transcript=payload.transcript,
+            platform=payload.platform,
+        ),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/clips", dependencies=[Depends(_verify_api_key)])
+def clips(payload: ClipsPayload) -> dict[str, str]:
+    job_id = job_manager.submit_task(
+        lambda task_id, log: PlatformProcessor(settings, log=log).clips(payload.media, task_id, payload.clips),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/thumbnail", dependencies=[Depends(_verify_api_key)])
+def thumbnail(payload: ThumbnailPayload) -> dict[str, str]:
+    job_id = job_manager.submit_task(
+        lambda task_id, log: PlatformProcessor(settings, log=log).thumbnail(
+            payload.media,
+            task_id,
+            text=payload.text,
+            timestamp=payload.timestamp,
+            template=payload.template,
+        ),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/thumbnail/create", dependencies=[Depends(_verify_api_key)])
+def thumbnail_create(payload: ThumbnailPayload) -> dict[str, str]:
+    return thumbnail(payload)
+
+
+@api.post("/metadata", dependencies=[Depends(_verify_api_key)])
+def metadata(payload: MetadataPayload) -> dict[str, str]:
+    job_id = job_manager.submit_task(
+        lambda task_id, log: PlatformProcessor(settings, log=log).metadata(
+            task_id,
+            topic=payload.topic,
+            transcript=payload.transcript,
+            platform=payload.platform,
+        ),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/publish", dependencies=[Depends(_verify_api_key)])
+def publish(payload: PublishPayload) -> dict[str, str]:
+    job_id = job_manager.submit_task(
+        lambda task_id, log: PlatformProcessor(settings, log=log).publish(payload.model_dump(), task_id),
+        callback_url=payload.callback_url,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/toolkit", dependencies=[Depends(_verify_api_key)])
+def toolkit(payload: ToolkitPayload) -> dict[str, str]:
+    data = payload.model_dump()
+    if payload.model_extra:
+        data.update(payload.model_extra)
+    job_id = job_manager.submit_task(
+        lambda task_id, log: PlatformProcessor(settings, log=log).toolkit(data, task_id),
+        callback_url=payload.callback_url,
+        export_target=payload.export_target,
+    )
+    return _submission_response(job_id)
+
+
+@api.post("/edit", dependencies=[Depends(_verify_api_key)])
+def edit(payload: ToolkitPayload) -> dict[str, str]:
+    return toolkit(payload)
+
+
+@api.post("/transcribe")
+def transcribe(payload: TranscribePayload) -> dict:
+    from renderer.core.ingest import AssetIngestor
+    from renderer.core.utils import temp_workdir
+
+    try:
+        with temp_workdir(settings.temp_dir, "transcribe") as work:
+            audio = AssetIngestor(settings).resolve(payload.audio, Path(work) / "inputs", "audio")
+            return RenderEngine(settings).transcribe(
+                audio,
+                model_size=payload.model_size,
+                language=payload.language,
+                task=payload.task,
+                beam_size=payload.beam_size,
+                vad_filter=payload.vad_filter,
+                word_timestamps=payload.word_timestamps,
+            )
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@api.post("/subtitles")
+def subtitles(payload: SubtitlePayload) -> FileResponse:
+    try:
+        events = [SubtitleEvent(float(event["start"]), float(event["end"]), str(event["text"])) for event in payload.events]
+        path = settings.temp_dir / f"subtitles_{uuid.uuid4().hex}.{payload.format}"
+        generator = SubtitleGenerator()
+        if payload.format == "ass":
+            generator.write_ass(events, path, payload.template)
+            media_type = "text/x-ssa"
+        else:
+            generator.write_srt(events, path)
+            media_type = "application/x-subrip"
+        return FileResponse(path, media_type=media_type, filename=path.name)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@api.post("/scene-builder")
+def scene_builder(payload: SceneBuildPayload) -> dict[str, Any]:
+    if not payload.assets:
+        raise HTTPException(status_code=400, detail="At least one asset is required")
+    style = get_creative_style(payload.creative_style)
+    words = payload.script.split()
+    total_duration = payload.duration or max(style.scene_duration * len(payload.assets), len(words) * 0.35, 3.0)
+    per_scene = total_duration / len(payload.assets)
+    captions = _split_words_for_assets(words, len(payload.assets))
+    scenes = [
+        {
+            "start": round(index * per_scene, 3),
+            "duration": round(per_scene, 3),
+            "media": asset,
+            "caption": captions[index] if index < len(captions) else "",
+            "transition": _style_transition(payload.transition, style.transition_sequence, index),
+            "effect": style.scene_effect_sequence[index % len(style.scene_effect_sequence)],
+            "background": "blur",
+            "layout": "fill",
+        }
+        for index, asset in enumerate(payload.assets)
+    ]
+    return {"scenes": scenes, "creative_style": style.metadata_payload()}
+
+
+@api.post("/transcribe/upload")
+async def transcribe_upload(
+    file: UploadFile = File(...),
+    model_size: str | None = Form(default=None),
+    language: str | None = Form(default=None),
+    task: str = Form(default="transcribe"),
+    beam_size: int = Form(default=5),
+    vad_filter: bool = Form(default=True),
+    word_timestamps: bool = Form(default=True),
+) -> dict:
+    try:
+        uploads = await _stage_uploads([file])
+        audio = next(iter(uploads.values()))
+        return RenderEngine(settings).transcribe(
+            audio,
+            model_size=model_size,
+            language=language,
+            task=task,
+            beam_size=beam_size,
+            vad_filter=vad_filter,
+            word_timestamps=word_timestamps,
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@api.get("/status")
+def status_query(job_id: str = Query(...)) -> dict:
+    return status(job_id)
+
+
+@api.get("/status/{job_id}")
+def status(job_id: str) -> dict:
+    try:
+        return job_manager.get(job_id).__dict__
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Job not found") from exc
+
+
+@api.post("/cancel/{job_id}")
+def cancel(job_id: str) -> dict:
+    try:
+        return job_manager.cancel(job_id).__dict__
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Job not found") from exc
+
+
+@api.post("/admin/cleanup")
+def cleanup(older_than_seconds: int | None = None) -> dict[str, int]:
+    return job_manager.cleanup(older_than_seconds)
+
+
+@api.get("/download")
+def download_query(job_id: str = Query(...), token: str | None = Query(default=None)) -> FileResponse:
+    return download(job_id, token)
+
+
+@api.get("/download/{job_id}")
+def download(job_id: str, token: str | None = Query(default=None)) -> FileResponse:
+    try:
+        record = job_manager.get(job_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Job not found") from exc
+    if record.state != "COMPLETED" or not record.output_path:
+        raise HTTPException(status_code=409, detail=f"Job is {record.state}")
+    if record.download_token and not verify_download_token(settings.signing_secret, job_id, token):
+        raise HTTPException(status_code=403, detail="Invalid or missing download token")
+    path = Path(record.output_path)
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="Output file is missing")
+    return FileResponse(path, media_type=_media_type(path), filename=path.name)
+
+
+@api.post("/inspect")
+def inspect_asset(path: str) -> dict:
+    try:
+        return RenderEngine(settings).inspect_asset(path)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+def _render_request(payload: RenderPayload) -> RenderRequest:
+    payload = RenderPayload.model_validate(apply_creative_style(apply_preset(payload.model_dump(exclude_unset=True))))
+    request = RenderRequest(
+        scenes=[Scene(**scene.model_dump()) for scene in payload.scenes],
+        template=payload.template,
+        preset=payload.preset,
+        creative_style=payload.creative_style,
+        platform=payload.platform,
+        output_name=payload.output_name,
+        voiceover=payload.voiceover,
+        background_music=payload.background_music,
+        music_volume=payload.music_volume,
+        music_fade_in=payload.music_fade_in,
+        music_fade_out=payload.music_fade_out,
+        music_loop=payload.music_loop,
+        music_start=payload.music_start,
+        music_ducking=payload.music_ducking,
+        voice_volume=payload.voice_volume,
+        subtitle_format=payload.subtitle_format,  # type: ignore[arg-type]
+        auto_subtitles=payload.auto_subtitles,
+        subtitle_language=payload.subtitle_language,
+        whisper_model_size=payload.whisper_model_size,
+        preview=payload.preview,
+        audio_normalize=payload.audio_normalize,
+        watermark=payload.watermark,
+        watermark_position=payload.watermark_position,
+        intro=payload.intro,
+        outro=payload.outro,
+        callback_url=payload.callback_url,
+        export_target=payload.export_target,
+        priority=payload.priority,
+        scheduled_at=payload.scheduled_at,
+        normalize=payload.normalize,
+        metadata=payload.metadata,
+    )
+    Timeline(request.scenes)
+    return request
+
+
+def _project_render_request(project: dict[str, Any], payload: ProjectRenderPayload) -> RenderRequest:
+    scenes: list[dict[str, Any]] = []
+    for tracks in project.get("timeline", {}).get("tracks", {}).values():
+        for track in tracks:
+            if track.get("hidden") or track.get("type") not in {"video", "overlay"}:
+                continue
+            for item in track.get("items", []):
+                if item.get("hidden"):
+                    continue
+                media = _item_media(project, item)
+                if not media:
+                    continue
+                scenes.append(
+                    {
+                        "start": float(item.get("start", 0.0)),
+                        "duration": float(item.get("duration", 1.0)),
+                        "media": media,
+                        "caption": item.get("caption") or item.get("text") or "",
+                        "transition": item.get("transition", "fade"),
+                        "background": item.get("background", "blur"),
+                        "layout": item.get("layout", "fill"),
+                        "effect": _first_named(item.get("effects")),
+                    }
+                )
+    if not scenes:
+        raise ValueError("Project has no renderable video or overlay timeline items")
+    export_settings = project.get("export_settings", {})
+    data = {
+        "scenes": sorted(scenes, key=lambda scene: scene["start"]),
+        "template": payload.template or export_settings.get("template", "tiktok_classic"),
+        "preset": payload.preset,
+        "creative_style": payload.creative_style or project.get("metadata", {}).get("creative_style"),
+        "platform": payload.platform or export_settings.get("platform"),
+        "output_name": payload.output_name,
+        "callback_url": payload.callback_url,
+        "export_target": payload.export_target,
+        "preview": payload.preview,
+        "normalize": payload.normalize,
+        "metadata": project.get("metadata", {}) | payload.metadata | {"project_id": project.get("id"), "project_name": project.get("name")},
+    }
+    return _render_request(RenderPayload.model_validate(data))
+
+
+def _ai_reels_request(payload: AIReelsPayload) -> AIReelsRequest:
+    payload = AIReelsPayload.model_validate(apply_creative_style(apply_preset(payload.model_dump(exclude_unset=True))))
+    return AIReelsRequest(**payload.model_dump())
+
+
+def _generation_data(payload: GenerationPayload) -> dict[str, Any]:
+    data = payload.model_dump()
+    if payload.model_extra:
+        data.update(payload.model_extra)
+    params = data.pop("params", {}) or {}
+    if isinstance(params, dict):
+        data.update(params)
+    return data
+
+
+def _item_media(project: dict[str, Any], item: dict[str, Any]) -> str | None:
+    direct = item.get("media") or item.get("path") or item.get("source")
+    if direct:
+        return str(direct)
+    asset_id = item.get("asset_id")
+    if not asset_id:
+        return None
+    for asset in project.get("assets", []):
+        if asset.get("id") == asset_id:
+            return str(asset.get("path") or asset.get("url") or asset.get("source") or "")
+    return None
+
+
+def _first_named(records: Any) -> str | None:
+    if not isinstance(records, list) or not records:
+        return None
+    first = records[0]
+    if isinstance(first, dict):
+        return first.get("effect") or first.get("name")
+    return str(first)
+
+
+async def _stage_uploads(files: list[UploadFile]) -> dict[str, str]:
+    upload_dir = settings.temp_dir / "uploads" / uuid.uuid4().hex
+    staged: dict[str, str] = {}
+    total_bytes = 0
+    for upload in files:
+        filename = safe_filename(upload.filename or f"asset_{len(staged)}")
+        if not _allowed_upload(filename):
+            raise HTTPException(status_code=415, detail=f"Unsupported asset type: {filename}")
+        target = upload_dir / filename
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("wb") as output:
+            while True:
+                chunk = await upload.read(1024 * 1024)
+                if not chunk:
+                    break
+                total_bytes += len(chunk)
+                if total_bytes > settings.max_download_bytes:
+                    shutil.rmtree(upload_dir, ignore_errors=True)
+                    raise HTTPException(status_code=413, detail="Uploaded assets exceed MAX_DOWNLOAD_BYTES")
+                output.write(chunk)
+        staged[filename] = str(stage_upload(target, upload_dir, filename))
+    return staged
+
+
+def _monitor_payload() -> dict[str, Any]:
+    disk = shutil.disk_usage(settings.base_dir)
+    return {
+        "health": "ok",
+        "queue": job_manager.summary(),
+        "workers": {
+            "max_workers": settings.max_workers,
+            "ffmpeg_timeout_seconds": settings.ffmpeg_timeout_seconds,
+            "whisper_model_size": settings.whisper_model_size,
+            "whisper_device": settings.whisper_device,
+        },
+        "disk": {
+            "total_bytes": disk.total,
+            "used_bytes": disk.used,
+            "free_bytes": disk.free,
+        },
+        "directories": {
+            "temp": str(settings.temp_dir),
+            "exports": str(settings.exports_dir),
+            "jobs": str(settings.jobs_dir),
+            "storage": str(settings.storage_dir),
+        },
+    }
+
+
+def _extract_zip(path: Path) -> dict[str, str]:
+    output_dir = settings.temp_dir / "uploads" / f"zip_{uuid.uuid4().hex}"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    extracted: dict[str, str] = {}
+    with zipfile.ZipFile(path) as archive:
+        for member in archive.infolist():
+            if member.is_dir():
+                continue
+            name = safe_filename(Path(member.filename).name)
+            if not _allowed_upload(name):
+                continue
+            target = output_dir / name
+            resolved = target.resolve()
+            if output_dir.resolve() not in resolved.parents and resolved != output_dir.resolve():
+                raise HTTPException(status_code=400, detail="Unsafe ZIP member path")
+            with archive.open(member) as source, target.open("wb") as destination:
+                shutil.copyfileobj(source, destination)
+            extracted[name] = str(target)
+    return extracted
+
+
+def _asset_kind(filename: str) -> str:
+    suffix = Path(filename).suffix.lower()
+    if suffix in {".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi", ".gif"}:
+        return "video"
+    if suffix in {".mp3", ".wav", ".m4a", ".aac", ".flac", ".ogg"}:
+        return "audio"
+    if suffix in {".jpg", ".jpeg", ".png", ".webp", ".avif"}:
+        return "image"
+    if suffix in {".srt", ".ass", ".vtt"}:
+        return "subtitle"
+    return "other"
+
+
+def _allowed_upload(filename: str) -> bool:
+    suffix = Path(filename).suffix.lower()
+    return suffix in {
+        ".mp4",
+        ".mov",
+        ".m4v",
+        ".webm",
+        ".mkv",
+        ".avi",
+        ".gif",
+        ".mp3",
+        ".wav",
+        ".m4a",
+        ".aac",
+        ".flac",
+        ".ogg",
+        ".jpg",
+        ".jpeg",
+        ".png",
+        ".webp",
+        ".avif",
+        ".srt",
+        ".ass",
+        ".vtt",
+        ".zip",
+    }
+
+
+def _media_type(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix == ".json":
+        return "application/json"
+    if suffix == ".zip":
+        return "application/zip"
+    if suffix == ".jpg" or suffix == ".jpeg":
+        return "image/jpeg"
+    if suffix == ".png":
+        return "image/png"
+    if suffix == ".gif":
+        return "image/gif"
+    if suffix == ".mp3":
+        return "audio/mpeg"
+    if suffix in {".srt", ".vtt", ".ass"}:
+        return "text/plain"
+    return "video/mp4"
+
+
+def _replace_upload_refs(value: Any, uploads: dict[str, str]) -> Any:
+    if isinstance(value, dict):
+        return {key: _replace_upload_refs(item, uploads) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_replace_upload_refs(item, uploads) for item in value]
+    if isinstance(value, str) and value.startswith("upload://"):
+        name = safe_filename(value.removeprefix("upload://"))
+        if name not in uploads:
+            raise HTTPException(status_code=400, detail=f"Missing uploaded file for reference: upload://{name}")
+        return uploads[name]
+    return value
+
+
+def _split_words_for_assets(words: list[str], count: int) -> list[str]:
+    if count <= 0:
+        return []
+    if not words:
+        return [""] * count
+    base, remainder = divmod(len(words), count)
+    captions: list[str] = []
+    cursor = 0
+    for index in range(count):
+        size = base + (1 if index < remainder else 0)
+        size = max(1, size)
+        captions.append(" ".join(words[cursor : cursor + size]))
+        cursor += size
+    return captions
+
+
+def _style_transition(requested: str, sequence: tuple[str, ...], index: int) -> str:
+    if requested and requested != "fade":
+        return requested
+    return sequence[index % len(sequence)] if sequence else "fade"

services/render_engine/app.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+import uvicorn
+
+from api import api, job_manager, project_manager, settings
+from renderer import RenderEngine
+from renderer.core.models import AIReelsRequest
+from renderer.scenes import Timeline
+from renderer.studio import capability_catalog
+from renderer.templates import apply_creative_style, apply_preset, list_creative_styles, list_platform_profiles, list_templates
+
+
+def create_dashboard() -> gr.Blocks:
+    with gr.Blocks(title="Ava2lon Studio AI") as dashboard:
+        gr.Markdown(
+            "# Ava2lon Studio AI\n"
+            "CPU-first CapCut-class video automation studio with REST API parity, async jobs, webhooks, and project JSON."
+        )
+        with gr.Tab("Projects"):
+            project_name = gr.Textbox(label="Project name", value="Untitled Ava2lon Project")
+            project_metadata = gr.Textbox(label="Metadata JSON", lines=5, value=json.dumps({"platform": "tiktok"}, indent=2))
+            project_create = gr.Button("Create Project", variant="primary")
+            project_list = gr.Button("Refresh Projects")
+            project_output = gr.JSON(label="Projects")
+            project_create.click(fn=_create_project, inputs=[project_name, project_metadata], outputs=project_output)
+            project_list.click(fn=_list_projects, outputs=project_output)
+
+        with gr.Tab("Assets"):
+            gr.Markdown("Use `/upload` or `/assets/upload` for multipart assets, then attach them to a project with `/project/assets/add`.")
+            asset_project_id = gr.Textbox(label="Project ID")
+            asset_json = gr.Textbox(label="Asset JSON", lines=6, value=json.dumps({"path": "clip.mp4", "kind": "video"}, indent=2))
+            asset_button = gr.Button("Attach Asset", variant="primary")
+            asset_output = gr.JSON(label="Project")
+            asset_button.click(fn=_add_project_asset, inputs=[asset_project_id, asset_json], outputs=asset_output)
+
+        with gr.Tab("Timeline"):
+            timeline_project_id = gr.Textbox(label="Project ID")
+            timeline_track_type = gr.Dropdown(choices=["video", "audio", "text", "overlay", "sticker", "subtitle"], value="video", label="Track type")
+            timeline_item = gr.Textbox(
+                label="Timeline item JSON",
+                lines=8,
+                value=json.dumps({"media": "clip.mp4", "start": 0, "duration": 5, "caption": "Hook"}, indent=2),
+            )
+            timeline_add_button = gr.Button("Add To Timeline", variant="primary")
+            timeline_output = gr.JSON(label="Project")
+            timeline_add_button.click(fn=_timeline_add, inputs=[timeline_project_id, timeline_track_type, timeline_item], outputs=timeline_output)
+
+            timeline_operation_json = gr.Textbox(
+                label="Operation JSON",
+                lines=8,
+                value=json.dumps({"operation": "split", "item_id": "clip_123", "params": {"offset": 2.5}}, indent=2),
+            )
+            timeline_operation_button = gr.Button("Apply Operation")
+            timeline_operation_button.click(fn=_timeline_operation, inputs=[timeline_project_id, timeline_operation_json], outputs=timeline_output)
+
+        with gr.Tab("Templates"):
+            template_button = gr.Button("Load Template Catalog")
+            template_output = gr.JSON(label="Templates")
+            template_button.click(fn=lambda: _catalog_section("templates"), outputs=template_output)
+
+        with gr.Tab("Effects"):
+            effect_button = gr.Button("Load Effect Catalog")
+            effect_output = gr.JSON(label="Effects")
+            effect_button.click(fn=lambda: _catalog_section("effects"), outputs=effect_output)
+
+        with gr.Tab("Filters"):
+            filter_button = gr.Button("Load Filter Catalog")
+            filter_output = gr.JSON(label="Filters")
+            filter_button.click(fn=lambda: _catalog_section("filters"), outputs=filter_output)
+
+        with gr.Tab("Captions"):
+            caption_text = gr.Textbox(label="Caption source text", lines=6)
+            caption_button = gr.Button("Submit Caption Job", variant="primary")
+            caption_output = gr.JSON(label="Caption Job")
+            caption_button.click(fn=_submit_caption_generation, inputs=caption_text, outputs=caption_output)
+
+        with gr.Tab("Audio"):
+            audio_button = gr.Button("Load Audio Catalog")
+            audio_output = gr.JSON(label="Audio")
+            audio_button.click(fn=lambda: {"audio": capability_catalog()["audio"], "music": capability_catalog()["music_generator"]}, outputs=audio_output)
+
+        with gr.Tab("AI Tools"):
+            ai_tool = gr.Dropdown(choices=capability_catalog()["ai_editing"], value="auto_viral_score", label="AI tool")
+            ai_payload = gr.Textbox(label="AI payload JSON", lines=8, value=json.dumps({"platform": "tiktok", "text": "A strong opening hook"}, indent=2))
+            ai_button = gr.Button("Submit AI Tool", variant="primary")
+            ai_output = gr.JSON(label="AI Job")
+            ai_button.click(fn=_submit_ai_tool, inputs=[ai_tool, ai_payload], outputs=ai_output)
+
+        with gr.Tab("Rendering"):
+            render_json = gr.Textbox(
+                label="Render JSON",
+                lines=14,
+                value="",
+                placeholder="Paste a production render request JSON object with absolute or uploaded asset paths.",
+            )
+            render_button = gr.Button("Submit Render", variant="primary")
+            render_output = gr.JSON(label="Submission")
+            render_button.click(fn=_submit_render_json, inputs=render_json, outputs=render_output)
+
+        with gr.Tab("AI Reels"):
+            script = gr.Textbox(label="Script", lines=6)
+            voiceover = gr.File(label="Voiceover", file_types=["audio"], type="filepath")
+            assets = gr.File(label="Assets", file_count="multiple", type="filepath")
+            template = gr.Dropdown(choices=list_templates(), value="tiktok_classic", label="Caption Template")
+            creative_style = gr.Dropdown(choices=list_creative_styles(), value="viral_shorts", label="Creative Style")
+            platform = gr.Dropdown(choices=list_platform_profiles(), value="tiktok", label="Platform")
+            music = gr.File(label="Background Music", file_types=["audio"], type="filepath")
+            ai_button = gr.Button("Submit AI Reel", variant="primary")
+            ai_output = gr.JSON(label="Submission")
+            ai_button.click(fn=_submit_ai_reel, inputs=[script, voiceover, assets, template, creative_style, platform, music], outputs=ai_output)
+
+        with gr.Tab("Batch Render"):
+            batch_json = gr.Textbox(label="Batch JSON", lines=14, value=json.dumps({"jobs": []}, indent=2))
+            batch_button = gr.Button("Submit Batch", variant="primary")
+            batch_output = gr.JSON(label="Batch Submission")
+            batch_button.click(fn=_submit_batch_json, inputs=batch_json, outputs=batch_output)
+
+        with gr.Tab("Job Status"):
+            status_job_id = gr.Textbox(label="Job ID")
+            status_button = gr.Button("Refresh")
+            status_output = gr.JSON(label="Status")
+            status_button.click(fn=_job_status, inputs=status_job_id, outputs=status_output)
+
+        with gr.Tab("Logs"):
+            logs_job_id = gr.Textbox(label="Job ID")
+            logs_button = gr.Button("Load Logs")
+            logs_output = gr.Textbox(label="Logs", lines=20)
+            logs_button.click(fn=_job_logs, inputs=logs_job_id, outputs=logs_output)
+
+        with gr.Tab("Downloads"):
+            download_job_id = gr.Textbox(label="Job ID")
+            download_button = gr.Button("Get Output")
+            download_output = gr.File(label="Rendered Video")
+            download_button.click(fn=_download_path, inputs=download_job_id, outputs=download_output)
+
+        with gr.Tab("Transcribe"):
+            transcribe_audio = gr.File(label="Audio or Video", file_types=["audio", "video"], type="filepath")
+            transcribe_model = gr.Dropdown(
+                choices=["tiny", "base", "small", "medium", "large-v3"],
+                value=settings.whisper_model_size,
+                label="Whisper Model",
+            )
+            transcribe_language = gr.Textbox(label="Language", placeholder="Optional ISO code, e.g. en")
+            transcribe_button = gr.Button("Transcribe", variant="primary")
+            transcribe_output = gr.JSON(label="Transcript")
+            transcribe_button.click(
+                fn=_transcribe_file,
+                inputs=[transcribe_audio, transcribe_model, transcribe_language],
+                outputs=transcribe_output,
+            )
+
+        with gr.Tab("Asset Inspector"):
+            asset_path = gr.Textbox(label="Asset path")
+            inspect_button = gr.Button("Inspect")
+            inspect_output = gr.JSON(label="Metadata")
+            inspect_button.click(fn=_inspect_asset, inputs=asset_path, outputs=inspect_output)
+
+        with gr.Tab("AI Analysis"):
+            analysis_media = gr.Textbox(label="Media URL or path")
+            analysis_transcript = gr.Textbox(label="Transcript", lines=5)
+            analysis_platform = gr.Dropdown(choices=list_platform_profiles(), value="tiktok", label="Target Platform")
+            analysis_button = gr.Button("Submit Analysis", variant="primary")
+            analysis_output = gr.JSON(label="Analysis Job")
+            analysis_button.click(
+                fn=_submit_analysis,
+                inputs=[analysis_media, analysis_transcript, analysis_platform],
+                outputs=analysis_output,
+            )
+
+        with gr.Tab("Clip Generator"):
+            clip_media = gr.Textbox(label="Media URL or path")
+            clip_json = gr.Textbox(label="Clip JSON", lines=6, value=json.dumps([{"start": 0, "end": 8}], indent=2))
+            clip_button = gr.Button("Generate Clips", variant="primary")
+            clip_output = gr.JSON(label="Clip Job")
+            clip_button.click(fn=_submit_clips, inputs=[clip_media, clip_json], outputs=clip_output)
+
+        with gr.Tab("Metadata"):
+            metadata_topic = gr.Textbox(label="Topic or transcript", lines=5)
+            metadata_platform = gr.Dropdown(choices=list_platform_profiles(), value="tiktok", label="Platform")
+            metadata_button = gr.Button("Generate Metadata", variant="primary")
+            metadata_output = gr.JSON(label="Metadata Job")
+            metadata_button.click(fn=_submit_metadata, inputs=[metadata_topic, metadata_platform], outputs=metadata_output)
+
+        with gr.Tab("Publishing"):
+            publish_media = gr.Textbox(label="Media URL or rendered output path")
+            publish_title = gr.Textbox(label="Title")
+            publish_platforms = gr.Textbox(label="Platforms", value="youtube,tiktok,instagram")
+            publish_button = gr.Button("Create Publish Draft", variant="primary")
+            publish_output = gr.JSON(label="Publish Job")
+            publish_button.click(fn=_submit_publish, inputs=[publish_media, publish_title, publish_platforms], outputs=publish_output)
+
+        with gr.Tab("Settings"):
+            settings_button = gr.Button("Load Settings")
+            settings_output = gr.JSON(label="Settings")
+            settings_button.click(fn=_settings_payload, outputs=settings_output)
+
+        with gr.Tab("Queue Monitor"):
+            queue_button = gr.Button("Refresh Queue")
+            queue_output = gr.JSON(label="Queue")
+            queue_button.click(fn=_queue_status, outputs=queue_output)
+
+    return dashboard
+
+
+def _submit_render_json(payload: str) -> dict[str, Any]:
+    data = apply_creative_style(apply_preset(json.loads(payload)))
+    request = Timeline.request_from_payload(data)
+    job_id = job_manager.submit_render(request)
+    return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
+
+
+def _create_project(name: str, metadata_json: str) -> dict[str, Any]:
+    metadata = json.loads(metadata_json or "{}")
+    return {"project": project_manager.create(name, metadata=metadata)}
+
+
+def _list_projects() -> dict[str, Any]:
+    return {"projects": project_manager.list()}
+
+
+def _add_project_asset(project_id: str, asset_json: str) -> dict[str, Any]:
+    return {"project": project_manager.add_asset(project_id, json.loads(asset_json or "{}"))}
+
+
+def _timeline_add(project_id: str, track_type: str, item_json: str) -> dict[str, Any]:
+    return {"project": project_manager.add_to_timeline(project_id, json.loads(item_json or "{}"), track_type=track_type)}
+
+
+def _timeline_operation(project_id: str, operation_json: str) -> dict[str, Any]:
+    data = json.loads(operation_json or "{}")
+    return {
+        "project": project_manager.timeline_operation(
+            project_id,
+            data.get("operation", "drag"),
+            item_id=data.get("item_id"),
+            params=data.get("params", {}),
+        )
+    }
+
+
+def _catalog_section(section: str) -> dict[str, Any]:
+    catalog = capability_catalog()
+    return {section: catalog.get(section)}
+
+
+def _submit_caption_generation(text: str) -> dict[str, Any]:
+    from renderer.studio import StudioTaskProcessor
+
+    job_id = job_manager.submit_task(lambda task_id, log: StudioTaskProcessor(settings, log=log).caption_generate({"text": text}, task_id))
+    return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
+
+
+def _submit_ai_tool(tool: str, payload: str) -> dict[str, Any]:
+    from renderer.studio import StudioTaskProcessor
+
+    data = json.loads(payload or "{}")
+    job_id = job_manager.submit_task(lambda task_id, log: StudioTaskProcessor(settings, log=log).ai_tool(tool, data, task_id))
+    return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
+
+
+def _submit_batch_json(payload: str) -> dict[str, Any]:
+    data = json.loads(payload)
+    requests = [Timeline.request_from_payload(apply_creative_style(apply_preset(job))) for job in data.get("jobs", [])]
+    return {"job_ids": job_manager.submit_batch(requests)}
+
+
+def _submit_ai_reel(
+    script: str,
+    voiceover: str,
+    assets: list[str],
+    template: str,
+    creative_style: str,
+    platform: str,
+    music: str | None,
+) -> dict[str, Any]:
+    request = AIReelsRequest(
+        script=script,
+        voiceover=voiceover,
+        assets=assets or [],
+        template=template,
+        creative_style=creative_style,
+        platform=platform,
+        background_music=music,
+    )
+    job_id = job_manager.submit_ai_reels(request)
+    return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
+
+
+def _job_status(job_id: str) -> dict[str, Any]:
+    return job_manager.get(job_id).__dict__
+
+
+def _job_logs(job_id: str) -> str:
+    return "\n\n".join(job_manager.get(job_id).logs)
+
+
+def _download_path(job_id: str) -> str | None:
+    record = job_manager.get(job_id)
+    if record.state != "COMPLETED":
+        return None
+    return record.output_path
+
+
+def _inspect_asset(path: str) -> dict[str, Any]:
+    return RenderEngine(settings).inspect_asset(path)
+
+
+def _transcribe_file(path: str, model_size: str, language: str) -> dict[str, Any]:
+    return RenderEngine(settings).transcribe(
+        path,
+        model_size=model_size,
+        language=language.strip() or None,
+        word_timestamps=True,
+    )
+
+
+def _submit_analysis(media: str, transcript: str, platform: str) -> dict[str, Any]:
+    from renderer.platform import PlatformProcessor
+
+    job_id = job_manager.submit_task(
+        lambda task_id, log: PlatformProcessor(settings, log=log).analyze(media, task_id, transcript=transcript, platform=platform)
+    )
+    return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
+
+
+def _submit_clips(media: str, clips_json: str) -> dict[str, Any]:
+    from renderer.platform import PlatformProcessor
+
+    clips = json.loads(clips_json)
+    job_id = job_manager.submit_task(lambda task_id, log: PlatformProcessor(settings, log=log).clips(media, task_id, clips))
+    return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
+
+
+def _submit_metadata(topic: str, platform: str) -> dict[str, Any]:
+    from renderer.platform import PlatformProcessor
+
+    job_id = job_manager.submit_task(lambda task_id, log: PlatformProcessor(settings, log=log).metadata(task_id, topic=topic, platform=platform))
+    return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
+
+
+def _submit_publish(media: str, title: str, platforms: str) -> dict[str, Any]:
+    from renderer.platform import PlatformProcessor
+
+    payload = {"media": media, "title": title, "platforms": [item.strip() for item in platforms.split(",") if item.strip()], "draft": True}
+    job_id = job_manager.submit_task(lambda task_id, log: PlatformProcessor(settings, log=log).publish(payload, task_id))
+    return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
+
+
+def _queue_status() -> dict[str, Any]:
+    return job_manager.summary()
+
+
+def _settings_payload() -> dict[str, Any]:
+    return {
+        "product": "Ava2lon Studio AI",
+        "base_dir": str(settings.base_dir),
+        "temp_dir": str(settings.temp_dir),
+        "exports_dir": str(settings.exports_dir),
+        "storage_dir": str(settings.storage_dir),
+        "max_workers": settings.max_workers,
+        "whisper_model_size": settings.whisper_model_size,
+        "whisper_device": settings.whisper_device,
+        "capabilities": capability_catalog()["principles"],
+    }
+
+
+app = gr.mount_gradio_app(api, create_dashboard(), path="/dashboard")
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860)