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 onloss 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 <break time="Ns" /> 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.
script.md
[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 lists every direction.
Trail the word, and lead it only when the audience must read
Theoffset 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.
cues.json
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 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 show2x 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 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 atwords_per_minute, which defaults to 140.
script.md
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.