Turn any idea into a shot-by-shot storyboard with AI-powered scene analysis, mood scoring, and soundtrack vibes.
CutAI takes a short script — written by you or generated by AI from a genre and premise — and breaks it into professional, filmable scenes with shot-by-shot breakdowns, camera angle suggestions, mood analysis, and soundtrack vibes. Everything is presented in a drag-and-drop visual storyboard editor with a dark film-editing aesthetic. Think Figma meets screenplay software meets AI.
📜 AI Script Generation Enter a genre and premise, and CutAI writes a short screenplay with properly structured scenes, slug lines, and dialogue.
🎥 Shot-by-Shot Breakdown Every scene is analyzed into individual shots with shot type (wide, close-up, tracking), camera angle (low-angle, dutch, bird's-eye), camera movement (dolly, crane, pan), and duration estimates.
🎨 Rich Text Storyboard Panels Scene cards feature mood-colored gradient backgrounds, monospace scene descriptions, time-of-day indicators, camera badges, and character tags — a premium film production document feel without requiring image generation.
:drag: Drag-and-Drop Storyboard Canvas Reorder scenes by dragging cards on a responsive grid. Changes persist to the database instantly.
📊 Mood Analysis Four-dimensional mood scoring (tension, emotion, energy, darkness) visualized as an arc across scenes with interactive Recharts graphs.
🎵 Soundtrack Vibes Per-scene soundtrack suggestions including genre, tempo, instruments, and reference tracks (e.g., "Similar to: Hans Zimmer — Time").
🛤️ Visual Timeline React Flow-powered timeline with mood-colored nodes, scene connections, and click-to-navigate synchronization with the storyboard.
✏️ Inline Editing & Regeneration Edit scene titles, descriptions, and shot details inline. Regenerate any scene's analysis with one click.
📦 Export Download your storyboard as JSON or a professionally formatted PDF with mood bars, shot tables, and scene breakdowns.
🏠 Project Management Create, list, duplicate, and delete projects from a gallery home page.
CutAI supports two modes for LLM-powered generation, switchable via a single environment variable:
- Model:
llama-3.1-8b-instant - Speed: Ultra-fast inference (~300 tokens/sec)
- Requirements: Just a free Groq API key — no GPU needed, runs on any machine
- Best for: Deployment, low-spec machines, quick iteration
- Model:
qwen2.5:3b(orqwen2.5:7bfor higher quality) - Speed: Moderate (depends on GPU)
- Requirements: NVIDIA GPU with 4–6 GB VRAM, Ollama installed
- Best for: Fully offline use, zero API costs, unlimited generation, privacy
Switch between them with one env var:
LLM_PROVIDER=groq # Cloud mode (default)
LLM_PROVIDER=local # Local mode via OllamaCutAI also supports local Stable Diffusion 1.5 for AI-generated storyboard frame images when a capable GPU is available:
IMAGE_PROVIDER=local # Local SD 1.5 (requires NVIDIA GPU, 6GB+ VRAM)
IMAGE_PROVIDER=replicate # Replicate API (cloud)User Input (genre + premise OR raw script)
|
v
┌──────────────┐
│ LLM Engine │ Groq API or local Ollama
│ (Llama/Qwen)│
└──────┬───────┘
│
v
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Script Parser│────>│Scene Analyzer│────>│ SD Prompt │
│ (scenes + │ │ (shots, mood,│ │ Generator │
│ structure) │ │ soundtrack) │ │ (per shot) │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
v v v
┌─────────────────────────────────────────────────────────┐
│ SQLite Database │
│ Projects → Scripts → Scenes → Shots (with SD prompts) │
└────────────────────────┬────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────────┐
│ React Frontend │
│ Storyboard Canvas │ Shot Panel │ Timeline │ Mood Graph │
└─────────────────────────────────────────────────────────┘
- Python 3.11+
- Node.js 18+
- A Groq API key (free tier works)
git clone https://github.com/Swapnil-bo/CutAI.git
cd CutAIcd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txtcd frontend
npm installCreate backend/.env:
GROQ_API_KEY=your_groq_api_key_here
LLM_PROVIDER=groq# Terminal 1 — Backend
cd backend
uvicorn main:app --reload --port 8000
# Terminal 2 — Frontend
cd frontend
npm run devOpen http://localhost:5173 and start creating.
For fully offline generation with no API costs:
Download from ollama.com and install.
ollama pull qwen2.5:3b # Lightweight, ~2GB VRAM
# OR
ollama pull qwen2.5:7b # Higher quality, ~4.5GB VRAMUpdate backend/.env:
LLM_PROVIDER=local
OLLAMA_MODEL=qwen2.5:3bOllama runs as a background service automatically after installation. Verify:
ollama ps # Check loaded models
ollama list # Check installed models| Mode | GPU | RAM | Notes |
|---|---|---|---|
| Cloud (Groq) | None required | 4 GB+ | Works on any machine — laptop, desktop, even a Raspberry Pi |
| Local LLM (Ollama) | NVIDIA RTX 3050+ (4–6 GB VRAM) | 8 GB+ | Qwen 2.5 3B uses ~2 GB VRAM, 7B uses ~4.5 GB |
| Local LLM + SD 1.5 | NVIDIA RTX 3050+ (6 GB VRAM) | 8 GB+ | Sequential pipeline — LLM and SD never run simultaneously |
Note: On 8 GB RAM systems, Ollama context window is limited to
num_ctx=4096to prevent memory pressure. Close unnecessary applications during local generation.
| Layer | Technology |
|---|---|
| Frontend | React 18, Vite, Tailwind CSS, Zustand, Framer Motion |
| Drag & Drop | @dnd-kit/core, @dnd-kit/sortable |
| Timeline | React Flow |
| Charts | Recharts |
| Backend | FastAPI, Python 3.13, Pydantic v2 |
| Database | SQLite + SQLAlchemy (async via aiosqlite) |
| Cloud LLM | Groq API (llama-3.1-8b-instant) |
| Local LLM | Ollama (qwen2.5:3b / qwen2.5:7b) |
| Image Gen | Stable Diffusion 1.5 (local) / Replicate SDXL (cloud) |
| PDF Export | fpdf2 |
| Icons | Lucide React |
- AI-Generated Storyboard Frames — Local Stable Diffusion 1.5 image generation per shot (pending PSU upgrade for stable GPU power delivery)
- Replicate SDXL Integration — Cloud image generation for deployment without GPU requirements
- Audio Generation — AI-composed scene soundtracks based on mood scores and soundtrack vibes
- Video Export — Stitch storyboard frames into an animatic with shot timing and transitions
- Collaborative Editing — Real-time multi-user storyboard editing with WebSocket sync
- Version History — Scene-level undo/redo and version diffing
- Custom Art Styles — LoRA fine-tuned models for consistent visual styles across a project
cutai/
├── backend/
│ ├── main.py # FastAPI app + CORS + static files
│ ├── config.py # Settings, model names, env vars
│ ├── models/
│ │ ├── database.py # Async SQLAlchemy engine
│ │ ├── schemas.py # Pydantic models (Script, Scene, Shot, Mood, Soundtrack)
│ │ └── db_models.py # SQLAlchemy ORM models
│ ├── services/
│ │ ├── llm_client.py # Ollama/Groq wrapper with JSON mode
│ │ ├── script_parser.py # Script generation + parsing
│ │ ├── scene_analyzer.py# Shots, mood, soundtrack analysis
│ │ └── vram_manager.py # GPU memory orchestration
│ └── routers/
│ ├── storyboard.py # Generation pipeline + SSE + export
│ ├── scenes.py # Scene CRUD + regeneration
│ ├── scripts.py # Script CRUD
│ └── projects.py # Project management
├── frontend/
│ └── src/
│ ├── components/
│ │ ├── storyboard/ # Canvas, SceneCard, ShotPanel
│ │ ├── timeline/ # React Flow visual timeline
│ │ ├── analysis/ # MoodGraph, SoundtrackPanel, CameraAngleTag
│ │ ├── script/ # ScriptEditor, ScriptGenerator
│ │ └── layout/ # Header, Sidebar, MainCanvas
│ └── stores/ # Zustand (project, storyboard, UI)
└── docs/screenshots/
Built by Swapnil as part of 100 Days of Vibe Coding
Powered by Claude Code (Opus 4.6)