> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decktalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Writing for the ear
> Write a narration script that gives every reveal a word to start on.
This guide shows how to write a script that gives each reveal a word to start on. Read it before you design slides, and again when a reveal feels early or late.
DeckTalk times every reveal from the spoken words, so the script sets the timing. The advice below comes from building DeckTalk's own films and from watching where reveals felt early or late.
## Write the script first
Write the whole script before you design a slide. Then read it aloud one time. The words that carry the argument are the words that the reveals start on, so you need those words first. A slide that you design first often needs a sentence that nobody would say.
## Say the name before the reveal
Name the thing, and let the reveal follow the name. When the script says "here is the bowl", the bowl appears on "bowl", not before it.
* A reveal before its words makes the listener ask what the picture is.
* A reveal long after its words shows something the listener has already imagined.
Choose the phrase that names the thing as the cue phrase. The rest of the sentence then explains the thing while it is on screen.
## Start the cue phrase on the named thing
A cue time is the start of the first word of the cue phrase. Begin the phrase with the word that names the reveal.
```json cues.json theme={null}
{ "cue": "3.4steps", "on": "steps downhill" }
```
This cue starts on "steps", a verb, and the ball takes its first step as the word is said. A phrase such as "and then" names nothing on the slide. The starter's cue phrases are nouns that name something visible, such as `This is DeckTalk`, `what you will say`, `the slides`, `the formula`, and `in code`.
## Give each idea one reveal
Give each idea its own reveal, and give each reveal its own sentence. For a lesson, about one cue every ten to fifteen seconds is a comfortable rate.
* Three reveals in one breath look like an animation, not an explanation.
* A minute with no reveal gives the listener nothing new to look at.
If one sentence carries two ideas, split it into two sentences.
## Put silence before a reveal
A short silence before a reveal makes the reveal feel like an event. Three kinds of stage direction make that silence.
| Direction | Sent to the voice | Use it for |
| --------------------------------- | ----------------------------------- | ----------------------------------------------------- |
| `[beat]` | a dash after the sentence before it | Use it freely before a reveal. |
| `[pause N]` | a `` tag | Use it where you want the audience to stop and think. |
| Any other text in square brackets | a dash, the same as `[beat]` | Use it as a note to yourself. It also makes a beat. |
The starter puts a beat before each card, so each one arrives as its own event:
```md script.md theme={null}
This is DeckTalk. [beat] You write what you will say, [beat] and you write the slides that go with it.
[beat] Then every picture waits for its own word.
```
Only a timed pause sends a break tag, because frequent break tags make the voice less steady. Use timed pauses sparingly. Back-to-back directions do not add up, and the longest pause wins. [script.md](/reference/script-md) lists every direction rule.
DeckTalk adds silence before the first word and after the last word of every section, so the picture changes before the voice speaks. A script never needs a pause at either end.
## Shift a reveal with the offset key
The offset key moves a cue time by a number of seconds. A positive offset key moves it later, and a negative offset key moves it earlier.
```json cues.json theme={null}
{ "cue": "3.4steps", "on": "steps downhill", "offset": 0.2 }
```
* **A positive offset key, 0.1 to 0.2 s.** The reveal comes just after the word starts, while the word is still spoken. This feels like the narrator pointing at something. The example above moves the ball's first step 0.2 s after the start of "steps".
* **A negative offset key.** Use it only when the audience must read along, such as a line of code that the voice reads out. The text must be on screen before its first word is spoken.
The starter's cues have no offset key, so every reveal in a new project starts on its word.
## Close a section on \$end
The last reveal of a section can use `$end` as its cue phrase. `$end` is the end of the section's last spoken word, so a summary line appears as the voice stops.
To keep a section's last frame on screen after its narration ends, set `hold_seconds` on that page section. To open a section on a longer or a shorter silence, set its `lead_seconds`. [cues.json](/reference/cues-json) documents `$start` and `$end`.
## Write numbers as words
Write numbers, symbols, and abbreviations the way the voice must say them. A cue phrase must match the spoken words, and the voice can say digits in more than one way.
For example, write "two x" in the script and show `2x` on the slide. The starter's script says "decktalk dot AI", and its end card shows decktalk.ai. `decktalk narrate` reports a section whose spoken text still holds a digit or a symbol as `SPOKEN SYMBOL?`, an uncertain finding.
## Rehearse with a build without voice
A build without voice costs nothing and needs no key. Use it to check the pacing before you spend credits.
```console theme={null}
decktalk build --no-voice
```
* A build without voice estimates word times at `silent_words_per_minute` (150) and adds every declared pause.
* The click track has a soft click at every estimated word start, so you can hear the pacing.
* `decktalk verify` measures the picture against the clicks. [The a/v value](/reference/verify#the-a/v-value) explains that check.
Watch the video for pacing. A reveal that comes too early in a build without voice usually comes too early with the real voice too. [How it works](/concepts/how-it-works#the-build-without-voice) explains what a build without voice proves.
## Give a section a time budget
A time budget is a time range after a dash in a section heading. `decktalk narrate` compares the budget with the estimated length and, after a voiced build, with the real length.
```md script.md theme={null}
## 3. How AI learns — 0:40 to 1:40
```
This table comes from `decktalk narrate --dry-run` on the starter, with the section from
[Your first deck](/guides/first-deck) added and its heading budgeted `— 0:20 to 0:30`. The dry run calls no API.
```text theme={null}
# section words est target actual placeholders
---------------------------------------------------------------------
1 open 26 0:11 -- -- -
2 how-it-works 30 0:13 -- -- -
3 close 25 0:11 -- -- -
4 gradient-descent 100 0:43 0:10 -- -
---------------------------------------------------------------------
total 181 1:18 --
```
* `target` is the length of the budget, ten seconds for section 4.
* `est` paces the words at `words_per_minute` (140). Section 4 estimates 0:43, so it runs far past its budget.
* `actual` fills in after a voiced build.
* A section with no budget in its heading reads `--` in both columns.
If `est` is longer than `target`, delete a sentence. Widen the budget only after a voiced build fills the `actual` column.
A section's `min_seconds` in `cues.json` checks the other direction. If the speech is shorter than `min_seconds`, `decktalk align` reports an uncertain finding.
## Next
* **Copy a common slide:** [Slide recipes](/guides/slide-recipes)
* **Choose a cue phrase that matches:** [Cues](/concepts/cues#matching-rules)
* **Write your own section:** [Your first deck](/guides/first-deck)