Skip to main content
This guide writes one section of your own, from nothing, in the four files you write. Do it after the quickstart, in the my-lesson project it made. The starter holds sections 1, 2 and 3, and this adds a section 4 beside them. Nothing has to be deleted first. The section is deliberately small. The point is not the slide: it is the loop of writing a section, letting decktalk check tell you what is missing, and measuring the film afterwards.

​
How one section ties four files together

A section is one number written in four places, and one moment on a page named in two. cues.json owns when a cue fires and the page owns what a thing looks like and what it means. No attribute on the page says when a cue fires, and no row in cues.json says what a thing looks like. An element on a slide has four moments, each naming a cue local to that slide: data-in when it arrives, data-back when it steps back, data-front when it comes forward again, and data-out when it leaves. Write the cue name on the page and its cue id in cues.json: data-in="waits" inside <template data-slide="4.1"> is the cue id 4.1:waits.

​
Write the section

1

Add the words to script.md

Paste this at the end of script.md.
script.md
Each ## N. Title heading opens a section, and the number is what every other file refers to. The voice does not speak text in square brackets, so the line naming the scene is a note to yourself. [beat] is a short pause and [pause 3] asks the voice for three seconds of silence. script.md lists every rule, and Writing for the ear covers choosing words a picture can land on.
2

Add the section to decktalk.toml

Paste this after the last [[section]] table.
decktalk.toml
Every script section needs one [[section]] table with the same number, and the tables are read in order. page names the file and scene names the scene inside it that this section plays. chapter is the chapter title in the finished film. decktalk.toml lists every key.
3

Add the scene to deck/index.html

Paste this just before </body> in deck/index.html. It reuses the starter’s own classes, so it needs no new CSS.
deck/index.html
  • A [data-scene] wrapper is a scene and never draws anything itself. data-name is what the scene index calls it.
  • Each <template data-slide> inside it is one slide, cloned onto the stage when the slide mounts. data-preview-seconds is how long the preview rests on the slide, and no recording reads it.
  • An element with data-in stays hidden until that cue fires. The cue name is yours to choose, and it has to be unique within the slide.
  • data-describe says in one sentence what the moment shows. It is what the transcript reads and what a reviewer checks a reveal against, and a moment without one is reported.
  • Every element is placed absolutely on the canvas, so one thing arriving moves nothing else.
Declare a scene number one time per page. A second [data-scene="4"] wrapper replaces the first. The page contract covers the whole model, and decktalk schema page prints every attribute with their values, ranges and warning codes.
4

Add one cue row to cues.json

Add a "4" entry under "sections", with a row for the heading alone. The second moment is left out on purpose. Put a comma after the closing brace of section "3" first, because JSON separates one entry from the next with a comma.
cues.json
id is the cue id, 4.1:heading here. phrase is a word or short phrase from that section of script.md, matched with case and punctuation ignored, and occurrence picks which match when the phrase is said more than once. $start is the section start, $end is the end of speech, and offset_seconds shifts a cue by seconds. cues.json lists every key, and Cues explains the matching.

​
Let check find what is missing

decktalk check judges the written files and the pages before a build. It calls no API, it writes nothing a stage reads, and it prices what a voiced build would cost. A plain run also draws build/storyboard.html from the frames it freezes. Run it on the new section. --section 4 narrows it to the section you just wrote. --no-frames keeps the browser, which is what reads the moments the page declares, and drops the comparison of frozen frames, which is the slow part and not what finds a missing row.
It exits 1, because it found an error. The slide declares 4.1:waits and no row gives it a second, which is CUE_UNLISTED. The finding carries a safe fix, so --fix applies it.
The row is in the file. --fix writes it on one line as {"id": "4.1:waits", "phrase": ""},, and the block below lays it out like the rows around it:
cues.json
The fix writes the id, because DeckTalk knows the id, and leaves phrase empty, because the phrase is your line and not DeckTalk’s. The run reads the project again after the fix and reports the empty phrase as CUE_UNRESOLVED, so it still exits 1. Write the phrase and the section is complete.
cues.json
Nothing found, and it exits 0. The first line says the takes already on disk were not looked up, because no voice is named, and the last line is what voicing the section would cost.
Run decktalk check with no flags before a build. It opens the pages, freezes every slide either side of every cue, and reports a reveal too small to be measured, which is the judgement --no-frames drops. --fail-on warning also fails on a warning, and --allow CODE carries on past one code.

​
Build it and measure it

--no-spend uses estimated word times and a placeholder, so the new section costs nothing to try. Each placeholder is reported as TAKE_MISSING, a warning, so the build still exits 0. Its page records beside the other three, so a fourth section adds little to the time the build takes. verify runs as the last stage of a build, and it is also a command, so you can measure one section without building again.
Spoken is the second the cue phrase is said on the film’s clock. Shown is the second the picture was measured arriving in the encoded frames. Offset is the difference, and it is the product’s whole claim written as a number: both moments landed within a few hundredths of a second of their word. verify reports CUE_OFF and exits 1 when that difference is outside the limit, which is verify.cue_offset_max_ms. Verify defines every measurement it takes. Run decktalk verify with no scope to measure every section, every cut and every seam at once.

​
What to do next with it

  • Voice it. With a key in .env, decktalk check --json prices the narration and decktalk storyboard shows you what you are about to buy. Requirements and costs covers the ceiling.
  • Make the slide worth watching. Design a slide covers reveal styles, the camera and making a reveal large enough to be measured, and Slide recipes has patterns to copy.
  • Change one word and rebuild. Rebuild one section says which edit runs which stage again.