CineForge is an advanced Hollywood-grade AI Movie Production Bible, Screenplay, and Shot-by-Shot Storyboarding suite. Designed for directors, screenwriters, concept artists, and AI filmmakers, CineForge converts genre prompts or brief synopses into complete production bibles, formatted multi-scene screenplays, synchronized 16-shot sequences, and structured JSON prompts for image and video motion generation engines (Runway Gen-3 Alpha, Luma Dream Machine, Sora, Kling AI, Pika, Midjourney, and Stable Diffusion).
- System Architecture & Overview
- Core App Workflows
- 1. Genre Selection & Movie Bible Generation
- 2. Movie Production Bible Management
- 3. Character Demographics & Diversity System
- 4. Multi-Scene Screenplay Engine
- 5. Screenplay Viewer & Real-Time Script Editor
- 6. Shot-by-Shot Storyboard & Motion Prompt Generator
- 7. 4x4 Master Contact Sheet Grid Matrix
- 8. Project Import, Export & Local Persistence
- AI Prompt Architecture & Backend API Routes
- Structured JSON Schemas & Prompt Specs
- Local Setup & Environment Configuration
CineForge is constructed with a full-stack Node.js + React architecture:
- Frontend: React 18, Vite, TypeScript, Tailwind CSS, Lucide React Icons, Motion (Framer Motion).
- Backend: Express server running on port
3000with native TypeScript type stripping (tsxin dev,esbuildCommonJS bundling for production). - AI Models & SDKs:
- Google Gen AI SDK (
@google/genai):gemini-2.5-flash: Generates structured Movie Production Bibles with rigid JSON schemas and multicultural character representations.gemini-3.6-flash: Generates sequential screenplay scenes (Scene #2, #3, etc.) with exactly 16 shots.gemini-3.1-flash-lite-image: Renders 16:9 cinematic concept keyframes.
- Procedural Engine & Fallback Services:
- Procedural Movie Bible Generator (
bibleGenerator.ts): Provides fallback bibles with diverse names and demographics if API keys are missing or offline. - Pollinations AI Image Endpoint: Provides visual rendering fallback for shot concept art.
- Procedural Movie Bible Generator (
- Google Gen AI SDK (
- 20+ Preset Genres: Cyberpunk, Film Noir, High Fantasy, Psychological Thriller, Romantic Comedy, Post-Apocalyptic, Supernatural Horror, Space Opera, Gothic Horror, Martial Arts Wuxia, Western, Crime Heist, Superhero Origin, Retro 80s Sci-Fi, Historical Epic, Kaiju Monster, Spy Thriller, Surrealist Art-House, Steampunk, and Documentary True Crime.
- Custom Genre & Prompt Bar: Users can enter custom genre prompts or brief 1-line synopses (e.g., "A disgraced deep-sea salvage diver discovers an ancient alien relic inside a sunken WWII submarine").
- Instant Forge: Clicking "Forge Complete Movie Bible" sends the request to
/api/generate-bible, returning a fully realized production bible in seconds.
- Overview Tab: Displays the Movie Title, Tagline, expanded Synopsis, and a Quick Re-Forge Bar.
- Characters & Costumes Tab:
- Manages 5 Main Characters with detailed backstories, role, physical traits, personality, motivation, and comprehensive demographic data.
- 5 Costumes Per Character: Each character includes 5 wardrobe variations with descriptions, materials/colors, and thematic significance.
- Character Model Sheets: Generates and exports structured JSON and clean text prompts for:
- Full Character Master Specification JSON
- Isolated Headshot Studio Portrait JSON
- 3-Angle Costume Model Sheet JSON (Full Front View, Side Profile View, Full Back View)
- Reference Image Upload: Users can upload custom reference portraits and costume artwork for any character or costume.
- Sets & Production Design Tab:
- Manages 5 Primary Sets detailing Location Heading, Set Type, Architectural Description, Lighting Cues, and Camera Framing Guidance.
- Interactive concept image uploads and prompt copying per set.
- Story Props Tab:
- Manages 5 Key Story Props with Visual Appearance, Narrative Significance, and Key Scene Usage.
- Custom prop photo uploads and prompt copying.
CineForge features an advanced character demographic management suite:
- Demographic Fields:
- Age: Exact numerical age or age range (e.g.,
28,35,42). - Sex / Gender: Gender expression (e.g.,
Female,Male,Non-Binary,Intersex,Agender,Android / Synthetic). - Height: Imperial and metric height (e.g.,
5'9" (175 cm)). - Weight: Imperial and metric weight (e.g.,
145 lbs (66 kg)). - Skin Tone: Specific melanin and skin undertone description (e.g.,
Fair / Porcelain,Warm Beige / Sand,Olive / Mediterranean,Warm Bronze / Golden,Rich Brown / Chestnut,Deep Ebony / Black,Pale / Synthetic). - Racial Descent / Ancestry: Cultural and genetic ancestry (e.g.,
East Asian,African Descent,South Asian,Hispanic / Latino,European / Caucasian,Middle Eastern,Indigenous / First Nations,Pacific Islander,Afro-Latino,Multiracial,Android / Non-Human).
- Age: Exact numerical age or age range (e.g.,
- Interactive Quick Choice Suggestions:
- Clickable suggestion chips/pills under every demographic field in the Edit Character Modal for instant auto-fill during character creation or editing.
- Random Diverse Name Generator:
- A dedicated "Random Diverse Name" button generates authentic multicultural names from global name pools (e.g., Amina Okafor, Mei-Ling Jiang, Mateo Benitez, Tariq Al-Mansoor, Priya Nair, Kenji Sato, Zadie Adebayo, Sofia Garcia, Kwame Mensah, Zeynep Yilmaz).
- Demographics Display Grid:
- Physical Demographics & Cultural Identity card rendered prominently on the character detail view with instant edit actions.
- AI Prompt Integration:
- All demographic specifications seamlessly flow into backend Gemini prompts, Still Frame Visual JSONs, and Full Character Master JSON exports.
- Scene Bar Navigation: Switch seamlessly between Scene 1, Scene 2, Scene 3, and beyond.
- AI Scene Expansion Modal: Generate new sequential scenes with custom prompt guidance (e.g. "Generate an intense rooftop pursuit scene at night during a rainstorm").
- Scene Management: Add, view, or delete generated scenes.
- 4 View Modes:
- Annotated Screenplay: Standard script format augmented with interactive shot badges, timecodes, camera framing tags, and set markers.
- Clean Standard Screenplay: Pure industry-standard screenplay text (Scene Headers, Action Blocks, Character Headings, Parentheticals, Dialogue).
- Shot & Dialogue Schedule Table: Structured breakdown showing shot headings, camera lenses, timing ranges, speaker names, and spoken lines. Includes inline dialogue editing.
- Edit Screenplay Script Text: Full raw script text editor. Editing character headings or dialogue lines in this editor automatically re-parses screenplay timing and synchronizes all downstream shot prompts.
- 16-Shot Sequence Guarantee: Every scene automatically pads or formats into exactly 16 shots, mapping perfectly to a 4x4 matrix grid.
- Automatic Speech & Timecode Calculator:
- Speech duration calculated at 2.6 words per second.
- Camera motion buffer added depending on lens type (Wide/Crane = 2.2s, Close-Up = 1.0s, Tracking = 1.8s).
- Calculates start timecode, end timecode, and duration per shot.
- Shot Prompt Tabs:
- Structured JSON Spec: Complete camera, set, costume, prop, visual action, dialogue, still frame, and video motion parameters in valid JSON.
- AI Video Motion Prompt: Tailored for AI video generators (Runway Gen-3, Luma, Sora, Kling, Pika) with lip-sync timing, 24fps motion physics, and gesture controls.
- Still Frame Visual Prompt: High-budget cinematic text prompt for image generators.
- Inline Shot & Dialogue Editor: Edit shot headings, camera lenses, speaker names, spoken dialogue lines, and physical action descriptions directly on any shot card.
- Shot Concept Art:
- Click "Generate Concept Image" to render a 16:9 cinematic preview via Gemini / Pollinations AI.
- Upload custom reference storyboard images.
- 16-Panel Composite Prompt: Compiles all 16 shots into a structured 4x4 grid matrix (Row A-D, Col 1-4) representing the entire scene on a single contact sheet.
- 4 Cinematic Style Presets:
- 35mm Film: Warm vintage grain, natural tungsten key light, subtle lens flare.
- Anamorphic Director's Storyboard: Ultra-wide 2.39:1 aspect ratio, blue streak flares, high contrast.
- Cyberpunk Neon: Saturated cyan and magenta neon backlighting, wet reflective surfaces.
- High Contrast Graphic Noir: Monochromatic black-and-white chiaroscuro, heavy shadows, stark key lighting.
- Master Grid Image Rendering: Generates or allows uploading of a 4x4 master contact sheet image.
- Export Project JSON: Download the complete movie bible, characters, costumes, sets, props, multi-scene screenplays, shot prompts, and custom image references as a single
.jsonproject file. - Import Project JSON: Load any previously saved CineForge project file to resume editing.
- Reset State: Clear active overrides or revert to procedural/genre defaults.
Endpoint: POST /api/generate-bible
Model: gemini-2.5-flash with JSON Response Schema.
You are a Hollywood master screenwriter and production designer.
Create a complete, original, high-craft Movie Production Bible for the movie genre: "{genre}" (Genre ID: "{genreId}").
{promptValue ? `MANDATORY BRIEF SYNOPSIS LINE TO EXPAND: "${promptValue}".` : ''}
CRITICAL MANDATORY REQUIREMENTS:
1. Title and catchy Tagline reflecting the genre and brief synopsis.
2. High-impact Synopsis (detailed 1-2 paragraphs expanding the brief synopsis line).
3. EXACTLY 5 distinct Characters with rich multicultural diversity in names, racial descent/ancestry (e.g. East Asian, African, South Asian, Latino/Hispanic, Middle Eastern, Indigenous, European, Multiracial), ages, sex/gender, height, weight, skin tone, detailed backstories, physical descriptions, personality traits, and motivations.
- MANDATORY DIVERSITY REQUIREMENT: Ensure the character names reflect authentic global and cultural representation suitable for the movie's world and genre.
- For EACH character, specify fields: age, sex, height, weight, skinTone, racialDescent.
- For EACH of the 5 characters, write EXACTLY 5 distinct Costumes (with name, description, materialsAndColors, thematicSignificance).
4. EXACTLY 5 Sets with detailed description, lighting cues, and camera angles.
5. EXACTLY 5 Props that directly drive the plot forward with visual appearance, narrative significance, and key scene usage.
6. Scene 1 Screenplay: Full formatted script incorporating some of the 5 characters, 1 of the 5 sets, and at least 1 of the 5 props.
7. Shot-by-Shot breakdown for Scene 1 (at least 5 shots):
- For EACH shot, write a detailed "establishingImagePrompt" that explicitly INJECTS full scene information (Movie Title & Genre, Scene Title, Set Location & Lighting Cues, Characters present & Costume details, Props used, Camera Angle & Lens, and Staging Action) so it can be directly fed into an AI image generator!
Format your response STRICTLY as valid JSON matching this schema.
Endpoint: POST /api/generate-scene
Model: gemini-3.6-flash with JSON Response Schema.
You are a Hollywood master screenwriter and storyboarding director.
Generate Scene #{sceneNumber} for the movie "{bible.title}" ({bible.genre}).
Movie Synopsis: "{bible.synopsis}".
Available Sets: {availableSets}.
Available Characters: {availableChars}.
Available Props: {availableProps}.
USER SCENE REQUEST: "{sceneTitle || customPrompt}".
REQUIREMENTS:
1. Scene Title (e.g., "Scene {sceneNumber}: [Descriptive Title]").
2. Select 1 Primary Set ID and Name from the movie bible's sets.
3. Select characters present and props used from the bible.
4. Screenplay Script Text (full formatted screenplay script text with scene header, action paragraphs, and dialogue).
5. EXACTLY 16 Shot-by-Shot prompts (Shot #1 to Shot #16) covering the scene from opening establishing shot to climax! Each shot must have:
- shotNumber (1..16)
- shotHeading
- cameraAngleAndLens
- actionText
- charactersPresent
- setUsed
- propsUsed
- establishingImagePrompt
Format your response STRICTLY as valid JSON.
Endpoint: POST /api/generate-shot-image
Model: gemini-3.1-flash-lite-image (Primary) / Pollinations AI (Fallback).
High budget cinematic movie screenshot, 8k resolution, photorealistic film grain, dramatic key lighting: {promptText}
{
"shot_number": 1,
"shot_heading": "INT. CYBERPUNK LAB - NIGHT - ESTABLISHING WIDE",
"timecode": "00:00 - 00:04",
"duration_seconds": 4,
"camera": {
"lens_and_angle": "Wide 24mm Anamorphic Lens",
"motion": "Slow forward tracking shot"
},
"environment": {
"set_name": "Cyberpunk Neural Deck Lab",
"location_type": "Interior High-Tech Lab",
"description": "Nerve-center lab lined with server racks and holographic monitors",
"lighting": "Low-key volumetric neon blue key light with sharp shadow gradients"
},
"characters": [
{
"name": "Kaelen Vex",
"role": "Protagonist / Neural Hacker",
"age": "29",
"sex": "Male",
"height": "5'11\" (180 cm)",
"weight": "165 lbs (75 kg)",
"skin_tone": "Warm Tan / Olive",
"racial_descent": "East Asian / Multiracial",
"physical_description": "A resolute hacker with textured dark hair and sharp cheekbones",
"personality_traits": "Resilient, fiercely independent",
"costumes": [
{
"name": "District 9 Rain-Slicker",
"description": "Heavy waterproof dark coat with glowing cyan seams",
"materials_and_colors": "Matte black waterproof vinyl, cyan fiber-optic trim",
"thematic_significance": "Street-level resistance against corporate control"
}
]
}
],
"props": [
{
"name": "Neural Data Deck",
"appearance": "Overclocked brass and copper cyberdeck with pulsing purple heat-sinks"
}
],
"visual_action": "Kaelen Vex steps forward through drifting steam as monitors flicker.",
"dialogue": {
"speaker": "Kaelen Vex",
"spoken_line": "If these coordinates are accurate, we have less than ten minutes.",
"parenthetical": "(checking scanner)"
}
}{
"prompt_type": "FULL_CHARACTER_MASTER_CONCEPT_PROMPT",
"character": {
"id": "c1",
"name": "Amina Okafor",
"role": "Protagonist / Lead Specialist",
"age": "32",
"sex": "Female",
"height": "5'9\" (175 cm)",
"weight": "145 lbs (66 kg)",
"skin_tone": "Rich Caramel / Golden Brown",
"racial_descent": "African Descent",
"physical_description": "A resolute figure with sharp cheekbones, intense eyes, and an athletic build.",
"personality_traits": "Strategic, fiercely loyal, calm under fire.",
"motivation": "To protect innocent lives and uncover the full truth.",
"backstory": "A veteran of high-stakes conflicts...",
"costumes": [
{
"name": "Primary Tactical Duty Outfit",
"description": "Reinforced duster with utility holsters.",
"materials_and_colors": "Charcoal leather, matte black Kevlar.",
"thematic_significance": "Preparedness for high-stakes conflict."
}
]
}
}- Node.js: v18+ or v20+
- npm: v9+
Create a .env file at the root of the project (reference .env.example):
# Server Port (Default 3000)
PORT=3000
# Google Gemini API Key for AI Production Bible & Screenplay Generation
GEMINI_API_KEY=your_gemini_api_key_here-
Install dependencies:
npm install
-
Start Dev Server:
npm run dev
Boots Express backend server on http://0.0.0.0:3000 with Vite middleware.
-
Production Build:
npm run build
Bundles Vite client assets into
dist/and builds standalone CommonJS backend intodist/server.cjsviaesbuild. -
Production Start:
npm start