Film Creator

Required Tools:

• Node.js 24+ (pre-installed in HappyCapy)
• FFmpeg (pre-installed in HappyCapy)

Quick Start

Create a Film from Text

node scripts/create_film.js "A lonely robot discovers the last flower on Earth"

Create a Film from Image

node scripts/create_film.js --image "/path/to/image.jpg" "Transform this into a cinematic story"

Create a Film with Custom Settings

node scripts/create_film.js \
  "A time traveler's final journey" \
  --model "openai/sora-2" \
  --aspect-ratio "16:9" \
  --output "my_film.mp4"

Features

Screenplay Generation

• Story Structure: Three-act structure adapted for 30-second format
• Scene Breakdown: 5-6 distinct scenes with clear transitions
• Visual Descriptions: Detailed shot compositions and camera movements
• Cinematic Language: Professional terminology (establishing shot, close-up, tracking shot, etc.)
• Emotional Arc: Clear beginning, middle, and end with emotional progression

Video Generation

• Multi-Scene Production: Generates 5-6 individual scenes
• Cinematic Quality: Uses professional video generation models
• Smart Prompting: Converts screenplay into optimized video generation prompts
• Continuity: Maintains visual consistency across scenes

Film Assembly

• Scene Stitching: Seamlessly combines individual scenes
• Transitions: Smooth cuts or fade transitions between scenes
• Duration Control: Precisely timed to 30 seconds total
• Quality Preservation: No re-encoding loss

Supported Models

Recommended for Film Creation

Usage Examples

Basic Film Creation

# From a simple concept
node scripts/create_film.js "A cat astronaut explores a distant planet"

# With specific genre
node scripts/create_film.js "A noir detective story set in the rain"

# From an uploaded image
node scripts/create_film.js --image "concept_art.jpg" "Make this into an epic adventure"

Advanced Options

# Use premium model for highest quality
node scripts/create_film.js \
  "An emotional reunion at a train station" \
  --model "openai/sora-2-pro" \
  --output "reunion.mp4"

# Create vertical video for mobile
node scripts/create_film.js \
  "A day in the life of a street performer" \
  --aspect-ratio "9:16" \
  --model "byteplus/seedance-1-0-pro"

# Generate only the screenplay
node scripts/generate_screenplay.js "A magical library where books come alive"

Workflow

Step 1: Creative Analysis

The system analyzes your input (text or image) to identify:

• Core concept and theme
• Emotional tone
• Visual style
• Key story elements

Step 2: Screenplay Writing

Generates a professional screenplay including:

• Scene Headings: INT./EXT. location and time
• Action Lines: Visual descriptions of what happens
• Camera Directions: Shot types and movements
• Timing: Duration for each scene

Example screenplay output:

FADE IN:

EXT. ABANDONED CITY - DAY

WIDE ESTABLISHING SHOT: A desolate cityscape covered in rust and vines.
The sun casts long shadows through broken buildings.

A small ROBOT (weathered, curious) rolls through debris, its single eye
scanning the ground.

CLOSE-UP: The robot's sensors light up as it detects something.

LOW ANGLE: The robot stops at a crack in the concrete where a single
FLOWER blooms in brilliant red.

EXTREME CLOSE-UP: The robot's optical lens focuses on the flower,
reflecting its petals.

The robot extends a gentle mechanical hand, not to touch, but to protect.

FADE OUT.

Step 3: Scene-by-Scene Generation

Each scene is converted to an optimized video prompt:

• Camera angles and movements specified
• Visual details enhanced
• Lighting and mood emphasized
• Continuity elements maintained

Step 4: Video Assembly

All scenes are combined with:

• Frame-accurate stitching
• Optional transitions (cut/fade)
• Audio-ready format (MP4)
• Optimized compression

Command Reference

create_film.js (Main Script)

Parameters:

• prompt (required): Text description or story concept
• --image PATH (optional): Image file to use as creative inspiration
• --model MODEL (optional): Video generation model (default: google/veo-3.1-generate-preview)
• --aspect-ratio RATIO (optional): Video aspect ratio (default: 16:9)
• --output PATH (optional): Output file path (default: generated_film.mp4)
• --no-assembly (optional): Generate scenes only, don't combine them
• --transition TYPE (optional): Transition type: "cut" or "fade" (default: cut)

generate_screenplay.js

Generate screenplay without video production:

node scripts/generate_screenplay.js "Your story concept" [--output screenplay.txt]

generate_scene.js

Generate a single scene from a prompt:

node scripts/generate_scene.js "Scene description with camera angles" [--model MODEL] [--duration SECONDS]

assemble_film.js

Combine pre-generated scene videos:

node scripts/assemble_film.js scene1.mp4 scene2.mp4 scene3.mp4 --output final.mp4

Best Practices

Writing Effective Prompts

Good prompts include:

• Clear genre or style ("noir film", "whimsical animation style")
• Emotional core ("a story about hope", "bittersweet reunion")
• Visual anchors ("neon-lit city", "misty forest")
• Character elements ("lonely protagonist", "mischievous creature")

Examples:

✓ "A cyberpunk story about a hacker who discovers they're an AI"
✓ "A heartwarming tale of a child's robot friend, Studio Ghibli style"
✓ "A suspenseful noir detective story in the rain at night"
✓ "An epic space opera battle with massive starships"

✗ "Make a video"  (too vague)
✗ "Something cool"  (no direction)

Model Selection

• Use Google Veo 3.1 for most projects - excellent balance of quality and reliability
• Use OpenAI Sora 2 Pro for highest cinematic quality and complex physics
• Use BytePlus Seedance when you need non-standard aspect ratios (1:1, 9:16, 21:9)

Image Input Tips

When using an image as input:

• Provide a complementary text prompt to guide the narrative
• The system will analyze visual elements (colors, composition, mood)
• Works best with conceptual or atmospheric images
• Character-focused images can become protagonists

Duration Optimization

• Each scene is 5 seconds for optimal storytelling pace
• 6 scenes = 30 seconds total
• This pacing allows for:
  • Establishing shot
  • Rising action
  • Climax/key moment
  • Resolution
  • Emotional beat
  • Closing image

Troubleshooting

"Generation timeout" or "Scene generation failed"

Video generation can take time. The script automatically waits up to 5 minutes per scene. If it fails:

• Try a simpler prompt for that scene
• Use a faster model (google/veo-3.1-fast-generate-preview)
• Check your internet connection

"FFmpeg error" during assembly

Ensure all scene files were generated successfully:

ls -lh scene_*.mp4

If some scenes are missing or corrupted, regenerate them individually:

node scripts/generate_scene.js "Scene description" --output scene_3.mp4

Poor visual continuity between scenes

The screenplay generator aims for continuity, but AI models may interpret scenes differently. To improve:

• Add more specific visual details in your prompt
• Specify a consistent color palette or lighting
• Use model-specific style references

"API key not found"

Set the environment variable:

export AI_GATEWAY_API_KEY="your-api-key-here"

Technical Details

Screenplay Format

The generated screenplay follows industry-standard formatting:

• Scene headings in caps
• Action lines in present tense
• Camera directions in caps or parentheses
• Timing notes for pacing

Video Specifications

• Format: MP4 (H.264)
• Resolution: Model-dependent (typically 1280x720 or 1920x1080)
• Frame Rate: 24-30 fps
• Duration: Exactly 30 seconds
• Aspect Ratios: 16:9, 9:16, or custom (model-dependent)

Assembly Process

Uses FFmpeg with:

• Lossless concatenation when possible
• Minimal re-encoding
• Frame-accurate cutting
• Preserved metadata

Examples Gallery

Example 1: Sci-Fi Short

Prompt: "A lonely robot discovers the last flower on Earth"

Generated Screenplay (abbreviated):

Scene 1: Wide shot of desolate cityscape
Scene 2: Robot character introduction
Scene 3: Discovery of flower (key moment)
Scene 4: Emotional close-up of robot's reaction
Scene 5: Robot protecting the flower
Scene 6: Hopeful closing image

Example 2: Fantasy Adventure

Prompt: "A young wizard's first spell goes wonderfully wrong"

Key Scenes:

• Establishing: Magic academy interior
• Character: Nervous student with wand
• Action: Spell casting with dramatic effects
• Consequence: Humorous magical mishap
• Reaction: Wizard's surprise and laughter
• Resolution: Acceptance and learning moment

Example 3: Noir Detective

Prompt: "A 1940s detective receives a mysterious case in the rain"

Style Elements:

• High contrast lighting (noir aesthetic)
• Rain effects and reflections
• Dramatic shadows
• Close-ups on key objects
• Moody, atmospheric tone

Integration with Other Skills

This skill works well with:

• generate-image: Create concept art before film production
• image-enhancer: Improve reference images
• video-frames: Extract keyframes from generated films for editing

Limitations

• Maximum duration: 30 seconds (by design)
• Scene count: 5-6 scenes (optimal for pacing)
• No dialogue audio (visual storytelling only)
• No custom music (silent film format)
• Limited character consistency across scenes (model limitation)

Future Enhancements

Potential additions:

• Background music generation and integration
• Text-to-speech for dialogue
• Extended duration options (60s, 90s)
• Multi-character tracking
• Style transfer between reference and generated scenes
• Storyboard visualization before generation

Credits

Built on top of:

• AI Gateway API (video generation)
• FFmpeg (video assembly)
• Node.js (orchestration)

License

MIT License - Free to use and modify