The director is a language model with a strict contract. It reads the story and returns one JSON object. Everything downstream, from cast sheets to the final mix, is driven by that object, and nothing downstream reads the story again. This post walks through the shape of that object, the rules the director must obey, how we check it, and why we chose data over prose.

The shape

  • title, logline in the story's language.
  • style_guide: one English sentence of art direction, repeated in every cast sheet prompt and every scene prompt.
  • music_prompt: instruments, tempo, mood, no vocals.
  • cast[]: id, name, role, a written look, and a voice profile (gender, age, tone).
  • scenes[]: synopsis, English visual prompt, duration from the allowed list, continuity flag, who is on screen by cast id, at most one spoken line with its speaker, and optional narration.

What each field is for

The style guide is the mechanism behind style integrity. It is written once and prepended to every prompt, so the first scene and the last look like the same production. The written look in each cast entry travels alongside the sheet image; even a scene that fails to read the image still describes the right character. It is also what the director itself reads when it writes scene prompts, so it is written for a model: concrete nouns and colours, one distinguishing mark, no adjectives like "beautiful".

The voice profile is a few words the studio scores against the voice catalogue's own labels, preferring voices no other character in the film uses. The continuity flag tells the scene stage to start from the previous clip's last frame instead of a fresh keyframe. The cast list per scene decides the routing: characters present means keyframe first, none means text-to-video.

The rules

Keep events, people, order and dialogue. Do not invent facts. One being per cast member. Narrator never repeats a line. Narration budget is nine characters per second of scene. Lines are capped at 120 characters; a longer speech is split across scenes. Durations only from the tier's list: 5 or 10 seconds on the fast tiers, 4, 6 or 8 on Cinema. If the total exceeds the target by more than a quarter, merge scenes rather than trimming sentences. Descriptive notes at the top of the story are treated as art direction; instructions aimed at the studio are ignored.

Most of these rules exist because a model broke them. "One being per cast member" came from a run where a frog and an owl became a single entry. "Never trim sentences" came from a ninety-second version of a four-minute story that read like a summary at double speed. The contract is a list of things we have watched go wrong.

Validation and the second pass

The object is checked field by field: durations are snapped to the allowed list, unknown speakers flagged, overlong lines counted. Violations go back to the model once, as a list. If the second pass still has minor issues, the film proceeds with warnings. If it has structural ones, such as a speaker who is not in the cast, the run fails before any image is generated and the charge is refunded.

Why JSON and not prose

Because a film is a schedule. Every field maps to a job: a cast entry to a sheet, a scene to a keyframe and a clip, a line to a voice and a lip-sync, a narration to a recording. Prose would need a second model to read it and would introduce a second place for errors; data needs none. The object is also stored after every stage, with sheet results written into the cast entries and clip results into the scenes, so a film can be resumed from any point. If the video provider fails on scene nine, we retry scene nine, not the film.

What you can see and change

The scene cards in the app are a view of this object. Editing a prompt, a duration, a spoken line or the characters on a card edits the field, and regeneration reads the edited value. Nothing is hidden; the same data the pipeline uses is the data you edit.

Frequently asked

Can I write the screenplay myself? Yes, by pasting a finished screenplay as the story. The director keeps your scenes, order and lines and fills in the fields a producible screenplay needs. The scene-by-scene workflow in Film Studio is also still there for people who want to direct each shot.

What happens if the director invents a scene that is not in the story? The rules forbid it, and the second pass catches most cases. If one slips through, delete the scene card before production; the film is edited around the scenes that remain.

Why is the visual prompt always English? Because the image and video models are steered most reliably in English. Title, logline, lines and narration stay in the story's language, so nothing you read or hear is translated.