Skip to main content
The script is markdown with a few rules. Each ## N. Title heading starts section N, and the text under it is what the voice says for that section. Everything else on this page is how the text is cleaned before it is sent.
script.md

​
Headings

Text before the first numbered heading is never spoken, which is why the scaffold keeps its notes above a --- line. A section whose number maps to a clip in decktalk.toml is skipped by narrate, so its body can hold a stage direction that says what plays.

​
Directions and placeholders

A direction that stands before any prose in its section has nothing to pause after and is dropped. Two directions in a row keep the longest pause rather than adding them, and a beat beside a timed pause yields the timed pause. Silence before the first spoken section and after every section’s last word is added to the audio by ffmpeg rather than requested from the voice: lead_break_seconds opens the first section, and every section is padded so that speech ends at least min_tail_seconds, 0.7 by default, before the file does. direction_break_seconds is only the length a beat is assumed to take when a silent build estimates timings. All three are [narration] keys in Configuration.

​
Markdown stripping

The text is cleaned before it is sent, in this order.
  1. A link [text](url) becomes its text.
  2. A beat becomes a dash and a timed pause becomes a break tag, each appended to the paragraph before it.
  3. Inline code, bold, and emphasis lose their markers.
  4. Heading marks, list bullets, and list numbers at the start of a line are removed.
  5. Paragraphs are joined on single spaces, and blank lines separate them.
The cleaned text is what the voice receives. The spoken text, which cue matching and the captions reflect, has neither the dashes nor the tags, so a cue phrase should match the plain words. decktalk narrate --dry-run prints the exact text for each section with its pauses.

​
Length

The narrate table estimates each section at words_per_minute, which defaults to 140, and a silent build sizes its placeholder at silent_words_per_minute, which defaults to 150, plus every declared pause. As a rule of thumb, a section runs about 140 words per minute plus direction_break_seconds, 0.7 by default, per beat. Writing for the ear has the time-budget workflow.

​
Numbers and symbols

Write numbers and symbols the way you want them said, because the cue phrases in cues.json match spoken words. “two x” is a reliable cue and “2x” is not. The slide shows the symbols.