> ## Documentation Index > Fetch the complete documentation index at: https://docs.decktalk.app/llms.txt > Use this file to discover all available pages before exploring further. # Writing for the ear > How to write a DeckTalk narration script that cues well, with stage directions, beats, pauses, offsets, time budgets, and a silent rehearsal. DeckTalk cuts the video to the words, so the script decides the timing. A script that reads well on paper can still cue badly, because a reveal needs a word to land on and a listener needs a moment to look. These are the habits that make the difference. They come from building the scaffold and from watching where reveals feel late or early. ## Write the script first Write the whole narration before you touch a slide, and read it aloud once. The words that carry the argument are the words the visuals will land on, and you cannot pick them until they exist. A slide that is designed first tends to demand a sentence that nobody would say. ## Say it, then show it Name the thing, and let the reveal follow the name. When the narration says "here is the curve" the curve should start drawing on "curve", not before it. A visual that appears ahead of its words makes the listener wonder what they are looking at, and a visual that appears long after them has already been imagined. The cue phrase is therefore the phrase that names the thing, and the rest of the sentence explains it while it is on screen. ## Give every reveal a noun to land on A cue resolves to the first word of its phrase, so the phrase should begin with the word that names the visual. "Start with a loss surface" cues on `loss surface` and lands on "loss", which is a noun the listener can attach to the bowl that draws. A phrase such as "and then" lands on nothing in particular. The scaffold's cues are all nouns or verbs with a concrete referent: `loss surface`, `Pick a point`, `learning rate`, `Is this query`, `Write the script`. ## One reveal per idea Give each idea its own reveal, and give each reveal its own sentence. Roughly one cue every ten to fifteen seconds is a comfortable rate for a lesson. Three reveals in one breath look like an animation rather than an explanation, and a minute with no reveal at all lets the picture go stale. When one sentence carries two ideas, split it. ## Put silence before a reveal A short silence before a reveal makes the reveal read as an event. Two directions do this, and they reach the voice differently. `[beat]` is a beat: the voice reads it as a dash at the end of the sentence before it and pauses there as it would at any dash, and nothing else is sent. `[pause N]` sends a `` tag and is the only direction that does, because frequent break tags make the voice add fillers and breaths. Use beats freely and timed pauses sparingly. The scaffold pauses for three seconds before the answer so that the audience can think. ```md script.md theme={null} [beat] Pause and think: what happens if the learning rate is too large? [pause 3] You overshoot, and bounce from side to side. [beat] Small enough, and you settle at the bottom. ``` Anything else in square brackets is a stage direction. It is not spoken and it is a beat where it sat, so a direction such as `[Deck scene 3. A loss bowl draws.]` is both a note to yourself and a pause. The silence before the first section and after every section's last word is added by ffmpeg rather than requested from the voice, so a script never needs a pause at either end. [script.md](/reference/script-md) lists every direction. ## Trail the word, and lead it only when the audience must read The `offset` key in `cues.json` shifts a cue in seconds. A small positive offset, one or two tenths of a second, lets the word finish before the visual moves, which feels like the narrator pointing at something. The scaffold trails `settle` by 0.2 seconds, so the point reaches the bottom of the bowl as the word ends. ```json cues.json theme={null} { "cue": "3.1min", "on": "settle", "offset": 0.2 } ``` Lead the word with a negative offset only when the audience must read along with the narration, such as a line of code that the voice is reading out. Then the text has to be on screen before the first word of it is spoken. ## Close on \$end The last visual of a section can land on `$end`, the end of the section's speech, so that a summary line or a final state appears as the voice stops. This is also the right place for a `hold_seconds` on the last page section, which holds the final frame after the narration ends. [cues.json](/reference/cues-json) documents `$start` and `$end`. ## Write numbers as words The words come back from the voice, and a cue phrase must match them. A number written as digits comes back in whatever form the voice chose to say, so "2x" in the script is fragile as a cue. Write "two x" in the script and show `2x` on the slide. The same goes for symbols and abbreviations. ## Rehearse with a silent build `decktalk build --silent` runs every stage with a silent placeholder track and estimated word times, so it costs nothing and needs no key. The estimate paces the words at `silent_words_per_minute` and adds every declared pause, and the cues resolve to plausible times. The placeholder track is not pure silence: it carries a soft click at every estimated word start, so the pacing is audible, and `decktalk verify` can measure the picture against the clicks. Watch the result for pacing. A reveal that arrives too early in a silent rehearsal usually arrives too early with the real voice as well. [How it works](/concepts/how-it-works#the-silent-build) explains what the clicks prove. ## Give a section a time budget A heading may carry a time budget after a dash, and the narrate table compares it with the estimate and, once the voice has spoken, with the real length. The estimate is the word count at `words_per_minute`, which defaults to 140. ```md script.md theme={null} ## 3. Gradient descent — 0:40 to 1:20 ``` ```text theme={null} # section words est target actual placeholders --------------------------------------------------------------------- 1 open 21 0:09 -- 0:11 - 2 three-lines 47 0:20 -- 0:22 - 3 gradient-descent 94 0:40 0:40 0:47 - 4 before-and-after 104 0:45 -- 0:47 - 5 close 38 0:16 -- 0:20 - --------------------------------------------------------------------- total 304 2:10 2:27 ``` The `target` column is the budget's length. Section 3 was budgeted at forty seconds and the silent rehearsal ran to forty-seven, which is the signal to cut a sentence or to widen the budget once the voice has spoken and the `actual` column is real. The `min_seconds` key on a section in `cues.json` works the other way around and warns when the speech is shorter than the visuals need. ## Next [Slide recipes](/guides/slide-recipes) pairs script lines with cues and markup for six common slides. [Cues](/concepts/cues) has the matching rules and the placement rules of thumb in one list.