Upload 5 files

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    TEMP_DIR=/app/temp \
+    EXPORTS_DIR=/app/exports \
+    JOBS_DIR=/app/jobs \
+    BASYX_BASE_DIR=/app \
+    MAX_RENDER_WORKERS=1 \
+    FFMPEG_TIMEOUT_SECONDS=900 \
+    MAX_RETRIES=3
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    fonts-dejavu-core \
+    libmagic1 \
+    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 \
+    && chmod -R 777 /app/temp /app/exports /app/jobs
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,199 @@
+---
+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 --> 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"]
+    Normalize --> FFmpeg["FFmpeg / FFprobe"]
+    Scenes --> FFmpeg
+    Subtitles --> FFmpeg
+    Transitions --> FFmpeg
+    Audio --> FFmpeg
+```
+
+Package layout:
+
+```text
+renderer/
+  core/          settings, models, 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.
+
+### `POST /render`
+
+Submit one render job.
+
+```json
+{
+  "template": "tiktok_classic",
+  "output_name": "campaign_clip.mp4",
+  "voiceover": "/app/uploads/voiceover.wav",
+  "background_music": "/app/uploads/music.mp3",
+  "subtitle_format": "ass",
+  "normalize": true,
+  "scenes": [
+    {
+      "start": 0,
+      "duration": 5,
+      "media": "/app/uploads/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"
+}
+```
+
+### `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": "/app/uploads/voiceover.wav",
+  "assets": ["/app/uploads/scene1.jpg", "/app/uploads/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": "/app/uploads/a.mp4"}]
+    }
+  ]
+}
+```
+
+### `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. If the job is still running, the endpoint returns `409`.
+
+### `POST /inspect`
+
+Probe one asset path and return MIME type, duration, codecs, bitrate, resolution, FPS, stream list, and cache metadata.
+
+## 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.
+
+## Reliability
+
+- FFmpeg subprocesses are killed after `FFMPEG_TIMEOUT_SECONDS`.
+- 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.

api.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+
+from renderer.core.config import Settings
+from renderer.core.models import AIReelsRequest, RenderRequest, Scene
+from renderer.jobs import JobManager
+from renderer.scenes import Timeline
+
+settings = Settings()
+settings.ensure_dirs()
+job_manager = JobManager(settings)
+api = FastAPI(title="Basyx FFmpeg Rendering Engine", version="1.0.0")
+
+
+class ScenePayload(BaseModel):
+    start: float = Field(ge=0)
+    duration: float = Field(gt=0)
+    media: str
+    caption: str = ""
+    transition: str = "fade"
+    background: str = "blur"
+
+
+class RenderPayload(BaseModel):
+    scenes: list[ScenePayload]
+    template: str = "tiktok_classic"
+    output_name: str = "render.mp4"
+    voiceover: str | None = None
+    background_music: str | None = None
+    subtitle_format: str = "ass"
+    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"
+    output_name: str = "ai_reel.mp4"
+    background_music: str | None = None
+
+
+class BatchPayload(BaseModel):
+    jobs: list[RenderPayload]
+
+
+@api.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@api.post("/render")
+def render(payload: RenderPayload | AIReelsPayload) -> dict[str, str]:
+    if isinstance(payload, AIReelsPayload):
+        job_id = job_manager.submit_ai_reels(AIReelsRequest(**payload.model_dump()))
+    else:
+        job_id = job_manager.submit_render(_render_request(payload))
+    return {"job_id": job_id, "status_url": f"/status/{job_id}", "download_url": f"/download/{job_id}"}
+
+
+@api.post("/render/ai-reels")
+def render_ai_reels(payload: AIReelsPayload) -> dict[str, str]:
+    job_id = job_manager.submit_ai_reels(AIReelsRequest(**payload.model_dump()))
+    return {"job_id": job_id, "status_url": f"/status/{job_id}", "download_url": f"/download/{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.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.get("/download/{job_id}")
+def download(job_id: str) -> 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}")
+    path = Path(record.output_path)
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="Output file is missing")
+    return FileResponse(path, media_type="video/mp4", filename=path.name)
+
+
+@api.post("/inspect")
+def inspect_asset(path: str) -> dict:
+    from renderer import RenderEngine
+
+    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:
+    request = RenderRequest(
+        scenes=[Scene(**scene.model_dump()) for scene in payload.scenes],
+        template=payload.template,
+        output_name=payload.output_name,
+        voiceover=payload.voiceover,
+        background_music=payload.background_music,
+        subtitle_format=payload.subtitle_format,  # type: ignore[arg-type]
+        normalize=payload.normalize,
+        metadata=payload.metadata,
+    )
+    Timeline(request.scenes)
+    return request

app.py

@@ -0,0 +1,118 @@
+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, settings
+from renderer import RenderEngine
+from renderer.core.models import AIReelsRequest
+from renderer.scenes import Timeline
+from renderer.templates import list_templates
+
+
+def create_dashboard() -> gr.Blocks:
+    with gr.Blocks(title="Basyx FFmpeg Rendering Engine") as demo:
+        gr.Markdown(
+            "# Basyx FFmpeg Rendering Engine\n"
+            "CPU-first rendering backend for reels, shorts, audiograms, captions, slideshows, and batch jobs."
+        )
+        with gr.Tab("Render"):
+            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")
+            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], 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("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)
+
+    return demo
+
+
+def _submit_render_json(payload: str) -> dict[str, Any]:
+    data = 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 _submit_batch_json(payload: str) -> dict[str, Any]:
+    data = json.loads(payload)
+    requests = [Timeline.request_from_payload(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) -> dict[str, Any]:
+    request = AIReelsRequest(script=script, voiceover=voiceover, assets=assets or [], template=template)
+    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)
+
+
+app = gr.mount_gradio_app(api, create_dashboard(), path="/dashboard")
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860)

requirements.txt

@@ -0,0 +1,9 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+gradio>=5.0.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