Log in
GuideBy HypernaturalVersion 5, updated

Make a script from source

hn/guide-make-a-script-from-source

How to get a job's script from what the person brings: a finished video, a written script or screenplay, a slide deck, or a source to retell (a website, a post, an article, a repo, a help page, a board) where you write the narration and the person approves it word for word. Ends in script.json (scenes, shots, a gendered cast, every line verbatim with a delivery note and emotion, action, beats, sound cues, all timed). Holds the length table (words per second by kind of read) and the beat-table format. Use for transcribing a video into a screenplay, script extraction, converting a script, writing narration from a source, script length, words per second, shot lists, Fountain.

SKILL.md

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

SourceRouteCost and timeQualityLeaf
A finished video (scene, ad, interview, vlog; any length)Speech-to-text, cuts from ffmpeg, then Gemini watches at 4 fps with soundA 2:50 video: one call, about 78k prompt tokens, about 2 min. An hour runs as 12 chunks, one after anotherShots match the real cuts; lines verbatim and attributed by mouthgemini-script-from-video
A written script, screenplay or shot listThe agent reads it into the same script.json; code checks every line word for wordOne LLM pass, reruns if a line is paraphrasedThe script's own shot names kept as labels; timings estimatedllm-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 scriptNot measuredOnly as good as the person's read-throughllm-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 scriptOne LLM pass and the person's read-throughEvery line traceable to the source; timed by the length tableguide-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 gets PERSON 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-highlights writes source/facts.md; a news story keeps source/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).

ReadWords per secondSeen as
Quick creator or news read for social2.5110 words for a 45 s short
Ad narrator or presenter2.5–2.7about 70 words in a 30 s ad; about 48 in a 20 s one with its end card
Faceless explainer narrator2.3–2.785 words read in 32–37 s by four voices on the same text
Repo or feature explainer2.4–2.7110–120 words for 45 s; 150 words for 62 s of narration
A presenter walking through slides2.5–3a 90 s personalized walkthrough
Calm summary read2.5 (150 a minute)a board summary
Dialogue between characters on eleven_v42.8–2.9written-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:

#TimePictureNarrationOn 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)

  1. 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.
  2. Check it: every line verbatim (the written route reports unmatched lines; rerun those), shots against a first/last-frame contact sheet of the cuts.
  3. Gate. review_approve with script.md (cast table, scenes, the script by scene and shot) and the shot stills as the subject'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.

Workflows that use this skill

FAQs

How to get a job's script from what the person brings: a finished video, a written script or screenplay, a slide deck, or a source to retell (a website, a post, an article, a repo, a help page, a board) where you write the narration and the person approves it word for word. Ends in script.json (scenes, shots, a gendered cast, every line verbatim with a delivery note and emotion, action, beats, sound cues, all timed). Holds the length table (words per second by kind of read) and the beat-table format. Use for transcribing a video into a screenplay, script extraction, converting a script, writing narration from a source, script length, words per second, shot lists, Fountain.

Install Hypernatural Desktop, a free Mac app, and connect it to Claude Code, Codex or Claude Desktop. Then describe the video you want and your agent finds the skill itself, or paste this page's link (https://hypernatural.ai/skill/hn/guide-make-a-script-from-source) and it installs hn/guide-make-a-script-from-source and follows it.

Nothing. The skill is free and runs with tools on your own Mac.

Yes. Ask your agent to adjust it for your job, or to save its own version. You can publish your version under your own handle so anyone can install it.

Go make something cool.

Install the app, open your agent, describe the video. That's the whole onboarding.

Sticker HypernaturalSticker BannerSticker TVBoy