Nova Director

AI Film Director — generate cinematic scenes with consistent characters in minutes.

Script → Storyboard → Image → Video → Assembly. Powered by multi-agent orchestration.

How It Works

Scene Description + Characters
        │
        ▼
  ┌─────────────┐
  │ Script       │  LLM breaks scene into cinematic shots
  │ Analysis     │  (wide → medium → close-up → reaction)
  └──────┬──────┘
         │
  ┌──────▼──────┐
  │ Character    │  Generate reference portraits for consistency
  │ References   │
  └──────┬──────┘
         │
  ┌──────▼──────┐
  │ Storyboard   │  Build prompts: character + camera + setting + mood
  └──────┬──────┘
         │
  ┌──────▼──────┐
  │ Image Gen    │  Reference frame per shot (Seedream, Gemini, etc.)
  └──────┬──────┘
         │
  ┌──────▼──────┐
  │ Video Gen    │  I2V animation per shot (Wan 2.6, Veo 3.1, Seedance)
  └──────┬──────┘
         │
  ┌──────▼──────┐
  │ Assembly     │  ffmpeg concat → final scene.mp4
  └─────────────┘

Quick Start

pip install nova-director
export MEGANOVA_API_KEY=sk-...

# From YAML scene file
nova-director generate examples/westworld-saloon.yaml

# From command line
nova-director generate \
  --description "A cowboy walks into a saloon and sits at the bar" \
  --character "John:tall man, weathered face, brown cowboy hat, leather vest" \
  --duration 15

Scene YAML Format

title: "Westworld Saloon"
description: |
  Dolores pushes through the swinging saloon doors.
  She spots the Man in Black at the bar. Their eyes meet.

setting: "Old West saloon — wooden beams, oil lamps, dusty"
mood: "tense, dramatic, cinematic"

characters:
  - name: Dolores
    appearance: "Young woman, blue eyes, blonde hair, blue prairie dress"
    personality: "Curious, resilient"

  - name: Man in Black
    appearance: "Tall man, black hat, black duster coat, weathered face"
    personality: "Cold, calculating"

Python API

import asyncio
from nova_director.director import direct_scene
from nova_director.models import Character, SceneConfig

characters = [
    Character(name="Dolores", appearance="Young woman, blue eyes, blonde hair, blue prairie dress"),
    Character(name="MiB", appearance="Tall man, black hat, black duster coat"),
]

config = SceneConfig(api_key="sk-...", api_base="https://api.meganova.ai")

result = asyncio.run(direct_scene(
    description="Dolores enters the saloon and sees the Man in Black",
    characters=characters,
    config=config,
    target_duration=20,
    setting="Old West saloon",
    mood="tense, cinematic",
))

print(f"Output: {result.output_path}")
print(f"Shots: {result.shots_generated}/{len(result.scene.shots)}")

Supported Models

Works with any OpenAI-compatible API. Default: MegaNova API.

Stage	Default Model	Alternatives
Script Analysis	gemini/gemini-3-flash-preview	Any chat model
Image Generation	Bytedance/seedream-5-0-lite-260128	Gemini Image, Dreamshaper
Video (I2V)	Alibaba/wan2.6-i2v	Veo 3.1 I2V, Seedance I2V
Video (T2V)	Alibaba/wan2.6-t2v	Veo 3.1, Seedance T2V

Requirements

• Python 3.10+
• API key for image/video generation (MegaNova or compatible)
• ffmpeg (for video assembly)

Character Consistency

The pipeline maintains character consistency through:

1. Reference portraits — generated once, used as I2V input for all shots
2. Appearance injection — character description included in every prompt
3. Storyboard prompts — camera angle + character + setting composed per shot

Cost Estimate

A typical 20-second scene (4 shots):

• 4 image generations: ~$0.04
• 4 I2V generations: ~$0.80
• 1 LLM planning call: ~$0.02
• Total: ~$0.86

License

MIT

Credits

Built by Meganova AI. Inspired by MovieAgent, ViMax, and FilmAgent.