OpenDirector

简体中文

Turn Codex into an AI film director.

OpenDirector is an open-source, agent-first pre-production workflow that turns scripts into director treatments, production shot lists, continuity notes, and model-ready image/video prompts. The agent makes creative judgments; a dependency-free CLI validates the production contract and exports reviewable files.

It does not pretend a still-image slideshow is a finished film, and it does not hide creative decisions inside a black box.

Why this exists

General AI video systems focus on generating assets or assembling a final video. Professional pre-production needs a different layer: shot purpose, screen direction, lens and movement choices, performance, light, sound, continuity, timing, and handoff formats. OpenDirector makes that layer explicit and editable.

v0.1 capabilities

• Script → director treatment and numbered shot plan through the bundled Codex skill
• Production fields for lens, framing, camera movement, composition, light, sound, and continuity
• Machine-readable assumptions that separate source facts from agent inference
• Separate stable-frame and motion prompts for image/video models
• Deterministic validation with actionable errors
• UTF-8 JSON, Excel-friendly CSV, and human-readable Markdown exports
• Zero runtime dependencies and no API key requirement

Quick start

Requirements: Python 3.10 or newer.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
opendirector validate examples/library-morning/shot-plan.json
opendirector export examples/library-morning/shot-plan.json --output output

Expected validation result:

valid: 6 shots, 30s

The export command writes:

output/shot-plan.normalized.json
output/shot-list.csv
output/director-plan.md

Use with Codex

Copy or symlink skills/opendirector into your Codex skills directory, then ask:

Use OpenDirector to turn this 60-second script into a restrained director treatment, shot list, continuity plan, and image/video prompts. Validate and export the result.

The skill is intentionally agent-agnostic at the file level: another capable coding agent can follow the same SKILL.md and JSON contract.

Example

examples/library-morning is a fictional, non-client 30-second scene. It includes the source script, validated shot plan, and reviewable expected outputs. No proprietary material is included.

Architecture

script / brief
      ↓
OpenDirector skill (creative reasoning)
      ↓
shot-plan.json (editable contract)
      ↓
validator + exporters (deterministic)
      ↓
JSON + CSV + Markdown handoff

Scope and limitations

OpenDirector v0.1 validates structure, identifiers, durations, and required production fields. It cannot automatically prove artistic quality, physical feasibility, legal clearance, factual accuracy, or character continuity. A director must review those decisions before production.

Development

PYTHONPATH=src python -m unittest discover -s tests -v
python /path/to/skill-creator/scripts/quick_validate.py skills/opendirector

See CONTRIBUTING.md for contribution rules and the v0.2 roadmap.

License

MIT