What a viewer gets
- Every reveal starts on the word that names it, so a command appears as the voice says it and nothing on the slide is read ahead.
- The commands and the output on screen are the ones the project rendered on the day it was built, not the ones an author remembered while recording.
- Captions, chapters, a transcript page and a poster frame come out of the same build, so a viewer can read the walkthrough instead of watching it.
- A section that shows a terminal or an editor can be a video file of your own instead of a page, cut and mixed against the same narration.
What the author writes
Four files hold the whole tutorial.
A code slide is markup. An equation is a
data-tex attribute typeset by the KaTeX release DeckTalk
serves on the page’s own origin, so no equation needs a download. A reveal is a moment
attribute naming a cue local to its slide, so data-in="expand" inside
<template data-slide="4.1"> waits for the cue 4.1:expand, and cues.json is where that cue gets
a phrase. decktalk schema page prints every attribute with their values and ranges.
The workflow
1
Start a project
decktalk init my-tutorial writes a deck that already builds: three sections and one equation,
with the runtime and KaTeX served by the engine. It also writes six skills under
.agents/skills/, and an AGENTS.md when the directory has none. Add --no-skills to leave the skills out and --no-input to be asked
nothing.2
Judge it before you build it
decktalk check reads script.md, cues.json and the pages, freezes a frame either side of
every cue, and prints what the narration of a voiced run would cost. decktalk check --no-pages
does the same reading with no browser at all and names the judgements it could not reach.3
Draft it with no voice
decktalk build --no-spend runs the whole pipeline on placeholder narration, whose words are
timed by estimate at narration.placeholder_words_per_minute, so every cue still lands somewhere.
It spends nothing and needs no key, so the pacing is settled before anything is bought.
decktalk build --no-spend --to record stops once the pages are recorded, before the score and
the cut.4
Look at the storyboard, then buy the voice
decktalk storyboard freezes every slide at every cue onto build/storyboard.html, which is
the human checkpoint before anything is bought. Then decktalk build --spend voices the
sections that need it, and --max-cost N refuses the run before the first call if the most it
could cost is over N US dollars.5
Rebuild one section when the library changes
Edit the sentence, the slide or the cue, then run
decktalk build --section 4. A section whose
words did not change keeps its take, so it is never voiced twice.On a locked-down machine
A tutorial author inside a company meets two real conditions. A cloud speech service receives the script, and the first run that needs them downloads Chromium and ffmpeg. What leaves your machine names every host and every request body, and Requirements and costs covers the package index mirror, the browser path and the cache directory a managed machine needs.decktalk install fetches the toolchain up front
rather than in the middle of a build, and a build with --no-spend sends nothing to a paid speech
service, so a finished video can exist before any approval does.
Where to start
Read Quickstart for the first build and Your first deck for one section written end to end. Slide recipes has the slides a tutorial needs most, and Rebuild one section is the loop the whole use case rests on. Examples lists the finished projectsdecktalk init writes, and --example motion
shows a section that moves.