Every later step reads one script.json: scenes → shots → elements in order (dialogue
with character, parenthetical, emotion, V.O. or O.S.; action, with on-screen text as
ON SCREEN: …; reaction beats; sound and music cues), plus the cast and story beats,
all timestamped. It is written alongside a readable script.md and a script.fountain
that opens in screenwriting apps.
First question: what did the person bring? A finished video, a written script, a deck, or a source to retell. If a later job features the same people, carry the earlier script's cast over (labels, looks, voices) instead of starting fresh.
Routes
| Source | Route | Cost and time | Quality | Leaf |
|---|---|---|---|---|
| A finished video (scene, ad, interview, vlog; any length) | Speech-to-text, cuts from ffmpeg, then Gemini watches at 4 fps with sound | A 2:50 video: one call, about 78k prompt tokens, about 2 min. An hour runs as 12 chunks, one after another | Shots match the real cuts; lines verbatim and attributed by mouth | gemini-script-from-video |
| A written script, screenplay or shot list | The agent reads it into the same script.json; code checks every line word for word | One LLM pass, reruns if a line is paraphrased | The script's own shot names kept as labels; timings estimated | llm-convert-written-script |
| A slide deck (PDF) | Ask whether the script already exists (speaker notes, a voiceover draft). If it does, it is a written script. If the deck is all there is, write the narration per slide, then treat it as a written script | Not measured | Only as good as the person's read-through | llm-convert-written-script after the narration exists |
| A source to retell (a website, a blog post, a news article, a repo, a help page, a board) | You write the narration from the source's facts, as a beat table; then treat it as a written script | One LLM pass and the person's read-through | Every line traceable to the source; timed by the length table | guide-pull-product-highlights for the facts; llm-write-an-ad-script for an ad's beats, llm-write-a-hook for the opening, llm-pick-a-visual-metaphor for generated pictures |
A deck or a source alone means you wrote the words, so the person has to review them. Put every
narrated line in front of them in script.md with review_approve before anything is
voiced; they can edit it in place, and tell them this is the step where wording
changes are cheap. When the answer has edited, their version is the script. When they brought their own script, say so and
keep the check to a confirmation. There is no single answer: be explicit about which
case this job is.
Choosing and rules (both proven routes)
- Labels carry gender. A name is used only when it is spoken or shown. A named
cue carries the gender as an extension (
NORA (F),RAVI (M)); an unnamed one says it (WOMAN 1,FEMALE EXPERT); unclear presentation getsPERSON 1. Gemini returns bare roles (EXPERT) even when told not to, so enforce the rule in code after it. - A scene is a sequence. It starts at a cut where the story moves on; cutaways, inserts, replays, montage and B-roll that serve it stay in it, and intercutting is one scene. "New location = new scene" gave 16 scenes for a video whose person had cut it into 4; the sequence rule gave 5.
- Shots come from cuts, in code. Cuts at the long-video threshold, cuts under 0.4 s
apart counted once (
ffmpeg-scene-cuts, Which threshold for which job); each shot's middle frame goes to Gemini labelled with its number. Without the stills its descriptions drifted from shot 16 on (two shots swapped, one off from 18 to 21); with them all 23 matched. - Dialogue goes into shots by transcript time, which is exact; other elements into the shot Gemini names, because its own timestamps drift.
- A line across a cut is split; the part after the cut is continued (CONT'D).
- Every line gets a parenthetical and an emotion, mandatory in the prompt ("even a calm line has a delivery"): optional, only 5 of 27 lines got one.
- Context helps with names and roles the video doesn't state ("a deepfake-awareness training video; the woman in the grey jacket is a security expert").
- Written scripts are timed by word count: dialogue lasts at least its words at 2.8 words/s; sound and music cues play under without taking time. Estimates run long: 267 s estimated came out as a 227 s track on eleven_v4. Speeches may be split sentence by sentence, which is fine for direction.
Retelling a source
- Facts first. Write down what the source says before writing a line
(
guide-pull-product-highlightswritessource/facts.md; a news story keepssource/article.md). Every line of narration traces to one of them; a number keeps the source's wording ("reportedly" stays). - The shape is the job's. A workflow names its beat order (an ad's, a news short's, a post's argument); with none, keep the source's own order of ideas.
- One idea per line, one line per shot, and the opening line per
llm-write-a-hook. - Write the beat table (below), then the narration as one block with its audio tags.
Respellings for the voice are made when voicing (
guide-voice-a-script, Pronunciation), not in the approved script.
Length
Words per second by kind of read, measured on delivered takes. Count the narration's words, divide by the rate, and add the time the picture runs with no voice (a demo, an end card).
| Read | Words per second | Seen as |
|---|---|---|
| Quick creator or news read for social | 2.5 | 110 words for a 45 s short |
| Ad narrator or presenter | 2.5–2.7 | about 70 words in a 30 s ad; about 48 in a 20 s one with its end card |
| Faceless explainer narrator | 2.3–2.7 | 85 words read in 32–37 s by four voices on the same text |
| Repo or feature explainer | 2.4–2.7 | 110–120 words for 45 s; 150 words for 62 s of narration |
| A presenter walking through slides | 2.5–3 | a 90 s personalized walkthrough |
| Calm summary read | 2.5 (150 a minute) | a board summary |
| Dialogue between characters on eleven_v4 | 2.8–2.9 | written-script timing below |
The same text runs several seconds apart between voices (32.1–36.6 s across four), so leave a second or two of slack and fix the length on the picked take.
The beat table
Every written narration goes to the person as a table, one row per beat or shot:
| # | Time | Picture | Narration | On screen |
|---|
Add a You hear column when sound carries a beat (a demo, an effect). A retold script's table is the shot list too: the picture column is what the stills are made from.
Process (gate is a review)
- Make the script by the route above. Long videos are chunked at most 300 s, each chunk ending on a cut, each handed the cast found so far.
- Check it: every line verbatim (the written route reports unmatched lines; rerun those), shots against a first/last-frame contact sheet of the cuts.
- Gate.
review_approvewithscript.md(cast table, scenes, the script by scene and shot) and the shot stills as thesubject's files. The person corrects names, scene breaks and attributions before any casting or voicing.
Avoid
- Trusting diarization for who spoke: speaker ids cluster voices, not people (a deepfake shares the real man's id). Attribute by mouth and voice.
- Gemini's own timestamps for shots and scenes.
- A paraphrased line in
script.json: everything downstream speaks it.
Related
guide-cast-a-voice,guide-voice-a-script: the next steps.workflow-slide-deck-presenter,workflow-script-to-video: jobs that start here.


