A unified AI VFX production pipeline for cinematographically accurate image and video generation
Project Eliot
Director's Console combines a Cinema Prompt Engineering (CPE) rules engine, a Storyboard Canvas for visual production planning, a Gallery for browsing, organizing, and managing all project media, and an Orchestrator for distributed rendering across multiple ComfyUI nodes. Every prompt it generates is grounded in real-world cinematography — real cameras, real lenses, real film stocks, real lighting equipment — ensuring that only what is physically and historically possible can be configured.
- Key Features
- Screenshots
- Installation
- Quick Start
- Security & Deployment
- Storyboard Canvas
- Gallery
- ComfyUI Integration
- Cinema Prompt Engineering (CPE)
- AI LLM Provider Setup
- Technical Reference
- Architecture
- Completed Maintenance Notes
- Development
- License
-
Cinematographic Accuracy — Every configuration is validated against real-world constraints. You cannot pair a Panavision lens with a non-Panavision camera. You cannot use LED lighting in a 1960s film. You cannot handheld an IMAX camera. The rules engine enforces what is physically possible.
-
67 Live-Action Film Presets — From Metropolis (1927) to Parasite (2019), each preset loads the actual camera, lens, film stock, lighting, and aspect ratio used in that production.
-
43 Animation Presets — Studio Ghibli, Akira, Spider-Verse, Pixar, Arcane, and more. Each with accurate style domain, rendering pipeline, motion characteristics, and visual grammar.
-
Storyboard Canvas — Free-floating infinite canvas with draggable, resizable panels. Per-panel workflows, image history with navigation, star ratings, markdown notes, and multi-select alignment tools.
-
Gallery Tab — Full-featured media browser for all project files. Folder tree navigation, grid/masonry/list/timeline views, batch rename with regex and templates, drag-and-drop file moves, trash with restore, ratings, color tags, PNG metadata search, duplicate detection, and direct integration with Storyboard (send reference images, restore workflow parameters from metadata).
-
Recent Projects — Quick access to your last 10 projects from the main menu. Hover to see project path and last-opened time. Individual entries can be removed.
-
Video Generation Support — Full pipeline support for AI video workflows (Wan 2.2, CogVideoX, HunyuanVideo, etc.). Videos are detected from ComfyUI outputs (
images,gifs,videoskeys), saved with correct extensions, displayed inline with<video>playback, and persisted across project save/reload. -
Multi-Node ComfyUI Rendering — Connect multiple ComfyUI backends and render in parallel. Real-time progress via WebSocket with per-node stage tracking. Node metrics, health monitoring, and one-click restart.
-
Generation Progress Sidebar — Dedicated sidebar panel showing detailed progress for all active generations. Per-node workflow stage display (e.g., "Loading Checkpoint", "KSampler", "VAE Decode"), multi-phase progress for multi-KSampler workflows, and step counters. Replaces intrusive panel overlays with a minimal bottom bar indicator.
-
AI-Enhanced Prompts — Connect the configured LLM provider to refine prompts for a separate canonical image or video target model. The current video profile catalog includes versioned LTX, MiniMax H3, Seedance, Wan 3.0, and Kling 3.0/Omni guidance.
-
Model-Specific Output — Prompts are formatted for the selected target generator; image and video targets use different guides, tasks, and dialects.
-
Print Storyboards — Export your storyboard to print with configurable layouts (1–4 panels per row), page sizes, orientation, and optional panel notes.
- Python 3.11+ (with
piporuv) - Node.js 22.13+ or 24+ (with
npm) — Node 22.13 is the supported floor - ComfyUI — At least one running instance for image generation
- Git (for cloning)
# Clone the repository
git clone https://github.com/NickPittas/DirectorsConsole.git
cd DirectorsConsole
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
cd CinemaPromptEngineering/frontend
npm ci
cd ../..The frontend uses the maintained Vite 7 / ESLint 10 toolchain documented in
docs/tooling-upgrade-plan.md. After the security
refresh, both full and production-only npm audit --json checks report zero
findings; use npm ci so the checked-in lockfile is honored.
requirements-dev.txt installs the complete Python runtime plus test tools. The
single documented offline check is python scripts/check.py; see
docs/contributing.md for the commands and current
validation status.
For a clean workstation, python start.py --setup remains available to create
the launcher's per-service environments. The primary runtime launcher is:
python start.pyCPE Backend:
cd CinemaPromptEngineering
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
pip install -r requirements.txtFrontend:
cd CinemaPromptEngineering/frontend
npm ciOrchestrator:
cd Orchestrator
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
pip install -r requirements.txt# Start all services (backend, frontend, orchestrator)
python start.pyThis launches:
| Service | URL | Description |
|---|---|---|
| CPE Backend | http://localhost:9800 |
Cinema Prompt Engineering API |
| Storyboard Frontend | http://localhost:5173 |
React UI (opens in browser) |
| Orchestrator | http://localhost:9820 |
Render farm manager |
The launcher checks the configured service ports before startup and safely cleans up stale listeners when possible, including on Linux.
python start.py --no-orchestrator # Skip Orchestrator
python start.py --no-frontend # Skip Frontend (API only)
python start.py --no-browser # Don't auto-open browser
python start.py --setup # Verify environment onlyDeployment boundary: Director's Console is not formally security-audited. It is intended for trusted, access-controlled networks, not as a hardened public service.
- There is no application-wide authentication or authorization. Reachable peers can invoke exposed functions and submit malicious input.
- Do not expose the CPE, Orchestrator, frontend, or ComfyUI endpoints to public or untrusted networks. Host and network security—including access controls, firewalls, VPNs, and segmentation—is the responsibility of the host/network administrator.
- Network isolation reduces exposure but does not guarantee protection against malicious files, malicious workflows, or other vulnerabilities. Treat project files, workflows, and connected nodes accordingly.
- Provider credentials are not guaranteed to exist only in encrypted backend storage: browser provider configuration may be cached in the browser profile/local data. Protect that local data as well as the backend credential store.
- OAuth app configuration is external: set both
ANTIGRAVITY_CLIENT_IDandANTIGRAVITY_CLIENT_SECRETbefore a new Antigravity login or token refresh. Re-login alone will not fix missing app configuration; an administrator must supply the appropriately authorized OAuth client configuration first.
This project is intended for private, access-controlled networks and is not a formally audited or hardened public service. This documentation update makes no network policy change.
The Storyboard Canvas is a free-floating infinite workspace for planning and executing AI-generated visual productions. Panels can be freely positioned, resized, and organized on the canvas with zoom and pan controls.
Canvas Controls:
- Zoom: Mouse wheel (zooms from pointer position)
- Pan: Click and drag on empty canvas area
- Multi-Select: Ctrl+Click individual panels, or marquee-select by dragging
- Alignment: Snap guides appear when holding Shift; alignment toolbar for selected panels
- Keyboard Shortcuts: Ctrl+P (Print), Ctrl+S (Save), and more
Each panel is an independent production unit with its own:
- Workflow — Select any imported ComfyUI workflow per panel
- Parameters — Each panel stores its own parameter values (prompt, steps, CFG, sampler, etc.)
- Image & Video History — Navigate through all generated images and videos with forward/back arrows. Videos play inline with native
<video>controls inside a bounded, aspect-preserving viewport; letterboxing is used instead of cropping. - Storyboard AI Enhance — Use the gear button beside a prompt's Enhance with AI button to choose the target model, video dialect/task, and confirmed reference mapping before enhancing.
- Star Rating — Rate images 1–5 stars for quick review
- Markdown Notes — Attach production notes with edit/view toggle
- Panel Name — Custom names that map to folder structure (e.g., "Hero_Shot" creates
{project}/Hero_Shot/) - Node Selection — Choose which ComfyUI backend renders this panel
Prompt enhancement is available from each positive prompt field. Select a panel and workflow, then click the gear immediately beside Enhance with AI to open the styled settings popup; settings are not inserted as a bulk inline parameter panel. Choose:
- Target — the canonical image or video generator being prompted. This is separate from the LLM provider/model used to enhance the text. A known catalog image target may explicitly override a video workflow's default classification; unknown targets are blocked rather than guessed.
- Dialect — shown for registered video profiles, such as local MiniMax H3 versus the hosted MiniMax API dialect.
- Task —
T2V,I2V, orref2v(R2V) only when the selected profile supports it. Auto chooses from the confirmed media mapping. - Media mapping — include detected reachable workflow media, assign first/last-frame or reference roles, preserve per-kind ordinals, add optional descriptions, and confirm the mapping. Kling named-reference fields appear only for the applicable Kling target.
- Duration — shown when the selected task/dialect needs the workflow's effective duration, including local H3 last-frame alignment.
Click Done or press Escape, then click Enhance with AI on the prompt. Preferences persist with the panel/project draft. Media values stay local: only caller-confirmed metadata such as kind, role, ordinal, label, and description is sent to the enhancer; it does not perform vision inspection or upload media. If a target catalog/profile is unavailable, the UI blocks enhancement with an actionable retry message. A response is discarded when the prompt, panel, workflow, target, or mapping changed while it was running, while the existing guarded OAuth-token retention remains independent of stale content. Paid requests are not automatically retried.
For the full task matrix, exact local-H3 sections, version caveats, and source links, see Prompt enhancement profiles.
Image Viewer — Full-resolution image viewing with zoom and metadata display.
Image Compare — Side-by-side comparison of generated images to evaluate iterations.
Projects are saved with all panel positions, parameters, workflow assignments, ratings, notes, and image references. All generated images are organized in per-panel folders within your project directory. Persistent session drafts also recover current Cinema/Storyboard work after interruption; this is best-effort draft recovery, not a guarantee of the final keystroke, and interrupted generations are not automatically resubmitted.
Project Settings let you configure:
- Project storage path (local or network/NAS)
- Filename templates with tokens:
{panel},{workflow},{seed},{date}, etc. - ComfyUI node addresses
- Auto-save preferences
Print your storyboard with fully configurable layouts:
- Grid columns: 1, 2, 3, or 4 panels per row
- Page size: A4 or Letter
- Orientation: Portrait or Landscape
- Panel selection: All panels or only selected
- Notes: Optional panel notes display
- Live PDF preview before printing
The Gallery is a top-level tab alongside Cinema and Storyboard, providing a full file browser and media management interface for your project's generated images and videos.
- Folder Tree — Hierarchical tree view of your project directory with expand/collapse, file counts, and drag-drop support
- Multiple View Modes — Grid (virtualized, bounded thumbnails), Masonry (Pinterest-style borderless layout with natural aspect ratios), List (detailed table with metadata columns), and Timeline (chronological grouped by date)
- Responsive Grid — The grid observes available width and measures actual row heights, so an empty-to-loaded refresh or thumbnail-size resize does not crop or misplace rows.
- Lightbox — Full-resolution image/video viewer with keyboard navigation, zoom, and metadata overlay
- Compare View — Side-by-side comparison of selected images
- Hover Preview — Large preview tooltip on thumbnail hover
- Video Poster & Hover Scrub — Video thumbnails show a captured poster first, then scrub inside a bounded
containviewport on hover; existing media does not need regeneration or prebuilt thumbnails. - Video Aspect Handling — Gallery and Storyboard preserve the source aspect ratio and letterbox inside the available viewport. Grid cells remain bounded rather than resizing every container to natural video dimensions.
- Breadcrumb Navigation — Click-through path breadcrumbs for quick folder traversal
- Thumbnail Sizes — Adjustable thumbnail size slider in the toolbar
- Batch Rename — Rename multiple files with templates (
{name},{counter},{date},{parent}) and optional regex find/replace. Live preview before applying. - Auto-Rename — One-click sequential renaming within a folder (e.g.,
Shot_001.png,Shot_002.png, ...) - Drag-and-Drop Move — Drag files between folders in the tree view, with move confirmation dialog
- Move to New Folder — Create a new folder and move selected files in one step
- Trash System — Soft-delete files to a
.gallery/.trash/folder with full restore capability. Empty trash permanently deletes.
- Star Ratings — 1-5 star ratings per file, filterable from the filter bar
- Color Tags — Create custom named tags with colors, assign to files, filter by tag
- PNG Metadata Search — Full-text search across ComfyUI PNG metadata (prompts, models, samplers, seeds, etc.)
- Duplicate Detection — Find visually duplicate files by content hash across the project
- Folder Statistics — View file counts, total size, media type breakdown per folder
- Filter Bar — Filter by rating, tags, file type (image/video), and date range
- Saved Views — Save and restore view configurations (sort, filters, layout, folder state)
The Gallery uses the full page width: folder tree, main content, and the optional detail panel share one layout. Selection actions appear in a normal footer below all panes, not as a floating or overlay bar. Use the toolbar or folder-tree refresh button to rescan the tree and current folder without leaving the Gallery.
The Gallery and Storyboard tabs communicate via cross-tab events:
- Send as Reference Image — Right-click any gallery image to send it to the currently selected Storyboard panel as a reference image input
- Restore Workflow & Parameters — Right-click an image to extract its ComfyUI generation metadata and restore the workflow, prompt, and all parameters back to the Storyboard
- Batch Rename Sync — When files are renamed in the Gallery, the Storyboard automatically updates any panel image references that point to the renamed files
- Shared Project Context — Both tabs operate on the same project path, so changes in one are immediately visible in the other
Gallery metadata (ratings, tags, view states) is stored in a JSON flat-file at {projectPath}/.gallery/gallery.json. This design was chosen because projects live on NAS storage (CIFS/SMB mounts) where SQLite's file locking is incompatible. The JSON store uses atomic writes (write-to-temp + rename) and thread-safe locking.
Director's Console communicates directly with ComfyUI nodes for image and video generation. The frontend builds workflow JSON and sends it to ComfyUI's REST API, with real-time progress updates via WebSocket. Video outputs are automatically detected from ComfyUI's images, gifs, and videos output keys and saved with the correct file extension.
Manage your ComfyUI render backends from the Node Manager:
- View node status (online/busy/offline)
- System metrics (VRAM, RAM, queue depth)
- One-click restart (interrupt + free memory)
- Add/remove nodes
- Checkbox selection for multi-node rendering
- Import any ComfyUI workflow JSON
- Workflow Parser automatically extracts editable parameters (prompts, dimensions, steps, CFG, samplers, models, etc.)
- Per-panel assignment — each panel can use a different workflow
- Parameter isolation — switching workflows resets technical parameters to defaults while preserving prompts and image inputs
- Categorization — organize workflows into custom categories
- Schema-aware controls — parameter widgets and managed-node choices are derived from the imported workflow schema rather than guessed from arbitrary inputs.
Use the tags icon in the workflow toolbar to open Manage Workflow Categories. Select a workflow, choose Video Generation, then choose and save the actual child route: Text to Video, Image to Video, or First/Last Frame to Video. Saving updates the Storyboard tab/subcategory routing and persists the workflow's categories. Existing custom, legacy, and intentional multi-category tags are preserved. An incorrectly imported video workflow is not mass-reclassified automatically; assign the correct child route and save it manually.
Model and LoRA parameters now feature enhanced dropdown selection:
- Folder Structure — Models and LoRAs are organized by their folder hierarchy using
<optgroup>elements, making it easy to navigate large model libraries (e.g.,Flux/Flux 2/Klein/flux-2-klein-base-9b-fp8.safetensors) - Auto-Selection — When a workflow is loaded, the dropdown automatically pre-selects the model or LoRA that's currently configured in the workflow
- Cross-Platform Path Compatibility — Path separators are automatically normalized, ensuring workflows created on Windows work correctly when submitted to Linux or macOS ComfyUI nodes, and vice versa
Supported file types for folder grouping:
- Models:
.safetensors,.pt,.pth,.bin,.ckpt,.gguf - LoRAs:
.safetensors,.pt,.pth,.bin
When multiple ComfyUI backends are connected:
- Assign specific nodes to specific panels
- Queue jobs across multiple backends in parallel
- Real-time progress sidebar with per-node stage tracking (shows current workflow node: "CheckpointLoaderSimple", "KSampler", "VAEDecode", etc.)
- Multi-phase progress for video workflows with multiple KSamplers (e.g., "Phase 1/2")
- Step counters showing workflow execution progress (e.g., "Step 5/14")
- Global cancel button to interrupt all busy nodes
- Job groups for coordinated parallel execution
- Minimal non-intrusive panel indicator (3px bottom bar + percentage badge)
CPE transforms structured cinematography configurations into optimized AI prompts. Instead of writing free-text prompts, you select from validated menus of real cameras, lenses, lighting setups, and film styles. The system then:
- Validates your configuration against 56+ rules (34 live-action, 22 animation)
- Generates a technically accurate prompt with all selected parameters
- Formats the prompt for your specific target AI model
- Optionally enhances the prompt using an LLM provider for richer description
The rules engine is the core of CPE. It enforces that only what is physically and historically possible can be configured. This is not a suggestion system — it is a hard constraint engine.
| Level | Effect | Example |
|---|---|---|
| HARD | Blocks the configuration | "Film stock cannot be selected with digital cameras" |
| WARNING | Allows but flags as atypical | "Cheerful mood + low-key lighting is unusual" |
| INFO | Informational note | "Remember to set 2x de-squeeze in post for anamorphic" |
Camera & Film Stock Compatibility:
- Film cameras require a film stock selection; digital cameras cannot have one
- 65mm/70mm film stocks require large format cameras
- IMAX film stocks require IMAX cameras
- Ultra Panavision 70 requires 2.76:1 aspect ratio (and vice versa)
Lens & Camera Ecosystem:
- Panavision cameras only accept Panavision lenses (closed ecosystem)
- Panavision lenses require Panavision cameras (Alexa 65 exempt for Primo 70)
- Alexa 65 only accepts 65mm-format lenses (ARRI Prime 65, DNA, Primo 70, Hasselblad V, Vintage Spherical)
- Large Format cameras (Alexa LF/Mini LF) cannot use S35-only lenses (vignetting)
Physical Movement Constraints:
- Heavy cameras (>4kg) cannot be handheld, mounted on gimbals, or flown on drones
- Medium cameras cause operator fatigue warnings for handheld
- Jib cranes only allow Crane Up/Down, Arc, and Static movements
- Drones are limited to Track In/Out, Crane Up/Down, Arc, and Static
- Dolly zoom requires dolly or slider equipment
Era-Appropriate Technology:
- HMI lighting not available before 1972
- Kino Flo not available before 1987
- LED film lighting not available before 2002
- Film presets automatically disallow anachronistic light sources
Natural Light Physics:
- Sunlight not available at night
- Moonlight impossible at midday
- Direct sunlight not available during blue hour
- Low-key lighting impossible at midday outdoors
Composition & Optics:
- Wide lenses (<35mm) on close-ups cause facial distortion (warning)
- Long lenses (>85mm) on wide shots create heavy compression (warning)
- Vintage lenses may not resolve well on 8K+ sensors (warning)
- Certain compositions conflict with specific shot sizes (e.g., negative space in ECU)
Animation-Specific Rules:
- Manga must use monochrome/ink color, locked camera, graphic lighting, no motion, and 2D medium
- Illustration must be static with locked camera
- 2D animation cannot use Free 3D camera
- 3D animation requires volumetric lighting (not flat/minimal)
- Anime cannot use photoreal + naturalistic simulated combo
The UI doesn't just validate after the fact — it proactively disables invalid options in real-time. When you select a Panavision camera, only Panavision lenses are selectable. When you choose night time, the sun is greyed out. The get_available_options() endpoint tests every possible option against your current configuration and returns which ones would cause violations.
67 meticulously researched film presets spanning nearly a century of cinema. Each preset encodes the actual production equipment used on that film: camera body, film stock, lenses, focal lengths, aspect ratio, lighting style, color tone, mood, compositions, shot sizes, and movement.
| Preset | Year | Camera | Film Stock |
|---|---|---|---|
| Metropolis | 1927 | UFA Custom | Eastman Double-X |
| Un Chien Andalou | 1929 | Pathe Studio | Eastman Plus-X |
| Preset | Year | Camera | Film Stock |
|---|---|---|---|
| The Maltese Falcon | 1941 | Mitchell BNC | Eastman Plus-X |
| Citizen Kane | 1941 | Mitchell BNC | Eastman Plus-X |
| Casablanca | 1942 | Mitchell BNC | Eastman Plus-X |
| Double Indemnity | 1944 | Mitchell BNC | Eastman Plus-X |
| Bicycle Thieves | 1948 | Arriflex 35 | Eastman Plus-X |
| Sunset Boulevard | 1950 | Mitchell BNC | Eastman Plus-X |
| Preset | Year | Camera | Film Stock |
|---|---|---|---|
| Rashomon | 1950 | Mitchell BNC | Eastman Plus-X |
| Tokyo Story | 1953 | Mitchell BNC | Eastman Plus-X |
| Seven Samurai | 1954 | Mitchell BNC | Eastman Plus-X |
| The Seventh Seal | 1957 | Arriflex 35 | Eastman Plus-X |
| Vertigo | 1958 | Mitchell BNC | Eastman 5247 |
| Preset | Year | Camera | Film Stock |
|---|---|---|---|
| Breathless | 1960 | Eclair NPR | Eastman Plus-X |
| La Dolce Vita | 1960 | Arriflex 35 | Eastman 5247 |
| Lawrence of Arabia | 1962 | Super Panavision 70 | Kodak 65mm 250D |
| Jules et Jim | 1962 | Eclair NPR | Eastman Plus-X |
| Harakiri | 1962 | Mitchell BNC | Eastman Plus-X |
| Persona | 1966 | Arriflex 35BL | Eastman 5254 |
| The Battle of Algiers | 1966 | Arriflex 35 | Eastman Plus-X |
| 2001: A Space Odyssey | 1968 | Super Panavision 70 | Kodak 65mm 200T |
| Preset | Year | Camera | Film Stock |
|---|---|---|---|
| A Clockwork Orange | 1971 | Arricam ST | Eastman 5254 |
| The French Connection | 1971 | Arriflex 35BL | Eastman 5254 |
| The Godfather | 1972 | Arriflex 35BL | Eastman 5254 |
| Solaris | 1972 | Arriflex 35 | Eastman 5250 |
| Chinatown | 1974 | Panavision Panaflex | Eastman 5247 |
| Barry Lyndon | 1975 | Arricam ST | Eastman 5247 |
| One Flew Over the Cuckoo's Nest | 1975 | Arriflex 35BL | Eastman 5247 |
| The Mirror | 1975 | Arriflex 35 | Eastman 5250 |
| Taxi Driver | 1976 | Arriflex 35BL | Eastman 5247 |
| Star Wars | 1977 | Panavision Panaflex | Eastman 5247 |
| Alien | 1979 | Panavision Panaflex | Eastman 5247 |
| Apocalypse Now | 1979 | Arriflex 35BL | Eastman 5247 |
| Stalker | 1979 | Arriflex 35 | Eastman 5250 |
| Preset | Year | Camera | Film Stock |
|---|---|---|---|
| Blade Runner | 1982 | Panavision Panaflex | Eastman 5293 |
| Brazil | 1985 | Arriflex 35BL | Eastman 5293 |
| Come and See | 1985 | Arriflex 35 | Eastman 5250 |
| Blue Velvet | 1986 | Arriflex 35BL | Eastman 5293 |
| Preset | Year | Camera | Film Stock |
|---|---|---|---|
| Schindler's List | 1993 | Arricam ST | Kodak Double-X 5222 |
| Pulp Fiction | 1994 | Panavision Platinum | Kodak Vision 500T 5279 |
| The Shawshank Redemption | 1994 | Arricam ST | Kodak Vision 500T 5279 |
| La Haine | 1995 | Arriflex 35BL | Kodak Double-X 5222 |
| Heat | 1995 | Panavision Platinum | Kodak Vision 500T 5279 |
| The Thin Red Line | 1998 | Arricam ST | Kodak Vision 500T 5279 |
| The Matrix | 1999 | Panavision Millennium | Kodak Vision 500T 5279 |
| Eyes Wide Shut | 1999 | Arricam ST | Kodak Vision 500T 5279 |
| Preset | Year | Camera | Film Stock / Format |
|---|---|---|---|
| In the Mood for Love | 2000 | Arricam ST | Fuji Eterna 500T |
| Requiem for a Dream | 2000 | Arriflex 435 | Kodak Vision 500T 5279 |
| Mulholland Drive | 2001 | Panavision Millennium | Kodak Vision 500T 5279 |
| Amélie | 2001 | Arricam ST | Fuji Eterna 500T |
| Oldboy | 2003 | Arricam ST | Kodak Vision2 500T 5218 |
| Memories of Murder | 2003 | Arricam ST | Kodak Vision2 500T 5218 |
| Children of Men | 2006 | Arricam ST | Kodak Vision3 500T 5219 |
| No Country for Old Men | 2007 | Arricam ST | Kodak Vision3 500T 5219 |
| There Will Be Blood | 2007 | Panavision Millennium XL2 | Kodak Vision3 500T 5219 |
| The Dark Knight | 2008 | IMAX MSM 9802 / Panavision | IMAX 500T / Kodak Vision3 |
| Enter the Void | 2009 | Arriflex 435 | Kodak Vision3 500T 5219 |
| Preset | Year | Camera | Format |
|---|---|---|---|
| The Tree of Life | 2011 | Arricam ST | Kodak Vision3 500T 5219 |
| Drive | 2011 | Alexa | Digital |
| Her | 2013 | Alexa XT | Digital |
| Under the Skin | 2013 | Alexa | Digital |
| The Grand Budapest Hotel | 2014 | Arricam ST | Kodak Vision3 500T 5219 |
| Mad Max: Fury Road | 2015 | Alexa XT | Digital |
| Moonlight | 2016 | Alexa Mini | Digital |
| Roma | 2018 | Alexa 65 | Digital |
| The Lighthouse | 2019 | Arricam ST | Kodak Double-X 5222 |
| Parasite | 2019 | Alexa 65 | Digital |
43 animation presets across four style domains, each with curated rendering pipelines, motion characteristics, and visual grammars.
Studio Ghibli, Akira, Ghost in the Shell, Evangelion, Makoto Shinkai, Kyoto Animation, MAPPA, Wit Studio, Ufotable, Studio Trigger, Gainax, Satoshi Kon, Cowboy Bebop, Samurai Champloo, Mob Psycho 100, One Punch Man, Cyberpunk Edgerunners, Violet Evergarden, Attack on Titan, Death Note, Fullmetal Alchemist Brotherhood, Steins;Gate
Shonen, Dark Seinen, Shojo, Josei, Horror Manga, Slice of Life Manga
Pixar, DreamWorks, Disney 3D, Arcane, Spider-Verse, Unreal Cinematic, Blender Stylized, Stop Motion
Concept Art, Editorial Illustration, Book Illustration, Western Comics, Graphic Novel, Watercolor, Digital Painting
Each preset configures: medium (2D / 3D / Hybrid / Stop Motion), style domain, line treatment (clean / variable / inked / sketchy), color application (flat / cel / soft / painterly), lighting model (symbolic / graphic / naturalistic), surface detail, motion style (limited / full / exaggerated / fluid), and virtual camera behavior.
Beyond rule-based generation, CPE can send a structured prompt to an enhancing LLM. The target model is the image/video generator whose prompt is being written; the LLM provider and model are the service that rewrites it. Configure those separately in Settings. Do not treat the enhancing provider as the generation target.
- Choose the canonical target from the General, Image, or Video target dropdown. The scene prompt is a full-width row above these target controls.
- For a registered video target, choose its available dialect (for example,
local_h3orminimax_api). Dialects are model-specific; prose targets are not all one JSON template. - Configure an LLM provider/model in Settings, enter the scene idea and cinematography selections, and click Enhance with AI.
- Review/copy the AI-Enhanced Prompt, or use Send to Storyboard. Image targets use their family guide; profiled video targets use the selected video profile and default to a text-to-video enhancement context on this page because it has no workflow media mapping.
The canonical image catalog preserves all older targets and adds these 14 prompt-guide targets:
| Family | Canonical targets | Prompt distinction |
|---|---|---|
| Krea 2 | krea_2_large, krea_2_turbo |
Large supports richer supplied detail; Turbo stays concise for iteration. Vague ideas remain exploratory rather than acquiring invented props or camera specs. |
| FLUX.2 | flux_2_max, flux_2_pro, flux_2_flex, flux_2_klein, flux_2_dev |
Natural subject/action/style/context prose; no SD-style weighting or negative block. Klein gets a separate rich-narrative guide because it does not upsample prompts. |
| GPT Image 2.5 | gpt_image_2.5_sunburst, gpt_image_2.5_flare |
Sunburst prioritizes precise composition and editing constraints; Flare favors direct, efficient iteration. |
| Nano Banana | nano_banana_2, nano_banana_pro, nano_banana_2_lite |
Nano Banana 2 and Pro use complete scene/edit instructions; Lite is not optimized for multiple references or multi-turn sequential editing. |
| Seedream 5.0 | seedream_5.0_pro, seedream_5.0_lite |
Pro can express supplied layouts, typography, and spatial edits; Lite remains a focused natural-language task guide without assumed Pro controls. |
These are prompt-text guides, not image-generation integrations. Hosted/API model pages, open-weight releases, local checkpoints, and ComfyUI nodes are separate availability questions: Krea 2 includes open-weight releases, but that does not make every Krea service or feature local; likewise, a catalog target never promises local weights, a hosted endpoint, credentials, account/region access, or a ComfyUI workflow. FLUX 3 Image is intentionally excluded pending verified API/prompt availability.
Both the CPE page and Storyboard AI Enhance use the same target catalog and guides. Image enhancement has no separate image task, mode, or reference-mapping selector: the user's wording must identify a new generation or the exact edit. For edits, state what changes and what caller-provided identity, composition, lighting, or text must remain; the enhancer receives metadata only and does not inspect image bytes or invent reference contents. The Storyboard gear remains the place for video dialect/task and confirmed media mapping controls.
Official image sources: Krea 2, FLUX.2 prompting, GPT Image prompting, GPT Image 2.5 Sunburst, GPT Image 2.5 Flare, Gemini image generation, and Seedream 5.0 Pro/Lite.
The current registered video profiles remain LTX 2.3, LTX 2.5, MiniMax H3, MiniMax H3 Max, Seedance 2.0, Seedance 2.5, Wan 3.0, Kling 3.0, and Kling 3.0 Omni. The Prompt enhancement profiles guide links each versioned guide and its official sources.
Director's Console supports 13+ LLM providers for AI-enhanced prompt generation. Credentials saved through the backend use the existing local encrypted credential store (%APPDATA%/CinemaPromptEngineering/credentials.db) using Fernet encryption, but browser provider configuration may also be cached in local storage or the browser profile. Protect both the backend data and local browser data; this project does not promise that every key exists only in encrypted backend storage. Antigravity's OAuth app configuration is supplied externally through ANTIGRAVITY_CLIENT_ID and ANTIGRAVITY_CLIENT_SECRET; it is not embedded in the current source. This maintenance cleanup does not rewrite stored credentials or claim to purge repository history.
These providers require an API key, which you enter directly in the Settings panel:
| Provider | How to Get a Key | Models |
|---|---|---|
| OpenAI | platform.openai.com/api-keys | GPT-4o, GPT-4 Turbo, DALL-E 3 |
| Anthropic | console.anthropic.com | Claude 3.5 Sonnet, Claude 3 Opus |
| Google AI (Gemini) | Google AI Studio API keys | Models returned by the Google AI API |
| OpenRouter | openrouter.ai/keys | Multi-model aggregator (100+ models) |
| Replicate | replicate.com/account/api-tokens | FLUX, SDXL, open-source models |
| Stability AI | platform.stability.ai | Stable Diffusion, SDXL |
| fal.ai | fal.ai/dashboard | Fast FLUX/SDXL/video inference |
| Together AI | api.together.xyz | Open-source fast inference |
| GitHub Models | GitHub Personal Access Token (PAT) | GPT-4o, Claude, Llama via GitHub |
To add an API key provider:
- Open Settings (gear icon in the menu)
- Find the provider in the list
- Enter your API key
- Click Test Connection to verify the connection
- Click Save Changes
This is the authoritative Google setup path. No new provider is needed: the provider ID is google, the Settings label is Google AI (Gemini), and it uses the native Google AI API endpoint (generativelanguage.googleapis.com/v1beta).
- Open Settings.
- Select Google AI (Gemini).
- Create or copy a key from Google AI Studio API keys, then paste it into the API key field.
- Click Test Connection.
- Fetch the available models and select one.
- Click Save Changes.
This Google AI Studio API key is not an OAuth client secret and does not log you into Antigravity. Available models, quotas, billing, and service eligibility depend on the key/account and Google service; successful connection or model listing does not guarantee access to every Gemini feature. Never put a real key in this README, examples, issues, logs, or source control. The generic google OAuth configuration is a separate path and is not the Gemini API-key option.
These providers use OAuth authentication flows. They are separate from the Google API-key flow above. The current Antigravity client configuration is resolved from request/stored provider settings or external environment variables; missing configuration fails explicitly before an outbound OAuth request.
| Provider | UI label | Provider ID | Flow Type | Requires Client Secret |
|---|---|---|---|---|
| Antigravity | Antigravity (Gemini/Claude) | antigravity |
Authorization Code + PKCE | Yes |
| OpenAI Codex | OpenAI Codex (ChatGPT Plus/Pro) | openai_codex |
Authorization Code + PKCE | No |
Use an appropriately authorized Antigravity application configuration. Do not assume an existing client belongs to you or to Google, and do not use an arbitrary Google Cloud client expecting it to grant Cloud Code/Antigravity access; the account and client must be authorized for that service.
The CPE backend reads these values from its private environment file:
CinemaPromptEngineering/.env
CinemaPromptEngineering/.env is the private, gitignored backend file (on Unix, keep it mode 0600); .env.example is the tracked placeholder template. Only if .env does not already exist, copy CinemaPromptEngineering/.env.example to it. Do not overwrite an existing configured .env. Fill in the placeholders locally:
ANTIGRAVITY_CLIENT_ID=your-authorized-client-id
ANTIGRAVITY_CLIENT_SECRET=your-authorized-client-secret
Keep .env private, restart the CPE backend after changing it, and never put these values in the frontend .env, VITE_* variables, Git, logs, or issue reports. A missing .env is harmless at startup; an Antigravity request without complete app configuration fails explicitly before outbound HTTP. Existing OAuth tokens are not deleted by this configuration cleanup; re-login alone cannot fix missing app configuration. The loader is implemented and its fresh-process environment/path/missing-file/import-order checks pass; live provider/account verification remains pending.
The app uses http://localhost:36742/oauth-callback for Antigravity's local callback. Where the client type requires registered redirect URIs, the registration must match it. Desktop loopback-client rules differ from web-client rules, so do not create a web client merely to force these instructions to fit.
To set up an OAuth provider:
- Open Settings → find the provider.
- Click Connect — this opens a browser window for OAuth authorization.
- After authorization, the access token is handled by the existing local credential workflow.
- Tokens may refresh when the provider supports refresh; a live provider/account check is still required.
No API key needed — these connect to LLMs running on your machine:
| Provider | Default URL | Notes |
|---|---|---|
| Ollama | http://localhost:11434 |
Auto-detected when running |
| LM Studio | http://localhost:1234 |
OpenAI-compatible API |
Just start the local LLM server and Director's Console will detect it automatically.
Note for Ollama users: If you encounter issues, ensure you're using the latest Ollama version. Model names with tags (e.g.,
llama3:latest) are supported. Embedding models are automatically filtered from the chat model list.
49 camera bodies across 14 manufacturers, classified by weight for movement constraint enforcement:
Digital Cameras
| Manufacturer | Bodies |
|---|---|
| ARRI | Alexa 35, Alexa Mini, Alexa Mini LF, Alexa LF, Alexa 65, Alexa, Alexa XT |
| RED | V-Raptor, V-Raptor X, V-Raptor XL, Komodo-X, Monstro 8K, RED One |
| Sony | Venice 2, FX9, FX6 |
| Canon | C700 FF, C500 Mark II, C300 Mark III |
| Blackmagic | Ursa Mini Pro 12K, Pocket 6K |
| Panasonic | VariCam LT, S1H |
| Nikon | Z9 |
| DJI | Inspire 3, Mavic 3 Cine |
Film Cameras
| Manufacturer | Bodies |
|---|---|
| ARRI Film | Arricam ST, Arricam LT, ARRI 535B, ARRI 35BL, ARRI 35 III, Arriflex 35, Arriflex 35BL, Arriflex 435 |
| Panavision | Millennium XL2, Millennium, Platinum, Gold, Panastar, Panaflex, Super Panavision 70, Ultra Panavision 70, XL |
| Mitchell | BNC, BNCR, BFC 65 |
| Eclair | NPR |
| IMAX | MSM 9802, MKIV, GT |
| Vintage | UFA Custom, Pathe Studio |
Camera types: Digital, Film
Sensor sizes: Super 35, Full Frame, Large Format, 65mm, Micro Four Thirds, Film 35mm, Film 65mm, Film 70mm, IMAX 15/70, IMAX GT
Weight classes: Ultra Light (<2kg), Light (2–3kg), Medium (3–4kg), Heavy (>4kg)
47 lens families from 19 manufacturers:
Full Lens List
| Manufacturer | Families |
|---|---|
| ARRI | Signature Prime, Master Prime, Ultra Prime, Prime 65, Prime DNA |
| Zeiss | Supreme Prime, Master Prime, CP.3, Super Speed, Standard Speed, Ultra Prime, Planar, Planar f/0.7 |
| Cooke | S7/i, S4/i, Anamorphic/i, Panchro/i Classic, Speed Panchro |
| Panavision | Primo, Primo 70, Anamorphic, C Series, E Series, Sphero, Ultra Speed |
| Leica | Summilux-C, Summicron-C, Thalia |
| Canon | Sumire Prime, CN-E, K35 |
| Sony | CineAlta |
| Sigma | Cine, High Speed |
| Angénieux | Optimo, EZ, HR |
| Vintage | Bausch & Lomb Super Baltar, Bausch & Lomb Baltar, Todd-AO, Hawk V-Lite, Hawk V-Plus, Vintage Anamorphic, Vintage Spherical |
| Hasselblad | HC, V |
| IMAX | IMAX Optics |
Mount types: PL, LPL, XPL, Panavision, Mitchell BNC, IMAX
Focal length range: 8mm – 1200mm
Aspect ratios: 1.33:1, 1.37:1, 1.43:1, 1.66:1, 1.78:1, 1.85:1, 1.90:1, 2.20:1, 2.35:1, 2.39:1, 2.76:1
31 film stocks spanning the entire history of motion picture photography:
Full Film Stock List
| Category | Stocks |
|---|---|
| Kodak Vision3 (current) | 500T 5219, 250D 5207, 200T 5213, 50D 5203 |
| Kodak Vision2 | 500T 5218, 200T 5217 |
| Kodak Vision | 500T 5279, 320T 5277 |
| Black & White | Kodak Double-X 5222, Kodak Tri-X, Eastman Double-X, Eastman Plus-X |
| Historic Color | Eastman 5247, 5293, 5294, 5250, 5254, Technicolor, Kodachrome |
| Fuji | Eterna 500T, Eterna 250D, Eterna 250T |
| 65mm / 70mm | Kodak 65mm 500T, 65mm 250D, 65mm 200T |
| IMAX | 500T, 250D |
24 lighting sources with era-appropriate constraints:
| Category | Sources | Era Restriction |
|---|---|---|
| Natural | Sun, Moon, Overcast, Window, Skylight | — |
| Classic | Tungsten, Carbon Arc, Mercury Vapor, Sodium Vapor | Carbon Arc: 1895–1960s |
| Modern | HMI, Kino Flo, LED, Fluorescent | HMI: 1972+, Kino Flo: 1987+, LED: 2002+ |
| Practical | Practical Lights, Candle, Firelight, Neon, Television, Computer Screen | Neon: 1927+ |
| Mixed | Mixed, Available Light | — |
20 lighting styles: High Key, Low Key, Soft, Hard, Naturalistic, Expressionistic, Chiaroscuro, Rembrandt, Split, Rim, Silhouette, Motivated, Practical Motivated, Available Light, High Contrast, Controlled, Flat, Dramatic
16 movement equipment types with physics-based constraints:
| Equipment | Notes |
|---|---|
| Static | Tripod-mounted, no movement |
| Handheld | Limited to Ultra Light and Light cameras |
| Shoulder Rig | All weight classes with fatigue warnings |
| Steadicam | Smooth tracking, most weight classes |
| Gimbal | Electronic stabilization, light cameras only |
| Dolly / Dolly Track | Ground-level tracking shots |
| Slider | Short-range smooth movements |
| Crane | Full vertical and horizontal range |
| Jib | Limited to Crane Up/Down, Arc, Static |
| Technocrane | Precision remote-controlled crane |
| Motion Control | Repeatable programmed moves |
| Drone | Aerial, limited movements, light cameras only |
| Cable Cam | Suspended cable system |
| Car Mount | Vehicle-mounted for driving shots |
| SnorriCam | Body-mounted, actor-facing |
31 movement types: Static, Pan, Tilt, Pan & Tilt, Track In/Out, Push In, Pull Back, Truck Left/Right, Crab, Arc, Crane Up/Down, Boom Up/Down, Dolly Zoom, Push-Pull, Zoom In/Out, Crash Zoom, Roll, Whip Pan/Tilt, Follow, Lead, Orbit, Reveal, Fly Through
6 timing options: Static, Very Slow, Slow, Moderate, Fast, Whip Fast
12 shot sizes: Extreme Wide Shot (EWS), Wide Shot (WS), Medium Wide Shot (MWS), Medium Shot (MS), Medium Close-Up (MCU), Close-Up (CU), Big Close-Up (BCU), Extreme Close-Up (ECU), Over the Shoulder (OTS), POV, American Shot, Italian Shot
79 composition styles including: Rule of Thirds, Centered, Symmetrical, Golden Ratio, Golden Spiral, Dynamic Symmetry, Leading Lines, Frame Within Frame, Negative Space, Depth Layering, and many more.
81 mood options across positive, neutral, tension, dark, and intense categories.
13 color tones: Warm Saturated/Desaturated, Cool Saturated/Desaturated, Neutral Saturated/Desaturated, Monochrome, Sepia, Teal & Orange, Cross Processed, Bleach Bypass, High/Low Contrast B&W
┌─────────────────────────────────────────────────────────────┐
│ Director's Console │
├──────────────┬──────────────┬──────────────┬────────────────┤
│ Storyboard │ Gallery │ CPE Engine │ Orchestrator │
│ Canvas │ File Browser │ Python/FastAPI│ Python/FastAPI │
│ │ │ Port 9800 │ Port 9820 │
│ React + TypeScript │ │ │
│ Port 5173 │ │ │
├──────────────┴──────────────┴──────────────┴────────────────┤
│ │
│ Frontend ←──REST──→ CPE Backend ←──Manifests──→ Orchestrator │
│ │ │ │ │
│ │ │ │ │
│ └────WebSocket────────┴────Direct REST──→ ComfyUI Nodes │
│ │
│ Gallery ←──CustomEvents──→ Storyboard (cross-tab comm) │
│ Gallery ←──REST──→ Orchestrator /api/gallery/* (23 endpoints)│
│ │
├───────────────────────────────────────────────────────────────┤
│ Storage: Project files on local/NAS filesystem │
│ Gallery metadata: {project}/.gallery/gallery.json (JSON) │
│ Credentials: backend encrypted store + browser-local config │
└───────────────────────────────────────────────────────────────┘
Key Communication Patterns:
- Frontend → ComfyUI: Direct REST API calls and WebSocket for generation and progress
- Frontend → CPE Backend: REST API for prompt generation, validation, presets, settings, credentials
- Frontend → Orchestrator: REST API for job groups, backend management, project scanning, gallery operations
- Gallery ↔ Storyboard: Cross-tab CustomEvents on
windowfor reference images, workflow restore, file rename sync - CPE → Orchestrator → ComfyUI: JSON manifests for distributed rendering
- Private workstation refresh plan records the completed maintenance scope, checks, and remaining live-provider/ComfyUI verification limits.
- Prompt enhancement profiles documents the current target/task/dialect catalog, the CPE and Storyboard UI flow, reference-metadata limits, and official sources. The video capability matrix links six versioned guides: LTX 2.3, LTX 2.5, MiniMax H3, MiniMax H3 Max, Seedance 2.0, and Seedance 2.5. Wan 3.0 and Kling 3.0/Omni profiles are also covered by the registry-backed guide files. These are prompting guidance only, not a rendering backend or guarantee of local/API availability.
- To refresh the standalone node's generated rules copy, run
scripts/sync_comfy_node.pyfrom the repository root. Edit the canonicalCinemaPromptEngineering/cinema_rules/package, then run the helper before distributingComfyCinemaPrompting/.
# Backend with hot-reload
cd CinemaPromptEngineering
python -m uvicorn api.main:app --host 0.0.0.0 --port 9800 --reload
# Frontend with HMR
cd CinemaPromptEngineering/frontend
npm run dev
# Orchestrator with hot-reload
cd Orchestrator
python -m uvicorn orchestrator.api:app --host 0.0.0.0 --port 9820 --reloadSee docs/contributing.md for the supported Python 3.11+ and Node.js 22.13+ or 24+ setup. Run the complete offline regression check from the root:
python scripts/check.py# Root and Orchestrator suites in the pinned Python 3.11 environment
uv run --no-project --python 3.11 --with-requirements requirements-dev.txt python -m pytest -c pytest.ini tests/ Orchestrator/tests/ -v
# Specific test files
python -m pytest tests/test_cpe_api.py -v
python -m pytest tests/test_cinema_rules.py -v# Build frontend
cd CinemaPromptEngineering/frontend
npm run build
# Build standalone executable (Windows)
cd CinemaPromptEngineering
.\build_installer.ps1| Layer | Technology |
|---|---|
| Frontend | React 18, TypeScript 5.3+, Vite 7, ESLint 10, Zustand, TanStack Query v5 |
| Backend | Python 3.11+, FastAPI, Pydantic v2, httpx, aiohttp |
| Rendering | ComfyUI (direct WebSocket) |
| Storage | Local/NAS filesystem, JSON flat-file (Gallery metadata), SQLite (encrypted credentials) |
| Logging | Loguru |
Features:
- Gallery Tab: Full-featured media browser added as a top-level tab alongside Cinema and Storyboard. Includes folder tree navigation, grid/masonry/list/timeline views, batch rename with regex and templates, drag-and-drop file moves, trash with restore, star ratings, color tags, PNG metadata search, duplicate detection, and direct Storyboard integration (send reference images, restore workflow parameters). 23 new API endpoints on the Orchestrator (
/api/gallery/*). Gallery metadata stored as JSON flat-file ({project}/.gallery/gallery.json) for NAS/CIFS compatibility. - Recent Projects Menu: Quick access to last 10 projects from the main menu. Hover to see project path and last-opened time. Individual entries can be removed. Stored in localStorage.
- Pinterest-Style Masonry View: Gallery masonry layout redesigned with borderless thumbnails, 4px gaps, no card chrome. Selection uses outline, hover uses opacity fade.
Bug Fixes:
- Send to Storyboard Reference Image: Fixed endpoint URL (was incorrectly targeting Orchestrator port 9820 instead of CPE backend port 9800) and response field (
data.dataUrlinstead ofdata.data). - Batch Rename Storyboard Sync: Fixed
panel.imagenot updating when gallery files are renamed, causing 404 on the canvas.
Features:
- Intelligent Parameter Disable Propagation: When disabling an image or Lora input, all downstream nodes that depend on it are now automatically disabled. This prevents ComfyUI errors when bypassing inputs that have downstream dependencies (e.g., LoadImage → DWPreprocessor → ControlNetApply → KSampler chain).
Bug Fixes:
- Path Normalization: Fixed Windows backslash handling in model paths. Paths like
Qwen\model.safetensorsare now correctly converted toQwen/model.safetensorsfor Linux compatibility. - Ollama Integration: Fixed 405 error by appending
/api/chatto the endpoint. Model names withollama:prefix are now stripped before sending to the API. Embedding models are filtered from the chat model list. - Settings Persistence: Fixed model ID parsing to correctly handle colons in model names (e.g.,
ollama:llama3:latest).
Director's Console — Project Eliot
Because every frame deserves the precision of real cinematography.