Start dev server (serves both API and frontend at http://localhost:8000)

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Start dev server (serves both API and frontend at http://localhost:8000)
python -m backend.main

# Install dependencies
pip install -r backend/requirements.txt

# Test MiniMax API connectivity
python backend/test_minimax.py

# Required system dependency
# ffmpeg must be installed (brew install ffmpeg)

No build step, no linting, no test suite. Frontend is a single HTML file served via FastAPI StaticFiles.

Architecture

Multi-agent video production pipeline. User prompt goes through 6 sequential agents, producing a final MP4.

POST /api/create  -->  background thread runs pipeline  -->  SSE via GET /api/stream/{job_id}

Pipeline stages (sequential):
  Director (MiniMax M1 LLM)    -> shot outline JSON
  Script   (MiniMax M1 LLM)    -> production script with video_prompt, narration, subtitle per shot
  Visual   (Hailuo 2.3 video)  -> parallel video clips (ThreadPoolExecutor, max_workers=3)
  Voice    (Speech-2.6-HD TTS) -> sequential narration audio per shot
  Music    (Music-2.0)         -> single background track (optional)
  Editor   (ffmpeg)            -> concat videos, mix audio, burn subtitles -> final.mp4

Key data flow: Each agent's run() returns structured data consumed by the next agent. Director outputs {title, style, total_duration, shots[]}. Script enriches each shot with video_prompt (optimized for Hailuo), polished narration, and subtitle. Visual/Voice/Music produce file paths. Editor composites everything via ffmpeg subprocess calls.

Job lifecycle: main.py stores jobs in an in-memory dict. Pipeline runs in run_in_executor (background thread). Progress events accumulate in jobs[job_id]["events"] list, polled by SSE endpoint every 1s.

Frontend-backend coupling: Frontend JS references stages by name (director, script, visual, voice, music, editor) in stageMap to highlight corresponding UI cards. These stage names must match pipeline.py emit calls.

Key Conventions

• Every agent module in backend/agents/ exposes a run() function as its sole public interface
• All MiniMax API calls must check data["base_resp"]["status_code"] != 0 before accessing response payload -- API returns HTTP 200 even on business errors (insufficient balance, rate limit, etc.)
• LLM agents (director, script) strip markdown code fences from responses before JSON parsing
• Frontend uses relative API paths (/api/...). FastAPI app.mount("/", StaticFiles(...)) must be registered after all API routes
• Generated media files go to backend/output/ (gitignored). Config auto-creates this directory on import.
• Environment: single .env file at project root with MINIMAX_API_KEY

Mistakes Log