AI Short Film Pipeline (router)

Why this pipeline exists

A video model has no memory. It only knows what the current prompt and the current reference images tell it. Every failure in the source course — a third chair, a character in a different seat, a grandfather with the hero's face, waxy hands, scribbled notebook text, a smile after a crying scene — was the model filling a gap the prompt left open. So the whole discipline is: close every gap before spending credits, and when randomness still wins, fight it with parallel takes, not with one-at-a-time rerolls.

We have the advantage of hindsight. The course taught these lessons one failure at a time because that is how humans learn; a skill should not repeat the failures. It should encode the final state of knowledge and aim for first-pass success, then use parallelism to absorb what randomness remains.

Stages

Stages 2–4b run in parallel with each other. Stage 5 needs locked assets and calls 5b/5c as needed. Stage 6 loops to 5.

Who calls whom. Users talk to an entry skill (cinematic-film, game-cutscene-generator, boss-battle, …). Entry skills call these stages. Stages -1 through 6 are internal: they are documented so their decisions are legible, not so users have to invoke them.

Never generate video without passing through the gates. The only exception is the user explicitly saying "just generate it" — then note the skipped gates in review.md so the debt is visible.

Order of work (whole-film, not shot-by-shot)

The course went scene by scene: assets for scene 1, shoot scene 1, assets for scene 2… That is how you learn, not how you ship. The pipeline order is:

1. Outline (direction.md + story.md: spine, conflict ladder, emotion map) → user approves. The story stage supplies conflict, loss and dilemma even when the user did not ask for them; most users won't.
2. Full script, iterated until every block, shot and line is approved. Nothing is generated until here.
3. All assets for the whole film — every character, variant, location, prop, screen — generated in parallel batches, picked, locked. For dialogue or narration, use film-dialogue-voiceover now: recommend ElevenLabs MCP, resolve each speaker's real voice ID, generate and check the speech files, measure their durations, and verify the video's audio-input route. The script's build list includes these recordings.
4. Style check: block 1 only, standard (×4), on the final video model. The user confirms the look is live-action, the motion feels right, the references hold. If not, fix the prompt template, not the film.
5. All remaining blocks fired as one parallel wave (standard each; max for blocks the user flags as risky).
6. Lock by index — review picture and required speech; user names take numbers per block; assemble accepted takes.
7. Final mix last, speech preparation first. After picture lock, add music and effects and balance the mix. Speech that drives a performance is already prepared and attached before video generation. Off-screen narration may be mixed in later using its prepared track; never silently defer requested character voices until after a video batch.

Reasoning: every API call adds variance; every gate closed early removes a class of it. Batching the whole film also means all takes arrive together and the review is one sitting instead of eight.

Project folder (fixed)

films/<slug>/
  direction.md            stage 0: intent, genre, palette per location, quality variables in play
  script.md               stage 1: blocks, shots, justifications, build list
  continuity.md           ledger: per block → exit state of every character (emotion, wardrobe, seat, props in hand)
  asset-map.json          name → locked file/url/desc + which blocks it appears in
  voice-cast.json         character/narrator → provider, real voice ID, settings, accepted preview
  speech-lines.json       exact line → speaker, audio file, measured duration, shot, input binding
  assets/
    characters/  locations/  props/  screens/  speech/  candidates/
  prompts/
    block-<nn>[<a|b|c>][-v<k>].txt
  takes/
    block-<nn>/  ...takes, review.md, locks.json
  scenes/                 assembled block videos + last frames
  tasks/

asset-map.json entry shape:

"santiago": {"kind":"character","file":"assets/characters/santiago.png","url":"https://…",
             "desc":"25, Spanish, lean 1.82 m, dark curly hair, stubble, marbled camp shirt, olive trousers",
             "blocks":[1,3,5,7,8], "continuity_critical":["face","hair","shirt print"]}

continuity_critical lists the features a viewer would notice if they changed. Those features must be in the sheet and in every prompt's desc.

Batch modes

Reasoning: one 30 s 1080p video take can take 5–20 minutes. Serial rerolls make a 2-minute film a multi-day job. Four parallel copies of a well-specified prompt almost always yield at least one keeper per shot; max additionally explores four prompt axes at once so the next rewrite is informed by evidence, not guesses.

Shared scripts (scripts/ next to this file — resolve absolute path)

• batch.sh — fire N parallel async generations from prompt files, record task ids. This image/parameter-only helper does not upload speech; use a verified audio-capable MCP/API for audio-conditioned takes.
• poll.sh — poll, download, status table.
• capture.sh — screenshot a live web page for use as an on-screen prop.

Model defaults (verify with cohub models ls --model-type multimodal)

Block length with Seedance 2.5: default 30 s. One generation = one block; fewer calls = less variance. Go shorter (10–15 s) only when a block needs a match cut, a single line that must be isolated, or a physical beat the model must not rush. A ~2 min film ≈ 4–5 blocks of 30 s. Translate any 4K / 21:9 note in a source prompt to 1080p / 16:9 and keep the composition intent.

Non-negotiables

0. Read the stage skill before doing the stage. Open film-<stage>/SKILL.md with the read tool at the start of each stage and run its checklist literally. Working from memory is how the skill's own rules get skipped (this happened once: an outline was written with no conflict because §1b was never consulted).
1. Direction before script, script before assets, assets before video. Each earlier artifact is the specification for the next.
2. Every shot must justify itself (see film-direction). If it cannot say what it reveals and what breaks if it is cut, it is cut.
3. Continuity-critical details get their own reference image. Faces, hairstyles, wardrobe per scene, recurring props, anything with text, any one-off character who is featured (an old man in close-up), any real product UI. Background crowds do not.
4. Positive language only inside shot blocks. Say what is; never what is not.
5. Wide anchor first whenever a block has more than one shot in a known room.
6. Parallel by default. standard = 4 takes. Serial rerolls are not a strategy.
7. Lock explicitly. Every kept take/span is written to locks.json with the reason. If two takes each have a good half, prefer regenerating a merged version over a hard splice (splices between different generations rarely match; the source course did it, but the author of this pipeline found it reads unnatural).
8. Record everything — prompt text, task ids, verdicts, locks, continuity exit-states. A film is rebuilt from its notes.