Skip to main content
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 the scaffold 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.
cues.json
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 scaffold’s cue phrases are nouns or verbs that name something visible, such as box of knobs, guesses, steps downhill, tensors, and Open source.

​
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. The scaffold’s lesson puts a beat before each step size, so each path starts as its own event:
script.md
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 lists every direction rule. DeckTalk adds silence before the first section and after the last word of each section. 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.
cues.json
The words "it steps downhill" from section 3 sit in boxes as long as each word. A line at the start of "steps" marks the cue time with offset key 0. An accent line 0.2 s later marks offset key 0.2. An arrow pointing earlier marks a negative offset key, for text read aloud.The words "it steps downhill" from section 3 sit in boxes as long as each word. A line at the start of "steps" marks the cue time with offset key 0. An accent line 0.2 s later marks offset key 0.2. An arrow pointing earlier marks a negative offset key, for text read aloud.

A positive offset key moves the cue time after the start of its word.

  • 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 scaffold’s cues have no offset key, so every reveal in the scaffold 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 silence, set lead_seconds. 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 scaffold’s script says “decktalk dot app”, and the slide shows decktalk.app.

​
Rehearse with a silent build

A silent build costs nothing and needs no key. Use it to check the pacing before you spend credits.
  • A silent build 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 explains that check.
Watch the video for pacing. A reveal that comes too early in a silent build usually comes too early with the real voice too. How it works explains what a silent build 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.
script.md
This table comes from decktalk narrate --dry-run on the scaffold with that heading. The dry run calls no API.
  • target is the length of the budget, one minute for section 3.
  • est paces the words at words_per_minute (140). Section 3 estimates 2:02, so it runs past its budget.
  • actual fills in after a voiced build.
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 beats reports an uncertain finding.

​
Next