Upload 44 files

.dockerignore

@@ -0,0 +1,9 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+*.db
+.env
+.git
+.gitignore
+.cache

.gitattributes

@@ -0,0 +1,37 @@
+*.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
+fonts/TikTok-Bold.ttf filter=lfs diff=lfs merge=lfs -text
+gradio_demo.png filter=lfs diff=lfs merge=lfs -text

.gitattributes.editor

@@ -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

.gitattributes.ktts

@@ -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

.gitattributes.musicgen

@@ -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

.gitattributes.renderer

@@ -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

.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+
+.env
+.env.*
+!.env.example
+.venv/
+venv/
+
+temp/*
+!temp/.gitkeep
+exports/*
+!exports/.gitkeep
+jobs/*
+!jobs/.gitkeep
+storage/*
+!storage/.gitkeep
+
+*.db
+*.sqlite
+*.sqlite3
+

.gitignore.ktts

@@ -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

.gitignore.renderer

@@ -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
+

Dockerfile

@@ -1,15 +1,56 @@
-FROM python:3.12-slim
+FROM python:3.10-slim
 
-ENV PYTHONDONTWRITEBYTECODE=1
-ENV PYTHONUNBUFFERED=1
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=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 \
+    WHISPER_MODEL_DIR=/app/models \
+    WHISPER_MODEL_SIZE=tiny \
+    WHISPER_COMPUTE_TYPE=int8 \
+    WHISPER_DEVICE=cpu \
+    MAX_RENDER_WORKERS=1 \
+    FFMPEG_TIMEOUT_SECONDS=900 \
+    DOWNLOAD_TIMEOUT_SECONDS=60 \
+    MAX_DOWNLOAD_BYTES=524288000 \
+    ALLOW_PRIVATE_ASSET_URLS=false
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    ca-certificates \
+    curl \
+    espeak \
+    ffmpeg \
+    fonts-dejavu-core \
+    g++ \
+    gcc \
+    git \
+    imagemagick \
+    libglib2.0-0 \
+    libmagic1 \
+    libpq-dev \
+    libsm6 \
+    libsndfile1 \
+    libxext6 \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
+
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-COPY app ./app
-RUN useradd --create-home --uid 10001 flowforge
+RUN pip install --upgrade pip setuptools wheel \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY . .
 
-USER flowforge
+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 \
+    && chmod +x /app/start.sh
 
 EXPOSE 7860
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]
+
+CMD ["bash", "start.sh"]
+

Dockerfile.editor

@@ -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"]

Dockerfile.ktts

@@ -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"]

Dockerfile.musicgen

@@ -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"]

Dockerfile.renderer

@@ -0,0 +1,42 @@
+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 \
+    AVA2LON_SIGNING_SECRET=change-me-in-space-secrets \
+    BASYX_SIGNING_SECRET=change-me-in-space-secrets \
+    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"]

Dockerfile.whisper

@@ -0,0 +1,53 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# =========================
+# SYSTEM DEPENDENCIES (CRITICAL)
+# =========================
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    gcc \
+    g++ \
+    ffmpeg \
+    imagemagick \
+    fonts-dejavu-core \
+    libpq-dev \
+    libsm6 \
+    libxext6 \
+    libglib2.0-0 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# =========================
+# PYTHON BASE TOOLS
+# =========================
+RUN pip install --upgrade pip setuptools wheel
+
+# =========================
+# DEPENDENCIES (SINGLE LAYER)
+# =========================
+COPY requirements.txt .
+
+RUN pip install --no-cache-dir -r requirements.txt
+
+# =========================
+# APPLICATION CODE
+# =========================
+COPY . .
+
+# =========================
+# PERMISSIONS
+# =========================
+RUN chmod +x start.sh
+
+# =========================
+# ENV SAFETY (OPTIONAL BUT RECOMMENDED)
+# =========================
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+# =========================
+# START
+# =========================
+CMD ["bash", "start.sh"]

N8N_ENDPOINTS.md

@@ -0,0 +1,880 @@
+# Unified Media Studio API for n8n
+
+This reference describes every business API endpoint exposed by the unified
+Space and how to call it with n8n's **HTTP Request** node.
+
+## Base URL
+
+Store the deployed Space URL in an n8n variable:
+
+```text
+STUDIO_BASE_URL=https://<space-subdomain>.hf.space
+```
+
+Use this expression in HTTP Request nodes:
+
+```text
+{{ $vars.STUDIO_BASE_URL }}/health
+```
+
+Do not add a trailing slash to `STUDIO_BASE_URL`.
+
+## Standard HTTP Request Node Settings
+
+### JSON request
+
+- **Method:** Use the method in the endpoint tables.
+- **URL:** `{{ $vars.STUDIO_BASE_URL }}<path>`
+- **Send Body:** On
+- **Body Content Type:** JSON
+- **Specify Body:** Using JSON
+- **Response Format:** JSON
+
+For routes marked **API key**, add a Header Auth credential or enable
+**Send Headers**:
+
+```text
+X-API-Key: <AVA2LON_API_KEY value>
+```
+
+The header is only enforced when `AVA2LON_API_KEY` or `BASYX_API_KEY` is set in
+the Space environment.
+
+### Query parameters
+
+- Enable **Send Query Parameters**.
+- Add each query parameter shown in the endpoint table.
+- Do not place simple query parameters in the JSON body.
+
+### Multipart file upload
+
+- **Send Body:** On
+- **Body Content Type:** Form-Data
+- For text fields, select **Parameter Type: Form Data**.
+- For files, select **Parameter Type: n8n Binary File**.
+- Set **Name** to the API field name, usually `file` or `files`.
+- Set **Input Data Field Name** to the incoming n8n binary field, commonly
+  `data`.
+
+Add another `files` parameter for every additional binary file.
+
+### File download response
+
+For endpoints marked **File response**:
+
+- Set **Response Format** to File.
+- Set **Put Output in Field** to `data`.
+- The following n8n node can read the output from `$binary.data`.
+
+### Asynchronous job workflow
+
+Most renderer operations return:
+
+```json
+{
+  "job_id": "job_123",
+  "status_url": "/status/job_123",
+  "download_url": "/download/job_123?token=..."
+}
+```
+
+Recommended n8n flow:
+
+1. HTTP Request submits the job.
+2. Wait node pauses for several seconds.
+3. HTTP Request calls
+   `{{ $vars.STUDIO_BASE_URL }}{{ $json.status_url }}`.
+4. IF node checks whether `state` equals `COMPLETED`, `FAILED`, or `CANCELLED`.
+5. Loop through Wait while the state is `PENDING` or `RUNNING`.
+6. Download using the original submission node's `download_url`.
+
+For payloads with `callback_url`, use an n8n Webhook node's production URL to
+avoid polling.
+
+## Root and Discovery
+
+| Method | Path | n8n input | Response |
+| --- | --- | --- | --- |
+| GET | `/` | None | Redirects to `/dashboard`; use only for browser access. |
+| GET | `/apps` | None | JSON map of mounted applications and MCP tool count. |
+
+## Renderer Discovery and Monitoring
+
+These routes use the root base URL.
+
+| Method | Path | n8n input | Response |
+| --- | --- | --- | --- |
+| GET | `/health` | None | Renderer health. |
+| GET | `/monitor` | None | Runtime, queue, storage, and capability summary. |
+| GET | `/queue` | None | Job queue summary. |
+| GET | `/workers` | None | Worker and runtime settings. |
+| GET | `/presets` | None | Presets, templates, styles, transitions, and task IDs. |
+| GET | `/platforms` | None | Platform profile metadata. |
+| GET | `/toolkit/tasks` | None | Renderer toolkit task names. |
+| GET | `/capabilities` | None | Complete capability catalog. |
+| GET | `/effects` | None | Effects catalog. |
+| GET | `/filters` | None | Filter catalog. |
+| GET | `/transitions` | None | Transition catalog. |
+| GET | `/templates/catalog` | None | Templates, presets, and styles. |
+| GET | `/projects` | None | List saved projects. |
+
+## Projects and Timeline
+
+| Method | Path | n8n input | Auth | Response |
+| --- | --- | --- | --- | --- |
+| POST | `/projects` | JSON `ProjectPayload` | API key | Created project. |
+| POST | `/project/create` | JSON `ProjectPayload` | API key | Alias of `/projects`. |
+| GET | `/project/{project_id}` | Replace `{project_id}` | None | Project JSON. |
+| POST | `/project/save` | JSON `ProjectSavePayload` | API key | Saved project. |
+| POST | `/project/assets/add` | JSON `ProjectAssetPayload` | API key | Updated project. |
+| POST | `/timeline/add` | JSON `TimelineAddPayload` | API key | Updated project. |
+| POST | `/timeline/operation` | JSON `TimelineOperationPayload` | API key | Updated project. |
+| POST | `/timeline/split` | JSON `TimelineOperationPayload` | API key | Runs `split`. |
+| POST | `/timeline/trim` | JSON `TimelineOperationPayload` | API key | Runs `trim`. |
+| POST | `/timeline/ripple-delete` | JSON `TimelineOperationPayload` | API key | Runs `ripple_delete`. |
+| POST | `/timeline/insert` | JSON `TimelineOperationPayload` | API key | Runs `insert`. |
+| POST | `/timeline/replace` | JSON `TimelineOperationPayload` | API key | Runs `replace`. |
+| POST | `/timeline/group` | JSON `TimelineOperationPayload` | API key | Runs `group`. |
+| POST | `/timeline/lock` | JSON `TimelineOperationPayload` | API key | Runs `lock`. |
+| POST | `/timeline/hide` | JSON `TimelineOperationPayload` | API key | Runs `hide`. |
+| POST | `/timeline/duplicate` | JSON `TimelineOperationPayload` | API key | Runs `duplicate`. |
+| POST | `/effect/apply` | JSON `EffectApplyPayload` | API key | Updated project or asynchronous job. |
+| POST | `/filter/apply` | JSON `FilterApplyPayload` | API key | Updated project or asynchronous job. |
+| POST | `/transition/add` | JSON `TransitionAddPayload` | API key | Updated project or asynchronous job. |
+| POST | `/keyframe/add` | JSON `KeyframePayload` | API key | Updated project. |
+
+Example project creation:
+
+```json
+{
+  "name": "Campaign 01",
+  "metadata": {
+    "platform": "tiktok",
+    "creative_style": "high_energy"
+  },
+  "export_settings": {
+    "platform": "tiktok"
+  }
+}
+```
+
+## AI and Generation
+
+All routes in this table return asynchronous job information.
+
+| Method | Path | n8n input | Auth |
+| --- | --- | --- | --- |
+| POST | `/caption/generate` | JSON `CaptionGeneratePayload` | API key |
+| POST | `/music/generate` | JSON `GenerationPayload` | API key |
+| POST | `/voice/generate` | JSON `GenerationPayload` | API key |
+| POST | `/image/generate` | JSON `GenerationPayload` | API key |
+| POST | `/video/generate` | JSON `GenerationPayload` | API key |
+| POST | `/ai/{tool}` | Replace `{tool}`; JSON `AIToolPayload` | API key |
+| POST | `/assistant/{tool}` | Replace `{tool}`; JSON `AIToolPayload` | API key |
+
+Example:
+
+```json
+{
+  "prompt": "Upbeat cinematic background music",
+  "provider": "local",
+  "callback_url": "https://n8n.example/webhook/studio-complete",
+  "params": {
+    "duration": 20
+  }
+}
+```
+
+## Rendering and Uploads
+
+| Method | Path | n8n input | Auth | Response |
+| --- | --- | --- | --- | --- |
+| POST | `/render` | JSON `RenderPayload` or `AIReelsPayload` | None | Async job. |
+| POST | `/render/ai-reels` | JSON `AIReelsPayload` | None | Async job. |
+| POST | `/render/batch` | JSON `BatchPayload` | None | Array of job IDs. |
+| POST | `/automation/batch` | JSON `BatchPayload` | API key | Array of job IDs. |
+| POST | `/project/{project_id}/render` | Replace `{project_id}`; JSON `ProjectRenderPayload` | API key | Async job. |
+| POST | `/render/upload` | Multipart `request_json` plus zero or more `files` | None | Async job. |
+| POST | `/render/ai-reels/upload` | Multipart `request_json` plus zero or more `files` | None | Async job. |
+| POST | `/assets/upload` | Multipart; one or more `files` | None | Uploaded asset references. |
+| POST | `/upload` | Multipart `files`; optional `expand_zip` | None | Uploaded or expanded assets. |
+
+Basic render body:
+
+```json
+{
+  "scenes": [
+    {
+      "start": 0,
+      "duration": 5,
+      "media": "https://example.com/video.mp4",
+      "caption": "Opening hook",
+      "transition": "fade",
+      "background": "blur",
+      "layout": "fill"
+    }
+  ],
+  "output_name": "campaign.mp4",
+  "template": "tiktok_classic",
+  "auto_subtitles": true,
+  "subtitle_language": "en"
+}
+```
+
+For `/render/upload`, configure n8n Form-Data as:
+
+| Parameter Type | Name | Value |
+| --- | --- | --- |
+| Form Data | `request_json` | JSON string shown below |
+| n8n Binary File | `files` | Input Data Field Name such as `data` |
+
+```json
+{
+  "scenes": [
+    {
+      "start": 0,
+      "duration": 5,
+      "media": "upload://clip.mp4",
+      "caption": "Uploaded clip"
+    }
+  ],
+  "output_name": "render.mp4"
+}
+```
+
+The filename in `upload://clip.mp4` must match the uploaded binary filename.
+
+## Platform Processing and Toolkit
+
+All routes in this table require `X-API-Key` and return asynchronous job
+information.
+
+| Method | Path | n8n input |
+| --- | --- | --- |
+| POST | `/ingest` | JSON `IngestPayload` |
+| POST | `/analyze` | JSON `AnalyzePayload` |
+| POST | `/clips` | JSON `ClipsPayload` |
+| POST | `/thumbnail` | JSON `ThumbnailPayload` |
+| POST | `/thumbnail/create` | JSON `ThumbnailPayload` |
+| POST | `/metadata` | JSON `MetadataPayload` |
+| POST | `/publish` | JSON `PublishPayload` |
+| POST | `/toolkit` | JSON `ToolkitPayload` |
+| POST | `/edit` | JSON `ToolkitPayload`; alias of `/toolkit` |
+
+Toolkit example:
+
+```json
+{
+  "task": "compress",
+  "media": "https://example.com/input.mp4",
+  "output_name": "compressed.mp4",
+  "params": {
+    "crf": 28,
+    "resolution": "720p"
+  }
+}
+```
+
+## Transcription, Subtitles, Jobs, and Downloads
+
+| Method | Path | n8n input | Response |
+| --- | --- | --- | --- |
+| POST | `/transcribe` | JSON `TranscribePayload` | Transcription JSON. |
+| POST | `/subtitles` | JSON `SubtitlePayload` | File response (`.srt` or `.ass`). |
+| POST | `/scene-builder` | JSON `SceneBuildPayload` | Generated scene array. |
+| POST | `/transcribe/upload` | Multipart `file` plus optional transcription fields | Transcription JSON. |
+| GET | `/status` | Query `job_id` | Job record. |
+| GET | `/status/{job_id}` | Replace `{job_id}` | Job record. |
+| POST | `/cancel/{job_id}` | Replace `{job_id}` | Updated job record. |
+| POST | `/admin/cleanup` | Optional query `older_than_seconds` | Cleanup counts. |
+| GET | `/download` | Query `job_id`; optional `token` | File response. |
+| GET | `/download/{job_id}` | Replace `{job_id}`; optional query `token` | File response. |
+| POST | `/inspect` | Query `path` | Media metadata JSON. |
+
+Transcription body:
+
+```json
+{
+  "audio": "https://example.com/audio.mp3",
+  "model_size": "tiny",
+  "language": "en",
+  "task": "transcribe",
+  "beam_size": 5,
+  "vad_filter": true,
+  "word_timestamps": true
+}
+```
+
+Subtitle body:
+
+```json
+{
+  "events": [
+    {
+      "start": 0,
+      "end": 2.5,
+      "text": "Opening caption"
+    }
+  ],
+  "format": "srt",
+  "template": "tiktok_classic"
+}
+```
+
+## Kokoro TTS
+
+| Method | Path | n8n input | Response |
+| --- | --- | --- | --- |
+| POST | `/tts/v1/audio/speech` | JSON shown below | WAV file response. |
+
+Set the HTTP Request node's response format to **File**.
+
+```json
+{
+  "input": "This is generated speech.",
+  "voice": "af_bella.pt",
+  "model": "kokoro-v0_19.onnx",
+  "speed": 1.0
+}
+```
+
+`voice` and `model` are optional; the server uses its first configured voice and
+model when omitted.
+
+## MusicGen
+
+| Method | Path | n8n input | Response |
+| --- | --- | --- | --- |
+| GET | `/music/health` | None | Health JSON. |
+| POST | `/music/generate` | Query `prompt`; optional query `duration` | WAV file response. |
+
+For generation:
+
+- **Method:** POST
+- **URL:** `{{ $vars.STUDIO_BASE_URL }}/music/generate`
+- **Send Query Parameters:** On
+- `prompt`: `Soft cinematic instrumental`
+- `duration`: `10`
+- **Response Format:** File
+
+## Whisper Operator
+
+| Method | Path | n8n input | Response |
+| --- | --- | --- | --- |
+| POST | `/whisper/execute/{task_name}` | Multipart file or URL fields | JSON or file response. |
+| GET | `/whisper/api/health` | None | Health JSON. |
+| GET | `/whisper/api/status/{job_id}` | Replace `{job_id}` | Whisper queue status. |
+
+Use one of these multipart inputs for `/whisper/execute/{task_name}`:
+
+- `file`: n8n Binary File.
+- `url_input`: downloadable media URL.
+- `source`: alternative media URL.
+- `webhook`: optional callback URL.
+
+Supported task names:
+
+```text
+autonomous
+auto-publish
+publish
+bulk-publish
+generate-metadata
+generate-thumbnail
+schedule-post
+transcribe
+subtitles
+render
+highlights
+clips
+viral-score
+strategy
+batch
+```
+
+## Whisper Authentication
+
+These routes exist only when the Whisper authentication subsystem starts
+successfully.
+
+| Method | Path | n8n input |
+| --- | --- | --- |
+| POST | `/whisper/api/auth/signup` | JSON `SignupSchema` |
+| POST | `/whisper/api/auth/login` | JSON `LoginSchema` |
+| POST | `/whisper/api/auth/verify` | JSON `TokenSchema` |
+| POST | `/whisper/api/auth/refresh` | JSON `TokenSchema` |
+| POST | `/whisper/api/auth/logout` | No body |
+
+Examples:
+
+```json
+{
+  "email": "user@example.com",
+  "username": "studio_user",
+  "password": "strong-password"
+}
+```
+
+```json
+{
+  "email": "user@example.com",
+  "password": "strong-password"
+}
+```
+
+```json
+{
+  "token": "<JWT returned by signup or login>"
+}
+```
+
+Logout returns success but does not currently maintain a server-side token
+revocation list.
+
+## FFmpeg Editor
+
+| Method | Path | n8n input | Response |
+| --- | --- | --- | --- |
+| GET | `/editor/healthz` | None | Health and dependency checks. |
+| GET | `/editor/readyz` | None | Readiness; returns 503 when dependencies fail. |
+| GET | `/editor/tasks` | None | Editor task registry. |
+| POST | `/editor/n8n/execute/{task_id}` | JSON, multipart, or raw binary | Synchronous file response. |
+| POST | `/editor/n8n/jobs/{task_id}` | JSON, multipart, or raw binary | Background job JSON. |
+| POST | `/editor/execute/{task_id}` | Multipart fields | Synchronous file response. |
+| POST | `/editor/jobs/{task_id}` | Multipart fields | Background job JSON. |
+| GET | `/editor/status/{job_id}` | Replace `{job_id}` | Background job status. |
+| GET | `/editor/download/{job_id}` | Replace `{job_id}` | File response. |
+| GET | `/editor/history` | None | Recent output metadata. |
+| GET | `/editor/history/{history_id}/download` | Replace `{history_id}` | File response. |
+
+### Recommended editor request for n8n
+
+Use `/editor/n8n/jobs/{task_id}` for long-running jobs.
+
+Multipart request:
+
+- Add one or more **n8n Binary File** parameters. The field name may be
+  `files`.
+- Add text options as **Form Data**.
+- A URL may use `url`, `urls`, `file_url`, `source_url`, or `download_url`.
+
+JSON request:
+
+```json
+{
+  "url": "https://example.com/input.mp4",
+  "options": {
+    "resolution": "720p",
+    "crf": "28",
+    "preset": "medium",
+    "text": "Caption text"
+  }
+}
+```
+
+Raw binary request:
+
+- **Body Content Type:** n8n Binary File
+- **Input Data Field Name:** `data`
+- Add header `X-Filename: input.mp4`
+- Put editor options in query parameters.
+
+Available editor option fields:
+
+```text
+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
+```
+
+### Editor task IDs
+
+Use one value below as `{task_id}`:
+
+| Task ID | Purpose | Files |
+| --- | --- | --- |
+| `normalize` | Convert to H.264/AAC MP4 | 1 video |
+| `extract_audio` | Export MP3 audio | 1 video/audio |
+| `resize_916` | Crop to vertical 9:16 | 1 video |
+| `add_subtitles` | Burn SRT/ASS subtitles | video + subtitle |
+| `burn_lyrics` | Burn styled lyrics | video + subtitle |
+| `text_overlay` | Add caption text | 1 video |
+| `merge_music` | Add background music | video + audio |
+| `thumbnail` | Export JPG frame | 1 video |
+| `watermark` | Overlay logo/image | video + image |
+| `compress` | Reduce video size | 1 video |
+| `batch_compress` | Compress videos into ZIP | 1+ videos |
+| `make_gif` | Create GIF | 1 video |
+| `tiktok_lyrics` | Vertical lyric clip | 1 video |
+| `tiktok_pro_reframer` | Vertical reframe and style | 1 video |
+| `reels_blur_fit` | Blurred 9:16 fit | 1 video |
+| `reels_safe_caption` | Mobile-safe caption | 1 video |
+| `reels_hook_title` | Top hook/title | 1 video |
+| `reels_progress_bar` | Progress bar and trim | 1 video |
+| `reels_loop` | Loop to target duration | 1 video |
+| `reels_subtitle_safe` | Mobile-safe subtitles | video + subtitle |
+| `reels_reaction_stack` | Stack reaction videos | 2 videos |
+| `reels_audio_duck` | Duck music below video | video + audio |
+| `faceless_quote_card` | Text-only quote short | no file |
+| `faceless_story_pages` | Timed text story slides | no file |
+| `faceless_image_narration` | Image with narration | image + audio |
+| `faceless_video_narration` | B-roll with narration | video + audio |
+| `faceless_broll_montage` | Silent b-roll montage | 2+ videos |
+| `series_split_pack` | Split long video into series ZIP | 1 video |
+| `series_episode_badge` | Add episode badge | 1 video |
+| `series_batch_pack` | Package clips as numbered series | 2+ videos |
+| `series_recap_card` | Text-only recap card | no file |
+| `concat` | Join clips | 2+ videos |
+| `slideshow` | Build video from images | 2+ images |
+| `trim` | Cut by start/end | 1 video/audio |
+| `crop_aspect` | Crop to target aspect ratio | 1 video |
+| `waveform` | Create waveform video | 1 audio/video |
+| `extract_frames` | Export frames as ZIP | 1 video |
+| `add_intro_outro` | Join intro/main/outro | 2-3 videos |
+| `speed` | Change playback speed | 1 video |
+| `remove_audio` | Remove video audio | 1 video |
+| `replace_audio` | Replace video audio | video + audio |
+
+## JSON Payload Reference
+
+Fields marked `*` are required.
+
+### Rendering
+
+`ScenePayload`
+
+```text
+start*: number >= 0
+duration*: number > 0
+media*: string path or URL
+caption: string
+transition: string = "fade"
+background: string = "blur"
+layout: string = "fill"
+effect: string | null
+```
+
+`RenderPayload`
+
+```text
+scenes*: ScenePayload[]
+template: string = "tiktok_classic"
+preset, creative_style, platform: string | null
+output_name: string = "render.mp4"
+voiceover, background_music: string | null
+music_volume: number = 0.316
+music_fade_in, music_fade_out, music_start: number = 0
+music_loop, music_ducking: boolean = true
+voice_volume: number = 1
+subtitle_format: string = "ass"
+auto_subtitles: boolean = false
+subtitle_language, whisper_model_size: string | null
+preview, audio_normalize: boolean = false
+watermark, intro, outro: string | null
+watermark_position: string = "bottom-right"
+callback_url, export_target: string | null
+priority: integer = 0
+scheduled_at: number | null
+normalize: boolean = true
+metadata: object = {}
+```
+
+`AIReelsPayload`
+
+```text
+script*: string
+voiceover*: string
+assets*: string[]
+template: string = "tiktok_classic"
+creative_style, platform: string | null
+output_name: string = "ai_reel.mp4"
+background_music: string | null
+music_volume: number = 0.316
+music_fade_in, music_fade_out, music_start: number = 0
+music_loop, music_ducking: boolean = true
+voice_volume: number = 1
+```
+
+`BatchPayload`
+
+```text
+jobs*: RenderPayload[]
+```
+
+`ProjectRenderPayload`
+
+```text
+output_name: string = "project_render.mp4"
+template, preset, creative_style, platform: string | null
+callback_url, export_target: string | null
+preview: boolean = false
+normalize: boolean = true
+metadata: object = {}
+```
+
+### Projects and Editing
+
+`ProjectPayload`
+
+```text
+name*: string
+metadata: object = {}
+export_settings: object = {}
+template: object | null
+```
+
+`ProjectSavePayload`
+
+```text
+project_id: string | null
+project*: object
+```
+
+`ProjectAssetPayload`
+
+```text
+project_id*: string
+asset*: object
+```
+
+`TimelineAddPayload`
+
+```text
+project_id*: string
+track_type: string = "video"
+track_id: string | null
+item: object = {}
+```
+
+`TimelineOperationPayload`
+
+```text
+project_id*: string
+operation: string = "drag"
+item_id: string | null
+params: object = {}
+```
+
+`EffectApplyPayload`
+
+```text
+project_id, target_id, item_id: string | null
+effect*: string
+params: object = {}
+callback_url: string | null
+```
+
+`FilterApplyPayload`
+
+```text
+project_id, target_id, item_id: string | null
+filter*: string
+params: object = {}
+lut: string | null
+callback_url: string | null
+```
+
+`TransitionAddPayload`
+
+```text
+project_id, from_item_id, to_item_id, target_id: string | null
+transition*: string
+duration: number = 0.45
+params: object = {}
+callback_url: string | null
+```
+
+`KeyframePayload`
+
+```text
+project_id*: string
+target_id*: string
+property*: string
+time*: number >= 0
+value*: any JSON value
+easing: string = "linear"
+```
+
+### Generation and Platform Tools
+
+`GenerationPayload`
+
+```text
+prompt, text, media, provider: string | null
+callback_url, export_target: string | null
+params: object = {}
+additional JSON fields are accepted
+```
+
+`CaptionGeneratePayload`
+
+```text
+media, audio, text, transcript: string | null
+events: object[] | null
+template: string = "capcut"
+language: string | null
+engine: string = "whisper"
+word_timestamps: boolean = true
+emoji_insertion, speaker_detection: boolean = false
+karaoke, animated: boolean = true
+callback_url: string | null
+additional JSON fields are accepted
+```
+
+`AIToolPayload`
+
+```text
+project_id, media, transcript, text, platform: string | null
+callback_url: string | null
+params: object = {}
+additional JSON fields are accepted
+```
+
+`IngestPayload`
+
+```text
+sources*: [{ "url": string, "type": string|null, "name": string|null }]
+callback_url: string | null
+```
+
+`AnalyzePayload`
+
+```text
+media*: string
+transcript: string = ""
+platform, callback_url: string | null
+```
+
+`ClipsPayload`
+
+```text
+media*: string
+clips: object[] | null
+callback_url: string | null
+```
+
+`ThumbnailPayload`
+
+```text
+media*: string
+text: string = ""
+timestamp: number | null
+template: string = "bold"
+callback_url: string | null
+```
+
+`MetadataPayload`
+
+```text
+topic, transcript: string = ""
+platform, callback_url: string | null
+```
+
+`PublishPayload`
+
+```text
+media, asset, title, description: string | null
+platforms: string[] = []
+platform, scheduled_at: string | null
+draft: boolean = true
+callback_url: string | null
+```
+
+`ToolkitPayload`
+
+```text
+task*: string
+input, media, output_name: string | null
+params: object = {}
+callback_url, export_target: string | null
+additional JSON fields are accepted
+```
+
+### Transcription and Subtitles
+
+`TranscribePayload`
+
+```text
+audio*: string path or URL
+model_size, language: string | null
+task: string = "transcribe"
+beam_size: integer = 5
+vad_filter, word_timestamps: boolean = true
+```
+
+`SubtitlePayload`
+
+```text
+events*: [{ "start": number, "end": number, "text": string }]
+format: string = "srt"
+template: string = "tiktok_classic"
+```
+
+`SceneBuildPayload`
+
+```text
+script*: string
+assets*: string[]
+duration: number | null
+transition: string = "fade"
+creative_style: string | null
+```
+
+### Authentication
+
+`SignupSchema`
+
+```text
+email*: valid email
+username*: 3-32 letters, numbers, or underscores
+password*: 8-72 characters
+```
+
+`LoginSchema`
+
+```text
+email*: valid email
+password*: 1-72 characters
+```
+
+`TokenSchema`
+
+```text
+token*: 10-2048 characters
+```
+
+## Framework and UI Endpoints
+
+These are not business API operations:
+
+| Path | Purpose |
+| --- | --- |
+| `/dashboard` | Renderer Gradio interface. |
+| `/tts/` | Kokoro TTS Gradio interface. |
+| `/music/` | MusicGen Gradio interface. |
+| `/whisper/` | Whisper Gradio interface. |
+| `/editor/` | FFmpeg editor Gradio interface. |
+| `/mcp/` | MCP Streamable HTTP transport; use an MCP client rather than a normal REST request. |
+| `/docs` | Root FastAPI Swagger UI. |
+| `/redoc` | Root FastAPI ReDoc UI. |
+| `/openapi.json` | Root renderer OpenAPI schema. |
+| `/<service>/docs` | Mounted service Swagger UI when not shadowed by its UI mount. |
+| `/<service>/openapi.json` | Mounted service OpenAPI schema. |
+

README.editor.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`.

README.ktts-upstream.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

README.ktts.md

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

README.md

@@ -1,18 +1,55 @@
 ---
-title: FlowForge API
-emoji: ⚙️
-colorFrom: gray
-colorTo: red
+title: Unified Media Studio
+emoji: "🎬"
+colorFrom: green
+colorTo: blue
 sdk: docker
 app_port: 7860
 pinned: false
+license: mit
 ---
 
-# FlowForge API
+# Unified Media Studio
 
-FastAPI backend for the FlowForge AI n8n workflow builder.
+One Hugging Face Docker Space containing the five original applications.
 
-Configure `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `AUTH_REQUIRED=true`,
-one configured AI provider key, and `FRONTEND_URL` as Space secrets/variables before
-production deployment. The container fails fast when required production
-configuration is absent.
+| Application | Path |
+| --- | --- |
+| Rendering studio | `/dashboard` |
+| Kokoro TTS | `/tts/` |
+| MusicGen | `/music/` |
+| Whisper operator | `/whisper/` |
+| FFmpeg editor | `/editor/` |
+| MCP Streamable HTTP | `/mcp/` |
+
+The rendering API remains available at the Space root. `GET /apps` returns the
+mounted application paths.
+
+## n8n
+
+See [N8N_ENDPOINTS.md](N8N_ENDPOINTS.md) for all API endpoints, payload
+schemas, editor task IDs, file upload settings, asynchronous job handling, and
+HTTP Request node examples.
+
+## MCP
+
+Connect an MCP client to:
+
+```text
+https://<space-subdomain>.hf.space/mcp/
+```
+
+Every FastAPI application endpoint is exposed as a separate MCP tool. Tool
+arguments use a consistent transport wrapper:
+
+- `path_params`: values for placeholders such as `{job_id}`.
+- `query`: URL query parameters.
+- `body`: JSON, form, or text request body.
+- `body_type`: `json`, `form`, or `text`.
+- `headers`: forwarded headers such as `X-API-Key`.
+- `files`: multipart files containing `field_name`, `filename`,
+  `content_type`, and `content_base64`.
+
+Large response bodies are omitted from the MCP result. Increase
+`MCP_INLINE_RESPONSE_MAX_BYTES` when small generated files should be returned
+inline as base64.

README.musicgen.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

README.renderer.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.

README.whisper.md

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

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"

app.py

@@ -0,0 +1,69 @@
+from contextlib import AsyncExitStack, asynccontextmanager
+
+from fastapi.responses import RedirectResponse
+
+from editor_app import app as editor_app
+from ktts_app import app as tts_app
+from musicgen_app import app as music_app
+from mcp_server import RouteSource, create_mcp_server
+from renderer_app import app
+from whisper_app import app as whisper_app
+
+
+CHILD_APPS = (
+    ("/tts", tts_app, "tts"),
+    ("/music", music_app, "music"),
+    ("/whisper", whisper_app, "whisper"),
+    ("/editor", editor_app, "editor"),
+)
+
+renderer_lifespan = app.router.lifespan_context
+
+
+@app.get("/", include_in_schema=False)
+async def studio_home():
+    return RedirectResponse(url="/dashboard")
+
+
+@app.get("/apps", tags=["studio"])
+async def studio_apps():
+    return {
+        "renderer": "/dashboard",
+        "tts": "/tts/",
+        "music": "/music/",
+        "whisper": "/whisper/",
+        "editor": "/editor/",
+        "mcp": "/mcp/",
+        "mcp_tools": len(mcp_tool_catalog),
+    }
+
+
+for path, child_app, name in CHILD_APPS:
+    app.mount(path, child_app, name=name)
+
+
+mcp, mcp_tool_catalog = create_mcp_server(
+    app,
+    (
+        RouteSource("renderer", app),
+        RouteSource("tts", tts_app, "/tts"),
+        RouteSource("music", music_app, "/music"),
+        RouteSource("whisper", whisper_app, "/whisper"),
+        RouteSource("editor", editor_app, "/editor"),
+    ),
+)
+mcp_http_app = mcp.streamable_http_app()
+
+
+@asynccontextmanager
+async def studio_lifespan(root_app):
+    async with AsyncExitStack() as stack:
+        await stack.enter_async_context(renderer_lifespan(root_app))
+        for _, child_app, _ in CHILD_APPS:
+            await stack.enter_async_context(child_app.router.lifespan_context(child_app))
+        await stack.enter_async_context(mcp.session_manager.run())
+        yield
+
+
+app.router.lifespan_context = studio_lifespan
+app.mount("/mcp", mcp_http_app, name="mcp")

editor_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)

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

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()

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)

mcp_server.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import json
+import os
+import re
+from dataclasses import dataclass
+from typing import Any, Literal
+from urllib.parse import quote
+
+import httpx
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
+from mcp.server.fastmcp import FastMCP
+from pydantic import BaseModel, Field
+
+
+BodyType = Literal["json", "form", "text"]
+PATH_PARAMETER = re.compile(r"{(?P<name>[^}:]+)(?::(?P<converter>[^}]+))?}")
+INLINE_RESPONSE_LIMIT = int(os.getenv("MCP_INLINE_RESPONSE_MAX_BYTES", str(1024 * 1024)))
+TEXT_PREVIEW_LIMIT = int(os.getenv("MCP_TEXT_PREVIEW_MAX_CHARS", "12000"))
+RESTRICTED_HEADERS = {
+    "connection",
+    "content-length",
+    "host",
+    "transfer-encoding",
+}
+
+
+class EncodedFile(BaseModel):
+    field_name: str = Field(default="files", description="Multipart form field name.")
+    filename: str
+    content_base64: str = Field(description="Base64-encoded file content.")
+    content_type: str = "application/octet-stream"
+
+
+@dataclass(frozen=True)
+class RouteSource:
+    namespace: str
+    app: FastAPI
+    path_prefix: str = ""
+
+
+def create_mcp_server(
+    target_app: FastAPI,
+    route_sources: tuple[RouteSource, ...],
+) -> tuple[FastMCP, list[dict[str, Any]]]:
+    server = FastMCP(
+        "Unified Media Studio",
+        instructions=(
+            "Each tool maps to one Unified Media Studio HTTP endpoint. "
+            "Use path_params for URL placeholders, query for query parameters, "
+            "body for JSON or form data, headers for authentication, and files "
+            "for base64-encoded multipart uploads."
+        ),
+        host="0.0.0.0",
+        stateless_http=True,
+        json_response=True,
+        streamable_http_path="/",
+    )
+    catalog: list[dict[str, Any]] = []
+    used_names: set[str] = set()
+
+    for source in route_sources:
+        for route in source.app.routes:
+            if not isinstance(route, APIRoute):
+                continue
+
+            full_path = _join_paths(source.path_prefix, route.path)
+            for method in sorted(route.methods or []):
+                if method in {"HEAD", "OPTIONS"}:
+                    continue
+
+                tool_name = _tool_name(source.namespace, method, route, used_names)
+                description = _tool_description(method, full_path, route)
+                tool = _make_route_tool(target_app, method, full_path)
+                server.tool(name=tool_name, description=description)(tool)
+                catalog.append(
+                    {
+                        "name": tool_name,
+                        "method": method,
+                        "path": full_path,
+                        "namespace": source.namespace,
+                        "tags": list(route.tags or []),
+                    }
+                )
+
+    return server, catalog
+
+
+def _make_route_tool(target_app: FastAPI, method: str, path_template: str):
+    async def invoke_endpoint(
+        path_params: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        body_type: BodyType = "json",
+        headers: dict[str, str] | None = None,
+        files: list[EncodedFile] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Invoke the mapped Studio endpoint.
+
+        Path placeholders belong in path_params. Query-string values belong in
+        query. Use body_type="form" for form fields and files for multipart
+        uploads. Existing endpoint authentication headers are forwarded.
+        """
+        request_path = _render_path(path_template, path_params or {})
+        request_headers = _clean_headers(headers or {})
+        request_kwargs = _request_kwargs(body, body_type, files or [])
+
+        transport = httpx.ASGITransport(app=target_app, raise_app_exceptions=False)
+        async with httpx.AsyncClient(
+            transport=transport,
+            base_url="http://studio.internal",
+            follow_redirects=True,
+            timeout=None,
+        ) as client:
+            async with client.stream(
+                method,
+                request_path,
+                params=query or None,
+                headers=request_headers or None,
+                **request_kwargs,
+            ) as response:
+                return await _serialize_response(response, method, request_path)
+
+    invoke_endpoint.__name__ = f"invoke_{method.lower()}_{_slug(path_template)}"
+    return invoke_endpoint
+
+
+def _request_kwargs(
+    body: Any,
+    body_type: BodyType,
+    files: list[EncodedFile],
+) -> dict[str, Any]:
+    if files:
+        multipart_files = []
+        for item in files:
+            try:
+                content = base64.b64decode(item.content_base64, validate=True)
+            except (ValueError, binascii.Error) as exc:
+                raise ValueError(f"Invalid base64 content for {item.filename}") from exc
+            multipart_files.append(
+                (
+                    item.field_name,
+                    (item.filename, content, item.content_type),
+                )
+            )
+        return {
+            "data": _form_items(body),
+            "files": multipart_files,
+        }
+
+    if body is None:
+        return {}
+    if body_type == "json":
+        return {"json": body}
+    if body_type == "form":
+        return {"data": _form_items(body)}
+    if isinstance(body, str):
+        return {"content": body}
+    return {"content": json.dumps(body)}
+
+
+def _form_items(body: Any) -> dict[str, str | list[str]]:
+    if body is None:
+        return {}
+    if not isinstance(body, dict):
+        raise ValueError("Form bodies must be JSON objects")
+
+    items: dict[str, str | list[str]] = {}
+    for key, value in body.items():
+        values = value if isinstance(value, list) else [value]
+        encoded_values: list[str] = []
+        for item in values:
+            if isinstance(item, (dict, list)):
+                encoded = json.dumps(item)
+            elif item is None:
+                encoded = ""
+            elif isinstance(item, bool):
+                encoded = str(item).lower()
+            else:
+                encoded = str(item)
+            encoded_values.append(encoded)
+        items[str(key)] = encoded_values if isinstance(value, list) else encoded_values[0]
+    return items
+
+
+def _render_path(path_template: str, path_params: dict[str, Any]) -> str:
+    expected = {match.group("name") for match in PATH_PARAMETER.finditer(path_template)}
+    missing = sorted(expected - path_params.keys())
+    if missing:
+        raise ValueError(f"Missing path parameters: {', '.join(missing)}")
+
+    def replace(match: re.Match[str]) -> str:
+        name = match.group("name")
+        converter = match.group("converter")
+        safe = "/" if converter == "path" else ""
+        return quote(str(path_params[name]), safe=safe)
+
+    return PATH_PARAMETER.sub(replace, path_template)
+
+
+async def _serialize_response(
+    response: httpx.Response,
+    method: str,
+    request_path: str,
+) -> dict[str, Any]:
+    content_type = response.headers.get("content-type", "").split(";", 1)[0].lower()
+    result: dict[str, Any] = {
+        "status_code": response.status_code,
+        "method": method,
+        "path": request_path,
+        "content_type": content_type or None,
+    }
+
+    for header in ("content-disposition", "location"):
+        if header in response.headers:
+            result[header.replace("-", "_")] = response.headers[header]
+
+    declared_size = _content_length(response.headers.get("content-length"))
+    if declared_size is not None and declared_size > INLINE_RESPONSE_LIMIT:
+        result["size_bytes"] = declared_size
+        result["body_omitted"] = True
+        return result
+
+    content = await _read_bounded(response, INLINE_RESPONSE_LIMIT + 1)
+    if not content:
+        result["body"] = None
+        return result
+
+    if len(content) > INLINE_RESPONSE_LIMIT:
+        result["size_bytes_at_least"] = len(content)
+        result["body_omitted"] = True
+        if _is_text_content(content_type):
+            result["preview"] = content[:TEXT_PREVIEW_LIMIT].decode("utf-8", errors="replace")
+        return result
+
+    if content_type == "application/json" or content_type.endswith("+json"):
+        try:
+            result["body"] = json.loads(content)
+        except (UnicodeDecodeError, ValueError):
+            result["body"] = content[:TEXT_PREVIEW_LIMIT].decode("utf-8", errors="replace")
+        return result
+
+    if _is_text_content(content_type):
+        result["body"] = content[:TEXT_PREVIEW_LIMIT].decode("utf-8", errors="replace")
+        return result
+
+    result["size_bytes"] = len(content)
+    result["body_base64"] = base64.b64encode(content).decode("ascii")
+    return result
+
+
+async def _read_bounded(response: httpx.Response, limit: int) -> bytes:
+    content = bytearray()
+    async for chunk in response.aiter_bytes():
+        remaining = limit - len(content)
+        if remaining <= 0:
+            break
+        content.extend(chunk[:remaining])
+        if len(content) >= limit:
+            break
+    return bytes(content)
+
+
+def _content_length(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return max(0, int(value))
+    except ValueError:
+        return None
+
+
+def _tool_name(
+    namespace: str,
+    method: str,
+    route: APIRoute,
+    used_names: set[str],
+) -> str:
+    base = _slug(f"{namespace}_{method}_{route.name or route.path}")
+    if len(base) > 96:
+        digest = hashlib.sha1(base.encode("utf-8")).hexdigest()[:10]
+        base = f"{base[:85]}_{digest}"
+
+    candidate = base
+    suffix = 2
+    while candidate in used_names:
+        candidate = f"{base}_{suffix}"
+        suffix += 1
+    used_names.add(candidate)
+    return candidate
+
+
+def _tool_description(method: str, full_path: str, route: APIRoute) -> str:
+    summary = route.summary or route.description or route.name or "Studio API endpoint"
+    summary = " ".join(summary.split())
+    return (
+        f"{method} {full_path}. {summary} "
+        "Arguments: path_params, query, body, body_type, headers, and base64 files."
+    )
+
+
+def _join_paths(prefix: str, path: str) -> str:
+    if not prefix:
+        return path or "/"
+    if path == "/":
+        return f"{prefix.rstrip('/')}/"
+    return f"{prefix.rstrip('/')}/{path.lstrip('/')}"
+
+
+def _clean_headers(headers: dict[str, str]) -> dict[str, str]:
+    return {
+        str(key): str(value)
+        for key, value in headers.items()
+        if str(key).lower() not in RESTRICTED_HEADERS
+    }
+
+
+def _is_text_content(content_type: str) -> bool:
+    return (
+        content_type.startswith("text/")
+        or content_type in {"application/javascript", "application/xml"}
+        or content_type.endswith("+xml")
+    )
+
+
+def _slug(value: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", value).strip("_").lower()
+    return cleaned or "endpoint"

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="/")

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}"

renderer_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)

requirements.editor.txt

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

requirements.ktts.txt

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

requirements.musicgen.txt

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

requirements.renderer.txt

@@ -0,0 +1,11 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+gradio>=5.0.0
+huggingface_hub<1.0
+pydantic>=2.7.0
+python-multipart>=0.0.9
+psutil>=5.9.8
+pytest>=8.2.0
+pytest-cov>=5.0.0
+httpx>=0.27.0
+faster-whisper>=1.0.0

requirements.txt

@@ -1,9 +1,44 @@
-fastapi==0.139.0
-uvicorn[standard]==0.51.0
-pydantic==2.13.4
-pydantic-settings==2.14.2
-httpx==0.28.1
-PyJWT[crypto]==2.10.1
-python-multipart==0.0.20
-pytest==8.3.4
-pytest-asyncio==0.25.0
+--extra-index-url https://download.pytorch.org/whl/cpu
+
+accelerate
+aiofiles>=23.2.1
+email-validator
+fastapi>=0.115.0
+faster-whisper==1.0.3
+ffmpeg-python>=0.2.0
+google-api-python-client>=2.118.0
+google-auth>=2.29.0
+google-auth-httplib2>=0.2.0
+google-auth-oauthlib>=1.2.0
+google-generativeai>=0.7.2
+gradio>=5.0.0
+httplib2>=0.22.0
+huggingface_hub<1.0
+httpx>=0.27.0
+imageio>=2.34.0
+imageio-ffmpeg>=0.4.9
+moviepy==1.0.3
+mcp>=1.28.1,<2
+numpy>=1.26.0
+onnxruntime
+passlib[bcrypt]>=1.7.4
+phonemizer
+psutil>=5.9.8
+psycopg2-binary>=2.9.9
+pydantic>=2.7.0
+pytest>=8.2.0
+pytest-cov>=5.0.0
+pysrt>=1.1.2
+python-jose[cryptography]>=3.3.0
+python-magic
+python-multipart>=0.0.9
+requests>=2.31.0
+scipy
+soundfile
+sqlalchemy>=2.0.25
+torch
+torchaudio
+torchvision
+transformers
+uvicorn[standard]>=0.30.0
+yt-dlp>=2025.1.0

requirements.whisper.txt

@@ -0,0 +1,71 @@
+# =========================
+# CORE API
+# =========================
+fastapi>=0.110.0
+uvicorn[standard]>=0.27.0
+python-multipart>=0.0.9
+
+# =========================
+# UI
+# =========================
+gradio>=4.0.0
+
+# =========================
+# VIDEO PIPELINE
+# =========================
+faster-whisper==1.0.3
+moviepy==1.0.3
+ffmpeg-python>=0.2.0
+imageio>=2.34.0
+imageio-ffmpeg>=0.4.9
+pysrt>=1.1.2
+
+# =========================
+# NUMERICS / DATA
+# =========================
+numpy>=1.26.0
+pydantic>=2.6.0
+
+# =========================
+# YOUTUBE / SOCIAL INGESTION
+# =========================
+yt-dlp>=2025.1.0
+
+# =========================
+# HTTP / NETWORK
+# =========================
+requests>=2.31.0
+httplib2>=0.22.0
+
+# =========================
+# GOOGLE YOUTUBE + PLATFORM APIs
+# =========================
+google-api-python-client>=2.118.0
+google-auth>=2.29.0
+google-auth-oauthlib>=1.2.0
+google-auth-httplib2>=0.2.0
+
+# =========================
+# GEMINI AI
+# =========================
+google-generativeai>=0.7.2
+
+# =========================
+# AUTH SYSTEM (JWT + SECURITY)
+# =========================
+python-jose[cryptography]>=3.3.0
+
+# FIXED BCRYPT STACK (CRITICAL STABILITY FIX)
+passlib[bcrypt]>=1.7.4
+email-validator
+
+# =========================
+# DATABASE (SQLALCHEMY + POSTGRES)
+# =========================
+sqlalchemy>=2.0.25
+psycopg2-binary>=2.9.9
+
+# =========================
+# OPTIONAL STABILITY LAYER
+# =========================
+aiofiles>=23.2.1

start.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -e
+
+echo "Starting Unified Media Studio..."
+
+exec uvicorn app:app --host 0.0.0.0 --port "${PORT:-7860}"

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
+"""
+}

whisper_app.py

@@ -0,0 +1,361 @@
+from fastapi import FastAPI, UploadFile, File, Form, Request
+from fastapi.responses import FileResponse, JSONResponse
+from contextlib import asynccontextmanager
+import os
+import uuid
+import asyncio
+from pathlib import Path
+import gradio as gr
+
+# ==============================
+# LOGGER + QUEUE
+# ==============================
+from utils.logger import logger
+from utils.job_queue import start_worker, create_job, get_job
+from ingestion.resolver import resolve_input
+
+# ==============================
+# AUTH SYSTEM (HARDENED IMPORT)
+# ==============================
+try:
+    from auth.routes import router as auth_router
+    from auth.database import Base, engine
+    AUTH_ENABLED = True
+except Exception as e:
+    logger.error(f"[AUTH BOOT FAILED] {e}")
+    AUTH_ENABLED = False
+
+# ==============================
+# CORE PIPELINE
+# ==============================
+from utils.transcription import transcribe_video
+from utils.srt import generate_srt
+from utils.render import render_subtitles
+from utils.highlights import detect_highlights
+from utils.viral_scorer import score_clip
+from utils.director import rewrite_script, viral_score
+from utils.engagement import simulate_retention
+from utils.platform import adapt_platform
+from utils.persona import predict_audience
+from utils.clipper import create_clips
+from utils.autonomous_engine import run_autonomous_engine
+
+# ==============================
+# PUBLISHER
+# ==============================
+from publisher.publisher_ai import autonomous_loop
+from publisher.scheduler_engine import init_scheduler
+from publisher.platform_dispatcher import dispatch_publish
+from publisher.bulk import execute as bulk_execute
+from publisher.metadata_engine import generate_metadata
+from publisher.thumbnail_engine import generate_thumbnail
+
+# ==============================
+# SAFE bcrypt SHIELD (DO NOT FAIL BOOT)
+# ==============================
+try:
+    import bcrypt
+except Exception as e:
+    logger.warning(f"[bcrypt warning ignored] {e}")
+
+# ==============================
+# INIT
+# ==============================
+BASE_DIR = Path(__file__).resolve().parent
+UPLOAD_DIR = str(BASE_DIR / "jobs")
+os.makedirs(UPLOAD_DIR, exist_ok=True)
+
+
+# =========================================================
+# SAFE DB INITIALIZATION
+# =========================================================
+def init_database_safe():
+    if not AUTH_ENABLED:
+        logger.warning("Auth disabled - skipping DB init")
+        return
+
+    try:
+        Base.metadata.create_all(bind=engine)
+        logger.info("Database initialized successfully")
+    except Exception as e:
+        logger.error(f"Database init failed (non-fatal): {e}")
+
+
+# =========================================================
+# LIFECYCLE
+# =========================================================
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+
+    logger.info("Starting Basyx Whisper V10.1")
+
+    # DB init (NON-FATAL)
+    init_database_safe()
+
+    # workers (must not block boot)
+    try:
+        start_worker()
+    except Exception as e:
+        logger.error(f"Worker failed: {e}")
+
+    # scheduler
+    try:
+        init_scheduler()
+    except Exception as e:
+        logger.error(f"Scheduler failed: {e}")
+
+    # autonomous engine (isolated task)
+    try:
+        asyncio.create_task(autonomous_loop())
+    except Exception as e:
+        logger.error(f"Autonomous engine failed: {e}")
+
+    yield
+
+    logger.info("Shutdown complete")
+
+
+# =========================================================
+# APP
+# =========================================================
+app = FastAPI(
+    title="Basyx Whisper V10.1 Autonomous Operator",
+    lifespan=lifespan,
+)
+
+# AUTH ROUTER (only if available)
+if AUTH_ENABLED:
+    app.include_router(auth_router)
+
+
+# =========================================================
+# TASKS
+# =========================================================
+VALID_TASKS = {
+    "autonomous",
+    "auto-publish",
+    "publish",
+    "bulk-publish",
+    "generate-metadata",
+    "generate-thumbnail",
+    "schedule-post",
+    "transcribe",
+    "subtitles",
+    "render",
+    "highlights",
+    "viral-score",
+    "strategy",
+    "batch",
+    "clips",
+}
+
+
+def normalize_task(task: str):
+    task = task.lower().replace("_", "-")
+    if task not in VALID_TASKS:
+        raise Exception(f"Unknown task: {task}")
+    return task
+
+
+# =========================================================
+# SAFE INPUT RESOLVER
+# =========================================================
+async def safe_resolve(file, source):
+    try:
+        if not file and not source:
+            return None
+
+        upload_file = file if isinstance(file, UploadFile) else None
+
+        return await asyncio.to_thread(resolve_input, source, upload_file)
+
+    except Exception as e:
+        logger.error(f"resolve_input failed: {e}")
+        return None
+
+
+# =========================================================
+# EXECUTION ENGINE
+# =========================================================
+async def execute_task(video_path, task, payload=None, webhook=None):
+
+    payload = payload or {}
+
+    if task == "bulk-publish":
+        return await bulk_execute(payload), None
+
+    if task not in ["bulk-publish", "schedule-post"] and not video_path:
+        return {"error": "No valid input resolved"}, None
+
+    if task == "autonomous":
+        return await asyncio.to_thread(run_autonomous_engine, video_path), None
+
+    if task == "auto-publish":
+        auto = await asyncio.to_thread(run_autonomous_engine, video_path)
+        return await dispatch_publish(variants=auto.get("all_variants", [])), None
+
+    if task == "publish":
+        return await dispatch_publish(video_path=video_path, payload=payload), None
+
+    if task == "generate-metadata":
+        return generate_metadata(video_path), None
+
+    if task == "generate-thumbnail":
+        output_path = os.path.join(UPLOAD_DIR, f"{uuid.uuid4()}.jpg")
+        thumb = generate_thumbnail(video_path, output=output_path)
+        return {"thumbnail": thumb}, output_path
+
+    if task == "batch":
+        job_id = create_job(video_path, webhook=webhook)
+        return {"status": "queued", "job_id": job_id}, None
+
+    if task == "transcribe":
+        words = await asyncio.to_thread(transcribe_video, video_path)
+        return {"words": words}, None
+
+    if task == "subtitles":
+        words = await asyncio.to_thread(transcribe_video, video_path)
+        return {"srt": generate_srt(words)}, None
+
+    if task == "render":
+        words = await asyncio.to_thread(transcribe_video, video_path)
+        srt = generate_srt(words)
+
+        output = os.path.join(UPLOAD_DIR, f"{uuid.uuid4()}_render.mp4")
+
+        await asyncio.to_thread(render_subtitles, video_path, srt, output)
+
+        return {"status": "render_complete"}, output
+
+    if task == "highlights":
+        words = await asyncio.to_thread(transcribe_video, video_path)
+        highlights = detect_highlights(words) or []
+        clips = create_clips(video_path, highlights)
+
+        return {"clips_created": len(clips)}, (clips[0] if clips else None)
+
+    if task == "clips":
+        words = await asyncio.to_thread(transcribe_video, video_path)
+        highlights = detect_highlights(words) or []
+        return {"clips": create_clips(video_path, highlights)}, None
+
+    if task == "viral-score":
+        words = await asyncio.to_thread(transcribe_video, video_path)
+        segments = detect_highlights(words) or []
+        return {"scores": [score_clip(s) for s in segments]}, None
+
+    if task == "strategy":
+        words = await asyncio.to_thread(transcribe_video, video_path)
+
+        script = rewrite_script(words)
+        persona = predict_audience(words)
+        curve = simulate_retention(words)
+
+        return {
+            "hook": script["hook"],
+            "persona": persona,
+            "viral_score": viral_score(curve),
+            "platforms": {
+                "tiktok": adapt_platform(script, "tiktok"),
+                "reels": adapt_platform(script, "reels"),
+            },
+        }, None
+
+    return {"error": "Task execution failed"}, None
+
+
+# =========================================================
+# ROUTER
+# =========================================================
+@app.post("/execute/{task_name}")
+async def execute_router(
+    request: Request,
+    task_name: str,
+    file: UploadFile = File(None),
+    url_input: str = Form(None),
+    source: str = Form(None),
+    webhook: str = Form(None),
+):
+
+    try:
+        task = normalize_task(task_name)
+        payload = {}
+
+        if request.headers.get("content-type", "").startswith("application/json"):
+            payload = await request.json()
+
+        video_path = await safe_resolve(file, url_input or source)
+
+        result, output = await execute_task(video_path, task, payload, webhook)
+
+        if output and isinstance(output, str) and os.path.exists(output):
+            return FileResponse(output)
+
+        return {"task": task, "result": result}
+
+    except Exception as e:
+        logger.exception(e)
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+# =========================================================
+# HEALTH
+# =========================================================
+@app.get("/api/health")
+def health():
+    return {
+        "status": "online",
+        "version": "V10.1",
+        "auth_enabled": AUTH_ENABLED
+    }
+
+
+@app.get("/api/status/{job_id}")
+def status(job_id: str):
+    return get_job(job_id) or {"error": "Job not found"}
+
+
+# =========================================================
+# GRADIO UI
+# =========================================================
+async def ui_handler(video, task, webhook, url_input):
+
+    source = url_input or video
+    video_path = await safe_resolve(video, source)
+
+    result, output = await execute_task(
+        video_path,
+        normalize_task(task),
+        {},
+        webhook,
+    )
+
+    return str(result), output
+
+
+with gr.Blocks() as demo:
+
+    gr.Markdown("# 🚀 Basyx Whisper V10.1 Stable Operator")
+
+    video_input = gr.Video()
+    url_input = gr.Textbox(label="Video URL")
+
+    task_dropdown = gr.Dropdown(
+        choices=list(VALID_TASKS),
+        value="autonomous",
+    )
+
+    webhook_input = gr.Textbox(label="Webhook")
+
+    run_btn = gr.Button("Execute")
+
+    output_box = gr.Textbox()
+    video_output = gr.Video()
+
+    run_btn.click(
+        ui_handler,
+        [video_input, task_dropdown, webhook_input, url_input],
+        [output_box, video_output],
+    )
+
+app = gr.mount_gradio_app(app, demo, path="/")