# AGENTS.md
Source: https://docs.decktalk.ai/agents/agents-md

The short file that tells any coding agent it is standing in a DeckTalk project.

`AGENTS.md` is a plain Markdown file that a coding agent loads at the start of every session. It is
stewarded by the Agentic AI Foundation, and Codex, Cursor, Copilot, VS Code, Zed, Aider and many
others read it. It is the one agent surface that costs context in every session, so it stays short.

`decktalk init` writes a ten-line `AGENTS.md` when the project has none. It never overwrites one
that is already there, so a project with its own `AGENTS.md` keeps it.

## What DeckTalk writes

The generated file says four things and stops.

* This folder is a DeckTalk project.
* The four input files are `script.md`, `decktalk.toml`, `cues.json` and the deck page.
* `decktalk status --json` is the first command to run, because it reports what the four files say,
  what is built and what is stale.
* The skills are in `.agents/skills/`, and they hold the procedures.

Procedures do not belong in `AGENTS.md`. A procedure that is loaded in every session is paid for in
every session, and the skills exist so that an agent loads a procedure only when it needs one. Keep
`AGENTS.md` to orientation, and put the steps in a skill.

## Adding DeckTalk to an AGENTS.md you already have

Add the same four lines to your own file under a heading of their own, and leave the rest alone. The
file is read as plain Markdown, so a heading and a short list are enough.

## Harnesses that read a different file

Claude Code reads `CLAUDE.md` rather than `AGENTS.md`. The usual arrangement is a `CLAUDE.md` whose
whole content is a reference to `AGENTS.md`, so one file stays the source. Gemini CLI reads
`GEMINI.md` by default and reads `AGENTS.md` when its context file setting names it.

`AGENTS.md` also serves a harness that reads no skills at all. For that harness it is the only
DeckTalk instruction in the session, which is why it names `decktalk status --json` rather than
describing the pipeline.


# Install the skills
Source: https://docs.decktalk.ai/agents/install

Where the skills land, which folders each coding agent reads, and what DeckTalk has actually tested.

`decktalk init` installs the six skills into a new project by default. Pass `--no-skills` to leave
them out.

```console theme={null}
decktalk init my-video
```

## The folders

The skills are written once, into one generic folder, and a second folder points at it.

| Path                                      | What it is                                                                                      |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `.agents/skills/decktalk-<name>/SKILL.md` | The skills themselves, in the folder the Agent Skills format names for sharing between clients. |
| `.claude/skills`                          | A link to `.agents/skills`, because Claude Code reads its own folder and not the generic one.   |

On a machine where a link cannot be made, which is usually Windows without the privilege for one,
`init` writes a copy instead of a link. The copy holds the same files, and it has to be written
again when the skills change.

Do not commit a second copy of a skill under another name. Several harnesses read both folders, and
two copies of one skill is the case where a harness has to guess.

## Which harness reads which folder

Every harness below loads a `SKILL.md` natively. The folders are the ones each harness documents for
a project.

| Harness                    | Project folders it reads                                  |
| -------------------------- | --------------------------------------------------------- |
| Claude Code                | `.claude/skills/`                                         |
| OpenAI Codex               | `.agents/skills/`                                         |
| Cursor                     | `.agents/skills/`, `.cursor/skills/`, `.claude/skills/`   |
| GitHub Copilot and VS Code | `.github/skills/`, `.claude/skills/`, `.agents/skills/`   |
| Gemini CLI                 | `.gemini/skills/`, `.agents/skills/`                      |
| Windsurf                   | `.windsurf/skills/`, `.agents/skills/`                    |
| opencode                   | `.opencode/skills/`, `.claude/skills/`, `.agents/skills/` |
| Amp                        | `.agents/skills/`, `.claude/skills/`                      |
| Goose                      | `.agents/skills/`, `.goose/skills/`, `.claude/skills/`    |

The two folders that `init` writes reach every harness in that table. `.agents/skills/` reaches
eight of them, and `.claude/skills` reaches Claude Code, which is the one harness that does not read
the generic folder.

<Warning>
  DeckTalk tests its skills on Claude Code alone. The release test is a trigger run over Claude Code
  and a build made from the skills alone. Every other harness in the table is supported through the
  generic folder and is untested, because the founder does not run it. A skill that misfires on
  another harness is worth a GitHub Discussions post, and it is not a case DeckTalk can reproduce.
</Warning>

## Why the skills use no harness-specific fields

DeckTalk skills use only the fields the open format defines, which are `name`, `description`,
`license`, `compatibility` and `metadata`. Several harnesses add fields of their own, and a field
that one harness honours and another ignores gives one skill two behaviours. Some services also
reject a skill whose front matter carries a key they do not know.

The cost of that choice is that no front-matter field can mark a skill as user-only, so the guards
against spending live in the skill text and in the CLI. [Agent skills](/agents/skills) lists them.

## Install the skills without installing DeckTalk

The repository carries a `skills` folder at its root that points at the same files, so a generic
skill installer can read the skills straight from the repository before DeckTalk is on the machine.
The skills drive a CLI, so they are only useful once that CLI exists.


# The JSON contract
Source: https://docs.decktalk.ai/agents/json

The one envelope every command prints under --json, the finding rows inside it, and what each exit code means.

Every DeckTalk command takes `--json`. Under that flag a command prints exactly one object on
stdout, prints nothing else on stdout, turns colour off and sends every log line to stderr. An
error prints the envelope too. This page is the short contract an agent needs. The per-command
payloads are in the [CLI reference](/reference/cli).

## The envelope

| Field       | Type             | Meaning                                                                                                                         |
| ----------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `schema`    | integer          | The envelope's shape version, which changes only when the shape changes. It is not the product version.                         |
| `version`   | string           | The installed DeckTalk version.                                                                                                 |
| `command`   | string           | The command as typed, with a subcommand joined by one space.                                                                    |
| `ok`        | boolean          | True when the command found nothing and raised nothing. It ignores `--exit-zero`.                                               |
| `exit_code` | integer          | The code the process is about to return, so a caller that lost the code can still read it.                                      |
| `summary`   | object           | A small object of counts and totals that leads the output. Its keys are the command's own.                                      |
| `findings`  | object           | `{"certain": n, "uncertain": n, "items": [...]}`.                                                                               |
| `written`   | array of strings | Every file the command wrote, as project-relative POSIX paths, in the order written. A read-only command writes an empty array. |
| `error`     | object or null   | Null on success and on a finding. On an error it carries `code`, `message`, `hint` and `path`.                                  |
| `<command>` | object           | The command's own payload, under the first word of the command name.                                                            |

## A finding row

Every row of `findings.items[]` has the same shape on every command, so an agent can dispatch on the
rows alone without reading the per-command payload.

| Key       | Type            | Meaning                                                                                                |
| --------- | --------------- | ------------------------------------------------------------------------------------------------------ |
| `code`    | string          | The verdict or reason code, such as `SPEECH_AT_CUT`. Dispatch on this.                                 |
| `label`   | string          | The human label, such as `SPEECH AT CUT`. Nothing parses it.                                           |
| `certain` | boolean         | True when the finding is certain.                                                                      |
| `section` | integer or null | The section number.                                                                                    |
| `cue`     | string or null  | The cue id.                                                                                            |
| `where`   | string or null  | The file, the page or the artifact the finding is about, as a project-relative path when it is a file. |
| `detail`  | string or null  | One sentence of detail, with any measured number in it.                                                |

A row that judges nothing carries the passing code `NOTE`, so `code` and `label` are strings on
every row and a reader never meets a null code.

## An error

The `error` object is filled by whatever raised the error, so a slot it does not know is null.

| Key       | Meaning                                                                       |
| --------- | ----------------------------------------------------------------------------- |
| `code`    | One of `CONFIG`, `MISSING_INPUT`, `PROVIDER`, `TOOL`, `USAGE` and `INTERNAL`. |
| `message` | One sentence. It never carries the value of a secret.                         |
| `hint`    | The smallest next action, or null.                                            |
| `path`    | The project-relative file the error is about, or null.                        |

In text mode the same error prints as `error[CONFIG]: ...` on stderr, so the code is readable
without `--json`.

## Exit codes

| Code | Meaning                                                                                               | How to tell                                                                   |
| ---- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 0    | The command ran and found nothing, or `--exit-zero` was passed.                                       | `ok` is true, or `exit_code` is 0 with findings present.                      |
| 1    | The command ran and found something, which is a certain finding or an uncertain one under `--strict`. | `error` is null and `findings.certain` or `findings.uncertain` is above zero. |
| 2    | A usage error from the parser, such as an unknown command, an unknown flag or a bad value.            | `error.code` is `USAGE`.                                                      |
| 3    | DeckTalk itself could not run.                                                                        | `error` is not null and `error.code` names the error class.                   |
| 130  | The run was interrupted. The process was signalled, and no envelope is promised.                      | There is no envelope to read.                                                 |

The rule an agent follows is one line. A non-zero exit with `error` null is a finding, and the agent
may fix the project and run the command again. A non-null `error` is an error, and the agent stops
and tells the person.

Write the trigger as `error == null` rather than as "exits 1", because a broken machine can exit
non-zero for reasons that are not the project's fault.

## Watching a build

`decktalk build` appends one JSON Lines object per event to `build/progress.jsonl`, relocatable with
`--progress`. Each row carries `ts`, `stage`, `stage_index`, `stage_count`, `section`, `event`,
`detail` and `pid`, and `event` is one of `start`, `done`, `skip` and `fail`.

Poll `decktalk status --json` rather than tailing that file. Its `run` object is null when no build
is running, and otherwise carries `pid`, `started`, `stage`, `sections_done`, `sections_total` and
`alive`.

## Reading what a project has

`status.narration` is the narration clock that `build/narration/takes.json` gives: `exists`,
`estimated`, `total_seconds`, and one `sections[]` row per spoken section with `key`, `title`,
`start`, `end` and `duration`. `estimated` is true while the takes are placeholders a run without
voice wrote.

Each `status.sections[]` row carries `key`, `kind`, `source`, `recorded`, `cut` and `stale`. `stale`
is null while the recording on disk still matches the project, and otherwise one sentence saying why
it does not, which is the same rule `record` uses to decide what to record again.


# Agent skills
Source: https://docs.decktalk.ai/agents/skills

The six packaged skills that teach a coding agent to write, build and repair a DeckTalk video.

DeckTalk ships six agent skills. A skill is a folder with a `SKILL.md` file, written in the Agent
Skills open format, that a coding agent loads when a task matches its description. The skills turn
the CLI into something an agent can drive on its own, and they carry the rules that a person would
otherwise learn from these docs.

The skills live inside the Python package, so every installation carries the skills that match its
own CLI. `decktalk init` writes them into a new project, and
[Install the skills](/agents/install) covers the folders they land in.

## The six skills

| Skill             | It starts when                                                                                                                                                                                                                                    | It ends with                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `decktalk-script` | someone asks for a new narrated video, explainer, tutorial, product demo or lesson, adds a section, or changes what the voice says.                                                                                                               | `script.md` written to a time budget, with a table of every spoken phrase and the symbols it stands for.      |
| `decktalk-slide`  | a narrated video needs a new slide or scene, when maths or code has to appear on screen, when a picture must be added to an existing section, or when a reveal is too small, overlapping or off frame.                                            | Markup that obeys the page contract, checked against the PNGs that `decktalk screenshots` writes.             |
| `decktalk-cues`   | a script, a page or a reveal changes, when align reports an unresolved or unknown cue, when a picture appears early, late or not at all, or when a reveal is too small for the checker to see.                                                    | Every `data-cue` matched to `cues.json` in both directions, with the gaps inside their thresholds.            |
| `decktalk-build`  | someone asks to build, render, export, preview or check a narrated video, an explainer, a tutorial or a lesson, or after any edit to script.md, cues.json, decktalk.toml or a deck page.                                                          | A verified build, with the frames shown to you before the work is called done.                                |
| `decktalk-fix`    | preflight, align, record, verify or build exits non-zero with error set to null, when a cue is unresolved or unknown, when a reveal lands off cue or shows no change, when a recording stalls or starts black, or when preflight skips every cue. | The smallest edit that clears the finding, and the failing command run again with `--only`.                   |
| `decktalk-revise` | someone says a demo, tutorial, explainer or lesson is out of date, asks for this week's update, or names a release that changed what the video claims.                                                                                            | The fewest edits, a build of the changed sections alone, and a change note with the sections and the dollars. |

## What the skills will not do on their own

The skills are written so that an agent cannot spend your money or hide a failure.

* A voiced run stops and asks. `decktalk-build` reports the sections a voiced run would voice, their
  characters, the dollars and the host, and then waits for your approval.
* No skill passes `--force`, `--exit-zero` or an `--allow-` flag, and no skill turns `verify` off.
* No skill edits the `[voice]` table without asking.
* `decktalk-fix` reads `findings.items[]` and fixes the project. On exit code 3 it stops and reports
  the error to you, because exit code 3 means DeckTalk itself could not run.

No portable field in the skill format stops a model from starting a skill on its own, so these
guards live in the skill text and in the CLI rather than in front matter.

## The other two agent surfaces

A skill is not the only thing to hand an agent.

* [The reference card](/reference/card) puts every file, command, rule and exit code on one page.
  Hand it to an agent that has no skills loaded.
* [`llms.txt`](https://docs.decktalk.ai/llms.txt) indexes every page on this site, and
  [`llms-full.txt`](https://docs.decktalk.ai/llms-full.txt) is the whole site as one file. Hand
  those to an agent that can fetch a URL.
* [The JSON contract](/agents/json) is what an agent reads back after every command.

DeckTalk ships no MCP server. The CLI with `--json` and its exit codes is the machine interface, and
the skills teach an agent to use it.


# Changelog
Source: https://docs.decktalk.ai/changelog

See what changed in each DeckTalk release, including the file formats and the page contract.

This page lists every DeckTalk release, newest first. DeckTalk follows semantic versioning.

A change to a file format or to the page contract raises the minor version. The file formats are
`decktalk.toml`, `cues.json`, and the build artifacts.

A project keeps the `deck/decktalk-runtime.js` it was created with. To move a project onto a newer
runtime, create a new project with the new DeckTalk and copy the deck pages across.

<Update label="0.4.0" description="2026-09-19">
  **⚠ BREAKING CHANGES**

  * **verdicts:** give the three counted judgements verdicts of their own

  * **cli:** wire --from and --to, retire measure and check, and report a stale recording

  * **narrate:** fold the narration clock into the take index, with a lead and a tail per take

  * **cli:** make the CLI a package that prints one envelope and one exit code

  * **assemble:** split the stage into cut, mix, loudness and publish, and write what a viewer needs

  * **verdicts:** make an unparsed or missing KaTeX a certain finding

  * **record:** fold measure and check into one record package

  * **narrate:** identify a take by its content and price the plan before it runs

  * **align:** check cues and pages against each other in both directions

  * rename the vocabulary for 0.4.0

  * **narrate:** fold the narration clock into the take index, with a lead and a tail per take ([5a6120a](https://github.com/jacobcbeaudin/decktalk/commit/5a6120a213de7d70ab0190bcc20c4afa65e59152))

  * rename the vocabulary for 0.4.0 ([6b2a9fe](https://github.com/jacobcbeaudin/decktalk/commit/6b2a9fe552a88d86fa278d0e2ba073d53fb4c4ce))

  **Features**

  * **align:** check cues and pages against each other in both directions ([7fd3603](https://github.com/jacobcbeaudin/decktalk/commit/7fd3603adb22b84c7e8423cdabc8598915a01e61))
  * **api:** export the cut list reader ([6b81600](https://github.com/jacobcbeaudin/decktalk/commit/6b81600b635cc23619bb16065436c66d22be12c4))
  * **assemble:** split the stage into cut, mix, loudness and publish, and write what a viewer needs ([5dccf25](https://github.com/jacobcbeaudin/decktalk/commit/5dccf25299eebc633e1b1841f6655a2029a607db))
  * **build:** run the real verify last, and write a progress log an agent can read ([1ad53a9](https://github.com/jacobcbeaudin/decktalk/commit/1ad53a90f7b5362b9745910df0dd3b7b19b79aba))
  * **cli:** make the CLI a package that prints one envelope and one exit code ([ee6bd9b](https://github.com/jacobcbeaudin/decktalk/commit/ee6bd9b4003bf46de2d8399d80a3828fff645110))
  * **cli:** wire --from and --to, retire measure and check, and report a stale recording ([2289630](https://github.com/jacobcbeaudin/decktalk/commit/22896304be59b31a784ad2d679ea177be65d75ea))
  * give every stage one result and enforce the five layers ([f51ba4d](https://github.com/jacobcbeaudin/decktalk/commit/f51ba4dce71bdb75ce55432e44a22b961c4ac3ae))
  * **media:** fetch a pinned, SHA-256 verified ffmpeg build in place of static-ffmpeg ([ba8be62](https://github.com/jacobcbeaudin/decktalk/commit/ba8be627bb2a85d44f34badbb92c3339422cefc7))
  * **media:** serve every page from a local origin, and add decktalk serve ([dc238f5](https://github.com/jacobcbeaudin/decktalk/commit/dc238f54b5b5ec501243073ef94e8a8c9b095f5d))
  * **narrate:** identify a take by its content and price the plan before it runs ([0ac39c4](https://github.com/jacobcbeaudin/decktalk/commit/0ac39c44b11f228d5c90c0db7c20a0a7154c9225))
  * **providers:** keep the ElevenLabs key on an https ElevenLabs host ([5d3b94d](https://github.com/jacobcbeaudin/decktalk/commit/5d3b94ddad1b9e67ec25765936a0fed9fb64dfa6))
  * **record:** fold measure and check into one record package ([b02e56b](https://github.com/jacobcbeaudin/decktalk/commit/b02e56b8d77de9d101f43e8989df59a135bc99c2))
  * **record:** keep a section whose scene, assets, words and cues are unchanged ([bf371fa](https://github.com/jacobcbeaudin/decktalk/commit/bf371fa15cde9ffdebdcf956cf93cfaefc121abf))
  * **runtime:** rebuild the page runtime on markup slides and close the first-frame race ([39aab42](https://github.com/jacobcbeaudin/decktalk/commit/39aab42498a62c711652acb08b2e9bf0d6ac3865))
  * **runtime:** write each reveal's description on the cue log row the transcript reads ([fe107ee](https://github.com/jacobcbeaudin/decktalk/commit/fe107ee4efc76f72bba27d232e83480251ddd489))
  * **scaffold:** make init write a small starter, an example, the skills and AGENTS.md ([fcea3e8](https://github.com/jacobcbeaudin/decktalk/commit/fcea3e83643ae0fc407ef314fc6c5ee02fc2b88e))
  * **scaffold:** ship KaTeX inside the wheel ([cbcad35](https://github.com/jacobcbeaudin/decktalk/commit/cbcad3544d7021393cfbdaf6c507b8681a27b1a7))
  * **screenshots:** give every written PNG a row, and add --json ([93cb221](https://github.com/jacobcbeaudin/decktalk/commit/93cb2212d3844fe0c951a07ff4c2e72327f7974d))
  * **scripts:** check every internal docs link and the navigation ([21c8a63](https://github.com/jacobcbeaudin/decktalk/commit/21c8a631ef39778ad76c37f327fce4d5536f502d))
  * **skills:** ship the six skills an agent works from, and a test that keeps them true ([b237a47](https://github.com/jacobcbeaudin/decktalk/commit/b237a47fdc09438e1c6929219f5d766dc2a88be7))
  * **status:** read the four input files against each other, and report the run ([b8c9298](https://github.com/jacobcbeaudin/decktalk/commit/b8c92985be3f622fe9bd4034cec839c1152648ed))
  * **verdicts:** give the three counted judgements verdicts of their own ([5a7ed81](https://github.com/jacobcbeaudin/decktalk/commit/5a7ed8198bda15d318540ebb1f8bf13ca8c1995a))
  * **verdicts:** make an unparsed or missing KaTeX a certain finding ([7eec66c](https://github.com/jacobcbeaudin/decktalk/commit/7eec66cff8043e3693ef61969b21f7f91274ddb6))
</Update>

<Update label="0.3.0" description="2026-09-15">
  **Features**

  * **beats:** warn when a cue phrase occurs more than once in its section ([1174081](https://github.com/jacobcbeaudin/decktalk/commit/1174081fd0a1f49c855c779f9123fe9615cf2b55))
  * **clip:** add decktalk clip and decktalk words ([846de9f](https://github.com/jacobcbeaudin/decktalk/commit/846de9f4f857f8d1621875f232b0ed9ff1f856bb))
  * **narrate:** add lead\_seconds and tail\_seconds, and allow hold\_seconds on any page section ([ce4baf9](https://github.com/jacobcbeaudin/decktalk/commit/ce4baf9b0006a8489d8ea9efc8fbbb55f51b2105))
  * **narrate:** print the take plan in a dry run, and add --json ([bd34f89](https://github.com/jacobcbeaudin/decktalk/commit/bd34f890c8515d0ce969f762ba46d9f39332336e))
  * **preflight:** check a voiced build before it spends credits or records ([6af0507](https://github.com/jacobcbeaudin/decktalk/commit/6af050748dd21332306bac1cbeb0bfa96445207d))
  * **runtime:** list each step's cues in the catalog, and freeze just before a cue ([fe329dd](https://github.com/jacobcbeaudin/decktalk/commit/fe329ddc1c2678314d3a3ecee5dc52b937632ab4))
  * **verify:** check that the cut into a carries\_previous section does not pop ([91e6578](https://github.com/jacobcbeaudin/decktalk/commit/91e6578a842f8cd3db1d929751597cb9d88dd251))
  * **verify:** mark a cue that passes by a thin change as THIN CHANGE? ([ffc09b6](https://github.com/jacobcbeaudin/decktalk/commit/ffc09b64f948c3e94f654999e55d28560215778c))

  **Bug Fixes**

  * **assemble:** warn about a recording that measure has not read ([95896c0](https://github.com/jacobcbeaudin/decktalk/commit/95896c01f38cf80c075fd8c93c1157867b79abb5))
  * **narrate:** refuse a silent run over voiced takes unless forced ([6517ebc](https://github.com/jacobcbeaudin/decktalk/commit/6517ebccf5629812ab1d0c938a4797515f6ab7db))
  * **narrate:** stop padding a cached take again on every run ([93d643a](https://github.com/jacobcbeaudin/decktalk/commit/93d643ac7f3ad772c20534a0850eee3e59c9c9e9))
  * **verify:** count only the sections in decktalk.toml ([32112eb](https://github.com/jacobcbeaudin/decktalk/commit/32112ebd8686f6b2a82efd1606ed6630f5d26fa0))
  * **verify:** fit probes and controls between close cues ([f4dee0e](https://github.com/jacobcbeaudin/decktalk/commit/f4dee0ea54372c0e2e8f025a50708737901ce39b))
</Update>

<Update label="0.2.1" description="2026-09-14">
  **Features**

  * **assemble:** caption the speech inside a clip section from its words file ([cf5b938](https://github.com/jacobcbeaudin/decktalk/commit/cf5b9388866a669d85c538cb3250ceb5cc1bd6c5))
  * **captions:** break captions at sentence ends ([3a7df4c](https://github.com/jacobcbeaudin/decktalk/commit/3a7df4cbc470defc7a2d6460d72dc1ddbd36df82))
  * **chapters:** merge consecutive sections with the same title into one chapter ([0191f1b](https://github.com/jacobcbeaudin/decktalk/commit/0191f1b17cdf6d4bd4dfcb753f1b59ba227d5025))
  * **narrate:** keep a renumbered section's take by copying it to the new name ([41ced3f](https://github.com/jacobcbeaudin/decktalk/commit/41ced3ff188c1e4db83f5341289eeed37bc24b93))
  * **template:** port the approved demo film's lesson into the scaffold ([0f5332a](https://github.com/jacobcbeaudin/decktalk/commit/0f5332a8d6cd31d8c1131f6bf3471e83ddaac516))
  * **template:** port the v16 demo film's edit into the scaffold ([a530783](https://github.com/jacobcbeaudin/decktalk/commit/a530783abd2f52924457929dc95711589d89da93))
</Update>

<Update label="0.2.0" description="2026-09-14">
  **Features**

  * a demo deck built to a fifteen-person review, with a WebGL loss surface ([148e59f](https://github.com/jacobcbeaudin/decktalk/commit/148e59f0dbdacd6c94de9ae58e3a6b0fa802d148))
  * captions, chapters, measured cue offsets, and a loudness pass that hits its target ([27a8c1d](https://github.com/jacobcbeaudin/decktalk/commit/27a8c1d77ea1d38a477cf27e8123f0030dc83003))
  * close on "Update your video the way you update a doc." ([339dfe9](https://github.com/jacobcbeaudin/decktalk/commit/339dfe990cda887f0063b16cb60ff2f753340bce))
  * closing scene, a cut check in verify, and a cover that survives a late capture ([b1e1cdd](https://github.com/jacobcbeaudin/decktalk/commit/b1e1cdd5bf46637530a50f65009fe3c114e5abf0))
  * demo deck after the round-two design and content review ([1c5e44c](https://github.com/jacobcbeaudin/decktalk/commit/1c5e44cbe724e37bf0650708a069c7d4928ab2f2))
  * demo v10, the storytelling panel's rewrite of all five scenes ([8754f83](https://github.com/jacobcbeaudin/decktalk/commit/8754f83aff96f5791be69449c260a21a1339aa2c))
  * demo v11, a lay lesson on how AI learns, with a slot for B-roll ([dd9147e](https://github.com/jacobcbeaudin/decktalk/commit/dd9147ee93be0a0a6d08aea5123733a417278c38))
  * **demo:** a ball walks the too-long and too-short paths as their markers appear ([e25bade](https://github.com/jacobcbeaudin/decktalk/commit/e25bade3033a011d055280343753924b9a6d24a2))
  * lesson-shaped scaffold, vendored KaTeX, pause directions, and page warnings ([5ee46a8](https://github.com/jacobcbeaudin/decktalk/commit/5ee46a8f27898a76d403b8d511ca53e93698d8b2))
  * machine-readable output and one exit policy for the read-only commands ([393cbf8](https://github.com/jacobcbeaudin/decktalk/commit/393cbf8e109c2b7bce761c3a1695863dc3dcdad4))
  * pass the slide and cue context to handlers, freeze at one cue, and warn on unreachable reveals ([675894d](https://github.com/jacobcbeaudin/decktalk/commit/675894d153dccfd635580991f86edad5dac83e46))
  * play a clip between page sections, with the narration paused around it ([e884b29](https://github.com/jacobcbeaudin/decktalk/commit/e884b293551db437c0a485f79af5e47c2d10f98d))
  * **record:** log when each cue was due, ran, and drew in the sidecar ([a9a25b3](https://github.com/jacobcbeaudin/decktalk/commit/a9a25b3801ada0e5be8c0d9c881f8b8743d99247))
  * **record:** pass the previous section's words as prevwords, so scene 2 carries the Open's real count times ([04cb547](https://github.com/jacobcbeaudin/decktalk/commit/04cb547cdc315054c974d943c36d90ef68ff2320))
  * refine the graphics and adopt the four-tick mark ([142f511](https://github.com/jacobcbeaudin/decktalk/commit/142f511310a7b31ea04459fbcbfb77512f93d928))
  * show the function before naming it in the demo, and close on decktalk.app ([f9f251f](https://github.com/jacobcbeaudin/decktalk/commit/f9f251fd804f7d3b1022deb28aea3c2cb3c09955))
  * **site:** host the demo video with the homepage ([fecdfa2](https://github.com/jacobcbeaudin/decktalk/commit/fecdfa2dcc0762e282f5fc87172ef2487c8ca8e4))
  * social card, README rebuilt around the lesson scaffold, and limiter headroom ([2a4a93b](https://github.com/jacobcbeaudin/decktalk/commit/2a4a93bd0fa183b40aae22787bec5fe32233d0b8))
  * teach the learning rate honestly in the demo's gradient descent scene ([0b8a958](https://github.com/jacobcbeaudin/decktalk/commit/0b8a95883617a28c1eb74c6f46118c58910696f0))
  * **template:** open the lesson on its title and bring in the rules card on "rules" ([e596540](https://github.com/jacobcbeaudin/decktalk/commit/e596540019a6e7340e332a1d80dd9d87a06c254e))
  * **template:** scaffold the v12 demo film ([ce17e25](https://github.com/jacobcbeaudin/decktalk/commit/ce17e256ee1b59fcdb1b0463acd8216fc221510e))
  * verify every cue by default, catch unknown cue ids, and keep clips at the edges ([bd6c236](https://github.com/jacobcbeaudin/decktalk/commit/bd6c2365ca3d1691ff71705dbba5a05ff4a2fbc4))

  **Bug Fixes**

  * accept -v and -q after the command, export result types, and report unexpected errors cleanly ([ffd86ad](https://github.com/jacobcbeaudin/decktalk/commit/ffd86ad00fd9878b7c28bb3998319612e0767952))
  * captions keep the script's punctuation and the onset scan sees low-contrast reveals ([24357b7](https://github.com/jacobcbeaudin/decktalk/commit/24357b7a5ed10fcb1a984c8629f47b7be87abf3a))
  * count only the part of a frame stall that falls after narration starts ([1be18ee](https://github.com/jacobcbeaudin/decktalk/commit/1be18eebae076cd8f89df37cb3ddc477c339046b))
  * cover the page until the clock starts so a cut cannot miss the marker ([f33a2d9](https://github.com/jacobcbeaudin/decktalk/commit/f33a2d94c3872ad932798395d05904ad9c1038dc))
  * define gradient descent before the surface appears, and hand off once at the edit ([1b25627](https://github.com/jacobcbeaudin/decktalk/commit/1b25627b091a0553435b9cc5e6eb041b454b106f))
  * exact frame seeks on every ffmpeg build, and sidecars that explain synced reveals ([2499312](https://github.com/jacobcbeaudin/decktalk/commit/249931205f61c076273fc997338c5e0748402aef))
  * fail check on a page error, warn on bad TeX and dead cues, ease the ball steps out, and keep doctor from downloading ([171f4bf](https://github.com/jacobcbeaudin/decktalk/commit/171f4bf654c0a88fa6c10f01c692cb69862ce111))
  * **narrate:** pad cached takes to min\_tail\_seconds ([df93b08](https://github.com/jacobcbeaudin/decktalk/commit/df93b087172e56ee098f6e034507539dc5023c40))
  * print a skipped verify row's reason once ([2cf727d](https://github.com/jacobcbeaudin/decktalk/commit/2cf727d38d4787a5fbcf00764f018d36f00422f1))
  * quote scene 3's real length in the edit scene and give the close a beat ([7f368cc](https://github.com/jacobcbeaudin/decktalk/commit/7f368cc999818551585a8da4f62e27a436c763c2))
  * read and write every text file as UTF-8, so init works on Windows ([645aebc](https://github.com/jacobcbeaudin/decktalk/commit/645aebc79fe183cc6dc3b8898fabe14ac4468874))
  * **record:** keep frames flowing after the cover so still pages record reveals on time ([0abcf45](https://github.com/jacobcbeaudin/decktalk/commit/0abcf4532d7ec8b1254e6e795355e95d40beeb5c))
  * report unknown cue ids from beats instead of stopping before the table ([63208b9](https://github.com/jacobcbeaudin/decktalk/commit/63208b98518df26d254ab07df8675b5da4c9cef7))
  * **runtime:** draw the preview index in the page's own colors ([5eec565](https://github.com/jacobcbeaudin/decktalk/commit/5eec565d761f7a0e0265e90c0f56a7dd8f6d0c2f))
  * say the thesis once in the demo deck ([a677391](https://github.com/jacobcbeaudin/decktalk/commit/a677391b3d7b10f52c02474ecca54370f241046e))
  * start the clock on the next frame, detect and retry stalled recordings, and make frame comparisons build-proof ([91cd81c](https://github.com/jacobcbeaudin/decktalk/commit/91cd81c3de6846ae0f338a8875447870994d1d8f))
  * timeline positions from decoded audio, word-synced reveals, a click test for sync, and a scaffold that teaches gradient descent ([9b38bc2](https://github.com/jacobcbeaudin/decktalk/commit/9b38bc23cfb177853e4e283c6a84c681057ae541))
  * trim the scanned span per stream so the looped reference frame is not seeked past its end ([028c845](https://github.com/jacobcbeaudin/decktalk/commit/028c84501cc976655cb8e3250f2cb2c5d6b11e97))
  * **verify:** compare luma only, so a static colored frame reads zero ([d74bdc6](https://github.com/jacobcbeaudin/decktalk/commit/d74bdc6ca2f7b9f1a3e8a5ec0e8b680344ead6ac))
  * **verify:** confirm each onset on 8 by 8 blocks, so encoder ringing never reads as an early reveal ([8e9887a](https://github.com/jacobcbeaudin/decktalk/commit/8e9887afa7a48b9961b83b98c175ab571b66806f))
  * warm every scene 3 mesh so no cue freezes the page on its first draw ([938f9a3](https://github.com/jacobcbeaudin/decktalk/commit/938f9a3637f2a90756e176e1185c3844f755f485))
  * warm the scene 3 figure at its real drawing state before narration starts ([90807c4](https://github.com/jacobcbeaudin/decktalk/commit/90807c4cdd8844a67690a93edc1f4cb41822862f))
  * warn on unknown decktalk.toml keys, let doctor pass without KaTeX, and add optional clip sections ([dcc4dbf](https://github.com/jacobcbeaudin/decktalk/commit/dcc4dbf1bcdee7327d38fb57107c1074fbaf25cc))
  * warn when a step mounts equations without KaTeX in cue mode ([2005a4a](https://github.com/jacobcbeaudin/decktalk/commit/2005a4a30b5e57336c1bc3fa87cc4532326525b5))
</Update>

<Update label="0.1.0" description="2026-09-12">
  First release. DeckTalk turns a markdown script, plain HTML slides, and an ElevenLabs
  voice into one mp4 in which every reveal lands on the word that introduces it. It records
  the slides in headless Chromium, cuts each section to the narration frame-exactly, mixes an
  optional soundscape, normalizes loudness, and verifies the result. Chromium and ffmpeg
  arrive through Python packages, and `--silent` renders a full draft without an API key.
</Update>


# Cues
Source: https://docs.decktalk.ai/concepts/cues

Learn how a cue phrase in cues.json becomes a cue time, and what happens when a cue and its page disagree.

A cue connects a spoken phrase to something that happens on a page, such as an element that
appears. Read this page when you choose a phrase, or when a cue does not resolve or starts on the
wrong word. [Writing for the ear](/guides/writing-for-the-ear) is the guide for writing phrases.

The starter's section 1 shows one cue, `1.1script`, in `script.md`, `cues.json`, and `deck/index.html`.

<CodeGroup>
  ```md script.md theme={null}
  ## 1. Open

  This is DeckTalk. [beat] You write what you will say, [beat] and you write the slides that go with it.
  [beat] Then every picture waits for its own word.
  ```

  ```json cues.json theme={null}
  { "sections": { "1": { "cues": [
    { "cue": "1.1title", "on": "This is DeckTalk", "occurrence": 1 },
    { "cue": "1.1script", "on": "what you will say", "occurrence": 1 },
    { "cue": "1.1deck", "on": "the slides", "occurrence": 1 },
    { "cue": "1.1word", "on": "its own word", "occurrence": 1 }
  ] } } }
  ```

  ```html deck/index.html theme={null}
  <div class="card" style="left: 120px; top: 430px" data-cue="1.1script"
       data-describe="a card for script.md, the file that holds what you say">
    <div class="k">script.md</div>
    <div class="v">what you will say</div>
  </div>
  ```
</CodeGroup>

1. You write the cue phrase in `cues.json`, and the cue id in the page.
2. The `align` stage resolves each cue phrase to a cue time, in seconds after the section start. The cue time of `1.1script` is the start of the word "what".
3. The `align` stage writes the cue times to `build/cue-times.json`.
4. The recorder passes the cue times to the page as `?cues=`, and the page fires each cue at its time.
5. `decktalk verify` checks that each reveal starts on its word.

`decktalk align` prints the cue times of every section. These lines come from a build without voice of
the starter, so the times are estimates.

```text theme={null}
sec  speech   need  cues
 01    13.0      -  1.1title@0.5,1.1script@2.9,1.1deck@6.27,1.1word@11.56
 02    14.6      -  2.1average@1.44,2.1formula@5.67,2.1code@9.43,2.1waited@11.31
 03    11.9      -  3.1idea@1.41,3.1again@7.8,3.1make@8.71
3 sections with cues, 0 unresolved  (estimated words: times are placeholders)
```

## Matching rules

The `align` stage matches a cue phrase against the section's spoken words with these rules:

1. It splits the phrase and the spoken words on whitespace only.
2. Each token keeps only A to Z, a to z, 0 to 9, and the straight apostrophe. Accented letters, Greek letters, and curly apostrophes are removed.
3. Matching ignores case, unless `case_sensitive` is true.
4. A phrase token with no characters left is ignored. For example, the phrase `learning rate η` matches as `learning rate`.
5. A hyphenated word is one token. "zig-zag" becomes `zigzag`, so the phrase "zig zag" does not match it.
6. The stage looks through the spoken words, in order, for a run that matches the phrase token for token. `occurrence` picks the run, and the default is the first. When the phrase matches more than once and the cue does not set `occurrence`, the stage warns and names each match with its time.
7. The cue time is the start of the run's first word, plus the offset key, rounded to hundredths of a second.
8. `$start` is 0.0 s plus the offset key. A negative result stays negative, and the page fires it at t=0.
9. `$end` is the end of the section's last spoken word, plus the offset key.

The page matches `data-text="spoken"` text with a different rule. It ignores apostrophes, but the `align`
stage keeps them. [`data-text="spoken"`](/reference/runtime#data-text="spoken") has the page's rules.

Write a cue phrase the way the voice says it, because the spoken words come from the voice. The
starter's script says "decktalk dot AI", and its end card shows decktalk.ai. So the cue `3.1make`
matches on "Make your own" and never on the text of the card. A number written in digits comes back
in the form the voice chose, so avoid digits in a cue phrase.

Stage directions are not spoken words. A `[beat]` becomes a dash, and a `[pause N]` becomes a break
tag. Neither is a word, so a phrase that spans a direction still matches.
[script.md](/reference/script-md) has the rules for directions.

## Which sections have cues

Every section key in `cues.json` must name a `[[section]]` in `decktalk.toml`. A section can have no
cues. A page section with no cues plays its preview timing in the recording. A clip section has no
narration, so the `align` stage skips its cues.

## Cue mismatches

A cue can disagree with its page in six ways. The `align` stage catches the first one before the
recording. The page catches the others during the recording.

| Mismatch                                                               | Caught by                       | Message                                                                                  | Result                                                                                                   |
| ---------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| A cue id in `cues.json` appears nowhere in its page.                   | the `align` stage               | `<id>: not in deck/index.html`                                                           | `align` exits 1, and `build` stops after the `align` table.                                              |
| No slide of the playing scene owns the cue.                            | the page, at the start          | `unknown cue id <id> (no slide id, owns list or preview object matches it)`              | The cue fires but mounts no slide. A matching element appears only if its slide is mounted at that time. |
| A slide owns the cue, but no element, handler, or slide id matches it. | the page, when the cue fires    | `cue "<id>" matches no element, handler, or slide`                                       | The cue fires with no visible effect. It still counts toward the mount time of its slide.                |
| An element's `data-cue` is not in `?cues=`.                            | the page, when the slide mounts | `data-cue "<id>" is not in ?cues=, so it reveals at its data-delay time after the mount` | The element appears at its `data-delay` time after the slide mounts.                                     |
| A slide owns no cue in `?cues=`.                                       | the page, at the start          | `slide "<slide>" owns no cue in ?cues=, so it never appears`                             | The slide never mounts.                                                                                  |
| No cue in `?cues=` has an owner.                                       | the page, at the start          | `no slide owns any listed cue, so nothing will mount`                                    | No slide mounts, and the recording shows an empty stage element.                                         |

In each message, `<id>` and `<slide>` stand for real ids. The page lists its warnings in
`window.__decktalk.warnings`. The recorder logs each one and writes it to the recording log. A handler that
`DeckTalk.on` registers for an id stops the second and third warnings for that id.
[Cue ownership](/concepts/page-contract#cue-ownership) has the ownership rules.

The `align` stage looks for each cue id in the page as a quoted literal, in single quotes, double
quotes, or backticks. So `data-cue="1.1bowl"`, a key of a slide's `preview` object, and a key of an `on`
object all count. The stage skips clip sections, and it skips a page file that does not exist,
because the recorder reports that. The cue still resolves, and `align` still writes `cue-times.json`.

These lines come from a copy of the starter whose `data-cue="2.1code"` was renamed `2.1codex` in
`deck/index.html`. `align` exits 1.

```text theme={null}
sec  speech   need  cues
 02    14.6      -  2.1average@1.44,2.1formula@5.67,2.1code@9.43,2.1waited@11.31
                    ! 2.1code: not in deck/index.html
                    ! 2.1codex: data-cue="2.1codex" in deck/index.html has no entry in cues.json
3 sections with cues, 0 unresolved  (estimated words: times are placeholders)
```

To fix an unknown id, add it to the page, or fix the id in `cues.json`. If a page builds its ids at
run time, pass `--allow-unknown-cues` to `align`, `preflight`, or `build`. The page warnings are then
the only check.

## Elements nobody cued

The check runs the other way too, because a cue and the element it reveals are one thing written in two
files. `align` reads every `data-cue` attribute in the pages and reports each id that `cues.json` never
names, as `UNCUED ELEMENT`, a certain finding. Such an element sits on the slide waiting for a phrase nobody
wrote, so the reveal never fires. It is the second line of the sample above, the one that names `2.1codex`.

Add the cue to `cues.json`, or drop the attribute from the page. An id that a script builds from a
variable, such as `data-cue="${IDS[i]}"`, is not a literal that any reader of the file can resolve, so
`align` leaves it to `decktalk preflight`, which reads the page's own catalog.

## Unresolved cues

If the `align` stage cannot match a phrase, it notes `phrase not found` and exits 1. These lines come
from a copy of the starter whose cue `2.1formula` has the typo "the formular".

```text theme={null}
sec  speech   need  cues
 02    14.6      -  2.1average@1.44,2.1code@9.43,2.1waited@11.31
                    ! 2.1formula: phrase not found: 'the formular'
3 sections with cues, 1 unresolved  (estimated words: times are placeholders)
```

`decktalk build` stops after the `align` stage, because a slide whose only cues are unresolved never
mounts. Fix the phrase, or pass `build --allow-unresolved-cues` to build without the cue. The page
then warns that the cue is not in `?cues=`, and its element appears at its `data-delay` time. The
`align` command itself has no such flag, because reporting the phrase is its whole job.

A cue that resolves past the end of the section's audio stays, with a note. A build without voice estimates
word times, so its cue times are estimates too. The table then ends with
`(estimated words: times are placeholders)`.

## Phrase choice

These guidelines help a reveal start on the right word.
[Writing for the ear](/guides/writing-for-the-ear) explains each one.

* Start the phrase with the word that names the thing that appears, because the cue time is the start of the first word. A noun such as `box of knobs` works, and so does a verb with its object, such as `steps downhill`. A connective such as "and then" does not.
* If a word repeats in the section, use two or three words, or set `occurrence`. Set `occurrence` to 1 to keep the first match and silence the warning.
* Set a small positive offset key, 0.1 to 0.2 s, so the viewer hears the word start before the element moves.
* Use a negative offset key only when the audience must read along.
* Put a `[beat]` or a `[pause N]` before a reveal that should feel like an event.
* Cue a summary on `$end` to show it as the voice stops.
* Write numbers as words in the script, and show digits on the slide.

## Sound on cues

A sound effect in `[[mix.sfx]]` names a `section` and a `cue`. The `assemble` stage places the sound
effect at that cue's time. Music marker uses the same `on`, `occurrence`, `case_sensitive`,
and `offset` keys to raise or mute the music at a phrase. [Sound](/concepts/sound) explains both.

## Terms

| Term                                | Meaning                                                                                                                    |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [cue](/reference/glossary)          | A cue is one entry in `cues.json`. It pairs a cue id with a cue phrase.                                                    |
| [cue id](/reference/glossary)       | A cue id ties a cue to the page. It is a slide id plus a short word, such as `1.1bowl`.                                    |
| [cue phrase](/reference/glossary)   | The cue phrase is the `on` value: a spoken phrase, `$start`, or `$end`.                                                    |
| [resolve](/reference/glossary)      | The `align` stage resolves a cue phrase to a cue time.                                                                     |
| [cue time](/reference/glossary)     | The cue time is the start of the cued word plus the offset key, rounded to hundredths, in seconds after the section start. |
| [offset key](/reference/glossary)   | The offset key is the cue's `offset` in `cues.json`. A positive value moves the cue time later.                            |
| [spoken words](/reference/glossary) | The spoken words are the words in the section's words file. Matching and `?words=` use them.                               |

## Next

* **Write phrases that time well:** [Writing for the ear](/guides/writing-for-the-ear)
* **Look up every key:** [cues.json](/reference/cues-json)
* **Learn which slide owns a cue:** [The page contract](/concepts/page-contract#cue-ownership)


# How it works
Source: https://docs.decktalk.ai/concepts/how-it-works

Understand how DeckTalk turns a script and HTML pages into one mp4, and why each reveal starts on its word.

`decktalk build` turns your script and pages into one mp4 in five stages. To build your first video, follow the
[Quickstart](/quickstart).

<Frame>
  <picture>
    <source />

    <img alt="Four panels. Write shows a markdown script. Narrate runs narrate and align, and shows a tick for every word of &#x22;A bowl. A ball. One. Two, three.&#x22; with 1.25 over &#x22;bowl&#x22;. Record runs record, and shows a slide where a bowl draws on and a ball steps down it. Assemble runs assemble and verify, and shows one mp4." />
  </picture>

  <picture>
    <source />

    <img alt="Four panels. Write shows a markdown script. Narrate runs narrate and align, and shows a tick for every word of &#x22;A bowl. A ball. One. Two, three.&#x22; with 1.25 over &#x22;bowl&#x22;. Record runs record, and shows a slide where a bowl draws on and a ball steps down it. Assemble runs assemble and verify, and shows one mp4." />
  </picture>
</Frame>

1. You write four files: `script.md`, `decktalk.toml`, `cues.json`, and the page.
2. The speech provider voices the script and returns a start and an end time for every word.
3. Headless Chromium records each page section, and each reveal fires at its cue time.
4. ffmpeg cuts each recording to its section and joins the sections into one mp4.
5. `verify` measures the final mp4, so an early or late reveal shows as a number.

## Stages

The five stages always run in this order. Each stage reads files that the stages before it wrote.

```mermaid theme={null}
flowchart TB
  S["script.md"] --> narrate
  narrate -- "words files, takes.json" --> align
  C["cues.json"] --> align
  align -- "cue-times.json" --> record
  P["deck pages"] --> record
  record -- "webm and recording log" --> assemble
  assemble -- "name.mp4, captions, chapters" --> verify
```

| Stage      | One job                                                                                                                                                      | Writes                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `narrate`  | `narrate` voices each section and gets a time for every word.                                                                                                | `build/narration/<hash>.mp3`, `<hash>.words.json`, `takes.json`, `narration.mp3` |
| `align`    | `align` turns each cue phrase into a cue time.                                                                                                               | `build/cue-times.json`                                                           |
| `record`   | `record` records each page section in headless Chromium, finds narration t=0 in the webm, and flags a recording that is black, short, stalled, or uncovered. | `build/recordings/NN.webm`, `recordings/NN.json`                                 |
| `assemble` | `assemble` cuts, joins, and mixes the sections into one mp4.                                                                                                 | `build/sections/NN.mp4`, `<name>.mp4`, captions, chapters                        |
| `verify`   | `verify` checks section starts, cuts, and cut continuity in the final mp4.                                                                                   | nothing                                                                          |

Each stage is also a command with the same name, and [the CLI reference](/reference/cli) lists them.
[Build artifacts](/reference/artifacts) gives the fields of every file. `assemble` also runs the
[loudness pass](/concepts/sound#loudness).

## Why the cuts are exact

Each reveal starts on its word because DeckTalk finds narration t=0 inside every recording, to the frame.

<Frame>
  <img alt="A strip of recorded frames. Three magenta cover frames come first, and a line marks t=0 at the first clean frame. Under the strip, the narration &#x22;A bowl. A ball. Watch it step down&#x22; starts at t=0. Dashed leads join &#x22;bowl&#x22; and &#x22;ball&#x22; to the outlined frames where the bowl and then the ball appear." />

  <img alt="A strip of recorded frames. Three magenta cover frames come first, and a line marks t=0 at the first clean frame. Under the strip, the narration &#x22;A bowl. A ball. Watch it step down&#x22; starts at t=0. Dashed leads join &#x22;bowl&#x22; and &#x22;ball&#x22; to the outlined frames where the bowl and then the ball appear." />
</Frame>

| Risk                                                                                             | What DeckTalk does                                                                                  |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| A browser starts to record at an unknown moment. Chromium on Windows starts later than on Linux. | The recorder covers the page in magenta and takes the first frame after the cover as narration t=0. |
| Chromium sends a frame only when the page paints.                                                | The cover holds an element that always moves, so frames keep coming while the page is covered.      |
| t=0 is known only to the nearest frame.                                                          | The video runs at 25 fps, the rate that Chromium records at. t=0 is exact to one frame, 40 ms.      |
| Section lengths add up to fractions of a frame.                                                  | `assemble` rounds each section span to whole frames counted from the start of the narration.        |
| A recording can end before its section span.                                                     | `assemble` repeats the last frame to fill the span. `hold_seconds` uses the same repeat.            |
| Joined audio adds a short delay at each join.                                                    | Each `sections/NN.mp4` has no audio. `assemble` mixes the sound once, from zero.                    |

The recorder removes the cover only when the page is ready. [The handshake](/concepts/page-contract#the-handshake)
shows each wait. `record` looks for the cover only in the first `[record] cover_scan_seconds` of each recording, 4 s by
default. The alignment never depends on wall-clock time.

## The build without voice

A build without voice replaces the voice with a click track, so it needs no account and no API key.

```text theme={null}
[sil ] 01  26 words -> 12.60s (estimated words, sound ends 12.487, lead 0.5s, tail 1.3s)
[sil ] 02  30 words -> 14.20s (estimated words, sound ends 14.087, lead 0.5s, tail 1.3s)
[sil ] 03  25 words -> 11.50s (estimated words, sound ends 11.387, lead 0.5s, tail 1.3s)
```

* The click track has a soft click at the start of every estimated word, and one where the last word ends, at -24 dBFS.
* `narrate` spaces the estimated words evenly at `silent_words_per_minute`, 150 by default. It adds each pause,
  beat, and tail. [script.md](/reference/script-md) gives the length rule.
* Every other stage runs as usual. A build without voice therefore tests the cues, the pages, the recording, the cut, and
  the checks.
* The `narrate` and `align` tables mark their times as estimated.
* The clicks let `verify` compare the picture with the sound in the final mp4. [Verify](/reference/verify#cues)
  explains the check.
* A build without voice skips the loudness pass, so the clicks keep their level.

A build without voice stops when the project has voiced takes, because it would empty the narration cache.
[A build without voice and a voiced build](/guides/rebuild-one-section#a-build-without-voice-and-a-voiced-build) explains the cost.

## Clips and the narration

A clip section plays a video with its own audio. `narrate` and `record` skip it, and the narration
pauses for a clip between two page sections.

<Frame>
  <img alt="Lanes on one time axis. The narration.mp3 lane holds sections 1, 2, 3, 4, 6, 8, and 9 back to back, with a split before sections 6 and 8. The video lane plays the 4 s clip of section 5 after section 4 and the 5.04 s slate of section 7 after section 6, and dashed leads move sections 6, 8, and 9 later. Captions sit under page sections only. Chapters mark the start of each title, and the five sections titled The edit share one." />

  <img alt="Lanes on one time axis. The narration.mp3 lane holds sections 1, 2, 3, 4, 6, 8, and 9 back to back, with a split before sections 6 and 8. The video lane plays the 4 s clip of section 5 after section 4 and the 5.04 s slate of section 7 after section 6, and dashed leads move sections 6, 8, and 9 later. Captions sit under page sections only. Chapters mark the start of each title, and the five sections titled The edit share one." />
</Frame>

[Add a clip section](/guides/clip-section) shows how to place a clip and how the narration splits.

## Caching

`narrate` keeps each section's audio and a hash of its text in `build/narration/takes.json`. After an edit,
`decktalk build` voices again only the sections whose text changed.

`record` keeps each section's recording the same way. The recording log holds `input_hash`, the digest of the
page URL with its cues and its spoken words, the frame geometry, the markup of the one scene the section plays,
the rest of that page, which every scene shares, and the content of every project file the page loaded, which
the log lists under `assets`. A section whose hash has not moved is kept. So an edit inside one scene records
the sections that play it and leaves the other sections of that page alone, while an edit to the page's head,
its styles or its scripts records every section of it. Replacing a picture the page loads records that section
again, although no line of HTML changed.
`decktalk build --only N` records section N whether it changed or not. A recording stays valid when a neighbor
section changes length, because cue times count from the start of their own section.
[Rebuild one section](/guides/rebuild-one-section) says what each edit runs again.

## What verify checks

`verify` checks the final mp4 in three ways.

* **Section starts:** the frame 0.2 s after each section start has a pixel brighter than luma 60.
* **Cuts:** the narration is at or below -40 dBFS in the last 0.15 s before each cut.
* **Cues:** the picture changes within 80 ms of each cue time. After a build without voice, it also changes within 120 ms
  of the click plus the offset key.

The verify stage inside `decktalk build` checks section starts and cuts, and cut continuity for a section that sets `seamless`. `decktalk verify` also checks the cues.
[Verify](/reference/verify) defines every measurement, limit, and result.

## Terms

| Term                                       | Meaning                                                                                                              |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| [Stage](/reference/glossary)               | One of `narrate`, `align`, `record`, `assemble`, and `verify`, in that order.                                        |
| [Build without voice](/reference/glossary) | A build with `--no-voice`. It uses estimated word times and writes a click track.                                    |
| [Voiced build](/reference/glossary)        | A build without `--no-voice`. The speech provider voices the script.                                                 |
| [Click track](/reference/glossary)         | The audio of a build without voice, with a soft click at every estimated word start and at the end of the last word. |
| [Narration t=0](/reference/glossary)       | The first frame after the magenta cover, where the page clock starts.                                                |
| [Recording](/reference/glossary)           | The webm that `record` writes for a page section.                                                                    |
| [Cut](/reference/glossary)                 | The boundary between two sections in the final video.                                                                |

## Next

* **Build your first video:** [Quickstart](/quickstart)
* **Rebuild after an edit:** [Rebuild one section](/guides/rebuild-one-section)
* **Read a verify table:** [Verify](/reference/verify)


# The page contract
Source: https://docs.decktalk.ai/concepts/page-contract

Learn how the recorder plays an HTML page in time with the narration, and which rules a page follows.

The page contract is the set of rules that lets the recorder play an HTML page in time with the
narration. To write a page, follow [Your first deck](/guides/first-deck).

1. `decktalk-runtime.js` implements the contract. A page can also [follow it by hand](/guides/page-by-hand).
2. A scene is markup: a `[data-scene]` wrapper holding one `<template data-slide>` per slide. Attributes do the work, and a page needs no JavaScript.
3. The URL of a page picks one of four modes.
4. The recorder hides the page under a magenta cover, then starts the page clock at narration t=0.
5. The first slide is already on the stage when the cover lifts. Every later slide mounts at the earliest cue it owns, and each cue fires at its cue time.
6. Your CSS styles the slides. The runtime adds only the stage element (`#dt-stage`), slide transitions, and reveal effects, and every rule of its own sits in `:where()`, so one rule of yours wins.

## Modes

A page holds scenes, and a page section plays one scene. A scene has slides, and each slide renders
one slide. A page plays in one of four modes, and `window.__decktalk.mode` holds the `mode` value.

| Mode        | `mode` value | Opened as                                                                  | What happens                                                                                                         |
| ----------- | ------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Index mode  | `index`      | no query                                                                   | The page lists every scene and slide, with play and freeze links.                                                    |
| Preview     | `preview`    | `?scene=N`                                                                 | Each slide mounts in turn and stays for its `hold` seconds. A browser preview plays this mode.                       |
| Cue mode    | `cue`        | `?scene=N&cues=id@s,…`                                                     | Cue times drive the page. The recorder uses this mode.                                                               |
| Freeze mode | `freeze`     | `?slide=ID`, optionally with `&after=CUE`, which `decktalk-probe.js` reads | One slide mounts with its reveals in their end state. `decktalk screenshots` and `decktalk preflight` use this mode. |

[Modes](/reference/runtime#modes) in the runtime reference lists the URL, the clock, and what
mounts in each mode.

### Browser preview and recording

A browser preview opens the page without `?cues=`, so it plays in preview. A recording plays in
cue mode. This table shows which values matter in each.

| Value                                   | In a browser preview                                               | In a recording                                                                                                  |
| --------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `hold` on a slide                       | The slide stays this many seconds, then the next slide mounts.     | The recorder ignores it. A slide mounts at its earliest cue, and the last slide stays until the recording ends. |
| The `preview` object, or `data-preview` | Each cue fires this many seconds after the slide mounts.           | Ignored. The cue times come from `build/cue-times.json`, and the object grants no ownership.                    |
| `data-delay` on an element              | The element appears this many seconds after the slide mounts.      | The same, for an element with no `data-cue`.                                                                    |
| `data-cue` on an element                | The element appears when the slide's preview timing fires its cue. | The element appears when its cue fires.                                                                         |
| `data-text="spoken"` on an element      | The element appears whole.                                         | The words appear one at a time, from the `?words=` list.                                                        |

`data-cue` and `data-delay` are two triggers for one element, so an element that carries both warns
and the delay is ignored. A cued element with no preview timing stays hidden through a browser
preview, which is what a page whose whole timing lives in `cues.json` shows.

### Where a page is served from

`record`, `screenshots` and `preflight` open every page at `http://project.localhost/`, and answer
each request under that origin from your project directory. A page may therefore `fetch()` a file
beside it and load an ES module, neither of which works from a `file://` URL, and a relative URL
resolves exactly as it would from a file on disk. Nothing is downloaded and no port is opened.

To open a page in your own browser the same way, run `decktalk serve` and follow the URL it prints.

## The handshake

```mermaid theme={null}
sequenceDiagram
    participant R as Recorder
    participant P as Page
    R->>P: add the magenta cover with an init script
    R->>P: open page.html?scene=N&cues=…&words=…&t0=signal
    Note over P: the runtime starts the mode and mounts the first slide
    P-->>R: load event
    R->>P: await document.fonts.ready, then window.__decktalk.ready
    Note over R: recorder wait
    R->>P: remove the cover
    R->>P: call DeckTalk.startClock() on the next animation frame
    Note over P: narration t=0, and cues fire from here
    Note over R: record the section span plus record_margin_seconds
    R->>P: read warnings, page errors, frameGaps, and spokenLog
```

With `t0=signal` in the URL, the page starts its clock only when the recorder calls
`DeckTalk.startClock()`. A browser preview has no `t0=signal`, so its clock starts at the `load`
event.

The recorder wait comes after `window.__decktalk.ready` resolves and before the recorder removes the
cover. Two `[record]` settings set it.

```text theme={null}
recorder wait = max(settle_seconds, min_cover_seconds - elapsed)
elapsed       = seconds since the recorder created its browser context
```

The defaults are `settle_seconds = 0.5` and `min_cover_seconds = 1.5`. The cover hides the page
during the wait. [How it works](/concepts/how-it-works#why-the-cuts-are-exact) explains why the
first frame after the cover is narration t=0.

From the first paint until the recording stops, the recorder keeps a 2 px square turning in the
bottom-right corner at 3 % opacity. The square keeps the browser drawing frames at the same pace
before and after t=0. A still page then records each reveal on its scheduled frame, not a frame or
two early. The square is too faint for `verify` or `record` to measure, and `decktalk screenshots` never
shows it. A page needs no motion of its own for timing.

A page that starts its own clock at `load` fires every cue early, by the whole time from `load` to
t=0. Every reveal in the video then comes before its word.

After the recording, the recorder reads these values from the page and writes them to the recording log:

* `window.__decktalk.warnings`. The recorder also logs each warning.
* The page's uncaught errors. A missing or empty `window.__decktalk.catalog` counts as one more error.
* `window.__decktalk.frameGaps`.
* `window.__decktalk.spokenLog`.

`record` reports `PAGE ERROR` for a page error, `KATEX ERROR` for a `data-tex` value KaTeX refused,
and `KATEX NOT LOADED` when the page asked for KaTeX and never got it. All three are certain, and
`verify` reports them again from the recording log. [decktalk record](/reference/cli#decktalk-record)
lists every verdict.

## Cue ownership

Each cue in `?cues=` has one owner, a slide of the playing scene. The runtime picks the owner with
three rules.

1. A slide whose id equals the cue id owns the cue.
2. A slide whose `owns` list names the cue owns the cue.
3. Otherwise, the slide whose id is the longest prefix of the cue id owns it. For example, slide `4.2` owns cue `4.2b1`, and slide `9` owns cue `9a`.

Rule 3 is the rule, and rules 1 and 2 are for the cue id that does not carry its slide's id. A
slide's preview timing grants no ownership, so seconds and ownership are never edited together by
accident. The runtime looks only in the playing scene.

In cue mode, ownership decides when each slide mounts:

* A slide mounts at the earliest cue time it owns.
* The first slide to mount is on the stage before the clock starts, whatever its earliest cue is, so no frame of the recording is drawn on an empty stage.
* A slide that owns no cue in `?cues=` never mounts.
* The last slide to mount stays until the recording ends.

A mismatch between `cues.json`, the page, and its slides adds a warning.
[Cue mismatches](/concepts/cues#cue-mismatches) lists each one, with its result.

## When a cue fires

When a cue fires, the runtime adds its id to `window.__decktalk.fired`. Then it does three things,
in this order:

1. Every element on the mounted slide whose `data-cue` matches the cue appears.
2. The mounted slide's `on[id]` handler runs, if the slide has one.
3. Every handler that `DeckTalk.on(id, fn)` registered for the cue runs, in the order of registration.

Each handler gets the slide element and a context object, `{ id, at, frozen, slideId }`. A handler
finds its elements with `slide.querySelector` and needs no global variable.
[Handler context](/reference/runtime#handler-context) describes the fields. An element with
`data-text="spoken"` starts to show its words one at a time when it appears.

## A seamless cut

`seamless = true` on a `[[section]]` says that the section opens on the picture the section before it
ended on, so the cut between them should not show. It is a claim the page keeps, not an effect: the
runtime carries nothing across the cut, and a scene always starts on its own first slide. The key does
three things.

* The recorder gives the section's page the previous section's spoken words as `?prevwords=`. Only a
  seamless section gets them.
* `decktalk verify` compares the previous section's last frame with this section's first frame in the
  finished video, and a changed share above `[verify] max_pop_percent` reads `POP AT CUT`, a certain
  finding. `decktalk preflight` estimates the same comparison from the two frozen states before
  anything is recorded.
* `decktalk.toml` refuses it on the first section, which has no picture before it.

To make a scene open on the previous scene's last picture, rebuild that picture in the new scene's
first state:

1. Copy the markup of the previous scene's last slide into the new scene's first slide.
2. Remove `data-cue` and `data-delay` from the copied elements, so they are there from the first frame
   instead of appearing on a cue. The first slide of a played scene enters with no animation.
3. Give the copies the same classes and styles, so they draw in the same place at the same size.
4. Add the new elements with their own `data-cue`, so they appear on their words.

A value the previous scene built from its words, such as a `data-text="spoken"` line, can be rebuilt
from `?prevwords=`. Keep the camera push off both scenes, because a pushed-in last frame cannot match an
unpushed first one, and leave the pair out of `[transition] dips`, because a dip fades through black.
[Cut continuity](/reference/verify#cut-continuity) defines the check.

## Build artifacts a page can read

A page gets its cue times as `?cues=`, from `build/cue-times.json`. It gets the section's spoken
words as `?words=`, and the words of the section before it as `?prevwords=`, both from the words file
of the take that section plays, which `build/narration/takes.json` names. A tool of your own can read
those files too. [Build artifacts](/reference/artifacts) has the shape of each file.

## Terms

| Term                                   | Meaning                                                                                                               |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [page](/reference/glossary)            | A page is an HTML file that page sections play, such as `deck/index.html`.                                            |
| [scene](/reference/glossary)           | A scene is one `[data-scene]` wrapper, or one `DeckTalk.scene(N, …)` call, in a page. A page section plays one scene. |
| [slide](/reference/glossary)           | A slide is one `<template data-slide>` of a scene, or one entry in its `slides`, and the markup it mounts.            |
| [mount](/reference/glossary)           | A slide mounts when it enters the page.                                                                               |
| [own](/reference/glossary)             | A slide owns a cue by the three ownership rules.                                                                      |
| [browser preview](/reference/glossary) | A browser preview is a page opened in a browser without `?cues=`. It plays in preview.                                |
| [cover](/reference/glossary)           | The cover is the magenta overlay that hides the page until narration t=0.                                             |
| [narration t=0](/reference/glossary)   | Narration t=0 is the moment `DeckTalk.startClock()` runs, on the first frame after the cover.                         |
| [recorder wait](/reference/glossary)   | The recorder wait is the time between `window.__decktalk.ready` and the removal of the cover.                         |
| [handler](/reference/glossary)         | A handler is a function in a slide's `on` object, or one that `DeckTalk.on(id, fn)` registers.                        |

## Next

* **Write your first page:** [Your first deck](/guides/first-deck)
* **Size a slide and choose reveal effects:** [Design a slide](/guides/design-a-slide)
* **Look up every attribute and field:** [Runtime](/reference/runtime)


# Sound
Source: https://docs.decktalk.ai/concepts/sound

Understand how DeckTalk mixes narration, clip audio, and the optional soundscape into one loudness-normalized track.

DeckTalk mixes the narration, the audio of each clip, and an optional soundscape into one track, then
normalizes its loudness. To place one sound on a cue, follow [Put a sound effect on a cue](/guides/sfx-on-a-cue).

1. The narration and the audio of every clip are always in the mix.
2. The music, the ambience bed, and sound effects are the soundscape. Each part stays off until `[mix]` in
   `decktalk.toml` names a file.
3. The music gets quieter under each spoken span and under each clip.
4. A markers file can swell or mute the music at a spoken phrase.
5. After the parts are summed, the loudness pass brings the mix to one target.

## Parts of the mix

The mix has five parts. Only the first two are always present.

| Part          | Source                          | What it does                                                                                                                               |
| ------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Narration     | `build/narration/narration.mp3` | The narration starts with the first page section. It pauses for each clip between page sections.                                           |
| Clip audio    | each clip file                  | Clip audio plays at its section start, trimmed to the clip's picture. It fades in and out over 20 ms, so a cut never clicks.               |
| Music         | `[mix] music`                   | The music loops for the whole video at `music_db`. It fades in over `music_fade_in_seconds` and out over `music_fade_out_seconds` seconds. |
| Ambience bed  | `[mix] ambience`                | The ambience bed loops at `ambience_db` under each page section that sets `ambience = true`.                                               |
| Sound effects | `[[mix.sfx]]`                   | Each sound effect plays once, at the cue time of its cue plus its `offset`.                                                                |

If a sound effect file is missing, or its cue did not resolve, `assemble` skips that effect with a warning. If the
music file is missing, `assemble` builds the video with no music and prints a warning. The `--no-soundscape` flag
leaves out the whole soundscape, so the mix holds only the narration and the clip audio.

## Ducking

The music ducks by `music_duck_db` under each spoken span and under each whole clip. At the default of
-6 dB, the music plays 6 dB quieter than `music_db` there.

* A page section's spoken span runs from its start to the end of its last spoken word.
* Under a clip, the duck covers the whole clip.
* The duck ramps over `[audio] duck_ramp_seconds`, 0.5 s by default, inside each edge of a spoken span or a clip.

The music therefore starts to rise in the last 0.5 s of speech, and it is at full level in the silence after
it. It stays down under a clip. The ramps are tuning keys under `[audio]` in
[Configuration](/reference/configuration#audio).

The next figure shows the music level around the clip section from [Add a clip section](/guides/clip-section),
for a project that has a music file. The levels are the `[mix]` and `[audio]` defaults.

<Frame>
  <img alt="The music level around clip section 5, from 3:14 to 3:25 of the video. It sits at −30 dB under each spoken span and under the whole clip. It ramps up to −24 dB over the last 0.5 s of speech in section 4, and briefly at the cut into section 6." />

  <img alt="The music level around clip section 5, from 3:14 to 3:25 of the video. It sits at −30 dB under each spoken span and under the whole clip. It ramps up to −24 dB over the last 0.5 s of speech in section 4, and briefly at the cut into section 6." />
</Frame>

## Markers

A markers file swells or mutes the music at spoken phrases. It gives the music some structure without an
edit to its file. Name it in `[mix] music_markers`. The starter ships no markers file, so this one is an
example to copy, and it swells the music at the start of section 1.

```json media/markers.json theme={null}
{
  "_comment": "Music structure. Each marker swells the bed by boost_db for boost_seconds at a spoken phrase (or $start/$end of a section); mute_seconds silences it for one beat first.",
  "boost_db": 3,
  "boost_seconds": 2,
  "markers": [
    { "name": "open", "section": 1, "on": "$start" }
  ]
}
```

| Key              | Where     | Default  | Meaning                                                           |
| ---------------- | --------- | -------- | ----------------------------------------------------------------- |
| `boost_db`       | top level | 3        | How far each marker swells the music, in dB.                      |
| `boost_seconds`  | top level | 2        | How long each swell lasts.                                        |
| `markers`        | top level | none     | The list of markers.                                              |
| `name`           | marker    | none     | The name that a warning uses for the marker.                      |
| `section`        | marker    | required | The number of the section that holds the phrase.                  |
| `on`             | marker    | `$start` | A spoken phrase, `$start`, or `$end`, matched as a cue phrase is. |
| `offset`         | marker    | 0        | Seconds to add to the matched time.                               |
| `occurrence`     | marker    | 1        | Which match of the phrase to use.                                 |
| `case_sensitive` | marker    | false    | Whether the match compares case.                                  |
| `mute_seconds`   | marker    | 0        | Seconds of silence before the swell starts.                       |
| `_comment`       | top level | none     | A note. DeckTalk does not read it.                                |

If `[mix] music_markers` names a file that does not exist, the music plays with no markers and a warning. If a
marker's phrase is not found, `assemble` skips that marker with a warning. The mute and swell ramps are
`marker_mute_ramp_seconds` and `marker_boost_ramp_seconds` under `[audio]`.

## Loudness

After the parts are summed, the loudness pass runs in this order.

1. It measures the integrated loudness and the true peak of the mix.
2. It applies the gain that reaches the integrated target, `[mix.loudness] target_lufs`.
3. It runs a limiter at 192 kHz to catch peaks between samples. The limiter sits 0.3 dB under the ceiling,
   `[mix.loudness] true_peak_db`.
4. It measures the result again and prints it.

The defaults are -16 LUFS integrated and a -1.5 dBTP ceiling, so the limiter acts on peaks above -1.8 dBTP. A
plain gain keeps the dynamics of the mix, and the limiter changes only the peaks.

The pass logs one `[loud]` line for a voiced build. It reads `I` before and after with the target,
`TP` before and after with the ceiling, and `LRA` before and after. A build without voice never
reaches the pass, so that line appears only after a voiced `assemble`.

* If the result is more than 1 LU from the target, or above the ceiling, `assemble` prints a warning.
* With `--strict`, that warning is an error instead.
* The `--no-loudness` flag skips the pass. [decktalk.toml](/reference/decktalk-toml) lists the `[mix.loudness]`
  keys.

A build without voice skips the pass. Its narration is a click track, with no speech to normalize. The clicks stay at
-24 dBFS, which is the level the [a/v check](/reference/verify#the-a/v-value) listens for.

```text theme={null}
[loud] skipped: the narration is a silent placeholder, so the soundtrack is encoded as it was mixed
```

## Generated sound

`decktalk soundscape` generates soundscape files from the prompts in `[soundscape]`. It uses the ElevenLabs sound
and music endpoints, which spend credits.

```toml decktalk.toml theme={null}
[soundscape.music]
prompt = "calm, minimal instrumental music for a lesson: soft piano and warm pads, slow, no drums, no melody hooks, unobtrusive under a narrator"
seconds = 120
force_instrumental = true

[soundscape.ambience]
text = "quiet lecture hall room tone, distant HVAC, no voices, steady"
duration_seconds = 25

[soundscape.sfx.tick]
text = "soft interface click, single, short, no reverb"
```

```console theme={null}
decktalk soundscape --dry-run       # print every request, and send nothing
decktalk soundscape                 # generate what is missing or changed
decktalk soundscape music    # generate one item
```

* Music and ambience go to the paths in `[mix]`. With no path there, they go to `build/music/music.mp3` and
  `build/sfx/ambience.mp3`.
* Each sound effect goes to `build/sfx/<name>.mp3`.
* Music longer than `[elevenlabs] max_music_chunk_seconds` is requested in chunks and joined with a crossfade.
* Each output has a manifest file with a hash of its request. A second run sends nothing unless a request changed.
* `--force` generates an item again, even when its request did not change.

```text theme={null}
items 1, generated 0
== music -> ~/my-lesson/build/music/music.mp3  [planned]
   POST https://api.elevenlabs.io/v1/music
   {'prompt': 'calm, minimal instrumental music for a lesson: soft piano and warm pads, slow, no drums, no melody hooks, unobtrusive under a narrator', 'force_instrumental': True, 'model_id': 'music_v2', 'music_length_ms': 120000}
```

[Requirements](/requirements#what-spends-credits) lists every command that spends credits.
[decktalk.toml](/reference/decktalk-toml) lists every `[soundscape]` key.

## Your own audio files

Point `[mix] music`, `[mix] ambience`, and each `[[mix.sfx]] file` at any audio file that ffmpeg can read.

Keep your own file at a path that no `[soundscape]` table writes to. `decktalk soundscape` generates any output
that has no manifest file next to it, and it overwrites your file. The starter has no `[mix]` sound keys and no
`[soundscape]` tables at all, so a new project makes no sound beyond the narration until you add them.

## Terms

| Term                                | Meaning                                                                                 |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| [Music](/reference/glossary)        | The music under the whole video.                                                        |
| [Ambience bed](/reference/glossary) | A loop of room sound under the sections that set `ambience = true`.                     |
| [Sound effect](/reference/glossary) | A one-shot audio file placed on a cue.                                                  |
| [Duck](/reference/glossary)         | The music gets quieter under a spoken span or a clip.                                   |
| [Spoken span](/reference/glossary)  | A section's start to the end of its last spoken word.                                   |
| [Mix](/reference/glossary)          | The narration, clip audio, and soundscape, summed and passed through the loudness pass. |

## Next

* **Put one sound on a cue:** [Put a sound effect on a cue](/guides/sfx-on-a-cue)
* **Set the mix levels:** [decktalk.toml](/reference/decktalk-toml)
* **See what spends credits:** [Requirements](/requirements#what-spends-credits)


# Accessible video
Source: https://docs.decktalk.ai/guides/accessible-video

What a DeckTalk build gives you for free, what you still owe a viewer, and how to check both.

Course platforms, company intranets and public sector sites often require captions and a transcript
by law. A DeckTalk build writes most of what that takes without being asked, because it already
knows the spoken words, where each one falls and what appeared on which second. Use this guide to
see what arrives free, what is yours to write and how to check the result.

## What every build writes

| File                                              | What it is                                                                                                                                         |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build/out/<name>.srt` and `build/out/<name>.vtt` | The captions, cut from the words the voice actually said, keeping the script's punctuation and case.                                               |
| `build/out/<name>.chapters.txt`                   | One chapter per section, named by the section's `chapter` value, which defaults to its script heading.                                             |
| `build/out/<name>-transcript.html`                | The transcript page, with one heading per chapter, the section's span in the video, the spoken text, and a list of the reveals with their seconds. |

Set `language` in the `[project]` table to the language tag of the narration, such as `en`, which is
the default. The transcript page takes it as its `lang` attribute, and the mp4's audio and video
streams are tagged with its three-letter form, so a player names the audio from the project's own
key. One value reaches everything a viewer picks from, and the tag cannot disagree with itself.

## Captions that carry the sound, not only the speech

Captions owe the audio and not only the dialogue. A viewer who cannot hear the ball bounce needs to
be told that it bounced.

Give each cued sound a `caption` string, and the build merges it into the captions as a cue of its
own.

```toml decktalk.toml theme={null}
[[mix.sfx]]
file = "build/sfx/bounce.mp3"
section = 2
cue = "2.1ball"
caption = "ball bounces"
```

A sound with no `caption` string is left out of the captions, and `assemble` reports it as
`NO CAPTION?` on every run. It is uncertain, so it costs exit 1 only under `--strict`, and the row
names the cue, which is how to find the `[[mix.sfx]]` table to give a line to.

A caption stays on screen for at least one second, except where a longer stay would overlap the cue
after it, so a one-word caption never flashes past. Two captions are never on screen at once,
because a sound that lands inside a speech cue joins that caption as a line of its own.

## The transcript, and the describe attribute

The transcript page is the media alternative for a viewer who cannot see the video. Out of the box
it carries the spoken text of every section, under one heading per chapter, with the section's span
in the finished video.

What it cannot carry is what a reveal meant, because nothing but you knows. Write that yourself, one
sentence per reveal, in a `data-describe` attribute beside the cue. Every reveal that has one gets a
line under its section, with the second it fired.

```html theme={null}
<figure data-cue="3.2error" data-reveal="draw"
        data-describe="The error curve falls steeply for the first ten steps and then flattens.">
```

The transcript prints those sentences in cue order under their section, so a reader gets the
diagram as prose. A described audio track can voice the same strings later, which is the second
reason to write them as full sentences rather than as labels. The starter writes one on every cued
element, so a first project's transcript already reads end to end.

Describe the reveals that carry meaning. A decorative flourish needs no sentence, and a description
of one only makes the transcript harder to read.

## What the author still owes

* **Keep cued elements out of the caption band.** A player draws captions across the bottom of the
  frame, so anything in the bottom fifteen percent, which is 162 px of a 1080 px frame, can be
  covered at the moment it appears. `preflight` reads the measured boxes and reports one as
  `IN CAPTION BAND?`, which is uncertain because a deck may put something there on purpose, so
  `--strict` is how a project says the band is reserved.
  [Design a slide](/guides/design-a-slide#make-each-reveal-big-enough-to-measure) gives the numbers.
* **Change lightness, not only hue.** `decktalk verify` compares luma alone, so a reveal that
  changes colour without changing lightness fails the check and also fails a viewer with low vision.
* **Give an image its alt text.** A slide image is ordinary HTML, and nothing writes its `alt`
  attribute for you.
* **Read the contrast.** `decktalk screenshots` writes one PNG per slide, which is what to read for
  small text over a busy background.
* **Say the thing you show.** A reveal that the narration never names has no word to start on and no
  place in the transcript, which is the same rule
  [Writing for the ear](/guides/writing-for-the-ear) gives for a different reason.

## How to check it

<Steps>
  <Step title="Run the checker">
    `decktalk verify` reads the final video and reports every recording, section start, cut, seam
    and cue landing. A reveal that did not land on its word is a reveal a caption reader will meet
    at the wrong moment.
  </Step>

  <Step title="Fail on the uncertain findings too">
    `decktalk preflight --strict` and `decktalk verify --strict` turn an uncertain finding, such as a
    reveal too thin to measure, into a failure rather than a note. A thin reveal is one a viewer with
    low vision is likeliest to miss.
  </Step>

  <Step title="Read the transcript page">
    Open `build/out/<name>-transcript.html` and read it with the video closed. A section whose list of
    reveals is short or missing is a section whose page needs `data-describe` sentences.
  </Step>

  <Step title="Watch it with the sound off">
    Play the video with the captions on and the sound off. Anything you learn only from the audio is
    a caption line that is missing.
  </Step>
</Steps>

## Publishing

Serve the video from a plain `<video>` element with a `<track>` for the captions, so the captions
and the chapters stay under your control rather than a third-party player's. Link the transcript
page next to the video, and give the link text that says what it is rather than "transcript".


# Build in CI and offline
Source: https://docs.decktalk.ai/guides/ci-and-offline

Build and check a DeckTalk video on every push, or on a machine with no network.

A build without voice needs no API key, and after `decktalk install` it needs no network. Use this guide to build and
check the video on every push, or on a machine that is offline.

`decktalk build` can pass when `decktalk verify` fails, because the build's own verify stage does not
measure the cues. To gate a job on the video, run both commands.

```console theme={null}
decktalk build --no-voice && decktalk verify
```

## Add a GitHub Actions job

This job builds the video with no API key, checks it, and uploads the video and the verify results.

```yaml .github/workflows/video.yml theme={null}
jobs:
  video:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.1.0
      - run: uv tool install decktalk
      - name: Cache Chromium and ffmpeg
        uses: actions/cache@v4
        with:
          path: |
            ~/.cache/ms-playwright
            ~/.cache/decktalk
          key: browsers-${{ runner.os }}
      - run: decktalk install
      - run: decktalk doctor
      - run: decktalk build --no-voice
        env:
          DECKTALK_VIDEO_PRESET: veryfast
      - run: decktalk verify --json > verify.json
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: video
          path: build/out/*.mp4
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: verify
          path: verify.json
```

* The cache paths are for Linux. [Requirements](/requirements#what-install-downloads) lists the paths on macOS and
  Windows.
* On Linux, `install` installs Chromium's system libraries, which needs sudo or root.
  [Linux system libraries](/requirements#linux-system-libraries) gives the full rule.
* `install` downloads ffmpeg into DeckTalk's own cache, beside Chromium, so the one cache entry above holds both.
* If a proxy blocks the Chromium download, set `PLAYWRIGHT_DOWNLOAD_HOST` to a mirror.

## What each command catches

Each command exits 1 on a different set of problems.

| Command              | Exits 1 on                                                                                                                                                 | Does not catch                                                                                                                             |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `decktalk build`     | `PAGE ERROR`, `BLACK`, `SPEECH AT CUT`                                                                                                                     | `TRUNCATED`, `STALLED`, `NO COVER`, `BLACK?`, `SPOKEN SYMBOL?`, every cue result                                                           |
| `decktalk align`     | `UNRESOLVED`, `UNCUED ELEMENT`, an unknown cue id                                                                                                          | anything about the pages or the video                                                                                                      |
| `decktalk record`    | `PAGE ERROR`, `STALLED`, `TRUNCATED`, `NO COVER`, `KATEX ERROR`, `KATEX NOT LOADED`, `CDN ASSET`                                                           | `BLACK?`, unless you pass `--strict`                                                                                                       |
| `decktalk verify`    | `BLACK`, `SPEECH AT CUT`, `OFF CUE`, `NO CHANGE`, `UNRESOLVED`                                                                                             | a `skipped` row, such as a cue marked `"verify": false`                                                                                    |
| `decktalk status`    | a missing or unreadable input file, and two input files that disagree                                                                                      | anything the build wrote                                                                                                                   |
| `decktalk doctor`    | a missing tool                                                                                                                                             | nothing about the project itself                                                                                                           |
| `decktalk preflight` | an unfilled placeholder, `UNRESOLVED`, `UNCUED ELEMENT`, `OFF STAGE`, and `PAGE ERROR`, `NO CHANGE` or `POP AT CUT` in frozen frames, before any recording | motion, timing, and every check on the final mp4. `IN CAPTION BAND?` and `CUES OVERLAP?` are reported and cost exit 1 only with `--strict` |

A cue phrase that is not found and a cue id that no page carries stop `build` as errors rather than
findings, so those two exit 3 there. `decktalk align` reports both as findings and exits 1.

A build without voice puts a click at every word start, so `verify` also reports an
[a/v value](/reference/verify#the-a/v-value) for each cue. The job fails when an a/v value is past
`max_av_frames`, which is three frames at the defaults. A build without voice therefore tests the recording, the cut,
and the mix, not only the cues.

`build --strict` stops on a missing clip, unless the clip section sets `optional = true`. That one is an error
rather than a finding, so it exits 3. With `--no-voice`, a build cannot fail on loudness at all, because a build
without voice skips the loudness pass.

## Fail the job on a bad video

Every command shares one exit rule. Use the exit codes as the assertions of a job.

| Code | What it means                                                                                                                                                                     |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | The command ran and found nothing, or `--exit-zero` was passed.                                                                                                                   |
| 1    | The command found something. A certain finding, such as `OFF CUE` or `TRUNCATED`, always does this. An uncertain finding, whose label ends in `?`, does it only under `--strict`. |
| 2    | A usage error, such as an unknown flag.                                                                                                                                           |
| 3    | DeckTalk itself could not run. A missing input file, a malformed `decktalk.toml` or a provider that refused does this.                                                            |
| 130  | The run was interrupted.                                                                                                                                                          |

A non-zero exit with `error` null in the JSON is a finding the job can fix. A non-null `error.code`
is an error, and the job stops.

```console theme={null}
decktalk record --strict     # also fail on BLACK?
decktalk verify              # fail on any certain finding
```

`status` and `doctor` take `--exit-zero` and refuse `--strict`, because every finding they report is
certain and the flag could change nothing.

To keep the job running and decide later, add `--exit-zero` and read the JSON.

```console theme={null}
decktalk verify --json --exit-zero > verify.json
jq -e '.ok' verify.json
jq '.verify.cues[] | select(.verdict.code != "CHANGED")' verify.json
jq '.findings.items[]' verify.json
```

`--exit-zero` makes the command exit 0 on findings, but an error still exits 3. The JSON `ok` is false when the
command would exit non-zero without `--exit-zero`. `jq -e` then exits 1, the second `jq` line lists the cue rows
to look at, and the third lists every finding of the run in the shape every command shares.
[The `--json` envelope](/reference/cli#the-json-envelope) lists every key.

## Allow for slower runners

A hosted runner has no GPU that Chromium can use, so Chromium draws every frame in software. The macOS and Windows
runners are slower than Linux.

* A page renders more slowly on a runner than on a laptop.
* A canvas figure or a large SVG renders more slowly still.
* A reveal can start two or three frames late, and `verify` reports `OFF CUE`.
* A long draw after narration t=0 can read `STALLED`.

If that happens only on a slower runner, widen the limits for that runner. Keep the defaults on the machine that
records the published video. These three variables are the ones a slow runner needs, and the values on the right
are a starting point rather than a rule.

| Environment variable                | Default | A slower runner |
| ----------------------------------- | ------- | --------------- |
| `DECKTALK_VERIFY_MAX_OFFSET_FRAMES` | 2       | 4               |
| `DECKTALK_VERIFY_MAX_AV_FRAMES`     | 3       | 5               |
| `DECKTALK_RECORD_STALL_MS`          | 150     | 400             |

A reveal can also start late while a large layer moves, such as a canvas figure that pans. To gate a job on cue
timing, verify a light deck whose reveals land on still pages, and report the busy deck without failing. DeckTalk's
own test builds `tests/e2e/fixture`, a five-section still deck, with `pytest -m e2e`. It decides from the platform
it is running on: it fails on a cue offset over the limit on Linux, and on macOS and Windows it prints the largest
offset it saw and asserts a wider bound instead. Those two platforms run on every push to `main` and before a
release is published.

```yaml .github/workflows/video.yml theme={null}
      - name: Widen the sync tolerance on the slower runners
        if: runner.os != 'Linux'
        run: |
          echo "DECKTALK_VERIFY_MAX_OFFSET_FRAMES=4" >> "$GITHUB_ENV"
          echo "DECKTALK_VERIFY_MAX_AV_FRAMES=5" >> "$GITHUB_ENV"
          echo "DECKTALK_RECORD_STALL_MS=400" >> "$GITHUB_ENV"
```

## Build a voiced video in CI

Put `ELEVENLABS_API_KEY` and `ELEVENLABS_VOICE_ID` in the job's secrets, and export them to the build step.
DeckTalk never prints either value.

<Warning>A build without voice refuses to run in a project whose take index holds paid takes for the sections it was
asked to write, because replacing those rows would make the next voiced build pay for them again. The refusal names
the sections that are free to rehearse. Give a CI job that builds without voice its own checkout, or its own
`build/` directory.</Warning>

[A build without voice and a voiced build](/guides/rebuild-one-section#a-build-without-voice-and-a-voiced-build) explains why.

## Set the project directory

Every project command takes `--project DIR`. The `DECKTALK_PROJECT` variable sets the default, so a job can run
from the repository root.

```console theme={null}
DECKTALK_PROJECT=lessons/derivatives decktalk build --no-voice
```

## Build offline

A build without voice runs with no network after these steps.

<Steps>
  <Step title="Download the tools">
    On a machine with network, run `install`. It downloads Chromium and ffmpeg.

    ```console theme={null}
    decktalk install
    ```
  </Step>

  <Step title="Create the project">
    Run `init` after `install`. `init` copies the packaged KaTeX into `deck/katex/`.

    ```console theme={null}
    decktalk init my-lesson
    ```
  </Step>

  <Step title="Build the video">
    Run a build without voice in the project directory.

    ```console theme={null}
    decktalk build --no-voice
    ```
  </Step>
</Steps>

In the starter, `deck/index.html` loads KaTeX from `deck/katex/`, before the runtime. A page of your own
that points its KaTeX tags anywhere else leaves its equations as plain text offline, and `record` reports
`KATEX NOT LOADED`, which fails the command. Point the tags at the copy beside the page.

```html deck/index.html theme={null}
<link rel="stylesheet" href="./katex/katex.min.css">
<script src="./katex/katex.min.js"></script>
```

## Next

* **See every exit code:** [CLI](/reference/cli#exit-codes)
* **Fix a failed check:** [Troubleshooting](/help/troubleshooting)
* **Understand a cue result:** [Verify](/reference/verify#results)


# Add a clip section
Source: https://docs.decktalk.ai/guides/clip-section

Play a video clip with its own audio as an opening, between page sections, or as a close.

A clip section plays a video file of your own, with its own audio, as one section of the video. Use this guide
to open on camera, to add B-roll between page sections, or to close on a clip.

## Before you start

The steps use the starter that `decktalk init` writes. The starter is three page sections and no clip, so the
steps below add section 4 as a clip of its own, after the Close.

A clip section names its file with `clip`. `optional = true` plays a titled slate until the file is in place, so
a project can carry a clip section before its clip exists.

## Put a clip in a clip section

These steps add a test clip as section 4 of a new project named `clip-lesson`.

<Steps>
  <Step title="Create a project">
    ```console theme={null}
    decktalk init clip-lesson
    ```
  </Step>

  <Step title="Go into the project">
    ```console theme={null}
    cd clip-lesson
    ```
  </Step>

  <Step title="Add the clip section to decktalk.toml">
    Paste this table after the section 3 table. A clip section has no `page` and no `scene`, and
    `script.md` and `cues.json` say nothing about it, because the clip carries its own sound.

    ```toml decktalk.toml theme={null}
    [[section]]
    number = 4
    chapter = "On camera"
    clip = "media/intro.mov"          # your video, with its own audio
    words = "media/intro.words.json"  # the words spoken inside it, for the captions
    slate_seconds = 4      # a titled slate plays for this long while the file is missing
    optional = true        # plays the slate under --strict until the clip is in place
    ```

    * `clip` names your video file, relative to the project.
    * `words` names a words file for the captions. [Caption the speech in a clip](#caption-the-speech-in-a-clip) explains it.
    * `slate_seconds` sets how long the slate plays while the file is missing.
    * `optional = true` lets `--strict` play the slate. [Build with --strict](#build-with-strict) explains it.
  </Step>

  <Step title="Build the video">
    Run a build without voice.

    ```console theme={null}
    decktalk build --no-voice
    ```

    ```text theme={null}
    [cut ] 01  01.webm (t0 1.4s trimmed) -> 01.mp4  (14.280s)
    [cut ] 02  02.webm (t0 1.44s trimmed) -> 02.mp4  (15.880s)
    [cut ] 03  03.webm (t0 1.44s trimmed) -> 03.mp4  (14.720s)
    section 04: media/intro.mov is missing, so a slate plays for 4s. Drop your clip at that path. The section is optional, so --strict allows the slate
    [cut ] 04  slate -> 04.mp4  (4.000s)
    [cat ] 4 sections, straight cuts
    ```

    Each section gets a `[cut ]` line. The clip file does not exist yet, so section 4 plays a titled slate for its `slate_seconds`.
  </Step>

  <Step title="Put the clip file in place">
    Save your video as `media/intro.mov`. If you have no video, make a 4 s test clip. This command needs
    `ffmpeg` on your PATH.

    ```console theme={null}
    ffmpeg -f lavfi -i testsrc2=size=1920x1080:rate=25 -f lavfi -i sine=frequency=440 -t 4 -pix_fmt yuv420p media/intro.mov
    ```

    * A clip that is not 1920 by 1080 is scaled to fit and padded with black.
    * A clip with no audio track plays silent, and `assemble` prints a warning.
  </Step>

  <Step title="Cut the clip into the video">
    A new clip file changes no narration and no recording, so run only `assemble`.

    ```console theme={null}
    decktalk assemble
    ```

    ```text theme={null}
    [cut ] 03  03.webm (t0 1.44s trimmed) -> 03.mp4  (14.720s)
    [cut ] 04  intro.mov (own audio) -> 04.mp4  (4.000s)
    [cat ] 4 sections, straight cuts
    [mix ] 3 audio input(s) -> clip-lesson.mp4
    section 04: the words file media/intro.words.json is missing, so the clip plays without captions
    ```

    Check that section 4 reads `intro.mov (own audio)`. The mix gains a third input, which is the clip's own
    sound. The test clip has no words file, so that sound has no captions. Then run `decktalk verify` to check
    the video.
  </Step>
</Steps>

## Build with --strict

`--strict` on `build` or `assemble` turns a missing clip into an error. A clip section with `optional = true`
still plays its slate.

Before the test clip was in place, `decktalk assemble --strict` exited 0 and printed this warning for the clip
section.

```text theme={null}
section 04: media/intro.mov is missing, so a slate plays for 4s. Drop your clip at that path. The section is optional, so --strict allows the slate
```

A clip section without `optional = true` stops `--strict` when its file is missing. That is an error rather than a
finding, so the command exits 3 and writes no video.

```text theme={null}
error[MISSING_INPUT]: section 4: clip missing: ~/clip-lesson/media/intro.mov. Put your clip at that path, or set optional = true on the section to play its slate under --strict.
```

`decktalk status` reports the same thing without building. The missing clip is a `MISSING` row, and `status`
exits 1.

```text theme={null}
sections 4, cut 4, final True | 1 certain, 0 uncertain finding(s)
MISSING  media/intro.mov: section 04 names a clip that is not there
```

After your clip is in place, delete the `optional` line. `--strict` then catches the file if it goes missing
later.

## Add a clip section of your own

A section's number sets its place in the video. To add a clip between two page sections, give it the next number
and renumber every section after it.

1. In `decktalk.toml`, add 1 to the `number` of every section after the new clip, from the last one up.

2. Add the clip section's table in its place.

   ```toml decktalk.toml theme={null}
   [[section]]
   number = 4
   chapter = "Interview"
   clip = "media/interview.mp4"
   slate_seconds = 4
   optional = true         # plays the slate under --strict until the clip is in place
   ```

3. In `script.md`, renumber the same headings, and add a heading for the clip.

   ```md script.md theme={null}
   ## 4. Interview

   [The clip at media/interview.mp4 plays here, with its own sound.]
   ```

   The voice speaks nothing in a clip section, so the body can be a stage direction.

4. In `cues.json`, rename each later section key, from the last one up. The cue ids stay the same. They start with
   a scene number, and the scenes of the page do not change.

5. Run `decktalk build`.

A renumbered section keeps its narration. `narrate` finds the take by its hash and copies it to the new file name.

## How the narration splits

`build/narration/narration.mp3` holds the spoken sections back to back, with no gap for a clip. `assemble` splits the
narration at each clip between page sections.

<Frame>
  <img alt="Lanes on one time axis. The narration.mp3 lane holds sections 1, 2, 3, 4, 6, 8, and 9 back to back, with a split before section 6 and another before section 8. The video lane plays the 4 s clip of section 5 after section 4 and the 5.04 s slate of section 7 after section 6, and dashed leads move sections 6, 8, and 9 later. Captions sit under page sections only. Chapters mark the starts of sections 1, 2, 3, 4, and 9, because sections 4 to 8 share one title." />

  <img alt="Lanes on one time axis. The narration.mp3 lane holds sections 1, 2, 3, 4, 6, 8, and 9 back to back, with a split before section 6 and another before section 8. The video lane plays the 4 s clip of section 5 after section 4 and the 5.04 s slate of section 7 after section 6, and dashed leads move sections 6, 8, and 9 later. Captions sit under page sections only. Chapters mark the starts of sections 1, 2, 3, 4, and 9, because sections 4 to 8 share one title." />
</Frame>

* Each part of the narration starts where its first page section starts in the video.
* A slate splits the narration the same way a clip does.
* No caption covers a clip section, unless the section sets `words`. [Caption the speech in a clip](#caption-the-speech-in-a-clip) explains it.
* A clip section gets its own chapter, unless the section before it has the same title.

Example: with a 4 s clip in section 5, section 6 starts about 4 s later in the final mp4 than it does on the
narration clock, plus the frame rounding of every cut before it. `decktalk status` prints the narration times
and `build/out/cuts.json` the final ones. [Build artifacts](/reference/artifacts#time-bases) explains the two
time bases.

```text theme={null}
  01  deck/index.html?scene=1                  rec cut
  02  deck/index.html?scene=2                  rec cut
  03  deck/index.html?scene=3                  rec cut
  04  clip media/intro.mov                         cut
```

The narration does not depend on the length of a clip. After you replace a clip file, run only `decktalk assemble`,
then `decktalk verify`.

## The clip's sound

The clip's own audio joins the mix at its section start.

* The audio is trimmed to the clip's picture.
* The audio fades in and out over 20 ms, so a cut never clicks.
* The narration is silent while the clip plays.
* The music ducks under the whole clip. [Sound](/concepts/sound#ducking) explains ducking.

`verify` checks the start of a clip section, but a clip section has no cut row. The click search of the a/v check
never reaches into a clip's audio.

## Caption the speech in a clip

The captions come from the narration's word times, so a clip's own speech has no captions by default. Set
`words` on the clip section to caption it.

1. Write a words file for the clip. It is a JSON list with one object per word, in seconds after the clip starts.

   ```json media/interview.words.json theme={null}
   [
     { "word": "Watch", "start": 0.15, "end": 0.42 },
     { "word": "it.", "start": 0.48, "end": 0.71 }
   ]
   ```

   Give each word its own punctuation and case. The captions break at the sentence ends it marks.

2. Name the file in the clip section.

   ```toml decktalk.toml theme={null}
   [[section]]
   number = 4
   chapter = "Interview"
   clip = "media/interview.mp4"
   words = "media/interview.words.json"
   ```

3. Run `decktalk assemble`.

* A word that starts after the clip's picture ends has no caption.
* A slate or a clip with no audio track has no captions.
* If the words file is missing, `assemble` prints a warning and the clip has no captions.

A `<hash>.words.json` file from `build/narration` has this format. `decktalk clip` writes the words file of a clip that
it cuts from a build. [Cut a clip from a build](#cut-a-clip-from-a-build) shows how.

## Cut a clip from a build

`decktalk clip` cuts a span of a built page section into a clip and its words file. Use it to play part of the video
again in a clip section, such as the Open's count inside a later scene.

These steps use a project after `decktalk build --no-voice`. After a voiced build, the clip carries the real voice.

<Steps>
  <Step title="Find the span">
    Print the words of section 1 with their times, in seconds after the section starts.

    ```console theme={null}
    decktalk words --only 1
    ```

    ```text theme={null}
    sections 1, words 26
    == 01 Open  (14.29s, lead 0.5s, estimated)
      start     end  word
      0.500   0.961  This
      0.981   1.442  is
      1.462   1.922  DeckTalk.
      1.942   2.403  You
      2.423   2.884  write
      2.904   3.365  what
      3.385   3.845  you
      3.865   4.326  will
      4.346   4.807  say,
    ```

    The opening sentence runs from the start of "This" at 0.500 s to the end of "DeckTalk." at 1.922 s.
  </Step>

  <Step title="Cut the clip">
    ```console theme={null}
    decktalk clip 1 --start 0.48 --end 1.92 --hold 0.5 --out media/open-line.mp4
    ```

    ```text theme={null}
    section 01: the span cuts the word 'DeckTalk.' in two, so the words file leaves it out
    section 01: the narration is a silent placeholder, so the word times are estimates
    seconds 1.92, words 2 | 0 certain, 1 uncertain finding(s)
    wrote media/open-line.mp4  (1.92s: frames 12 to 47 of sections/01.mp4, 0.48 to 1.92s, hold 0.48s, gain +0 dB)
    wrote media/open-line.words.json  (2 words)
    use it in a clip section: clip = "media/open-line.mp4" and words = "media/open-line.words.json"
    ```

    * The picture comes from `build/sections/01.mp4`. `--start` and `--end` round to whole frames, so the span
      ran to 1.92 s rather than 1.93 s.
    * The sound is section 1's narration over the same span. `--hold 0.5` adds 0.48 s of the last frame in silence.
    * `media/open-line.words.json` lists the two whole words inside the span, in seconds after the clip starts.
    * The frame grid put the end inside "DeckTalk.", so that word is left out of the words file and `clip` reports
      it as an uncertain finding. Move `--end` into the silence beside the word to keep it.
  </Step>

  <Step title="Play the clip in a clip section">
    Add a clip section that names both files, and renumber the sections after it as
    [Add a clip section of your own](#add-a-clip-section-of-your-own) describes.

    ```toml decktalk.toml theme={null}
    [[section]]
    number = 4
    chapter = "The opening line again"
    clip = "media/open-line.mp4"
    words = "media/open-line.words.json"
    ```

    Then run `decktalk assemble`, and check that the section reads `open-line.mp4 (own audio)`.
  </Step>
</Steps>

* `--gain` changes the clip's level in dB, so a clip cut from another build can match the voice around it.
* The clip keeps the section's full picture, so a clip cut from a slide plays that whole slide.
* [`decktalk clip`](/reference/cli#decktalk-clip) lists every option.

## Keep one chapter across several sections

Each section starts a chapter. Consecutive sections with the same `chapter` share one chapter instead, so a page
section, a clip and the page section after it can read as one part of the video.

## Choose where the clip plays

A clip section can sit anywhere in the order of sections.

| Position                      | Example              | What the narration does                                                                      |
| ----------------------------- | -------------------- | -------------------------------------------------------------------------------------------- |
| Before the first page section | section 0            | The narration starts with the first page section, after the clip.                            |
| Between two page sections     | a clip in the middle | The narration pauses for the clip. It continues on the first frame of the next page section. |
| After the last page section   | a closing clip       | The narration has ended before the clip starts.                                              |

* `cues.json` names the cues of a section by its section number, such as `"4"`.
* A section's `scene` names the scene in the page, and the cue ids of that section start with a slide id of that
  scene. A page keeps its scene numbers when a clip section renumbers the sections around it, so a section number
  and its scene can differ.
* If you add or remove a clip section, renumber the sections in `decktalk.toml`, `script.md`, and `cues.json`. The
  pages stay the same.
* `hold_seconds` on a page section pauses the narration too, the same way a clip does.

## Open the video on a clip

These steps add a section 0 to a project, such as `my-lesson` from the [quickstart](/quickstart). Section 0
comes before section 1, so it needs no renumbering.

<Steps>
  <Step title="Add section 0 to decktalk.toml">
    Put this table above the section 1 table.

    ```toml decktalk.toml theme={null}
    [[section]]
    number = 0
    chapter = "On camera"
    clip = "media/open.mp4"
    slate_seconds = 6       # a titled slate plays for this long when the file is missing
    ```
  </Step>

  <Step title="Dip the cut out of the clip to black">
    In the existing `[transition]` table, change `dips = []` to `dips = [[0, 1]]`.

    ```toml decktalk.toml theme={null}
    dips = [[0, 1]]
    ```

    `dips` lists each cut that dips to black, as a `[from, to]` pair of section numbers. The starter sets
    `dips = []`, so every cut is straight. If you delete the key, every cut dips.
  </Step>

  <Step title="Add a heading to script.md">
    Add `## 0. On camera` above section 1. A clip section needs no heading, but the heading keeps the script in
    the order of the video.

    ```md script.md theme={null}
    ## 0. On camera

    [Your clip at media/open.mp4 plays here, with its own sound.]

    ## 1. Open
    ```
  </Step>

  <Step title="Put the clip file in place">
    Save your video as `media/open.mp4`.

    If the file is not ready, skip this step. A missing clip plays a titled slate for `slate_seconds`, with the
    section's chapter and the path where the file belongs.
  </Step>

  <Step title="Build the video">
    Run a build without voice.

    ```console theme={null}
    decktalk build --no-voice
    ```

    ```text theme={null}
    section 00: media/open.mp4 is missing, so a slate plays for 6s. Drop your clip at that path
    [cut ] 00  slate -> 00.mp4  (6.000s)
    [cut ] 01  01.webm (t0 1.44s trimmed) -> 01.mp4  (14.280s)
    ```

    Section 0 has no `optional` key, so its warning ends with `Drop your clip at that path`. `--strict` fails
    on this section until the file exists.
  </Step>
</Steps>

## Next

* **Look up every section key:** [decktalk.toml](/reference/decktalk-toml)
* **Rebuild after you replace a clip:** [Rebuild one section](/guides/rebuild-one-section)
* **Understand the mix:** [Sound](/concepts/sound)


# Design a slide
Source: https://docs.decktalk.ai/guides/design-a-slide

Size the elements of a slide, choose a reveal effect for each one, and add a camera push.

This guide shows how to size a slide, choose a reveal effect for each element, and add a camera
push. Use it when you write or change the scenes of a page.

## Before you start

You need a page that includes `decktalk-runtime.js`, such as the starter's `deck/index.html`.
[Your first deck](/guides/first-deck) shows how to add a scene to it.

## Size the slide

Size every element in CSS pixels, on a frame of 1920 by 1080.

```css deck/index.html theme={null}
.eyebrow { left: 120px; top: 80px; font: 600 24px/32px var(--mono); letter-spacing: .16em; text-transform: uppercase; color: var(--mute); }
.title { left: 120px; width: 1680px; font: 700 96px/1.06 var(--sans); letter-spacing: -.03em; }
```

The runtime draws each slide inside the stage element, `#dt-stage`. The stage element is 1920 by
1080 CSS pixels. The runtime scales it to fit the window and centers it. So a size in your CSS is a
size on the video frame.

| Element             | Suggested size                                   | In the starter's `deck/index.html`                                         |
| ------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- |
| Side margin         | 96 px or more, and 120 px for titles             | 120 px                                                                     |
| Body text           | 36 px or more                                    | 44 px for the card values in scene 1                                       |
| Headlines           | 64 px or more                                    | 96 px for the titles of scenes 1 and 3, and 76 px for the title of scene 2 |
| Eyebrows and labels | 22 px, in the monospace face and the muted color | 24 px monospace, in `--mute`                                               |

<Note>`[video] width` and `height` change only the browser window and the encoded frame. A frame
with another aspect ratio letterboxes the stage element, and the slides do not reflow.</Note>

A page can supply its own `<div id="dt-stage">`, and the runtime uses it. The lesson example's
`deck/lesson.html` does this to build one figure under all of its slides.

Put one idea on each slide. A slide with more than three or four reveals is hard to follow. If a
slide is busy, split it into two slides.

## Make each reveal big enough to measure

A reveal has to change about 0.3 percent of the frame to clear `verify`'s warning, and about 0.1
percent to pass at all. On a 1920 by 1080 frame that is 6,220 pixels for the warning and 2,073 for
the pass, which is roughly an 80 by 80 solid block and a 46 by 46 one. Design against the larger
number, because a reveal that only just passes in `preflight` can fail on the recording.

| Changed share of the frame | What `preflight` and `verify` say                                      |
| -------------------------- | ---------------------------------------------------------------------- |
| Below 0.1 percent          | `NO CHANGE`, a certain finding. The command exits 1.                   |
| 0.1 to 0.3 percent         | `THIN CHANGE?`, an uncertain finding. It exits 1 only with `--strict`. |
| Above 0.3 percent          | `changed`.                                                             |

Both checks compare luma alone, so brightness is what counts and hue is not. A reveal that swaps one
colour for another of the same lightness changes nothing they can see, and it also disappears for a
viewer with low vision. Change the lightness as well as the hue, or fill a shape rather than tint
one.

The starter's own slides are filled cards and bands rather than text on white for this reason. A
line of 44 px text is a few hundred pixels of ink, well under the floor, so give a small reveal a
filled container that appears with it.

Keep every cued element out of the bottom 15 percent of the frame, which is 162 px of a 1080 px
frame. A player draws captions there, so an element that appears in that band can be covered at the
moment it appears. `preflight` reports one as `IN CAPTION BAND?` from the measured box, which is
uncertain because a deck may put something there on purpose, so `--strict` is how a project says the
band is reserved. The starter puts its lowest band at `top: 720px`, which ends about 840 px down,
clear of the band.

## Choose a reveal effect

Set `data-reveal` on an element to choose the animation it plays when it appears.

```html deck/index.html theme={null}
<p class="line" data-cue="2.1average">A line of text</p>
<div class="code" data-cue="2.1code" data-reveal="fade">decktalk build</div>
<p class="answer" data-cue="2.1waited" data-reveal="pop">2x</p>
```

An element with no `data-reveal` uses `rise`. The table shows what each reveal effect does and where it
works well.

| Effect    | Motion                                                                  | Use it for                                                                    | Avoid it for                                                                       |
| --------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `rise`    | `rise` moves the element up 10 px as it fades in over 0.3 s.            | Use it for lines of text, labels, and cards.                                  | Avoid it for code, tables, and grids. There, the motion looks like a layout shift. |
| `fade`    | `fade` fades the element in over 0.3 s.                                 | Use it for code lines, chat bubbles, images, and anything that must not move. | Avoid it for one small element on a large slide. A viewer can miss a small fade.   |
| `draw`    | `draw` draws the stroke of an SVG path over 0.3 s, at a constant speed. | Use it for an SVG path with `pathLength="1"`.                                 | Avoid it for a filled shape. Only the stroke draws, and the fill shows at once.    |
| `drop`    | `drop` moves the element down 24 px as it fades in over 0.35 s.         | Use it for a tile or a stamp.                                                 | Avoid it for body text. The motion is too large for text.                          |
| `pop`     | `pop` scales the element from 60% past 108% to 100% over 0.5 s.         | Use it for the one result that the section builds to.                         | Avoid it for more than one element per slide. Two pops compete for attention.      |
| `dim`     | `dim` starts visible and fades the element to 16% opacity over 1.2 s.   | Use it for an element that recedes when its cue fires.                        | Avoid it for an element that has not been on screen long enough to notice.         |
| `instant` | `instant` shows the element on the frame of its cue, with no animation. | Use it for a cursor, a highlight, or a part of a figure.                      | Avoid it for text. A hard cut can look like a glitch.                              |

Set `data-duration` in seconds to change the length of an effect. Keep effects short, so each reveal is
visible on its word and not still moving on the next word. To show math, add
[`data-tex`](/reference/runtime#data-tex).

A `dim` reveal is the one effect that lowers brightness rather than raising it. The checks read the
size of the change and not its direction, so a `dim` that drops a large element to 16 percent opacity
clears the floor as readily as a reveal that appears.

## Check a slide before you record it

`decktalk preflight` freezes each slide before and at each cue and reports the changed share, with no
recording and no spend. Run it as soon as a slide is drawn.

```console theme={null}
decktalk preflight --only 4
```

```text theme={null}
check              slide       cue   chg %  result
4:4.1bowl          4.1        7.89    0.49  changed
4:4.1p0            4.1       12.33    0.11  THIN CHANGE?
4:4.1rule          4.1       22.68    0.45  changed
4:4.1over          4.1       39.94    0.73  changed
```

The frozen PNG files go under `build/preflight/NN/`, one per cue, named for the slide and the cue.
Open the two frames of any row you want to judge by eye. `decktalk screenshots --slide 4.1 --after
4.1rule` writes the same frozen state on its own.

## Add a camera push

Set `data-camera="push"` on a scene wrapper to zoom the stage element slowly from 100% to 103%.

```html deck/index.html theme={null}
<div data-scene="1" data-name="Open" data-camera="push">
  <template data-slide="1.1" data-hold="14">…</template>
</div>
```

A scene a script declares sets `camera: "push"` in its `DeckTalk.scene` call instead.

The push lasts the whole scene, and at least 4 s. Freeze mode shows no push.
[Scene fields](/reference/runtime#scene-fields) gives the exact length.

Use a push on one scene at most, such as the open. A push under every scene makes the whole video
move. `decktalk verify` removes the push from each probe's margin with the
[control share](/reference/verify#control-share). Its onset rule ignores the slow growth of the
push. The push still raises each probe's changed share.

## Next

* **Copy a complete slide:** [Slide recipes](/guides/slide-recipes)
* **Look up every attribute:** [Runtime](/reference/runtime#data-attributes)
* **Learn how a page plays:** [The page contract](/concepts/page-contract)


# Your first deck
Source: https://docs.decktalk.ai/guides/first-deck

Write one section in the four input files, then build it and verify its reveals.

This guide writes one section of a deck in the four files you write. Use it after the [quickstart](/quickstart), when you are ready to make a section of your own.

The section is a short lesson on gradient descent. Its slide draws a bowl in SVG and typesets the update rule with KaTeX.

## Before you start

Start from the starter, and add to it. Nothing has to be deleted first.

1. Create a project with `decktalk init my-lesson`. The starter puts the runtime and KaTeX in `deck/`.
2. Go into the project with `cd my-lesson`.

The starter has sections 1, 2 and 3 on `deck/index.html`, with one scene each. The steps below add a
section 4, with a scene of its own on the same page, after the starter's Close.

Declare each scene number only one time in a page. A second `[data-scene="4"]` wrapper replaces the
first, and no warning appears.

## How the four files connect

One section number and one cue id tie the four files together.

| In                | Name                                                       | Refers to                                                     |
| ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------- |
| `script.md`       | `## 4.`                                                    | the section number                                            |
| `decktalk.toml`   | `number = 4`, `scene = 4`                                  | the same section, and the scene the page plays for it         |
| `cues.json`       | `"4"`, `"cue": "4.1rule"`                                  | the section, and a cue id that the page knows                 |
| `deck/index.html` | `data-scene="4"`, `data-slide="4.1"`, `data-cue="4.1rule"` | the scene, its slide, and the element that appears on the cue |

The `narrate` stage also writes a words file for the section, with the start and end of every spoken word. The `align` stage matches each cue phrase against those spoken words.

## Write the section

<Steps>
  <Step title="Add the script to script.md">
    Paste this section into `script.md`, after section 3.

    ```md script.md theme={null}
    ## 4. Gradient descent

    [Deck scene 4. A loss bowl draws, a point steps down it, and the update rule appears.]

    Now a short lesson. Here is gradient descent, at a high level. [beat] Start with a loss
    surface. For this lesson it is a bowl. [beat] Pick a point anywhere on it. [beat] The gradient
    says which way is uphill, so take a step the other way. [beat] The learning rate sets
    the size of that step. [beat] Step again. [beat] And again, and each step is smaller as
    the slope flattens out.

    [beat] Pause and think: what happens if the learning rate is too large?

    [pause 3]

    You overshoot, and bounce from side to side. [beat] Too small, and you crawl. [beat] Just
    right, and you settle at the bottom.
    ```

    Each `## N. Title` heading starts a section. The voice does not speak text in square brackets. `[beat]` makes a short pause, and `[pause 3]` asks the voice for three seconds of silence. [script.md](/reference/script-md) lists every rule.
  </Step>

  <Step title="Add the section to decktalk.toml">
    Paste this table after the section 3 table.

    ```toml decktalk.toml theme={null}
    [[section]]
    number = 4
    chapter = "Gradient descent"
    page = "deck/index.html"
    scene = 4
    ```

    Every script section needs one `[[section]]` table with the same `number`. `page` names the page, and `scene` names the scene that the page plays. [decktalk.toml](/reference/decktalk-toml) lists every key.
  </Step>

  <Step title="Add the cues to cues.json">
    Add this entry under `"sections"`.

    ```json cues.json theme={null}
    "4": {
      "min_seconds": 30,
      "cues": [
        { "cue": "4.1", "on": "$start" },
        { "cue": "4.1bowl", "on": "loss surface" },
        { "cue": "4.1p0", "on": "Pick a point" },
        { "cue": "4.1p1", "on": "take a step" },
        { "cue": "4.1rule", "on": "learning rate", "occurrence": 1 },
        { "cue": "4.1p2", "on": "Step again" },
        { "cue": "4.1p3", "on": "And again" },
        { "cue": "4.1think", "on": "Pause and think" },
        { "cue": "4.1over", "on": "overshoot" },
        { "cue": "4.1settle", "on": "settle", "offset": 0.2 }
      ]
    }
    ```

    Each reveal starts on one phrase:

    * The bowl draws on "loss surface".
    * Each move of the point starts on the phrase that names it, such as "take a step".
    * The update rule appears on "learning rate", and names its occurrence because the section
      says the phrase twice.
    * The overshoot path draws on "overshoot".
    * The settled point appears 0.2 s after the start of "settle", because its offset key is 0.2.

    The `4.1` cue on `$start` only mounts the slide at 0.0 s, so both checks skip it: `decktalk preflight` as `NO_SLIDE`, because the slide declares no element for it, and `decktalk verify` as `REFERENCE_CLAMPED`, because no frame comes before 0.0 s. Neither skip fails. If the speech is shorter than `min_seconds`, `decktalk align` reports an uncertain finding. [Cues](/concepts/cues) explains how phrases match.
  </Step>

  <Step title="Add the scene to deck/index.html">
    Paste the CSS into the page's `<style>` element, and the scene just before `</body>` in `deck/index.html`.

    <Tip>Markup in a `<template data-slide>` is not a JavaScript string, so a backslash is written once, and
    `${` and a backtick are ordinary characters. That is the reason to write a slide as markup rather than as a
    [`render`](/reference/runtime#slide-fields) function.</Tip>

    ```html deck/index.html theme={null}
    <style>
      .row { position: absolute; left: 120px; top: 200px; right: 120px; display: flex; gap: 64px; align-items: flex-start; }
      .row .text { flex: 1; }
      .h2 { margin: 0 0 16px; font: 600 64px/1.1 var(--sans); letter-spacing: -.02em; color: var(--ink); }
      .note { margin: 0; font-size: 36px; line-height: 1.3; color: var(--mute); }
      .math { margin: 40px 0; font-size: 58px; color: var(--ink); }
      .ax { stroke: var(--mute); stroke-width: 2; }
      .curve { fill: none; stroke: var(--accent); stroke-width: 6; stroke-linecap: round; }
      .zig { fill: none; stroke: var(--mute); stroke-width: 4; stroke-dasharray: 12 10; }
      .step circle { fill: var(--accent); }
      .step line { stroke: var(--ink); stroke-width: 4; }
      .step .ring { fill: none; stroke: var(--accent); stroke-width: 3; }
    </style>
    <div data-scene="4" data-name="Gradient descent">
      <template data-slide="4.1" data-hold="26"
                data-preview="4.1bowl@0.5 4.1p0@3 4.1p1@5 4.1rule@7 4.1p2@9 4.1p3@11 4.1think@13 4.1over@17 4.1settle@21">
        <div class="row">
          <svg viewBox="0 0 1000 520" width="1000" height="520" style="overflow:visible">
            <line class="ax" x1="60" y1="470" x2="960" y2="470"/>
            <line class="ax" x1="60" y1="40" x2="60" y2="470"/>
            <path class="curve" pathLength="1" data-cue="4.1bowl" data-reveal="draw" data-duration="1.6"
                  data-describe="a loss bowl draws from left to right" d="M80,70 Q510,880 940,70"/>
            <path class="zig" pathLength="1" data-cue="4.1over" data-reveal="draw" data-duration="1.4"
                  data-describe="a zigzag path bounces from side to side" d="M190,200 L830,200 L230,320 L790,320 L300,410"/>
            <g class="step" data-cue="4.1p0" data-reveal="pop"><circle cx="190" cy="200" r="26"/></g>
            <g class="step" data-cue="4.1p1" data-reveal="pop"><line x1="190" y1="200" x2="330" y2="330"/><circle cx="330" cy="330" r="26"/></g>
            <g class="step" data-cue="4.1p2" data-reveal="pop"><line x1="330" y1="330" x2="420" y2="405"/><circle cx="420" cy="405" r="26"/></g>
            <g class="step" data-cue="4.1p3" data-reveal="pop"><line x1="420" y1="405" x2="470" y2="440"/><circle cx="470" cy="440" r="26"/></g>
            <g class="step" data-cue="4.1settle" data-reveal="pop"><circle cx="510" cy="453" r="34"/><circle class="ring" cx="510" cy="453" r="52"/></g>
          </svg>
          <div class="text">
            <h2 class="h2">Gradient descent</h2>
            <p class="note">Follow the slope downhill, one step at a time.</p>
            <div class="math" data-cue="4.1rule" data-tex-display data-tex="\theta_{t+1} = \theta_t - \eta\,\nabla L(\theta_t)"
                 data-describe="the update rule for gradient descent">θ(t+1) = θ(t) − η ∇L(θ(t))</div>
            <p class="note" data-cue="4.1think" data-reveal="fade">Pause and think: what if the learning rate is too large?</p>
          </div>
        </div>
      </template>
    </div>
    ```

    * A `[data-scene]` wrapper is a scene, and each `<template data-slide>` inside it is one slide. The wrapper never draws.
    * Slide `4.1` owns every cue here, because every cue id starts with the slide id. `data-preview` says only when each one fires in a browser preview.
    * An element with `data-cue` stays hidden until its cue fires. `data-reveal` picks its reveal effect, and `data-describe` says in a sentence what the reveal shows.
    * The bowl path has `pathLength="1"` and `data-reveal="draw"`, so its stroke draws over `data-duration` (1.6 s).
    * KaTeX typesets the `data-tex` element. The plain text inside the element is the fallback.

    The scene brings its own CSS, because the starter's stylesheet styles only its own classes. [Runtime](/reference/runtime) lists every attribute.
  </Step>
</Steps>

## Look before you build

Check the slide in a browser and in screenshots before you record it. [Browser preview and recording](/concepts/page-contract#browser-preview-and-recording) says which page values a browser preview uses and which values the recording uses.

1. Run `decktalk serve` and follow the URL it prints. That is the origin the recorder uses.
2. Open `deck/index.html?slide=4.1` there. The slide mounts with every element visible.
3. Open `deck/index.html?scene=4&hud=1`. The scene plays in preview, with the clock on top.
4. Take a screenshot of every slide with `decktalk screenshots`. The PNG files go under `build/screenshots/`.
5. Estimate every reveal with `decktalk preflight --only 4`. It freezes the page before and at each cue, and flags a
   reveal too small for `verify` as `THIN CHANGE?` or `NO CHANGE`.

```text theme={null}
check              slide       cue   chg %  result
4:4.1              4.1        0.00       -  skipped NO_SLIDE: slide 4.1 declares no element for the cue
4:4.1bowl          4.1        7.89    0.49  changed
4:4.1p0            4.1       12.33    0.11  THIN CHANGE?
4:4.1p1            4.1       19.23    0.16  THIN CHANGE?
4:4.1rule          4.1       22.68    0.45  changed
4:4.1p2            4.1       26.63    0.14  THIN CHANGE?
4:4.1p3            4.1       27.61    0.11  THIN CHANGE?
4:4.1think         4.1       33.53    0.45  changed
4:4.1over          4.1       39.94    0.73  changed
4:4.1settle        4.1       48.03    0.22  THIN CHANGE?
10 cue(s): 4 changed, 5 THIN CHANGE?, 1 skipped. Frozen frames in build/preflight
```

The five point moves and the settled dot change 0.11 to 0.22 percent of the frame, over the 0.1 percent floor that
would read `NO CHANGE` and under the 0.3 percent one that reads `changed`, so `preflight` calls each of them
`THIN CHANGE?`. A larger dot clears the floor. [Design a slide](/guides/design-a-slide#make-each-reveal-big-enough-to-measure)
gives the pixel sizes.

If the project has no voiced build yet, you can also check where each cue phrase resolves. On a voiced project, a `narrate` without voice stops, because it would empty the narration cache. Skip these actions there.

1. Write estimated word times with `decktalk narrate --no-voice`.
2. Print each cue time with `decktalk align`.

```text theme={null}
sec  speech   need  cues
 04    49.8   30.0  4.1@0.0,4.1bowl@7.89,4.1p0@12.33,4.1p1@19.23,4.1rule@22.68,4.1p2@26.63,4.1p3@27.61,4.1think@33.53,4.1over@39.94,4.1settle@48.03
```

Each entry reads `cue id@cue time`, in seconds after the section start. If a phrase is not in the spoken words, `align` prints `phrase not found`, and `build` stops.

## Build and verify

Build the video without an account, then measure the reveals.

1. Build the video with `decktalk build --no-voice`.
2. Measure two cues with `decktalk verify 4:4.1rule 4:4.1over`.

```text theme={null}
check                 cue       at   chg %   ctl %   offset     a/v  result
4:4.1rule           22.68    67.56    0.46    0.00    -40ms   -49ms  changed
4:4.1over           39.94    84.82    0.72    0.00    -60ms   -64ms  changed
```

Both rows read `changed`. The offset column is the time from the cue time to the onset of the reveal, in milliseconds. `decktalk verify` reports `OFF CUE` and exits 1 when that time is outside the offset limit. Only a build without voice gives the `a/v` column, because only the click track has clicks. [Verify](/reference/verify#cues) defines every column.

Run `decktalk verify` with no arguments to check every cue of every section, the section starts and the cuts at once.

If you have an ElevenLabs key in `.env`, run `decktalk build` to voice the video. It spends credits on every section, because the last build had no voice.

## The finished section

These are the four files of the section, in one place.

<CodeGroup>
  ```md script.md theme={null}
  ## 4. Gradient descent

  [Deck scene 4. A loss bowl draws, a point steps down it, and the update rule appears.]

  Now a short lesson. Here is gradient descent, at a high level. [beat] Start with a loss
  surface. For this lesson it is a bowl. [beat] Pick a point anywhere on it. [beat] The gradient
  says which way is uphill, so take a step the other way. [beat] The learning rate sets
  the size of that step. [beat] Step again. [beat] And again, and each step is smaller as
  the slope flattens out.

  [beat] Pause and think: what happens if the learning rate is too large?

  [pause 3]

  You overshoot, and bounce from side to side. [beat] Too small, and you crawl. [beat] Just
  right, and you settle at the bottom.
  ```

  ```toml decktalk.toml theme={null}
  [[section]]
  number = 4
  chapter = "Gradient descent"
  page = "deck/index.html"
  scene = 4
  ```

  ```json cues.json theme={null}
  "4": {
    "min_seconds": 30,
    "cues": [
      { "cue": "4.1", "on": "$start" },
      { "cue": "4.1bowl", "on": "loss surface" },
      { "cue": "4.1p0", "on": "Pick a point" },
      { "cue": "4.1p1", "on": "take a step" },
      { "cue": "4.1rule", "on": "learning rate", "occurrence": 1 },
      { "cue": "4.1p2", "on": "Step again" },
      { "cue": "4.1p3", "on": "And again" },
      { "cue": "4.1think", "on": "Pause and think" },
      { "cue": "4.1over", "on": "overshoot" },
      { "cue": "4.1settle", "on": "settle", "offset": 0.2 }
    ]
  }
  ```

  ```html deck/index.html theme={null}
  <style>
    .row { position: absolute; left: 120px; top: 200px; right: 120px; display: flex; gap: 64px; align-items: flex-start; }
    .row .text { flex: 1; }
    .h2 { margin: 0 0 16px; font: 600 64px/1.1 var(--sans); letter-spacing: -.02em; color: var(--ink); }
    .note { margin: 0; font-size: 36px; line-height: 1.3; color: var(--mute); }
    .math { margin: 40px 0; font-size: 58px; color: var(--ink); }
    .ax { stroke: var(--mute); stroke-width: 2; }
    .curve { fill: none; stroke: var(--accent); stroke-width: 6; stroke-linecap: round; }
    .zig { fill: none; stroke: var(--mute); stroke-width: 4; stroke-dasharray: 12 10; }
    .step circle { fill: var(--accent); }
    .step line { stroke: var(--ink); stroke-width: 4; }
    .step .ring { fill: none; stroke: var(--accent); stroke-width: 3; }
  </style>
  <div data-scene="4" data-name="Gradient descent">
    <template data-slide="4.1" data-hold="26"
              data-preview="4.1bowl@0.5 4.1p0@3 4.1p1@5 4.1rule@7 4.1p2@9 4.1p3@11 4.1think@13 4.1over@17 4.1settle@21">
      <div class="row">
        <svg viewBox="0 0 1000 520" width="1000" height="520" style="overflow:visible">
          <line class="ax" x1="60" y1="470" x2="960" y2="470"/>
          <line class="ax" x1="60" y1="40" x2="60" y2="470"/>
          <path class="curve" pathLength="1" data-cue="4.1bowl" data-reveal="draw" data-duration="1.6"
                data-describe="a loss bowl draws from left to right" d="M80,70 Q510,880 940,70"/>
          <path class="zig" pathLength="1" data-cue="4.1over" data-reveal="draw" data-duration="1.4"
                data-describe="a zigzag path bounces from side to side" d="M190,200 L830,200 L230,320 L790,320 L300,410"/>
          <g class="step" data-cue="4.1p0" data-reveal="pop"><circle cx="190" cy="200" r="26"/></g>
          <g class="step" data-cue="4.1p1" data-reveal="pop"><line x1="190" y1="200" x2="330" y2="330"/><circle cx="330" cy="330" r="26"/></g>
          <g class="step" data-cue="4.1p2" data-reveal="pop"><line x1="330" y1="330" x2="420" y2="405"/><circle cx="420" cy="405" r="26"/></g>
          <g class="step" data-cue="4.1p3" data-reveal="pop"><line x1="420" y1="405" x2="470" y2="440"/><circle cx="470" cy="440" r="26"/></g>
          <g class="step" data-cue="4.1settle" data-reveal="pop"><circle cx="510" cy="453" r="34"/><circle class="ring" cx="510" cy="453" r="52"/></g>
        </svg>
        <div class="text">
          <h2 class="h2">Gradient descent</h2>
          <p class="note">Follow the slope downhill, one step at a time.</p>
          <div class="math" data-cue="4.1rule" data-tex-display data-tex="\theta_{t+1} = \theta_t - \eta\,\nabla L(\theta_t)"
               data-describe="the update rule for gradient descent">θ(t+1) = θ(t) − η ∇L(θ(t))</div>
          <p class="note" data-cue="4.1think" data-reveal="fade">Pause and think: what if the learning rate is too large?</p>
        </div>
      </div>
    </template>
  </div>
  ```
</CodeGroup>

## Next

* **Copy a common slide:** [Slide recipes](/guides/slide-recipes)
* **Make the script time well:** [Writing for the ear](/guides/writing-for-the-ear)
* **Open the video with a clip:** [Add a clip section](/guides/clip-section)


# Write a page by hand
Source: https://docs.decktalk.ai/guides/page-by-hand

Write a page that follows the page contract without decktalk-runtime.js, for a page built with another framework.

Most pages should include `decktalk-runtime.js` and skip this guide. Use this guide only when a page
comes from another framework and cannot include the runtime. It lists what the recorder and
`decktalk screenshots` need, and it shows a small page that does all of it.

## Before you start

You need to write JavaScript. Read [The page contract](/concepts/page-contract) first.

## Meet the needs of the recorder

The recorder drives the page through its URL and a few globals. This table pairs each action of
the recorder with what your page does.

| What the recorder does                                                                            | What your page does                                                                                                                 |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| The recorder opens `page.html?scene=N&cues=id@s,…&t0=signal`, with any `params` from the section. | The page reads `scene` and `cues`. It schedules cue `id` at `s` seconds after the clock starts.                                     |
| The recorder adds `&words=word@s,…` when the section's take has words.                            | The page can use the words to show text one word at a time, or it can ignore them.                                                  |
| The recorder adds `&prevwords=word@s,…` when the section just before has words.                   | A page that opens on the previous section's last frame can read them, or it can ignore them.                                        |
| The recorder awaits `document.fonts.ready`, then `window.__decktalk.ready` when it is a Promise.  | The page sets `window.__decktalk.ready` to a Promise that resolves when the page is ready.                                          |
| The recorder calls `window.DeckTalk.startClock()` one time, at narration t=0.                     | The page starts its clock in that call and nowhere else.                                                                            |
| The recorder reads `window.__decktalk.catalog` after the recording.                               | The page lists at least one scene in `catalog`. A missing or empty list is a page error.                                            |
| `preflight` freezes a slide at and before each cue.                                               | Each catalog entry carries `slides`, the slide ids in page order, and `cues`, each slide id mapped to its cue ids in preview order. |
| The recorder reads `window.__decktalk.warnings`, `frameGaps`, and `spokenLog`.                    | The page adds a string to `warnings` for anything it cannot do. `frameGaps` and `spokenLog` are optional.                           |
| The recorder uses a browser window of `[video] width` by `height`.                                | The page draws at 1920 by 1080, or it scales a 1920 by 1080 element to fit the window.                                              |

The magenta cover belongs to the recorder, so a page needs no cover of its own.
[How it works](/concepts/how-it-works#why-the-cuts-are-exact) explains what the cover does.

## Support decktalk screenshots

`decktalk screenshots` uses the page in three ways:

* It opens the page with no query and reads `window.__decktalk.catalog`. If the page has no catalog, `screenshots` warns and skips the page.
* It opens `?slide=ID` for each slide id in the catalog. With `--after`, it opens `?slide=ID&after=CUE`.
* In frame mode, `screenshots --section N --at S` opens the recorder's URL. It logs `window.__decktalk.fired` with each frame.

`decktalk preflight` also reads `catalog[].cues`, which maps each slide id to its cue ids in preview order. It opens
`?slide=ID&after=CUE` and `?slide=ID&before=CUE`. A scene whose entry carries no `cues` map gets every cue skipped as
`NO_CATALOG`, and a cue that the map does not name is skipped as `NO_SLIDE`, because a freeze stops only at a
listed cue. A page that answers neither parameter is not skipped: it shows every element both times, and each cue
reads `NO CHANGE`.

## Write the minimal page

<Warning>Start the page clock only inside `DeckTalk.startClock()`. A page that starts its clock at
`load` fires every cue early, and every reveal in the video comes before its word.</Warning>

The page below follows the whole contract in about forty lines. It has one scene with one slide, and
each cue shows the element with the matching `data-cue`. Its `ORDER` list is the one place the cue
ids are written, which is what lets freeze mode answer `&after=` and `&before=`.

```html deck/plain.html theme={null}
<!doctype html>
<meta charset="utf-8">
<style>
  html, body { margin: 0; background: #0b0f14; color: #f4f6f8; font: 44px/1.3 Inter, sans-serif; }
  #stage { position: absolute; left: 0; top: 0; width: 1920px; height: 1080px; padding: 100px 160px; box-sizing: border-box; }
  [data-cue] { opacity: 0; transition: opacity .35s; }
  [data-cue].on { opacity: 1; }
  .block { margin-top: 40px; width: 1200px; height: 220px; border-radius: 24px; background: #2c1fea; }
</style>
<div id="stage">
  <h1 data-cue="4.1a">A page by hand</h1>
  <div class="block" data-cue="4.1b"></div>
</div>
<script>
  const ORDER = ["4.1a", "4.1b"];
  const params = new URLSearchParams(location.search);
  const state = { mode: "index", scene: params.get("scene"), slide: "4.1", cues: [], fired: [], warnings: [], origin: null,
                  catalog: [{ scene: "4", name: "By hand", slides: ["4.1"], cues: { "4.1": ORDER } }],
                  now: () => state.origin === null ? -Infinity : (performance.now() - state.origin) / 1000 };
  window.__decktalk = state;
  window.__decktalk.ready = document.fonts.ready;

  const cues = (params.get("cues") || "").split(",").filter(Boolean).map((token) => {
    const at = token.lastIndexOf("@");
    return { id: token.slice(0, at), t: parseFloat(token.slice(at + 1)) };
  });
  state.cues = cues;
  for (const c of cues) if (!document.querySelector(`[data-cue="${c.id}"]`)) state.warnings.push(`unknown cue id ${c.id}`);

  function fire(id) {
    state.fired.push(id);
    document.querySelectorAll(`[data-cue="${id}"]`).forEach((el) => el.classList.add("on"));
  }
  function startClock() {
    if (state.origin !== null) return;
    state.origin = performance.now();
    if (cues.length) state.mode = "cue";
    for (const c of cues) setTimeout(() => fire(c.id), c.t * 1000);
  }
  window.DeckTalk = { startClock };

  if (params.has("slide")) {
    state.mode = "freeze";
    const after = params.get("after"), before = params.get("before");
    const last = after ? ORDER.indexOf(after) : before ? ORDER.indexOf(before) - 1 : ORDER.length - 1;
    ORDER.slice(0, last + 1).forEach(fire);
  } else if (params.get("t0") !== "signal") {
    startClock();   // a browser preview starts at once
  }
</script>
```

## Put the page in a project

These steps add the page as section 4 of the starter that `decktalk init` writes, so nothing already
there has to change.

<Steps>
  <Step title="Save the page">
    Save the page above as `deck/plain.html` in the project.
  </Step>

  <Step title="Add the section to decktalk.toml">
    ```toml decktalk.toml theme={null}
    [[section]]
    number = 4
    chapter = "By hand"
    page = "deck/plain.html"
    scene = 4
    ```

    The scene number, the section number and the cue id prefix agree, which is the rule every project follows.
  </Step>

  <Step title="Add the script and the cues">
    <CodeGroup>
      ```md script.md theme={null}
      ## 4. By hand

      This page follows the contract with no runtime. [beat] It shows one block on its own word.
      ```

      ```json cues.json theme={null}
      "4": { "cues": [
        { "cue": "4.1a", "on": "This page" },
        { "cue": "4.1b", "on": "one block" }
      ] }
      ```
    </CodeGroup>
  </Step>

  <Step title="Resolve the cues">
    ```console theme={null}
    decktalk narrate --no-voice
    decktalk align
    ```

    ```text theme={null}
    sec  speech   need  cues
     04     7.6      -  4.1a@0.5,4.1b@4.94
    ```

    `align` finds each cue id in the page as a quoted literal, so `data-cue="4.1a"` and the `ORDER` list both count.
  </Step>

  <Step title="Check the frozen states">
    ```console theme={null}
    decktalk screenshots --page deck/plain.html
    decktalk preflight --only 4
    ```

    ```text theme={null}
    check              slide       cue   chg %  result
    4:4.1a             4.1        0.50    1.12  changed
    4:4.1b             4.1        4.94   12.69  changed
    2 cue(s): 2 changed. Frozen frames in build/preflight
    ```

    A page that ignores `&after=` and `&before=` shows every element in freeze mode, so each pair of frames is
    identical and every cue reads `NO CHANGE`. That is the check this page's `ORDER` list exists for.
  </Step>

  <Step title="Record the section">
    ```console theme={null}
    decktalk record --only 4
    ```

    ```text theme={null}
    [rec ] section 04 (deck/plain.html?scene=4)  9.2s ...
           build/recordings/04.webm  (t=0 at 1.440s, ok)
    sections 1, recorded 1, kept 0
    ```

    The row reads `ok`, and `t0_method` in `build/recordings/04.json` starts with `cover`. A `NO COVER` there
    means the page started its own clock instead of waiting for `DeckTalk.startClock()`.
  </Step>
</Steps>

The page has no preview timing. A browser preview with `?scene=4` shows nothing until you add
`&cues=4.1a@1,4.1b@2` to the URL. Run `decktalk serve` and open the page from the URL it prints, because
the recorder opens every page over http and not from a `file://` URL.

## Compare with the runtime

The runtime gives a page more than this minimal page does:

* an index of scenes and slides
* preview timing from `hold` and `data-delay`
* reveal effects, count-ups, typewriting, and word sync
* KaTeX typesetting, with a wait for the library
* a camera push
* a warning for each mismatch between cues and slides
* a list of gaps between animation frames

[Runtime](/reference/runtime) lists all of it. A page by hand can add any of these features.

## Next

* **Learn how a page plays:** [The page contract](/concepts/page-contract)
* **Look up the runtime's fields:** [Runtime](/reference/runtime#window-__decktalk)
* **Write a page with the runtime:** [Your first deck](/guides/first-deck)


# Rebuild one section
Source: https://docs.decktalk.ai/guides/rebuild-one-section

Find what an edit runs again, and rebuild only the sections you changed.

After an edit, `decktalk build` voices again only the sections whose text changed. Use this guide to find
what an edit runs again, and to rebuild only the sections you changed.

## Before you start

Check which kind of build the project had last, because you run the same kind again.

```console theme={null}
decktalk status
```

After a [build without voice](/concepts/how-it-works#the-build-without-voice), the narration total ends in
`(estimated: silent placeholders)`. After a voiced build, it does not. If you run the other kind, read
[A build without voice and a voiced build](#a-build-without-voice-and-a-voiced-build) first.

## Find the command for your edit

Find your edit in the first column. `N` is the number of the section you changed.

| You changed                                                        | Run                                                                                                                                                                                       |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A sentence in section N of `script.md`                             | `decktalk build --only N`                                                                                                                                                                 |
| The title in the heading of section N                              | `decktalk build --only N`                                                                                                                                                                 |
| A cue of section N in `cues.json`                                  | `decktalk build --only N`                                                                                                                                                                 |
| A slide in the scene that section N plays                          | `decktalk build --only N`, with one `--only` for each section that plays that scene                                                                                                       |
| The head, a style, a script or the runtime file of a page          | `decktalk build` with one `--only N` for each section that plays that page, such as `decktalk build --only 1 --only 9`, because those parts sit outside every scene and reach all of them |
| `record_margin_seconds` on section N                               | `decktalk build --only N`                                                                                                                                                                 |
| `lead_seconds` or `tail_seconds` on section N                      | `decktalk build --only N`                                                                                                                                                                 |
| The voice id, the model, the output format, or a `[voice]` setting | `decktalk build`                                                                                                                                                                          |
| A clip file, `hold_seconds`, `[transition]`, or `[mix]`            | `decktalk assemble`, then `decktalk verify`                                                                                                                                               |

After a build without voice, add `--no-voice` to each `decktalk build` command.

A page can show the words of the section before it, which it reads from
[`prevwords`](/reference/runtime#url-parameters). The starter's pages do not, but a page of yours that opens on
the previous section's last frame does. After an edit to section 1, record such a section 2 as well.

```console theme={null}
decktalk build --only 1,2
```

<Frame>
  <img alt="Three section columns cross three lanes above an assemble bar. Every section is a page section. In the narrate lane, section 1 reads voiced and the other page sections read cached. A plain build records every page section. With --only 1, section 1 reads recorded and the other page sections read kept. The assemble bar spans all three sections." />

  <img alt="Three section columns cross three lanes above an assemble bar. Every section is a page section. In the narrate lane, section 1 reads voiced and the other page sections read cached. A plain build records every page section. With --only 1, section 1 reads recorded and the other page sections read kept. The assemble bar spans all three sections." />
</Frame>

## What each edit runs again

The next table gives the reason for each row of the first table.

| You changed                                                | Voiced again  | Recorded again                   | Why                                                                                     |
| ---------------------------------------------------------- | ------------- | -------------------------------- | --------------------------------------------------------------------------------------- |
| A sentence in section N                                    | section N     | section N                        | The cache key includes the exact text of the section.                                   |
| The heading title of section N                             | none          | none                             | A take is named by its content hash, so the heading is display only.                    |
| A cue of section N                                         | none          | section N                        | The page receives its cue times when `record` opens it.                                 |
| A slide in the scene that section N plays                  | none          | section N                        | The hash covers that one scene's markup, so no other section of the page moves.         |
| The head, a style, a script or the runtime file of a page  | none          | each section that plays the page | Those parts are shared by every scene, so the hash of every section of that page moves. |
| `record_margin_seconds` on section N                       | none          | section N                        | The recording length changes.                                                           |
| `lead_seconds` or `tail_seconds` on section N              | none          | section N                        | The section span changes. `narrate` places the silence without a request.               |
| The voice id, model, output format, or a `[voice]` setting | every section | every section                    | The cache key includes each of them, so every word time moves.                          |
| A clip file, `hold_seconds`, `[transition]`, or `[mix]`    | none          | none                             | Only `assemble` reads them.                                                             |

A recording stays valid when a neighbor section changes length. Cue times count from the start of their
own section, so a longer section 2 does not move a cue in section 3. A page that reads `prevwords` is the
exception. It shows the words of the section before it, so record it again after that section changes.

## The narration cache

The narration cache is the narration directory itself. A take is named by its content hash, made from these
values:

* the speech provider's name and the voice id
* the model and the output format
* the voice settings
* the exact text sent for the section

The `narrate` stage sends nothing for a section when the mp3 and the words file of its hash are both on
disk. `build/narration/takes.json` then says which section plays which take.

The hash leaves out the text of the neighbor sections, so an edit never voices a neighbor again.

The hash also leaves out the section number and the heading. Inserting a section, renumbering one, or
retitling one moves no file and voices nothing, and two sections with the same words share one take. No
silence DeckTalk adds is inside a take: every section's lead and tail are placed when the takes are joined,
from the take and that section's own keys alone, so a take is free to move and a section reused beside an
edited one lands exactly where it did.

Set [`[narration] cache_dir`](/reference/configuration#narration) to keep the take files outside `build/`,
where a fresh clone and a second worktree find them again. A hash names each one, so several projects may
share one such directory. The take index and `narration.mp3` stay under `build/narration/`, because they
belong to one project.

A section that is voiced again costs the characters of its whole text, not only the changed sentence.
[Requirements](/requirements#what-spends-credits) lists every command that spends credits.

## The recording cache

`record` has a cache of its own, and it needs no flag. The recording log of each section carries
`input_hash`, the digest of the markup of the one scene the section plays, the rest of its page file,
its cues, its spoken words, the frame geometry and every local file the page loaded, which the log
lists under `assets`. A section whose hash has not moved keeps its webm and is not recorded again.

The scene is the `[data-scene]` element the section plays, read from the page source as you wrote it,
so no browser has to open for a run to know which recordings still stand. A page that builds its
scenes in script instead, with `DeckTalk.scene(N, …)`, has no such element to cut out, so every
section of that page is keyed on the whole file. A section you leave out of `--only` whose scene or
whose shared page did move is reported as `INCONSISTENT`, and the film keeps the recording made
before the edit.

```text theme={null}
[rec ] section 01  kept: its scene, the page around it, its assets, words and cues are unchanged
[rec ] section 02  kept: its scene, the page around it, its assets, words and cues are unchanged
[rec ] section 03  kept: its scene, the page around it, its assets, words and cues are unchanged
sections 3, recorded 0, kept 3
```

So a plain `decktalk build` records only what changed. `--only` is for the other direction: it records
the sections you name whether they changed or not, which is how you take a bad recording again.

## Limit a build to some sections

Pass `--only` with a section number. It also takes a comma list and a range, and the flag repeats, so these four
lines name the same kind of thing.

```console theme={null}
decktalk build --only 3
decktalk build --only 3,6
decktalk build --only 7-9
decktalk build --only 3 --only 6
```

`--only` means the same on every command that works per section, which is `build`, `narrate`, `record`,
`preflight`, `verify` and `words`.

The flag limits `record` to the sections you name, and records them whether or not they changed. Without it, `record` keeps every section whose scene, shared page, loaded files, words and cues are unchanged. The other stages still work on
every section:

* `narrate` voices any section whose text changed, even a section you did not name.
* `assemble` cuts and joins every section, because the final mp4 needs all of them.
* The verify stage checks every section start and every cut.

Name every section whose text or scene changed, and every section of a page whose head, styles or
scripts you changed. A section you leave out keeps its old recording, even if its words moved.
`--only` needs a page section, because a clip section has no recording.

## Record one section again

Use these steps when a recording of section `N` is bad, for example after `STALLED` or `TRUNCATED`. The
steps voice nothing when the text is unchanged, and they keep every other recording.

<Warning>`decktalk build --no-voice` stops when a section it would write already holds a paid take, and names
the sections that are free to rehearse. Use `--only` with those, which is how you rehearse a new section of a
film you have already paid for.</Warning>

<Steps>
  <Step title="Build the section again">
    If the last build was voiced, run this command.

    ```console theme={null}
    decktalk build --only N
    ```

    If the last build had no voice, run `decktalk build --no-voice --only N` instead.
  </Step>

  <Step title="Measure the cues of the section">
    The build checks section starts, cuts, and cut continuity, but not cues. Run `decktalk verify` for the cues.

    ```console theme={null}
    decktalk verify --only N
    ```

    Every cue row of section `N` reads `changed` or `skipped`.
    [The verify reference](/reference/verify#results) explains each result.
  </Step>
</Steps>

## Run the stages by hand

Each stage is also a command. These are the commands that `decktalk build --only 3` runs, plus a cue check.

```console theme={null}
decktalk narrate                   # add --no-voice if the last build had no voice
decktalk align
decktalk record --only 3
decktalk assemble
decktalk verify --only 3
```

Some edits need fewer commands.

| After this edit                         | Run                                                                         |
| --------------------------------------- | --------------------------------------------------------------------------- |
| A slide changed, and the script did not | `decktalk record --only N`, `decktalk assemble`, `decktalk verify --only N` |
| A clip file changed                     | `decktalk assemble`, `decktalk verify`                                      |

## Voice every section again

Use `--force` to ignore the narration cache. A forced run spends credits on every section.

```console theme={null}
decktalk narrate --dry-run
decktalk narrate --force
decktalk build --force
```

`decktalk narrate --dry-run` makes no API call. It prints the text that each section would send, and a take
plan that says which sections a voiced run would voice and which it already holds, with what the run costs.
So you can count the characters first. `decktalk narrate --dry-run --json` gives the same plan as JSON. `decktalk preflight` adds the cue check and
an estimate of each reveal from frozen frames, so you can fix a small reveal before you pay for the takes.

## A build without voice and a voiced build

A build without voice writes its own placeholder takes and replaces the rows of the take index. The next voiced
build would then voice those sections again and spend credits on them. So a `narrate` or `build` without voice
stops when a section it was asked to write already holds a paid take, and it writes nothing.

```text theme={null}
error[CONFIG]: build/narration/takes.json holds paid takes for section(s) 01, and a run without voice would replace them in the take index, so the next voiced build would voice them again and spend credits on all of them.
  hint: Rehearse the sections nobody has paid for: --only 2 --only 3.
```

The refusal is scoped to the sections the run was asked to write, so a film you have already paid for still
rehearses its new section for nothing. The paid mp3 files themselves are never touched, because a placeholder
take is named `silent-<hash>.mp3` and a voiced take is named by its own digest. What the run would replace is
the index:

1. The take index says, per row, whether that row is a paid take or a placeholder.
2. `assemble` cuts to the times the index carries, and a placeholder's times are estimates.
3. A row replaced by a placeholder is a row the next voiced build pays for again.

In a project that has never been voiced, a build without voice loses nothing. The first voiced build voices every
section anyway.

After a project has been voiced, rehearse with a build without voice in a copy of the project. To replace the voiced
takes on purpose, pass `--force`, as in `decktalk build --no-voice --force`. Neither kind of
build replaces the final mp4 until it finishes. Set `[output] timestamped_copy = true` to keep a dated copy
of each finished video next to `build/out/<name>.mp4`.

## Next

* **Learn why a recording stays valid:** [How it works](/concepts/how-it-works#caching)
* **Check the video after a rebuild:** [Verify](/reference/verify)
* **See what spends credits:** [Requirements](/requirements#what-spends-credits)


# Put a sound effect on a cue
Source: https://docs.decktalk.ai/guides/sfx-on-a-cue

Play a one-shot sound effect that starts on a spoken cue.

This guide plays a one-shot sound effect on a cue. The sound starts on a spoken word. Use it when you want a sound to mark a reveal, such as a click as a card lands.

The example puts a click on `1.1word`, the cue in the starter's section 1 where the closing band appears. The starter ships no `[soundscape]` or `[[mix.sfx]]` tables, so every table below is one you add.

## Before you start

* Build the project one time, with `decktalk build --no-voice` or `decktalk build`. The `align` stage must resolve the cue first.
* To generate the effect, put an ElevenLabs API key in `.env`. Generating an effect spends credits. [What spends credits](/requirements#what-spends-credits) lists the cost.
* If you have your own audio file, you need no key. Any file that ffmpeg can read works.

<Steps>
  <Step title="Describe the effect">
    If you brought your own file, put it in the project and skip to step 4.

    Add a `[soundscape.sfx.<name>]` table with a prompt for the ElevenLabs sound generator.

    ```toml decktalk.toml theme={null}
    [soundscape.sfx.tick]
    text = "soft interface click, single, short, no reverb"
    ```

    `decktalk soundscape` writes this effect to `build/sfx/tick.mp3`. To use another path, add an `out` key to the table.
  </Step>

  <Step title="Preview the request">
    Print the request without sending it. The dry run needs no key and spends nothing.

    ```console theme={null}
    decktalk soundscape --dry-run tick
    ```

    ```text theme={null}
    items 1, generated 0
    == tick -> ~/my-lesson/build/sfx/tick.mp3  [planned]
       POST https://api.elevenlabs.io/v1/sound-generation
       {'text': 'soft interface click, single, short, no reverb', 'duration_seconds': 0.5, 'prompt_influence': 0.5, 'model_id': 'eleven_text_to_sound_v2'}
    ```

    Check the output path and the prompt. The effect lasts 0.5 s unless the table sets `duration_seconds`.
  </Step>

  <Step title="Generate the effect">
    Send the request.

    ```console theme={null}
    decktalk soundscape tick
    ```

    The command writes `build/sfx/tick.mp3`. If the request and the file have not changed, a later run sends nothing. To generate the effect again, add `--force`.
  </Step>

  <Step title="Place the effect on a cue">
    Add a `[[mix.sfx]]` table that names the file, the section, and the cue id.

    ```toml decktalk.toml theme={null}
    [[mix.sfx]]
    file = "build/sfx/tick.mp3"
    section = 1
    cue = "1.1word"
    db = -16
    caption = "soft click"
    ```

    * `db` sets the level of the effect. The default is -16.
    * `offset` moves the effect by a number of seconds. The default is 0.
    * `caption` is the line a caption reader sees when the sound plays. Without it the sound is in the video and in no caption. [Accessible video](/guides/accessible-video#captions-that-carry-the-sound-not-only-the-speech) explains why it matters.

    DeckTalk places the effect at the section's start in the final video, plus the cue time, plus `offset`.
  </Step>

  <Step title="Mix the effect into the video">
    Run the `assemble` stage. It mixes the audio again, and it records nothing.

    ```console theme={null}
    decktalk assemble
    ```

    If the file is missing, or the cue did not resolve, `assemble` prints a warning and skips the effect. The video still builds.

    ```text theme={null}
    sfx build/sfx/tick.mp3 is missing, so it is skipped
    ```
  </Step>
</Steps>

## Next

* **Learn every part of the mix:** [Sound](/concepts/sound)
* **Swell or mute the music on a phrase:** [Markers](/concepts/sound#markers)
* **Check what a generated effect costs:** [Requirements and costs](/requirements#what-spends-credits)


# Slide recipes
Source: https://docs.decktalk.ai/guides/slide-recipes

Copy six common slides into a project, each with its script lines, section table, cues, and scene.

This page has six slides that you can copy into a project. Use a recipe when you need a common
slide, such as a derivation or a code block.

* [Sync a subtitle to the voice](#sync-a-subtitle-to-the-voice)
* [Show a derivation line by line](#show-a-derivation-line-by-line)
* [Show a chat before and after](#show-a-chat-before-and-after)
* [Show code one line per phrase](#show-code-one-line-per-phrase)
* [Compare two columns](#compare-two-columns)
* [Wait for a screenshot to load](#wait-for-a-screenshot-to-load)

## Before you start

Each recipe is one section, shown as four files: `script.md`, `decktalk.toml`, `cues.json`, and
`deck/index.html`. The recipes use section numbers 7 to 12, which the starter does not use. Each
`<style>` block defines the classes that its recipe needs. The recipes also use the starter's
`.eyebrow` class and its color and font variables.

To add a recipe to a project, follow these steps:

1. Paste the `script.md` lines after the last section of the script.
2. Paste the `[[section]]` table after the last `[[section]]` in `decktalk.toml`.
3. Paste the `cues.json` entry inside the `sections` object.
4. Paste the `<style>` block into the page's `<style>`, and the scene markup into `<body>`.
5. If the section number is already in use, change it in all four files.

## Sync a subtitle to the voice

An element with `data-text="spoken"` shows its words one at a time, as the voice says them.

<CodeGroup>
  ```md script.md theme={null}
  ## 7. The idea

  Write the script. [beat] Build the video. [beat] Every picture waits for its word.
  ```

  ```toml decktalk.toml theme={null}
  [[section]]
  number = 7
  page = "deck/index.html"
  scene = 7
  ```

  ```json cues.json theme={null}
  "7": { "cues": [
    { "cue": "7.1a", "on": "Write the script" },
    { "cue": "7.1b", "on": "Build the video" },
    { "cue": "7.1c", "on": "Every picture" }
  ] }
  ```

  ```html deck/index.html theme={null}
  <style>
    .stack { position: absolute; left: 120px; top: 360px; display: flex; flex-direction: column; gap: 32px; }
    .stack > * { margin: 0; }
    .line { font: 450 48px/1.4 var(--sans); color: var(--ink); }
  </style>
  <script>
  DeckTalk.scene(7, { name: "The idea", slides: [
    { id: "7.1", hold: 10, preview: { "7.1a": 1, "7.1b": 3.5, "7.1c": 6 }, render: () => `
      <div>
        <p class="eyebrow">The idea</p>
        <div class="stack">
          <p class="line" data-cue="7.1a" data-text="spoken">Write the script.</p>
          <p class="line" data-cue="7.1b" data-text="spoken">Build the video.</p>
          <p class="line" data-cue="7.1c" data-text="spoken">Every picture waits for its word.</p>
        </div>
      </div>` },
  ]});
  </script>
  ```
</CodeGroup>

The cue makes each line appear, and its words appear one at a time from there. The text must match
the script word for word. If a line differs by one word, it appears whole, and the page warns
`data-text="spoken" text not found in the spoken words`. To check the slide at one cue, open
`?slide=7.1&after=7.1b`, which hides the line for `7.1c`.

## Show a derivation line by line

Each line of the derivation is its own element with its own cue. `data-tex-display` typesets it as
display math, and the answer uses `pop` so it stands out. The starter's `deck/index.html` loads
KaTeX from the copy `decktalk init` put beside it.

<Warning>Inside the backticks of a `render` function, write every backslash twice, because a single
backslash breaks the TeX or blanks the page. In markup a backslash is written once, which is the
reason this recipe is a `<template data-slide>` ([`data-tex`](/reference/runtime#data-tex)).</Warning>

<CodeGroup>
  ```md script.md theme={null}
  ## 8. The derivative of x squared

  Start with the definition of the derivative, the limit of a difference quotient. [beat]
  Expand the square, and the x squared terms cancel. [beat] Only two x is left.
  ```

  ```toml decktalk.toml theme={null}
  [[section]]
  number = 8
  page = "deck/index.html"
  scene = 8
  ```

  ```json cues.json theme={null}
  "8": { "cues": [
    { "cue": "8.1a", "on": "definition" },
    { "cue": "8.1b", "on": "Expand" },
    { "cue": "8.1c", "on": "Only two x", "offset": 0.2 }
  ] }
  ```

  ```html deck/index.html theme={null}
  <style>
    .derivation { position: absolute; left: 120px; top: 300px; display: flex; flex-direction: column; gap: 56px; }
    .math { margin: 0; font-size: 58px; color: var(--ink); }
    .math .katex-display { margin: 0; }
    .math .katex-display > .katex { text-align: left; }
    .answer { color: var(--accent); }
  </style>
  <div data-scene="8" data-name="The derivative of x squared">
    <template data-slide="8.1" data-hold="14" data-preview="8.1a@1 8.1b@5 8.1c@9">
      <div class="derivation">
        <p class="math" data-cue="8.1a" data-tex-display
           data-tex="\frac{d}{dx}\,x^2 = \lim_{h \to 0} \frac{(x+h)^2 - x^2}{h}">(d/dx) of x^2 = the limit as h goes to 0 of ((x+h)^2 - x^2) / h</p>
        <p class="math" data-cue="8.1b" data-tex-display
           data-tex="= \lim_{h \to 0} \frac{2xh + h^2}{h} = \lim_{h \to 0} (2x + h)">= the limit of (2xh + h^2) / h = the limit of (2x + h)</p>
        <p class="math answer" data-cue="8.1c" data-reveal="pop" data-tex-display
           data-tex="\frac{d}{dx}\,x^2 = 2x">(d/dx) of x^2 = 2x</p>
      </div>
    </template>
  </div>
  ```
</CodeGroup>

The plain text inside each element shows when KaTeX is absent, so write it as a readable fallback.
In markup a backslash is written once. A slide built by a `render` function is a JavaScript string,
where every backslash has to be written twice, which is the reason to prefer a `<template>`.

## Show a chat before and after

The question types in with `data-text="type"`, and the reply fades in one line at a time. The bubble and
its first line share a cue, so the bubble's background appears when its text starts. The second
slide is the "after", and its cue `9.2` mounts it.

<CodeGroup>
  ```md script.md theme={null}
  ## 9. Before and after

  Watch a vague prompt first. [beat] Write about photosynthesis. [beat] The reply is true,
  and it is flat. [beat] One line says what it is. [beat] Another line says where it happens.

  [Slide 9.2.]

  Now ask for what you actually want. [beat] Explain it to a ninth grader, in three
  sentences. [beat] Same model, better prompt.
  ```

  ```toml decktalk.toml theme={null}
  [[section]]
  number = 9
  page = "deck/index.html"
  scene = 9
  ```

  ```json cues.json theme={null}
  "9": { "cues": [
    { "cue": "9.1ask", "on": "Write about" },
    { "cue": "9.1r1", "on": "One line" },
    { "cue": "9.1r2", "on": "another line" },
    { "cue": "9.2", "on": "Now ask" },
    { "cue": "9.2ask", "on": "Explain it" },
    { "cue": "9.2reply", "on": "Same model" }
  ] }
  ```

  ```html deck/index.html theme={null}
  <style>
    .chat { position: absolute; left: 120px; top: 300px; width: 1680px; display: flex; flex-direction: column; gap: 32px; }
    .bubble { max-width: 1100px; padding: 28px 40px; border-radius: 24px; font: 450 36px/1.4 var(--sans); }
    .bubble p { margin: 0 0 12px; }
    .ask { align-self: flex-end; background: var(--accent); color: var(--ground); }
    .reply { align-self: flex-start; background: #f4f4f5; color: var(--ink); }
  </style>
  <script>
  DeckTalk.scene(9, { name: "Before and after", slides: [
    { id: "9.1", hold: 12, preview: { "9.1ask": 1, "9.1r1": 5, "9.1r2": 7 }, render: () => `
      <div>
        <p class="eyebrow">Before</p>
        <div class="chat">
          <div class="bubble ask" data-cue="9.1ask" data-text="type 40ms" data-reveal="fade">Write about photosynthesis.</div>
          <div class="bubble reply" data-cue="9.1r1" data-reveal="fade">
            <p data-cue="9.1r1" data-reveal="fade">Photosynthesis is the process by which plants convert light into energy.</p>
            <p data-cue="9.1r2" data-reveal="fade">It takes place in the chloroplasts.</p>
          </div>
        </div>
      </div>` },
    { id: "9.2", hold: 12, preview: { "9.2ask": 1, "9.2reply": 6 }, render: () => `
      <div>
        <p class="eyebrow">After</p>
        <div class="chat">
          <div class="bubble ask" data-cue="9.2ask" data-text="type 30ms" data-reveal="fade">Explain photosynthesis to a ninth grader in three sentences.</div>
          <div class="bubble reply" data-cue="9.2reply" data-reveal="pop">
            <p>Plants catch sunlight and use it to turn water and air into sugar.</p>
          </div>
        </div>
      </div>` },
  ]});
  </script>
  ```
</CodeGroup>

## Show code one line per phrase

Each line of code is a block element with its own cue. The container keeps the indentation with
`white-space: pre` and a monospace font. The lines use `fade`, because the motion of `rise` looks
wrong on code.

<CodeGroup>
  ```md script.md theme={null}
  ## 10. Three commands

  Three commands run the whole thing. [beat] Initialize a project. [beat] Build it
  without voice, with no key. [beat] Then build it with your voice.
  ```

  ```toml decktalk.toml theme={null}
  [[section]]
  number = 10
  page = "deck/index.html"
  scene = 10
  ```

  ```json cues.json theme={null}
  "10": { "cues": [
    { "cue": "10.1a", "on": "Initialize" },
    { "cue": "10.1b", "on": "without voice" },
    { "cue": "10.1c", "on": "your voice" }
  ] }
  ```

  ```html deck/index.html theme={null}
  <style>
    .code { position: absolute; left: 120px; top: 360px; font: 500 40px/1.5 var(--mono); white-space: pre; color: var(--ink); background: #f4f4f5; border-radius: 24px; padding: 40px 56px; }
    .code .cmt { color: var(--mute); }
  </style>
  <script>
  DeckTalk.scene(10, { name: "Three commands", slides: [
    { id: "10.1", hold: 10, preview: { "10.1a": 1, "10.1b": 4, "10.1c": 7 }, render: () => `
      <div>
        <div class="code"><div data-cue="10.1a" data-reveal="fade">decktalk init my-lesson</div><div data-cue="10.1b" data-reveal="fade">decktalk build --no-voice   <span class="cmt"># no key</span></div><div data-cue="10.1c" data-reveal="fade">decktalk build</div></div>
      </div>` },
  ]});
  </script>
  ```
</CodeGroup>

Keep the lines on one physical line inside the `render` template. With `white-space: pre`, the
page would otherwise show the template's own indentation.

## Compare two columns

Two columns appear left and then right, and each column has one cue. The `<style>` block lays them
out with flex.

<CodeGroup>
  ```md script.md theme={null}
  ## 11. Two ways to time a reveal

  On the left, a timeline editor. Every reveal is a number of seconds, and every edit moves them
  by hand. [beat] On the right, the words. Every reveal is a phrase, and it moves with the
  sentence.
  ```

  ```toml decktalk.toml theme={null}
  [[section]]
  number = 11
  page = "deck/index.html"
  scene = 11
  ```

  ```json cues.json theme={null}
  "11": { "cues": [
    { "cue": "11.1left", "on": "timeline editor" },
    { "cue": "11.1right", "on": "the words" }
  ] }
  ```

  ```html deck/index.html theme={null}
  <style>
    .cols { position: absolute; left: 120px; right: 120px; top: 300px; display: flex; gap: 48px; }
    .pane { flex: 1; background: #f4f4f5; border-radius: 24px; padding: 48px; min-height: 520px; }
    .pane h2 { margin: 0 0 24px; font: 600 56px/1.1 var(--sans); letter-spacing: -.02em; color: var(--ink); }
    .pane .line { margin: 0 0 16px; font: 450 36px/1.4 var(--sans); color: var(--ink); }
    .pane .caption { margin: 0; font: 450 30px/1.4 var(--sans); color: var(--mute); }
    .pane .accent { color: var(--accent); }
  </style>
  <script>
  DeckTalk.scene(11, { name: "Two ways to time a reveal", slides: [
    { id: "11.1", hold: 12, preview: { "11.1left": 1, "11.1right": 6 }, render: () => `
      <div>
        <div class="cols">
          <div class="pane" data-cue="11.1left">
            <h2>A timeline editor</h2>
            <p class="line">Every reveal is a number of seconds.</p>
            <p class="caption">Every edit moves them by hand.</p>
          </div>
          <div class="pane" data-cue="11.1right">
            <h2 class="accent">The words</h2>
            <p class="line">Every reveal is a phrase.</p>
            <p class="caption">It moves with the sentence.</p>
          </div>
        </div>
      </div>` },
  ]});
  </script>
  ```
</CodeGroup>

## Wait for a screenshot to load

The recorder starts the clock only after `window.__decktalk.ready` resolves. This recipe hands the
decode of a large image to `DeckTalk.waitFor`, so the image is ready before narration t=0. `waitFor`
adds a condition to the runtime's own wait rather than replacing it, so the KaTeX wait still applies.

<CodeGroup>
  ```md script.md theme={null}
  ## 12. The status report

  Here is the status report after a build. [beat] Every section shows a recording and a
  cut, and the captions and chapters sit beside the video.
  ```

  ```toml decktalk.toml theme={null}
  [[section]]
  number = 12
  page = "deck/index.html"
  scene = 12
  ```

  ```json cues.json theme={null}
  "12": { "cues": [
    { "cue": "12.1screenshot", "on": "status report" },
    { "cue": "12.1note", "on": "captions" }
  ] }
  ```

  ```html deck/index.html theme={null}
  <style>
    .screenshot { position: absolute; left: 260px; top: 140px; width: 1400px; border-radius: 16px; box-shadow: 0 24px 80px rgba(0,0,0,.25); }
    .note { position: absolute; left: 260px; top: 960px; margin: 0; font: 450 30px/1.4 var(--sans); color: var(--mute); }
  </style>
  <script>
  DeckTalk.scene(12, { name: "The status report", slides: [
    { id: "12.1", hold: 10, preview: { "12.1screenshot": 0.5, "12.1note": 5 }, render: () => `
      <div>
        <img class="screenshot" src="../media/status.png" alt="" data-cue="12.1screenshot" data-reveal="fade">
        <p class="note" data-cue="12.1note">Captions and chapters sit beside the video.</p>
      </div>` },
  ]});

  // Narration t=0 also waits until the screenshot has decoded.
  const image = new Image();
  image.src = "../media/status.png";
  DeckTalk.waitFor(image.decode());
  </script>
  ```
</CodeGroup>

`DeckTalk.waitFor` takes a Promise and holds narration t=0 until it settles. A Promise that rejects,
or one that has not settled after five seconds, becomes a page warning and the recording goes ahead,
so a missing image never hangs a build. [`window.__decktalk.ready`](/reference/runtime#window-__decktalk-ready)
explains the default wait.

## Next

* **Size a slide and choose reveal effects:** [Design a slide](/guides/design-a-slide)
* **Look up every attribute:** [Runtime](/reference/runtime#data-attributes)
* **Write phrases that time well:** [Writing for the ear](/guides/writing-for-the-ear)


# Writing for the ear
Source: https://docs.decktalk.ai/guides/writing-for-the-ear

Write a narration script that gives every reveal a word to start on.

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 DeckTalk's own films 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.

```json cues.json theme={null}
{ "cue": "3.4steps", "on": "steps downhill" }
```

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 starter's cue phrases are nouns that name something visible, such as `This is DeckTalk`, `what you will say`, `the slides`, `the formula`, and `in code`.

## 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.

| Direction                         | Sent to the voice                   | Use it for                                            |
| --------------------------------- | ----------------------------------- | ----------------------------------------------------- |
| `[beat]`                          | a dash after the sentence before it | Use it freely before a reveal.                        |
| `[pause N]`                       | a `<break time="Ns" />` tag         | Use it where you want the audience to stop and think. |
| Any other text in square brackets | a dash, the same as `[beat]`        | Use it as a note to yourself. It also makes a beat.   |

The starter puts a beat before each card, so each one arrives as its own event:

```md script.md theme={null}
This is DeckTalk. [beat] You write what you will say, [beat] and you write the slides that go with it.
[beat] Then every picture waits for its own word.
```

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](/reference/script-md) lists every direction rule.

DeckTalk adds silence before the first word and after the last word of every section, so the picture changes before the voice speaks. 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.

```json cues.json theme={null}
{ "cue": "3.4steps", "on": "steps downhill", "offset": 0.2 }
```

<Frame>
  <img alt="The words &#x22;it steps downhill&#x22; from section 3 sit in boxes as long as each word. A line at the start of &#x22;steps&#x22; 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." />

  <img alt="The words &#x22;it steps downhill&#x22; from section 3 sit in boxes as long as each word. A line at the start of &#x22;steps&#x22; 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." />
</Frame>

* **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 starter's cues have no offset key, so every reveal in a new project 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 a longer or a shorter silence, set its `lead_seconds`. [cues.json](/reference/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 starter's script says "decktalk dot AI", and its end card shows decktalk.ai. `decktalk narrate` reports a section whose spoken text still holds a digit or a symbol as `SPOKEN SYMBOL?`, an uncertain finding.

## Rehearse with a build without voice

A build without voice costs nothing and needs no key. Use it to check the pacing before you spend credits.

```console theme={null}
decktalk build --no-voice
```

* A build without voice 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](/reference/verify#the-a/v-value) explains that check.

Watch the video for pacing. A reveal that comes too early in a build without voice usually comes too early with the real voice too. [How it works](/concepts/how-it-works#the-build-without-voice) explains what a build without voice 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.

```md script.md theme={null}
## 3. How AI learns — 0:40 to 1:40
```

This table comes from `decktalk narrate --dry-run` on the starter, with the section from
[Your first deck](/guides/first-deck) added and its heading budgeted `— 0:20 to 0:30`. The dry run calls no API.

```text theme={null}
 #  section                words    est  target  actual  placeholders
---------------------------------------------------------------------
 1  open                      26   0:11    --      --    -
 2  how-it-works              30   0:13    --      --    -
 3  close                     25   0:11    --      --    -
 4  gradient-descent         100   0:43    0:10    --    -
---------------------------------------------------------------------
    total                    181   1:18            --
```

* `target` is the length of the budget, ten seconds for section 4.
* `est` paces the words at `words_per_minute` (140). Section 4 estimates 0:43, so it runs far past its budget.
* `actual` fills in after a voiced build.
* A section with no budget in its heading reads `--` in both columns.

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 align` reports an uncertain finding.

## Next

* **Copy a common slide:** [Slide recipes](/guides/slide-recipes)
* **Choose a cue phrase that matches:** [Cues](/concepts/cues#matching-rules)
* **Write your own section:** [Your first deck](/guides/first-deck)


# FAQ
Source: https://docs.decktalk.ai/help/faq

Answers about cost, lock-in, the voice, other tools, output files, and the lesson example.

This page answers common questions about DeckTalk. For a message that DeckTalk prints, see [Troubleshooting](/help/troubleshooting).

## What does it cost?

A build without voice costs nothing. A voiced build spends ElevenLabs credits for each section whose text changed.

* Every ElevenLabs plan can call the API, including the free plan. The free plan has limits for a video you publish.
* `decktalk soundscape` also spends credits, because it generates music, an ambience bed, and sound effects.
* A build without voice stops when the project has voiced takes, because it would empty the narration cache. [Rebuild one section](/guides/rebuild-one-section#a-build-without-voice-and-a-voiced-build) explains the cache.

[What spends credits](/requirements#what-spends-credits) lists the plan limits and every command that spends credits.

## Is there lock-in to ElevenLabs?

No. ElevenLabs is the built-in speech provider, because it returns word times.

* The speech provider is one module behind a two-method protocol. Any service that returns audio and word times can replace it.
* A local speech provider with word timings is one such replacement.
* A build without voice needs no speech provider, so the project files do not depend on any service.

[Python API](/reference/python-api) documents the protocol.

## How does the voice sound?

It sounds like the ElevenLabs voice you pick. Any voice id works, including a clone of your own voice.

* `[voice]` in `decktalk.toml` sets stability, similarity, style, and speed.
* DeckTalk sends the text before and after each section with the request. The rhythm and tone of the voice then stay even across cuts.

## Why not record the screen?

A screen recording needs a new take after every edit. You would also time every reveal again by hand. DeckTalk times each reveal from the spoken words, so a reveal moves with its word. [Rebuild one section](/guides/rebuild-one-section) shows what a change runs again.

## How is this different from the other tools?

DeckTalk takes its timing from the spoken words, and the slides are your own HTML.

| Tool                                  | Timing comes from                                                   | Slides are              | After you edit one sentence                                                                      |
| ------------------------------------- | ------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
| **DeckTalk**                          | the spoken words, one time per word                                 | your HTML               | DeckTalk voices one section again. `build --only N` records only that section.                   |
| Remotion, Motion Canvas               | frame numbers or seconds in code, by default                        | code                    | You time the change again by hand and render again.                                              |
| Manim                                 | seconds in code, or bookmarks in the narration with manim-voiceover | code                    | With manim-voiceover, bookmarks follow the new text. You still render the scene again in Python. |
| reveal.js plus a text-to-speech track | a fixed delay per slide, or a timing track you make by hand         | your HTML               | You time every slide again after the change.                                                     |
| Descript                              | a recording you made                                                | your screen             | Overdub voices the new words. The screen recording does not move with them.                      |
| Synthesia, HeyGen                     | the avatar's speech                                                 | their avatar and scenes | You generate the video again.                                                                    |

Choose DeckTalk when the timing must come from the words and the slides are yours. Other tools fit other jobs:

* For frame-by-frame animation, use Remotion, Motion Canvas, or Manim.
* To edit a recording you already made, use Descript.
* For an avatar on screen, use Synthesia or HeyGen.

## Is generated music required?

No. Each part of the soundscape is off until `[mix]` in `decktalk.toml` names its file.

* You can bring your own audio files.
* `decktalk soundscape` generates the parts from a prompt, and it spends credits.
* If a named file is missing, the build prints a warning and continues without that part.

[Sound](/concepts/sound) explains both ways.

## What comes out besides the video?

Every build writes captions and chapters beside the video.

* The `.srt` and `.vtt` captions come from the word times, with the script's punctuation.
* An ffmetadata chapters file has one chapter per section. Consecutive sections with the same title share one chapter.
* The mp4 holds the same chapters, so video players show the section titles.

`decktalk status` lists all three files. [Build artifacts](/reference/artifacts) gives their formats.

## Does another HTML framework work?

Yes. A page can be any HTML that follows the [page contract](/concepts/page-contract).

* [Write a page by hand](/guides/page-by-hand) shows the minimum page.
* The runtime is one file with no dependencies. It adds only the stage element to your markup.
* KaTeX is optional. `decktalk init` copies the packaged KaTeX into `deck/katex/`, and a page that needs no equations can drop its two tags.

## Does it run on Windows?

Yes. DeckTalk runs on Linux, macOS, and Windows.

* Paths in `decktalk.toml` use forward slashes on every platform.
* `decktalk install` puts Chromium in `%LOCALAPPDATA%\ms-playwright`. If a corporate proxy blocks the download, set `PLAYWRIGHT_DOWNLOAD_HOST` as Playwright documents.
* CI runs the full build on Windows for a `v*` tag that a person pushes, and on request. [What CI runs](https://github.com/jacobcbeaudin/decktalk/blob/main/CONTRIBUTING.md#what-ci-runs) lists every platform and trigger.

## What does the lesson example mean by error?

The "error" in `decktalk init --example lesson` is what machine learning calls the loss. The lesson uses "error" because the everyday word already says that lower is better.

* **One guess.** A loss function scores one guess. For a category guess, such as seal or otter, the usual loss is cross-entropy. It is large when the model gives the right answer a low probability.
* **The height of the bowl.** Training lowers the average loss over many examples. Gradient descent moves the knobs down the slope of that average.
* **Not the error rate.** The error rate is the share of wrong guesses. It changes in jumps, so it has no useful slope to follow.

[The examples](/quickstart#the-examples) says what each packaged project is.

## Where does the name come from?

A deck is the slides, and the talk is the narration. DeckTalk times the deck to the talk.

## Related

* **Fix a message that DeckTalk prints:** [Troubleshooting](/help/troubleshooting)
* **Check what a build needs and costs:** [Requirements and costs](/requirements)
* **Look up a term:** [Glossary](/reference/glossary)


# Troubleshooting
Source: https://docs.decktalk.ai/help/troubleshooting

Find a DeckTalk message, verdict, or warning by the text it prints, with its cause and fix.

This page lists each message, verdict, and warning that DeckTalk prints, with its cause and its fix.
Search the page for the text you see.

A line that starts `error[CODE]:` is an error, and the command exits 3 without finishing its work. A
verdict or a note is a finding, and the command finishes and exits 1, or 0 when the finding is
uncertain and `--strict` was not passed. [Exit codes](/reference/cli#exit-codes) has the whole set.

If the project has no voiced build yet, run `decktalk build --no-voice` first. It spends no credits,
and it shows if the problem is in the cues, the pages, or the assembly. If the project has a voiced
build, rehearse in a copy of the project. A build without voice stops on voiced takes, because it would empty the narration cache, as
[A build without voice and a voiced build](/guides/rebuild-one-section#a-build-without-voice-and-a-voiced-build)
explains.

## Find your message

| Text you see                                            | Printed by                               | Entry                                                                     |
| ------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| `playwright install failed`                             | `install`                                | [Entry](#playwright-install-failed-in-install)                            |
| `MISSING`                                               | `doctor`                                 | [Entry](#missing-in-doctor)                                               |
| `is not empty`                                          | `init`                                   | [Entry](#is-not-empty-in-init)                                            |
| `must be letters`                                       | `init`                                   | [Entry](#must-be-letters-in-init)                                         |
| `not set`                                               | `narrate`, `build`, `soundscape`         | [Entry](#not-set-in-narrate)                                              |
| `HTTP 401`, `HTTP 402`                                  | `narrate`, `build`, `soundscape`         | [Entry](#http-401-or-http-402-in-narrate)                                 |
| `could not reach`                                       | `narrate`, `build`, `soundscape`         | [Entry](#could-not-reach-in-narrate)                                      |
| `decktalk.toml is not there`                            | every project command                    | [Entry](#decktalk-toml-is-not-there-in-any-command)                       |
| `unknown table(s)`                                      | every project command                    | [Entry](#unknown-table-s-in-decktalk-toml)                                |
| `ignoring unknown key`                                  | every project command                    | [Entry](#ignoring-unknown-key-in-decktalk-toml)                           |
| `must be int, got float`, `UNREADABLE`                  | every project command                    | [Entry](#must-be-in-decktalk-toml)                                        |
| `invalid tuning value`                                  | every project command                    | [Entry](#invalid-tuning-value-in-decktalk-toml)                           |
| `unfilled placeholders`                                 | `narrate`, `build`                       | [Entry](#unfilled-placeholders-in-narrate)                                |
| `no spoken section matches`                             | `narrate`                                | [Entry](#no-spoken-section-matches-in-narrate)                            |
| `have no [[section]] in decktalk.toml`                  | `narrate`, `build`                       | [Entry](#have-no-section-in-decktalk-toml-in-narrate)                     |
| `have no take yet`                                      | `narrate`                                | [Entry](#have-no-take-yet-in-narrate)                                     |
| `holds paid takes`                                      | `narrate --no-voice`, `build --no-voice` | [Entry](#holds-paid-takes-in-narrate)                                     |
| `phrase not found`                                      | `align`, `build`                         | [Entry](#phrase-not-found-in-align)                                       |
| `could not be matched to the narration`                 | `build`                                  | [Entry](#phrase-not-found-in-align)                                       |
| `not in deck/index.html`                                | `align`, `build`                         | [Entry](#not-in-its-page-in-align)                                        |
| `appear nowhere in the page that plays them`            | `build`                                  | [Entry](#not-in-its-page-in-align)                                        |
| `UNRESOLVED`                                            | `align --json`, `verify`                 | [Entry](#unresolved-in-align-or-verify)                                   |
| `UNKNOWN CUE`                                           | `align --json`                           | [Entry](#unknown-cue-in-align)                                            |
| `shorter than the visuals need`                         | `align`                                  | [Entry](#shorter-than-the-visuals-need-in-align)                          |
| `is past the end of the audio`                          | `align`                                  | [Entry](#is-past-the-end-of-the-audio-in-align)                           |
| `occurs <N> times in this section`                      | `align`                                  | [Entry](#occurs-n-times-in-this-section-in-align)                         |
| `no words`                                              | `align`                                  | [Entry](#no-words-in-align)                                               |
| `is not in decktalk.toml`                               | `align`, `build`                         | [Entry](#is-not-in-decktalk-toml-in-align)                                |
| `NO CHANGE`, `THIN CHANGE?`                             | `preflight`                              | [Entry](#no-change-or-thin-change-in-preflight)                           |
| `PAGE ERROR`, `page error`                              | `record`, `build`                        | [Entry](#page-error-in-record)                                            |
| `STALLED`, `frame stall(s)`                             | `record`                                 | [Entry](#stalled-in-record)                                               |
| `TRUNCATED`                                             | `record`                                 | [Entry](#truncated-in-record)                                             |
| `NO COVER`                                              | `record`                                 | [Entry](#no-cover-in-record)                                              |
| `BLACK?`                                                | `record`                                 | [Entry](#black-in-record)                                                 |
| `KATEX ERROR`, `KATEX NOT LOADED`, `KaTeX did not load` | `record`, `verify`, `preflight`          | [Entry](#katex-error-or-katex-not-loaded-in-record)                       |
| `no narration span yet`                                 | `record`                                 | [Entry](#no-narration-span-yet-in-record)                                 |
| `is missing, so a slate plays`                          | `assemble`                               | [Entry](#is-missing-so-a-slate-plays-in-assemble)                         |
| `clip missing`, `recording missing`                     | `assemble` with `--strict`               | [Entry](#clip-missing-or-recording-missing-in-assemble)                   |
| `using black`                                           | `assemble`                               | [Entry](#using-black-in-assemble)                                         |
| `has no span in`                                        | `assemble`                               | [Entry](#has-no-span-in-in-assemble)                                      |
| `music missing`, `ambience missing`                     | `assemble`                               | [Entry](#music-missing-in-assemble)                                       |
| `unresolved; skipped`                                   | `assemble`                               | [Entry](#unresolved-skipped-in-assemble)                                  |
| `[loud] skipped`                                        | `assemble`                               | [Entry](#loud-skipped-in-assemble)                                        |
| `true peak`, `integrated loudness`                      | `assemble`                               | [Entry](#true-peak-or-integrated-loudness-in-assemble)                    |
| `BLACK`                                                 | `verify`                                 | [Entry](#black-in-verify)                                                 |
| `SPEECH AT CUT`                                         | `verify`                                 | [Entry](#speech-at-cut-in-verify)                                         |
| `POP AT CUT`                                            | `verify`, `build`                        | [Entry](#pop-at-cut-in-verify)                                            |
| `NO CHANGE`                                             | `verify`                                 | [Entry](#no-change-in-verify)                                             |
| `THIN CHANGE?`                                          | `verify`                                 | [Entry](#thin-change-in-verify)                                           |
| `OFF CUE`                                               | `verify`                                 | [Entry](#off-cue-in-verify)                                               |
| `NO_CLICK`                                              | `verify --json`                          | [Entry](#no_click-in-verify)                                              |
| `skipped`                                               | `verify`                                 | [Entry](#skipped-in-verify)                                               |
| `malformed check`                                       | `verify`                                 | [Entry](#malformed-check-in-verify)                                       |
| `nothing to verify`                                     | `verify`                                 | [Entry](#nothing-to-verify-in-verify)                                     |
| `is not a section in decktalk.toml`                     | `assemble`, `verify`                     | [Entry](#is-not-a-section-in-decktalk-toml-in-assemble-or-verify)         |
| `The take index is not there`                           | `words`, `clip`                          | [Entry](#the-take-index-is-not-there-in-words-or-clip)                    |
| `has no section video`                                  | `clip`                                   | [Entry](#has-no-section-video-in-clip)                                    |
| `is a clip section`                                     | `clip`                                   | [Entry](#is-a-clip-section-in-clip)                                       |
| `cuts the word`                                         | `clip`                                   | [Entry](#cuts-the-word-in-clip)                                           |
| `data-text="spoken" text not found in the spoken words` | page                                     | [Entry](#data-text="spoken"-text-not-found-in-the-spoken-words-in-a-page) |
| `matches no element, handler, or slide`                 | page                                     | [Entry](#matches-no-element-handler-or-slide-in-a-page)                   |
| `unknown cue id`                                        | page                                     | [Entry](#unknown-cue-id-in-a-page)                                        |
| `owns no cue in ?cues=`                                 | page                                     | [Entry](#owns-no-cue-in-a-page)                                           |

## install, doctor, and keys

### `playwright install failed` in install

**Cause.** Playwright could not download Chromium or, on Linux, its system libraries. The output above
the error shows the reason.

**Fix.**

1. If the output names a network or proxy problem, set `PLAYWRIGHT_DOWNLOAD_HOST` as Playwright documents.
2. If you are on Linux, run `decktalk install` as a user who can use sudo.
3. Run `decktalk install` again.

**More.** [What install downloads](/requirements#what-install-downloads)

### `MISSING` in doctor

**Cause.** A component is not installed. The detail says which one.

* If `chromium` shows `MISSING`, Chromium does not launch.
* If `ffmpeg` shows `MISSING`, no ffmpeg exists in `DECKTALK_FFMPEG`, the pinned download, or `PATH`.
* If `katex` shows `MISSING`, the wheel's KaTeX copy is incomplete. The detail names each absent file.

**Fix.**

1. Run `decktalk install`, or reinstall DeckTalk when the `katex` row is the one that is `MISSING`.
2. Run `decktalk doctor` again.

`doctor` exits 1 on a `MISSING` row.

**More.** [`decktalk doctor`](/reference/cli#decktalk-doctor)

### `is not empty` in init

`init` prints `error[CONFIG]: <dir> is not empty (pass force to write into it anyway)` and exits 3.

**Cause.** The target directory already has files.

**Fix.**

1. If you want a new project, pass an empty or new directory.
2. If you want to write into this directory, add `--force`. `--force` overwrites every file the starter also writes.

**More.** [`decktalk init`](/reference/cli#decktalk-init)

### `must be letters` in init

`init` prints `error[CONFIG]: project name '<name>' must be letters, digits, dots, dashes or underscores` and exits 3.

**Cause.** The project name starts with a character that is not a letter or digit, or has another
character. The default name is the directory name.

**Fix.**

1. Pass a valid name with `--name`, such as `--name my-lesson`.

**More.** [`decktalk init`](/reference/cli#decktalk-init)

### `not set` in narrate

A voiced run prints `ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID not set.` or one of the two names.

**Cause.** The key or the voice id is missing. A value that starts with `<`, such as `<voice-id>`,
counts as unset.

**Fix.**

1. If the project has no `.env`, run `cp .env.example .env`.
2. Replace both placeholder values in `.env`.
3. Run the command again.

You can also export both variables. A build without voice needs neither.

**More.** [Accounts](/requirements#accounts)

### `HTTP 401` or `HTTP 402` in narrate

The error reads `HTTP <code> from https://api.elevenlabs.io/v1/text-to-speech/<voice id>/with-timestamps: <detail>`.

**Cause.**

* A `401` means that the key is wrong or was revoked.
* A `402` or a quota message means that the plan has no characters left, or that the voice needs a paid plan.

**Fix.**

1. If the code is 401, copy a new key into `.env`.
2. If the code is 402, check the plan's character balance with ElevenLabs.
3. Run `decktalk narrate --dry-run` to see the exact text that a build sends.

**More.** [What spends credits](/requirements#what-spends-credits)

### `could not reach` in narrate

**Cause.** The machine has no route to the speech provider. The reason follows the URL.

**Fix.**

1. Check the network connection and any proxy.
2. If you only need a rehearsal, run `decktalk build --no-voice` in a copy of the project.

**More.** [A build without voice and a voiced build](/guides/rebuild-one-section#a-build-without-voice-and-a-voiced-build)

## Project files

### `decktalk.toml is not there` in any command

```text theme={null}
error[CONFIG]: decktalk.toml is not there.
  hint: Run from a project directory, pass --project DIR, or create one with `decktalk init DIR`.
```

**Cause.** The command did not run in a project directory, and `--project` was not given.

**Fix.**

1. Run `cd` into the project directory.
2. If there is no project yet, run `decktalk init DIR`.

If you run from elsewhere, pass `-p DIR` instead. `decktalk status` is the one command that reports
this rather than raising it. It prints a `MISSING` row and exits 1, because reading the four input
files is its whole job.

**More.** [Global options](/reference/cli#global-options)

### `unknown table(s)` in decktalk.toml

```text theme={null}
error[CONFIG]: decktalk.toml: unknown table(s) ['mixx']. The known tables are ['audio', 'elevenlabs', 'mix', 'narration', 'output', 'project', 'record', 'section', 'soundscape', 'transition', 'verify', 'video', 'voice'].
```

**Cause.** A top-level table name has a typo, or it is not a DeckTalk table.

**Fix.**

1. Compare the name with the known list in the error.
2. Rename or remove the table.

An unknown key inside a table prints a warning instead. See
[`ignoring unknown key` in decktalk.toml](#ignoring-unknown-key-in-decktalk-toml).

**More.** [Load rules](/reference/decktalk-toml#load-rules)

### `ignoring unknown key` in decktalk.toml

```text theme={null}
decktalk.toml: [voice]: ignoring unknown key 'stabilty' (did you mean 'stability'?).
```

**Cause.** A key inside a table has a typo, or it belongs to another table or section kind. DeckTalk
ignores the key and continues, so the setting has no effect.

**Fix.**

1. If the warning suggests a key, rename the key to that name.
2. If the warning says the key applies only to a page or clip section, move it to that kind of section.
3. Run the command again and check that the warning is gone.

The per-machine settings file gets the same warning, with its own path first.

**More.** [Load rules](/reference/decktalk-toml#load-rules)

### `must be` in decktalk.toml

```text theme={null}
sections 0 | 1 certain, 0 uncertain finding(s)
UNREADABLE  decktalk.toml: decktalk.toml: [soundscape.music]: 'seconds' must be int, got float
```

**Cause.** A value has the wrong type. The error names the table, the key, and both types. `status`
reports it as an `UNREADABLE` row and exits 1. Every other command raises it and exits 3.

**Fix.**

1. Look up the key's type in [decktalk.toml](/reference/decktalk-toml).
2. Change the value to that type.

**More.** [Load rules](/reference/decktalk-toml#load-rules)

### `invalid tuning value` in decktalk.toml

**Cause.** A tuning field in `decktalk.toml`, the per-machine file, or a `DECKTALK_<TABLE>_<FIELD>`
variable has a value of the wrong type.

**Fix.**

1. Look up the field's type in [Configuration](/reference/configuration).
2. Correct the value where you set it.

**More.** [Configuration](/reference/configuration)

## narrate

### `unfilled placeholders` in narrate

The error reads `unfilled placeholders ['<NAME>'] in the script; fill them or pass allow_placeholders`.

**Cause.** The script still has a `[CAPS]` placeholder, and the run is voiced.

**Fix.**

1. Run `decktalk narrate --dry-run` to list every placeholder.
2. Replace each placeholder in `script.md`.
3. If you want to voice the text as it is, pass `--allow-placeholders`.

**More.** [Directions and placeholders](/reference/script-md#directions-and-placeholders)

### `no spoken section matches` in narrate

```text theme={null}
error[CONFIG]: no spoken section matches [5]. The spoken sections are [1, 2, 3].
```

**Cause.** `--only` names a clip section or a number with no script heading.

**Fix.**

1. Pass a number from the list in the error.

**More.** [`decktalk narrate`](/reference/cli#decktalk-narrate)

### `have no [[section]] in decktalk.toml` in narrate

**Cause.** The script has a `## N.` heading with no `[[section]]` table of the same number.

**Fix.**

1. If the section is new, add a `[[section]]` table with that `number`.
2. If the number is a typo, fix the heading in `script.md`.

**More.** [Headings](/reference/script-md#headings)

### `have no take yet` in narrate

**Cause.** `narrate --only` voiced some sections, and other spoken sections have no audio yet. The
narration then covers only the sections that have a take.

**Fix.**

1. Run `decktalk narrate` with no `--only`.

**More.** [Rebuild one section](/guides/rebuild-one-section)

### `holds paid takes` in narrate

```text theme={null}
error[CONFIG]: build/narration/takes.json holds paid takes for section(s) 01, and a run without voice would replace them in the take index, so the next voiced build would voice them again and spend credits on all of them.
  hint: Rehearse the sections nobody has paid for: --only 2 --only 3.
```

**Cause.** You ran `decktalk narrate --no-voice` or `decktalk build --no-voice` over a section that already holds a
paid take. The run would replace that row of the take index with a placeholder, and the next voiced build would pay
for the section again. The paid mp3 files themselves are never touched, because a placeholder take is named
`silent-<hash>.mp3` and a paid take is named by its own digest.

**Fix.**

1. Rehearse the sections the hint names, with `--only`.
2. If you want to rehearse the whole project, copy it and run the build without voice in the copy.
3. If you want to drop the paid takes, run the same command with `--force`.

The refusal covers only the sections the run was asked to write, so a film you have already paid for still rehearses
a new section for nothing.

**More.** [A build without voice and a voiced build](/guides/rebuild-one-section#a-build-without-voice-and-a-voiced-build)

### A section opens on its first word

**Cause.** The section's lead is 0, from its own `lead_seconds = 0` or from `[narration] lead_seconds = 0`.
`narrate` removes a direction before the first words of a section, `[pause N]` included, so a pause in the
script cannot open it either. The first word plays as the section's first frame appears.

**Fix.**

1. Set `lead_seconds` on the page section in `decktalk.toml`, or raise `[narration] lead_seconds` for every
   section. `narrate` places that much silence before the take and sends no request.
2. Run `decktalk build --only N`, so the recording covers the lead.

**More.** [Silence in a section](/reference/decktalk-toml#silence-in-a-section)

## align

### `phrase not found` in align

```text theme={null}
sec  speech   need  cues
 01    13.0      -  1.1title@0.5,1.1script@2.9,1.1deck@6.27,1.1word@11.56
 02    14.6      -  2.1average@1.44,2.1code@9.43,2.1waited@11.31
                    ! 2.1formula: phrase not found: 'the formular'
 03    11.9      -  3.1idea@1.41,3.1again@7.8,3.1make@8.71
3 sections with cues, 1 unresolved  (estimated words: times are placeholders)
error[CONFIG]: 1 cue(s) could not be matched to the narration, and a slide whose cues are unresolved never appears.
  hint: Fix these phrases in cues.json, or pass --allow-unresolved-cues:
  section 02: 2.1formula: phrase not found: 'the formular'
```

`decktalk align` on its own prints the same table, reports the row as an `UNRESOLVED` finding and exits 1.
`build` raises instead, so it exits 3 and records nothing.

**Cause.** The cue phrase is not in the section's spoken words. The usual reasons, most common first:

* The phrase has a typo.
* The script writes a number as words, and the phrase uses digits, or the other way around.
* The phrase uses another word form, such as "rates" for "rate".
* A hyphen joins two words into one token.
* The phrase has a curly apostrophe. Matching removes it, but the spoken word keeps a straight one.

**Fix.**

1. Open the section's `words_file` from `build/narration/takes.json`.
2. Find the words as the voice says them.
3. Copy those words into the cue's `on` value in `cues.json`.
4. Run `decktalk align`.

If you want to build without the cue, pass `build --allow-unresolved-cues`. A slide whose cues are all
unresolved never mounts.

**More.** [Matching rules](/concepts/cues#matching-rules)

### `not in` its page in align

```text theme={null}
 02    14.6      -  2.1average@1.44,2.1formula@5.67,2.1code@9.43,2.1waited@11.31
                    ! 2.1code: not in deck/index.html
                    ! 2.1codex: data-cue="2.1codex" in deck/index.html has no entry in cues.json
3 sections with cues, 0 unresolved  (estimated words: times are placeholders)
error[CONFIG]: 1 cue id(s) in cues.json appear nowhere in the page that plays them, so the page would never reveal them.
  hint: Add data-cue="2.1code" to the slide in deck/index.html, fix the id in cues.json, or pass --allow-unknown-cues. The ids are:
  section 02: 2.1code: not in deck/index.html
```

A rename usually prints both lines, because the id `cues.json` names is now missing from the page and the id
the page carries is missing from `cues.json`. The second line is the `UNCUED ELEMENT` finding.

**Cause.** `align` looks for each cue id in its page in quotes or backticks, and did not find this
one. Either the id in `cues.json` has a typo, or no slide uses the cue.

**Fix.**

1. If the id has a typo, fix it in `cues.json`.
2. If no slide uses the cue, add `data-cue="<id>"` to the element in the page.
3. If the page builds its cue ids at run time, pass `--allow-unknown-cues`.

A key of a slide's `preview` object in a `DeckTalk.scene` call also counts as a mention, because it is a quoted
literal. A `data-preview="2.1code@8"` attribute does not, because the id there is part of a longer string.

**More.** [Cue mismatches](/concepts/cues#cue-mismatches)

### `UNRESOLVED` in align or verify

**Cause.**

* In `align --json`, a note has the verdict `UNRESOLVED` when a phrase is not found or the section has no words.
* In `verify`, a cue named on the command line is not in `cue-times.json`. The row reads `UNRESOLVED: the cue is not in cue-times.json`.

**Fix.**

1. If `align` printed it, follow [`phrase not found` in align](#phrase-not-found-in-align).
2. If `verify` printed it, check the `SECTION:CUE` spelling against `build/cue-times.json`.
3. If the cue is new, run `decktalk align` before `verify`.

**More.** [`decktalk verify`](/reference/cli#decktalk-verify)

### `UNKNOWN CUE` in align

**Cause.** In `align --json`, a note has the verdict `UNKNOWN CUE` when a cue id is not in its page. The
table prints the same note as `<cue>: not in <page>`.

**Fix.**

1. Follow [`not in` its page in align](#not-in-its-page-in-align).

**More.** [`decktalk align`](/reference/cli#decktalk-align)

### `shorter than the visuals need` in align

The note reads `speech <S>s is <D>s shorter than the visuals need`.

**Cause.** The section's speech ends before the `min_seconds` that `cues.json` sets for it. This is an
uncertain finding, so `align` exits 1 only with `--strict`.

**Fix.**

1. If the slides need more time, add words or a `[pause N]` to the section in `script.md`.
2. If the slides are fine, lower or remove `min_seconds` in `cues.json`.

**More.** [cues.json](/reference/cues-json)

### `is past the end of the audio` in align

**Cause.** A cue time is later than the section's audio, usually because of a large offset key. This
note is not a finding.

**Fix.**

1. Reduce the cue's `offset` in `cues.json`, or move the cue to an earlier phrase.

**More.** [cues.json](/reference/cues-json)

### `occurs N times in this section` in align

The note reads `'<phrase>' occurs <N> times in this section, at <T>s, <T>s. The cue uses the first. Set "occurrence" to choose one.`

**Cause.** The cue phrase matches more than one run of the section's spoken words, and the cue does not set
`occurrence`. The cue fires on the first match. If you meant a later one, the slide appears early, maybe by
many seconds. This note is not a finding, so `align` exits 0, even with `--strict`.

**Fix.**

1. Compare the times in the note with the moment the visual should appear.
2. If a later match is right, set `"occurrence"` to its position, such as `2`, in `cues.json`.
3. If the first match is right, set `"occurrence": 1` to keep it and silence the note.
4. Or make the phrase longer, so it matches only once.

**More.** [Matching rules](/concepts/cues#matching-rules)

### `no words` in align

The note reads `no words (estimated takes)` or `no words (missing words file)`.

**Cause.** The section's words file is empty or missing, so no phrase can resolve. Only `$start`
resolves.

**Fix.**

1. Run `decktalk narrate` again. For a rehearsal, run `decktalk narrate --no-voice` in a copy of the project.
2. Run `decktalk align`.

**More.** [`decktalk narrate`](/reference/cli#decktalk-narrate)

### `is not in decktalk.toml` in align

The error reads `cues.json: section <N> is not in decktalk.toml`.

**Cause.** A section key in `cues.json` has no `[[section]]` table of the same number.

**Fix.**

1. If the key is a typo, fix it in `cues.json`.
2. If the section is new, add its `[[section]]` table.

**More.** [cues.json](/reference/cues-json)

## preflight

### `NO CHANGE` or `THIN CHANGE?` in preflight

**Cause.** The frozen frame at the cue differs from the frozen frame before it by less than the `[verify]`
floors, or by less than `thin_change_factor` times them. The reveal is small even in its end state, so `verify`
is likely to read the same on the final mp4.

**Fix.**

1. Open the row's two PNG files under `build/preflight/NN/`.
2. If the reveal is too small to see, make it larger or give it more contrast in the page.
3. If the reveal is small on purpose, mark the cue `"verify": false`. Or leave it, and check it by eye after the build.

**More.** [`decktalk preflight`](/reference/cli#decktalk-preflight), [`THIN CHANGE?` in verify](#thin-change-in-verify)

## record

### `PAGE ERROR` in record

`record` logs `[page] NN  page error: <text>`, where `NN` is the section number. `build` stops after
the record table. A page with no catalog logs
`no window.__decktalk.catalog (is decktalk-runtime.js included, and does the page register a scene?)`.

**Cause.** The page threw an uncaught error, or it has no runtime catalog. The usual reasons, most
common first:

* A `render` template has a single backslash, such as `\underline`, which is a syntax error.
* The runtime `<script>` comes after the `DeckTalk.scene` calls.
* The page does not load `decktalk-runtime.js`.

**Fix.**

1. Run `decktalk serve` and open the page from the URL it prints, with `?scene=N&hud=1`.
2. Read the error in the browser console.
3. Fix the page.
4. Record the section again.

**More.** [Record one section again](/guides/rebuild-one-section#record-one-section-again)

### `STALLED` in record

`record` prints `STALLED <ms>ms` and logs `frame stall(s) after narration t=0`, and
`recording section NN again`.

**Cause.** The machine was too busy to paint, so a reveal was recorded late. After narration t=0, the
page saw a gap between two frames longer than `[record] stall_ms` (150).

**Fix.**

1. Close other work, or use a less busy machine.
2. Record the section again.

`record` already tried again up to `[record] retries` (2) times. A long first draw under the cover,
before t=0, is not a stall.

**More.** [Record one section again](/guides/rebuild-one-section#record-one-section-again)

### `TRUNCATED` in record

**Cause.** The recording is shorter than requested by more than `[record] truncated_slack_seconds`
(0.5). Chromium was stopped, or the machine stalled.

**Fix.**

1. Record the section again.
2. Run `decktalk record --only N` again.

`build` exits 0 on `TRUNCATED`, so a script must read the `record` table or its JSON.

**More.** [Record one section again](/guides/rebuild-one-section#record-one-section-again)

### `NO COVER` in record

`record` logs `no magenta cover found; narration t=0 is a guess`, and the log's `t0_method` starts with
`NO COVER`.

**Cause.** `record` found no magenta cover in the first `[record] cover_scan_seconds` (4.0) of the recording,
so t=0 is a guess. The usual reasons:

* The page removes the cover itself.
* A page written by hand starts its clock at load instead of at `DeckTalk.startClock()`.

**Fix.**

1. Make sure that the page loads the packaged `decktalk-runtime.js`.
2. If the machine is very slow, raise `[record] min_cover_seconds`.
3. Record the section again.

Without a cover, `record` uses the first painted frame plus `settle_seconds`. If no frame is painted,
it uses 1.1 s plus `settle_seconds`.

`record` scans only the first `[record] cover_scan_seconds`. If narration t=0 comes later, `record` still
reports `cover`, and every reveal is late. If you raise `min_cover_seconds` near 4, raise `cover_scan_seconds` too.

**More.** [The handshake](/concepts/page-contract#the-handshake)

### `BLACK?` in record

**Cause.** The brightest luma at the middle of the recording (`MAX50`) is below `[record] black_ymax`
(40). Usually the page threw before it drew anything, or the slide is dark on purpose.

**Fix.**

1. Run `decktalk serve` and open the page from the URL it prints, with `?scene=N&hud=1`.
2. If the page is blank, read the browser console and fix the error.
3. If the slide is dark on purpose, do nothing. `BLACK?` exits 1 only with `--strict`.

**More.** [`decktalk record`](/reference/cli#decktalk-record)

### `KATEX ERROR` or `KATEX NOT LOADED` in record

**Cause.** The page's equations were never typeset, so the slide shows the source instead. Both are
certain findings, and `verify` reports them again from the recording log.

* `KATEX ERROR` follows `data-tex could not be parsed: "<tex>"`. A backslash inside a `render` template is single.
* `KATEX NOT LOADED` follows `KaTeX did not load within 5 s, so [data-tex] elements stay plain text`. The page's KaTeX tags point nowhere.

**Fix.**

1. If a value did not parse, write every backslash twice inside the `render` backticks. In a
   `<template data-slide>` a backslash is written once, which is why the starter's equation is markup.
2. If KaTeX did not load, check that `deck/katex/` holds `katex.min.js`, `katex.min.css`, and `fonts/`.
3. Run `decktalk doctor` and check that the `katex` row is `ok`.
4. In `deck/index.html`, use the two local tags below.
5. Record the section again.

```html theme={null}
<link rel="stylesheet" href="./katex/katex.min.css">
<script src="./katex/katex.min.js"></script>
```

The starter's `deck/index.html` loads KaTeX before the runtime, which is the order a page needs.

**More.** [Build in CI and offline](/guides/ci-and-offline)

### `no narration span yet` in record

**Cause.** A page section has no take in `build/narration/takes.json`, so it has no length to record.
Usually the script has no `## N.` heading for that section, or `narrate` has not run since you added it.

**Fix.**

1. If the heading is missing, add `## N. Title` to `script.md`.
2. Run `decktalk narrate`.

**More.** [Headings](/reference/script-md#headings)

### A section is early or late by a fixed amount

**Cause.** Nothing is printed. The recording's t=0 is wrong, so every reveal in the section is off by
the same amount.

**Fix.**

1. Open `build/recordings/NN.json` and read `t0_method`.
2. If it starts with `NO COVER`, follow [`NO COVER` in record](#no-cover-in-record).
3. Record the section again.

**More.** [Record one section again](/guides/rebuild-one-section#record-one-section-again)

## assemble

### `is missing, so a slate plays` in assemble

```text theme={null}
section 04: media/intro.mov is missing, so a slate plays for 4s. Drop your clip at that path. The section is optional, so --strict allows the slate
```

**Cause.** The file that `clip` names does not exist, so a titled slate plays for `slate_seconds`.

The section in the sample sets `optional = true`, so its warning ends with
`The section is optional, so --strict allows the slate`. A section without `optional` ends at
`Drop your clip at that path`.

**Fix.**

1. If you have the video, put it at the path in `clip`.
2. If the section sets `optional = true`, delete that line after the clip is in place.
3. If you do not want the clip, delete the section from both `decktalk.toml` and `script.md`.

**More.** [Add a clip section](/guides/clip-section)

### `clip missing` or `recording missing` in assemble

```text theme={null}
error[MISSING_INPUT]: section 4: clip missing: ~/clip-lesson/media/intro.mov. Put your clip at that path, or set optional = true on the section to play its slate under --strict.
```

**Cause.** `--strict` turns a missing recording into an error. It does the same for a missing clip,
unless the clip section sets `optional = true`. Either way the command exits 3 and writes no video.

**Fix.**

1. If a clip is missing, put the video at the path in `clip`.
2. If you want the slate for now, set `optional = true` on the clip section.
3. If a recording is missing, record the section again.

**More.** [Clip section keys](/reference/decktalk-toml#clip-section-keys)

### `using black` in assemble

**Cause.** A page section has no recording, so `assemble` plays black for that section.

**Fix.**

1. Record the section again.

**More.** [Record one section again](/guides/rebuild-one-section#record-one-section-again)

### `has no span in` in assemble

**Cause.** A page section has no take in `build/narration/takes.json`, so it has no span to cut to. The
script has no heading for it, or `narrate` has not run since you added it.

**Fix.**

1. If the heading is missing, add `## N. Title` to `script.md`.
2. Run `decktalk build`.

**More.** [Headings](/reference/script-md#headings)

### `music missing` in assemble

```text theme={null}
music missing (~/my-lesson/build/music/music.mp3), so there is no music. Run `decktalk soundscape` to make it
```

**Cause.** `[mix]` names a music or ambience file that does not exist. The video plays without
it. The starter has no `[mix]` sound keys at all, so this only follows a key you added.

**Fix.**

1. If you want the sound, run `decktalk soundscape` or put your own file at the path.
2. If you do not want it, remove the key from `[mix]`.

**More.** [Sound](/concepts/sound)

### `unresolved; skipped` in assemble

`assemble` logs `marker '<name>' unresolved; skipped` or `sfx <file>: cue '<cue>' in section <N> is unresolved; skipped`.

**Cause.** A marker's phrase or a sound effect's cue did not resolve, so `assemble` left it out.

**Fix.**

1. If a marker is skipped, check its `section` and `on` values in the markers file.
2. If a sound effect is skipped, check that `align` resolved its cue in that section.
3. Run `decktalk assemble`.

**More.** [`markers.json`](/reference/decktalk-toml#markers-json)

### `[loud] skipped` in assemble

```text theme={null}
[loud] skipped: the narration is a silent placeholder, so the soundtrack is encoded as it was mixed
```

**Cause.** A build without voice has a click track, not speech, so `assemble` skips the loudness pass. The
clicks keep their level so that `verify` can find them.

**Fix.** None is needed. A voiced build runs the loudness pass.

**More.** [Loudness](/concepts/sound#loudness)

### `true peak` or `integrated loudness` in assemble

`assemble` logs `[loud] true peak <X> dBTP is above the <Y> dBTP ceiling` or
`[loud] integrated loudness <X> LUFS is <D> LU from the <Y> LUFS target`.

**Cause.** After the loudness pass, the voiced mix misses a `[mix.loudness]` target. With `--strict`,
the miss is an error.

**Fix.**

1. Lower the music, ambience, or sound effect levels in `[mix]`.
2. Run `decktalk assemble`.

**More.** [`[mix.loudness]`](/reference/decktalk-toml#mix-loudness)

## verify

### `BLACK` in verify

**Cause.** The brightest luma 0.2 s after a section start is at most `[verify] visible_ymax` (60).
Nothing bright is on screen when the section starts.

**Fix.**

1. Make sure that the scene's first cued slide draws something at t=0.
2. If a dip to black is long on purpose, raise `[verify] after_dip_seconds`.

**More.** [Section starts](/reference/verify#section-starts)

### `SPEECH AT CUT` in verify

**Cause.** The narration in the last 0.15 s before a cut is louder than -40 dBFS. The voice was still
speaking when the picture cut.

**Fix.**

1. Raise the section's `tail_seconds`, or `[narration] min_tail_seconds`, to leave more silence after the last
   word.

If the section must stay short, end its script sooner instead.

Clip sections carry their own audio and have no cut row.

**More.** [Cuts](/reference/verify#cuts)

### `POP AT CUT` in verify

**Cause.** A section sets `seamless = true`, but its first frame differs from the previous section's last
frame by more than `[verify] max_pop_percent` (0.1 percent of the pixels). The picture jumps at the cut. The
usual reasons:

* The page opens in a different state than the previous page ended in, such as a slide that is not shown yet.
* An element sits at a different position or size in the two pages.
* The previous section's last slide fires after its narration ends, so its recording ends early.

**Fix.**

1. Run `decktalk screenshots --section N --at 0` for this section, and compare it with the last frame of the previous section.
2. Make the page's opening state match the previous page's final state.
3. If the jump is intended, remove `seamless` from the section.

**More.** [Cut continuity](/reference/verify#cut-continuity)

### `NO CHANGE` in verify

**Cause.** The picture did not change enough across the cue, or it changed no more than it was already changing.
The usual reasons:

* The reveal is very small or very slow.
* The reveal changes only color at the same brightness. `verify` compares luma only.

**Fix.**

1. Run `decktalk screenshots --section N --at S`, where `S` is just after the value in the `cue` column.
2. If the reveal is subtle on purpose, mark the cue `"verify": false` in `cues.json`.
3. If the reveal is slow, lengthen `[verify] probe_delays`.

A cue less than a second after another cue gets probes that fit the gap. `verify` logs `another cue is close`
for it. A slow reveal may not finish inside a short gap. Check such a reveal by eye.

**More.** [Change test](/reference/verify#change-test), [Close cues](/reference/verify#close-cues)

### `THIN CHANGE?` in verify

**Cause.** The cue passed the change test, but only just. Its `chg %` is below 0.3, or its `chg %` minus its
`ctl %` is below 0.3. Those limits are `[verify] thin_change_factor` (3) times the floors of 0.1. A slightly
smaller reveal, or a little more motion elsewhere, would read `NO CHANGE`. This is an uncertain finding, so
`verify` exits 1 on it only with `--strict`.

**Fix.**

1. Run `decktalk screenshots --section N --at S`, where `S` is just after the value in the `cue` column.
2. If the reveal is too small to see, make it larger or give it more contrast in the page.
3. If the reveal is small on purpose and plainly visible, leave it. Or mark the cue `"verify": false`.
4. To turn the warning off, set `[verify] thin_change_factor = 1`.

**More.** [Change test](/reference/verify#change-test)

### `OFF CUE` in verify

This example shows the format of an `OFF CUE` row.

The row keeps the shape of every other cue row, with `OFF CUE` in place of `changed`.

```text theme={null}
check                 cue       at   chg %   ctl %   offset     a/v  result
3:3.1make            8.71    38.87   10.85    0.00    -90ms  -118ms  OFF CUE
```

**Cause.** The picture changed, but the offset column is past 80 ms or the `a/v` column is past 120 ms.
The table prints no distance, so compare the columns with those limits.

* A negative offset column means that something moved before the cue. Often an earlier reveal is still animating, or a `data-delay` element appeared at the mount.
* A positive offset column of more than a frame or two means that the reveal has its own delay, such as a CSS transition.

**Fix.**

1. Run `decktalk screenshots --section N --at S` for times around the value in the `cue` column.
2. Find the early motion or the delay in the frames.
3. If the delay is intended, raise `[verify] max_offset_frames`.

If only the `a/v` column is past its limit, see [A large `a/v` value in verify](#a-large-a/v-value-in-verify).

**More.** [Onset and offset](/reference/verify#onset-and-offset)

### A large `a/v` value in verify

**Cause.** Nothing but `OFF CUE` is printed. The audio and picture in the final file are out of step,
or a louder sound effect sits near the cued word.

**Fix.**

1. Build with `decktalk build --no-voice --no-soundscape` to rule out the soundscape.
2. Open `build/recordings/NN.json` and check that `t0_method` starts with `cover`.
3. Record the section again.
4. Check that the offset column alone is small.

A build without voice puts a click at every word start, and the `a/v` column compares the picture with that
click. The click and the cue come from the same word time. A large value therefore points at the
recording or the mix.

**More.** [verify](/reference/verify#cues)

### `NO_CLICK` in verify

**Cause.** After a build without voice, `verify` found no click within `[verify] click_search_seconds` (0.25)
of the cued word's start. The `a/v` column shows `-`, and the JSON reason is `NO_CLICK`.

**Fix.** None is needed. `verify` still judges the cue on its offset column.

A `$end` cue gets `NO_CLICK` when its last word is longer than `click_search_seconds`. `$end` sits on
the end of the last word, and clicks sit on word starts.

**More.** [verify](/reference/verify#cues)

### `skipped` in verify

**Cause.** `verify` measured nothing for the cue. The reason follows the verdict, and a skipped row
never fails.

**Fix.**

1. Find the reason in [Skipped rows](/reference/verify#skipped-rows), and apply its fix.

**More.** [Results](/reference/verify#results)

### `malformed check` in verify

The error reads `malformed check '<text>'; want SECTION:CUE, e.g. 3:3.1draw`.

**Cause.** A cue argument does not start with a section number and a colon.

**Fix.**

1. Write each cue as `SECTION:CUE`, such as `8:7.1checked`.

**More.** [`decktalk verify`](/reference/cli#decktalk-verify)

### `nothing to verify` in verify

```text theme={null}
error[MISSING_INPUT]: the section videos and the final mp4 are not both there, so there is nothing to verify.
  hint: Run `decktalk assemble` first.
```

**Cause.** The project has no assembled video yet.

**Fix.**

1. Run `decktalk build --no-voice`, or `decktalk assemble` if the recordings exist.
2. Run `decktalk verify`.

**More.** [`decktalk build`](/reference/cli#decktalk-build)

### `is not a section in decktalk.toml` in assemble or verify

```text theme={null}
build/sections/09.mp4 is not a section in decktalk.toml, so verify ignores it. Delete the file if an earlier build left it.
```

**Cause.** `build/sections/` holds a section video whose number is not a section in `decktalk.toml`. An earlier build
usually left it before you renumbered or removed sections. `assemble` and `verify` read only the sections in
`decktalk.toml`, so the file changes nothing.

**Fix.**

1. If you renumbered or removed the section, delete the file.

**More.** [`build/out/`](/reference/artifacts#build-out)

### A typewriter reveal fails the cue check

**Cause.** Nothing but `NO CHANGE` is printed. An element with `data-text="type"` or `data-text="spoken"` appears a
little at a time, so the first probe sees too little change.

**Fix.**

1. Give the element's container a reveal that appears at once on the same cue, such as `data-reveal="fade"`.
2. Keep `data-text="type"` or `data-text="spoken"` on the text inside it.

**More.** [Slide recipes](/guides/slide-recipes)

## words and clip

### `The take index is not there` in words or clip

```text theme={null}
error[MISSING_INPUT]: The take index is not there, so no section has a start to cut from.
  hint: Run `decktalk narrate`, or `decktalk narrate --no-voice` to spend nothing.
```

The command exits 3.

**Cause.** The project has no narration yet, so no section has word times.

**Fix.**

1. Run `decktalk narrate`, or `decktalk build --no-voice`.
2. Run the command again.

**More.** [`decktalk words`](/reference/cli#decktalk-words)

### `has no section video` in clip

```text theme={null}
error[MISSING_INPUT]: section 1 has no section video at ~/my-lesson/build/sections/01.mp4. Run `decktalk assemble` first.
```

**Cause.** `clip` cuts from the section video that `assemble` writes, and the section has none.

**Fix.**

1. Run `decktalk build --no-voice`, or `decktalk assemble` if the recordings exist.
2. Run `decktalk clip` again.

**More.** [`decktalk clip`](/reference/cli#decktalk-clip)

### `is a clip section` in clip

```text theme={null}
error[CONFIG]: section 4 is a clip section.
  hint: Cut a clip from a page section.
```

**Cause.** The section number names a clip section. A clip section has no narration, so `clip` has no mp3 to cut.

**Fix.**

1. Run `decktalk status`. Each page section row names its page, and each clip section row starts with `clip`.
2. Run `decktalk clip` with the number of a page section.

**More.** [`decktalk clip`](/reference/cli#decktalk-clip)

### `cuts the word` in clip

```text theme={null}
section 01: the span cuts the word 'This' in two, so the words file leaves it out
section 01: the span cuts the word 'DeckTalk.' in two, so the words file leaves it out
seconds 1.08, words 1 | 0 certain, 2 uncertain finding(s)
```

**Cause.** `--start` or `--end` falls inside a spoken word. The clip keeps the part of the word inside the span, but the
words file has no entry for the word, so no caption shows it. It is an uncertain finding, so `clip` exits 1 only with
`--strict`.

**Fix.**

1. Run `decktalk words --only N` for the section.
2. Move `--start` before the word's start, or `--end` after the word's end, into the silence next to the word.
3. Run `decktalk clip` again.

**More.** [`decktalk words`](/reference/cli#decktalk-words)

## Pages in a browser

The page writes each warning to the browser console with the prefix `decktalk:`. During a recording,
`record` logs it as `[page] NN  <warning>`, where `NN` is the section number, and writes it to the
recording log under `warnings`.

### `data-text="spoken" text not found in the spoken words` in a page

**Cause.** The text of a `data-text="spoken"` element matches no run of the section's spoken words, so the
element appears whole. Usually the slide writes a number as digits and the script writes it as words.

**Fix.**

1. Compare the element's text with the sentence in `script.md`.
2. Make the words match. Case and punctuation do not matter.

**More.** [Runtime](/reference/runtime)

### `matches no element, handler, or slide` in a page

```text theme={null}
[page] 02  cue "2.1code" matches no element, handler, or slide
```

**Cause.** The cue fired, but no element has that `data-cue`, no handler is registered for it, and no
slide has that id. `align` catches this only when the id has left the page file entirely. An id that is
still a quoted literal somewhere in the page, such as a key of a slide's `preview` object, passes `align`
and warns here instead.

**Fix.**

1. Add `data-cue="<id>"` to the element that should appear.

**More.** [Cue mismatches](/concepts/cues#cue-mismatches)

### `unknown cue id` in a page

The warning reads `unknown cue id <id> (no slide id, owns list or preview object matches it)`.

**Cause.** The page received a cue in `?cues=` that no slide in the playing scene owns.

**Fix.**

1. Check the id against the slide ids and their `owns` lists.
2. Add the id to the `owns` list of the slide that should own it.

**More.** [Cue ownership](/concepts/page-contract#cue-ownership)

### `owns no cue` in a page

The warning reads `slide "<id>" owns no cue in ?cues=, so it never appears`.

**Cause.** In cue mode, a slide mounts at its earliest cue. This slide owns none of the section's cues.

**Fix.**

1. Add a cue for the slide to `cues.json`.

If a cue for the slide already exists, list its id in the slide's `owns` instead.

**More.** [Cue mismatches](/concepts/cues#cue-mismatches)

### A page is empty, or `window.__decktalk` is missing

**Cause.** Nothing is printed. The page does not load `decktalk-runtime.js`, or its runtime `<script>`
tag comes after the `DeckTalk.scene` calls.

**Fix.**

1. Load `decktalk-runtime.js` before any `DeckTalk.scene` call.
2. Run `decktalk serve` and open the page from the URL it prints, to check the scene index.

**More.** [Page contract](/concepts/page-contract)

## Speed

### A build is slow

**Cause.** Nothing is printed. `record` plays each page section in real time, and encoding adds more
time.

**Fix.**

1. If you changed one section, run `decktalk build --only N`.
2. For drafts, set `DECKTALK_VIDEO_PRESET=veryfast`, or `preset = "veryfast"` under `[video]`.
3. For the final video, go back to the default preset.

A build without voice of the starter took 64 s for its 44.88 s video. The machine was a MacBook Pro
with an Apple M5 Pro and 64 GB of memory.

**More.** [Rebuild one section](/guides/rebuild-one-section)

## Related

If no entry fits, open an issue. Include the output of `decktalk doctor` and the `[[section]]` tables
involved.

* **Look up an option or exit code:** [CLI](/reference/cli)
* **Read a verify table:** [verify](/reference/verify)
* **Ask a general question:** [FAQ](/help/faq)


# Narrated presentations, cut to the word
Source: https://docs.decktalk.ai/index

Make a narrated video from a markdown script and HTML slides, where each reveal starts on its word.

<img alt="A playhead moves along the narration “A bowl. A ball. One. Two, three.” with a tick under each word. A bowl and a ball appear on the slide on their words. On each count word, the ball steps down the bowl and a box fills with that word's start time: 4.49 s, 5.26 s, and 5.77 s." />

<img alt="A playhead moves along the narration “A bowl. A ball. One. Two, three.” with a tick under each word. A bowl and a ball appear on the slide on their words. On each count word, the ball steps down the bowl and a box fills with that word's start time: 4.49 s, 5.26 s, and 5.77 s." />

## Start here

<div>
  [Quickstart](/quickstart)<br />Install DeckTalk, build the starter without an API key, and then add your voice.

  [Your first deck](/guides/first-deck)<br />Write one section across `script.md`, `decktalk.toml`, `cues.json`, and a page. Then verify its reveals.

  [Requirements and costs](/requirements)<br />What DeckTalk needs on your machine, and which commands spend credits.
</div>

## Understand the model

* [How it works](/concepts/how-it-works): the five stages, how DeckTalk finds narration t=0, and what `decktalk verify` checks.
* [Cues](/concepts/cues): how a cue such as `1.1bowl` names the phrase a reveal starts on.
* [Writing for the ear](/guides/writing-for-the-ear): give every reveal a word to start on.
* [The page contract](/concepts/page-contract): how a slide talks to the recorder. [Design a slide](/guides/design-a-slide) covers slide size, reveal effects, and the camera push.

<div>
  Building with an agent? The [reference card](/reference/card) puts every file, command, rule, and exit code in one place, and [`llms.txt`](https://docs.decktalk.ai/llms.txt) indexes every page.
</div>


# Quickstart
Source: https://docs.decktalk.ai/quickstart

Install DeckTalk, build the starter video without an account, then add your voice.

This quickstart installs DeckTalk and builds the starter video, first with no account and then with your voice. Only part 3 needs an ElevenLabs API key.

If an agent does these steps for you, give it the [Reference card](/reference/card).

## Before you start

* You need Python 3.12 or later.
* You need uv, pipx, or pip.
* On Linux, step 2 needs sudo or root.
* Part 3 needs an ElevenLabs API key and a voice id.

## Part 1: Install DeckTalk

<Steps>
  <Step title="Install DeckTalk">
    Install the `decktalk` command with your Python installer.

    <Tabs>
      <Tab title="uv">
        ```console theme={null}
        uv tool install decktalk
        ```

        uv is a Python package manager. If you do not have it, [install uv](https://docs.astral.sh/uv/getting-started/installation/) first.
      </Tab>

      <Tab title="pipx">
        ```console theme={null}
        pipx install decktalk
        ```
      </Tab>

      <Tab title="pip">
        ```console theme={null}
        python -m venv .venv && source .venv/bin/activate
        pip install decktalk
        ```

        On Windows, activate the environment with `.venv\Scripts\activate`.
      </Tab>
    </Tabs>

    ```text theme={null}
    Installed 1 executable: decktalk
    ```

    Check that the installer names the `decktalk` executable.
  </Step>

  <Step title="Download Chromium and ffmpeg">
    `decktalk install` downloads the tools that DeckTalk runs. Run it one time per machine.

    ```console theme={null}
    decktalk install
    ```

    ```text theme={null}
    == Chromium (Playwright)
    == ffmpeg 8.1.2
       ffmpeg  ~/Library/Caches/decktalk/ffmpeg/8.1.2-darwin-arm64/ffmpeg
       ffprobe ~/Library/Caches/decktalk/ffmpeg/8.1.2-darwin-arm64/ffprobe
    install complete
    ```

    Check that the last line is `install complete`. On Linux, this step asks for sudo. [What install downloads](/requirements#what-install-downloads) says where each download goes.
  </Step>

  <Step title="Check the tools">
    `decktalk doctor` reports each tool that DeckTalk needs.

    ```console theme={null}
    decktalk doctor
    ```

    ```text theme={null}
    components 6, missing 0
    python    ok      3.13.1 (~/.local/share/uv/tools/decktalk/bin/python)
    chromium  ok      151.0.7922.34
    ffmpeg    ok      ~/Library/Caches/decktalk/ffmpeg/8.1.2-darwin-arm64/ffmpeg
    ffprobe   ok      ~/Library/Caches/decktalk/ffmpeg/8.1.2-darwin-arm64/ffprobe
    config    ok      none (at ~/Library/Application Support/decktalk/decktalk.toml)
    katex     ok      0.18.7 in the wheel (~/.local/share/uv/tools/decktalk/lib/python3.13/site-packages/decktalk/katex)
    ```

    Check that the first line reads `missing 0` and that every row says `ok`. If a row does not, run `decktalk install` again. The `config` row is the per-machine settings file, which is optional, so `none` there is a passing row.
  </Step>
</Steps>

## Part 2: Build the starter without an account

<Steps>
  <Step title="Create the starter">
    `decktalk init` writes the starter: three sections, one page, one equation, and a build that
    takes about a minute. Nothing in it is a demo you have to delete first.

    ```console theme={null}
    decktalk init my-lesson
    ```

    ```text theme={null}
    files 16
    created ~/my-lesson
      decktalk.toml  the project file: sections -> pages or clips, voice, mix, soundscape
      script.md      the narration (## N. sections)
      cues.json      which spoken phrase each visual lands on
      deck/          the pages, decktalk-runtime.js and katex/ (open a page for its scene index)
      AGENTS.md      the rules an agent working in this project follows
      .agents/skills the six DeckTalk skills, linked from .claude/skills
    next: `decktalk build --no-voice` renders with placeholder narration, no API key and no spend
          then cp .env.example .env  (ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID) and `decktalk build`
    ```

    If you skipped step 2, run `decktalk install` now. `init` copies the packaged KaTeX into `deck/katex/` either way.

    <Tip>`decktalk init --example lesson my-lesson` writes a finished lesson instead, to read rather than
    to start from. `--no-skills` leaves the six skills out.</Tip>
  </Step>

  <Step title="Go into the project">
    ```console theme={null}
    cd my-lesson
    ```
  </Step>

  <Step title="Open the slides in a browser">
    Serve the project and open the page it prints. This takes seconds, and you see the slides before
    you build. `decktalk serve` answers from your project directory on 127.0.0.1, which is the origin
    the recorder uses, so what you see is what the recorder will see. Press Ctrl-C to stop it.

    ```console theme={null}
    decktalk serve --open
    ```

    ```text theme={null}
    http://127.0.0.1:57962/deck/index.html
    serving /Users/you/my-lesson, and Ctrl-C stops it
    ```

    The port is any free one unless you set `--port`.

    <Frame>
      <img alt="The starter page in index mode, headed My Lesson. A line names the stage as 1920 by 1080 and gives the URL parameters: ?scene=N previews a scene, ?slide=ID freezes a slide, &speed=2, &hud=1, and &cues=id@s with &t0=. Under it are Scene 1 Open, Scene 2 How it works, and Scene 3 Close, each with a play link, and under each one a single slide with its hold seconds and its four cue ids." />
    </Frame>

    Check that the page shows an index of its three scenes, one slide each. Every cue id of a slide is listed beside it.
  </Step>

  <Step title="Build the video without an account">
    A build without voice uses estimated word times and a click track, so it needs no key. Recording runs in real time. On a MacBook Pro with Apple M5 Pro and 64 GB memory, this build took about 64 seconds. Read [What the starter shows](#what-the-starter-shows) while it runs.

    ```console theme={null}
    decktalk build --no-voice
    ```

    ```text theme={null}
    [caps] 9 cue(s) -> my-lesson.srt, my-lesson.vtt
    [chap] 3 chapter(s) -> my-lesson.chapters.txt
    done: ~/my-lesson/build/out/my-lesson.mp4  (44.88s)
    [4/5 assemble] done in 2.5s
    ===== verify =====
    ...
    stages 5, seconds 44.88
    built build/out/my-lesson.mp4
    ```

    Check that the last line starts with `built`. Each of the five stages prints a table of its own above it.
  </Step>

  <Step title="Play the video">
    <Tabs>
      <Tab title="macOS">
        ```console theme={null}
        open build/out/my-lesson.mp4
        ```
      </Tab>

      <Tab title="Linux">
        ```console theme={null}
        xdg-open build/out/my-lesson.mp4
        ```
      </Tab>

      <Tab title="Windows">
        ```console theme={null}
        start build\out\my-lesson.mp4
        ```
      </Tab>
    </Tabs>

    The video is 44.88 seconds long, in three sections, with a soft click on each word. [What the starter shows](#what-the-starter-shows) describes each one.
  </Step>
</Steps>

## Part 3: Add your voice and change a sentence

If you have no ElevenLabs account, stop here. The video without voice is a complete build.

<Steps>
  <Step title="Copy the example settings file">
    <Tabs>
      <Tab title="macOS and Linux">
        ```console theme={null}
        cp .env.example .env
        ```
      </Tab>

      <Tab title="Windows">
        ```console theme={null}
        copy .env.example .env
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set your key and voice id">
    In `.env`, replace the two placeholders with your API key and voice id.

    ```dotenv .env theme={null}
    ELEVENLABS_API_KEY=<your-elevenlabs-key>     # Profile, then API keys, on elevenlabs.io
    ELEVENLABS_VOICE_ID=<voice-id>               # the id on a voice's card under Voices
    ```

    A value that still starts with `<` counts as unset. DeckTalk never prints the key and never writes it under `build/`.
  </Step>

  <Step title="Build the video with your voice">
    <Warning>`decktalk build` without `--no-voice` spends ElevenLabs credits. [What spends credits](/requirements#what-spends-credits) lists the cost.</Warning>

    ```console theme={null}
    decktalk build
    ```

    The `narrate` stage prints one line per section it sends, and the run ends with `built` as before. It
    voices all three sections, because a click track is never reused as a voice. `decktalk narrate --dry-run`
    prints what the run will send and what it will cost before you start it.

    ```console theme={null}
    decktalk narrate --dry-run
    ```

    ```text theme={null}
     #  section                take         sent spoken  reason
    -----------------------------------------------------------
     1  open                   synthesize    140    131  no take yet
     2  how-it-works           synthesize    150    141  no take yet
     3  close                  synthesize    126    120  no take yet
    -----------------------------------------------------------
    voice 3 section(s): 416 characters sent, 392 spoken, 949 with context. 0 cached. About $0.12 at $0.30 per 1,000.
    ```

    The rate comes from `[voice] price_per_1000_characters` in your own `decktalk.toml`, so the dollars are your plan's.
  </Step>

  <Step title="Change one word">
    In section 3 of `script.md`, add a word to the last line.

    ```diff script.md theme={null}
    -[beat] Make your own at decktalk dot AI.
    +[beat] Make your own today at decktalk dot AI.
    ```

    The cue for that line matches the phrase "Make your own", which is still there, so `cues.json`
    and the page need no change.
  </Step>

  <Step title="Build again">
    ```console theme={null}
    decktalk build
    ```

    DeckTalk voices only section 3 again. Sections 1 and 2 take their narration from the cache, because their text did not change. A take is named by the hash of its text and voice settings, so the two unchanged sections play the files they already have. [Rebuild one section](/guides/rebuild-one-section) says what each kind of edit runs again.

    <Tip>Run `decktalk narrate --dry-run` again after the edit. Sections 1 and 2 read `cached`, section 3 reads `synthesize`, and the totals count only what section 3 costs.</Tip>
  </Step>

  <Step title="Check that a reveal starts on its word">
    ```console theme={null}
    decktalk verify 3:3.1make
    ```

    ```text theme={null}
    check                 cue       at   chg %   ctl %   offset     a/v  result
    3:3.1make            8.71    38.87   10.85    0.00    +10ms    -6ms  changed
    ```

    Check that the result is `changed`. The offset column is the time from the cue time to the onset of the reveal, in milliseconds. The `a/v` column is filled only after a build without voice, because only a click track has clicks. [Verify](/reference/verify#cues) defines every column.
  </Step>
</Steps>

## What the starter shows

The starter is three sections on one page. Every slide is markup: a `<template data-slide>` inside a
`[data-scene]` wrapper, with a `data-cue` on each thing that appears. There is no JavaScript to read.

| Section         | Plays                      | What it shows                                                                                                                 |
| --------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 1. Open         | `deck/index.html`, scene 1 | The title, then a card for each of the two files you write, then the promise.                                                 |
| 2. How it works | `deck/index.html`, scene 2 | The heading, then one displayed equation typeset by KaTeX, then the same average as two lines of Python, then a closing band. |
| 3. Close        | `deck/index.html`, scene 3 | The idea, the line about rebuilding one part, and the end card.                                                               |

The equation is the one place the starter shows a trap: `data-tex` holds the TeX and the element's
own text is the fallback that shows if KaTeX ever fails to load. The comment beside it names all
three traps. [Design a slide](/guides/design-a-slide) is the next thing to read.

### The examples

`decktalk init --example NAME` writes a finished project instead of the starter.

| Name       | What it is                                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lesson`   | A lesson on how a model learns, with a figure drawn in code and moved on every cue. It is the example of a page that needs more than attributes. |
| `product`  | Reserved. It is the film that shows DeckTalk itself, and it ships with that film.                                                                |
| `tutorial` | Reserved. It is a short technical tutorial with a code slide, a terminal block and a screenshot.                                                 |

`decktalk init --example NAME` refuses a reserved name, so `lesson` is the one example to read today.

## Next

* **Write your own section:** [Your first deck](/guides/first-deck)
* **Make the script time well:** [Writing for the ear](/guides/writing-for-the-ear)
* **Rebuild only what changed:** [Rebuild one section](/guides/rebuild-one-section)


# Build artifacts
Source: https://docs.decktalk.ai/reference/artifacts

Look up the path, time base, and fields of every file that DeckTalk writes under build/.

DeckTalk writes every generated file under `build/`, and your own tools can read any of them. This page lists
each file, its time base, and its fields.

Field names in the JSON files match the dataclasses in `decktalk.artifacts`. The file shapes are part of the
stable surface that the [changelog](/changelog) tracks.

```text theme={null}
build/
  narration/     <hash>.mp3, <hash>.words.json, takes.json, narration.mp3
  cue-times.json
  recordings/    NN.webm, NN.json
  sections/      NN.mp4
  out/           <name>.mp4, <name>.srt, <name>.vtt, <name>.chapters.txt,
                 cuts.json, <name>-transcript.html, <name>-poster.png,
                 slates/NN-slate.png
  screenshots/   [<page>/]slide-<id>.png, [<page>/]slide-<id>-after-<cue>.png, section-NN-at-<S>s.png
  preflight/     the frozen frames that `decktalk preflight` compares
  progress.jsonl
  sfx/           ambience.mp3, <name>.mp3, and a manifest file next to each
  music/         music.mp3, its chunk files, and its manifest file
```

`NN` is the two-digit section number. `<hash>` is the content hash of a take, which is what identifies it:
`takes.json` says which section plays which take. `<name>` is `[project] name` in `decktalk.toml`. A clip
section has no take, words file, or recording.

## Time bases

Each time in these files counts from a fixed starting point, its time base. Read the time base before you
compare times from two files.

| Value                                                                                        | Counts from                                                                 |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `<hash>.words.json` `start` and `end`                                                        | The start of that take's mp3, which holds no silence of its own.            |
| `takes.json` section starts and ends                                                         | The start of `narration.mp3`, which holds the spoken sections back to back. |
| `cue-times.json`, `?cues=`, `?words=`, `decktalk words`, `decktalk clip --start` and `--end` | The section's own start, which is narration t=0 of its recording.           |
| A words file that `decktalk clip` writes                                                     | The start of that clip.                                                     |
| RecordingLog `t0_seconds`                                                                    | The start of the webm.                                                      |
| RecordingLog `frame_gaps` seconds                                                            | Narration t=0 of that recording, or `null` for a gap that ended before t=0. |
| `.srt`, `.vtt`, `.chapters.txt`, and the verify `at` and `cut at` columns                    | The start of the final mp4.                                                 |

A clip section adds its length to the final mp4, but not to `narration.mp3`. After a clip between two page
sections, a time in the final mp4 is the narration time plus the length of every earlier clip. A clip before
the first page section shifts every time. Page sections are cut on whole frames, so the two times can also
differ by up to one frame.

Example: a page section that follows a 4.36 s clip starts 4.36 s later in the final mp4 than it does in the
narration, and the whole-frame cuts before it move it by up to one more frame. `decktalk status` prints
narration times, and `build/out/cuts.json` prints final-mp4 times, so comparing the two rows for one section
gives the offset for that section.

## `build/narration/<hash>.words.json`

A words file lists each spoken word of one take, with its times in that take's mp3. The take carries no
silence of its own, so the first word can start at 0. Silence before a section is joined in when the takes
are joined, and [`decktalk words`](/reference/cli#decktalk-words) and `cue-times.json` include it.

```json theme={null}
[
 {
  "word": "This",
  "start": 0.0,
  "end": 0.461
 },
 {
  "word": "is",
  "start": 0.481,
  "end": 0.942
 },
```

| Field   | Type   | Meaning                                    |
| ------- | ------ | ------------------------------------------ |
| `word`  | string | The spoken word, with punctuation removed. |
| `start` | number | Start of the word, in seconds.             |
| `end`   | number | End of the word, in seconds.               |

Note: A build without voice writes estimated words, spaced evenly at `silent_words_per_minute`. Each estimated word
ends 0.02 s before the next one starts.

Note: [`decktalk words`](/reference/cli#decktalk-words) prints the same words in seconds after the section starts,
with the script's punctuation and case.

## `build/narration/takes.json`

The take index says which take each section plays. A take is identified by the content hash of everything
that changes its audio, and its mp3 is named by that hash, so inserting a section, renumbering one, or
retitling one moves no file and voices nothing. Two sections with the same words share one take.

The cache is the narration directory itself: a take whose mp3 and words file are on disk is a hit.
[`[narration] cache_dir`](/reference/configuration#narration) puts the take files alone outside `build/`,
where a fresh clone and a second worktree find them again, and where several projects may share them
because a hash names each one. `takes.json` and `narration.mp3` stay here, because they belong to one
project.

The index is also the narration clock. A section runs for its lead, its take up to where the take's sound
ends, and its tail, which is `lead_seconds` plus `sound_end_seconds` plus `tail_seconds`, and the sections are
joined in key order. Each of the three depends on the take and the section's own keys alone, so a section
keeps its length when a neighbour changes. Where each one sits in `narration.mp3` is therefore arithmetic over the rows: its start is the
sum of every earlier section's length, and its end is that plus its own. `decktalk status` prints those
times, and `decktalk words` prints each section's words against its own start.

```json theme={null}
{
  "script": "script.md",
  "model": "eleven_multilingual_v2",
  "output_format": "mp3_44100_128",
  "estimated": true,
  "estimate_basis": "150 wpm + declared pauses",
  "sections": {
    "01": {
      "index": 1,
      "chapter": "Open",
      "file": "silent-504cb8ea7d.mp3",
      "words_file": "silent-504cb8ea7d.words.json",
      "hash": "silent-504cb8ea7d",
      "word_count": 26,
      "estimated_seconds": 11.1,
      "duration_seconds": 12.6,
      "voiced": false,
      "target_seconds": null,
      "speech_end_seconds": 12.48,
      "sound_end_seconds": 12.487,
      "lead_seconds": 0.5,
      "tail_seconds": 1.3,
      "spoken": "This is DeckTalk. You write what you will say, and you write the slides that go with it. Then every picture waits for its own word."
    }
  },
  "total_seconds": 43.361
}
```

| Field                            | Type           | Meaning                                                                                                                                                                        |
| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `script`                         | string         | Path of the script, relative to the project.                                                                                                                                   |
| `model`                          | string         | Speech model the project voices with.                                                                                                                                          |
| `output_format`                  | string         | Audio format that the speech provider returned.                                                                                                                                |
| `estimated`                      | boolean        | True when any row is a placeholder take, so the times are guesses.                                                                                                             |
| `estimate_basis`                 | string         | Pacing of a build without voice, such as `150 wpm + declared pauses`. Empty after a voiced build.                                                                              |
| `sections`                       | table          | One entry per spoken section, keyed by `NN`.                                                                                                                                   |
| `sections.NN.index`              | integer        | Section number.                                                                                                                                                                |
| `sections.NN.chapter`            | string         | The chapter title: the section's own `chapter` key, else its `## N.` script heading, else `Section N`.                                                                         |
| `sections.NN.file`               | string         | Name of the take's mp3, which is its hash.                                                                                                                                     |
| `sections.NN.words_file`         | string         | Name of the take's words file, which is its hash.                                                                                                                              |
| `sections.NN.hash`               | string         | The take's content hash, and its identity. A placeholder take's hash starts with `silent-`.                                                                                    |
| `sections.NN.word_count`         | integer        | Word count of the spoken text.                                                                                                                                                 |
| `sections.NN.estimated_seconds`  | number         | Length estimate at `words_per_minute`.                                                                                                                                         |
| `sections.NN.duration_seconds`   | number         | Real length of the mp3, which holds none of the silence placed around it.                                                                                                      |
| `sections.NN.voiced`             | boolean        | False on the placeholder take that `--no-voice` wrote.                                                                                                                         |
| `sections.NN.target_seconds`     | number or null | Time budget from the time range in the heading, or `null` when the heading has none.                                                                                           |
| `sections.NN.speech_end_seconds` | number or null | End of the last spoken word.                                                                                                                                                   |
| `sections.NN.sound_end_seconds`  | number or null | Where the take's sound ends, measured from the mp3's own bytes: the start of the silence that runs to its end.                                                                 |
| `sections.NN.lead_seconds`       | number         | Silence placed before this take when the takes are joined: the section's `lead_seconds`, else `[narration] lead_seconds`. It is not in the mp3.                                |
| `sections.NN.tail_seconds`       | number         | Silence placed after `sound_end_seconds`: the section's `tail_seconds`, else `[narration] min_tail_seconds`. The join cuts or pads the take to it, and the mp3 is not changed. |
| `sections.NN.spoken`             | string         | The words sent to the voice, with the script's punctuation and case, and without break tags.                                                                                   |
| `total_seconds`                  | number         | Every section's lead, take to its sound end, and tail, which is the length of `narration.mp3`.                                                                                 |

Note: The section span runs from a section's start to its end in `narration.mp3`, and its length is
`lead_seconds + sound_end_seconds + tail_seconds`. The spoken span runs from that start to the end of the
last word, which is the start plus `lead_seconds` plus `speech_end_seconds`.

Note: Captions take their spelling from `spoken`, so they match the audio even after the script changes. A
take index without `spoken` falls back to the current script. [Rebuild one section](/guides/rebuild-one-section#the-narration-cache)
explains what the hash covers.

## `build/cue-times.json`

The cue times file holds every resolved cue of each section as an object. A section with no resolved cue is not in
the file.

```json theme={null}
{
  "estimated": true,
  "sections": {
    "01": [
      { "cue": "1.1title", "on": "This is DeckTalk", "at": 0.5, "word_at": 0.5 },
      { "cue": "1.1script", "on": "what you will say", "at": 2.9, "word_at": 2.9 },
      { "cue": "1.1deck", "on": "the slides", "at": 6.27, "word_at": 6.27 },
      { "cue": "1.1word", "on": "its own word", "at": 11.56, "word_at": 11.56 }
    ]
  }
}
```

| Field                   | Type           | Meaning                                                                               |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------- |
| `estimated`             | boolean        | True when the times come from the estimated words of a build without voice.           |
| `sections`              | table          | One array per spoken section, keyed by `NN`, in the order `align` resolved the cues.  |
| `sections.NN[].cue`     | string         | The cue id the page understands, as `cues.json` writes it.                            |
| `sections.NN[].on`      | string         | The phrase the cue was matched against, `$start` or `$end`.                           |
| `sections.NN[].at`      | number         | The cue time in seconds after the section starts, which is the `@` value of `?cues=`. |
| `sections.NN[].word_at` | number or null | Where the matched word begins, before the cue's `offset` key.                         |

The recorder joins the rows of one section into the `?cues=` value, as `cue id@at` items separated
by commas, and the page parser splits each item at the last `@`. A cue id starts with the id of the
slide that owns it, so section `01` above plays a scene whose one slide is `1.1`.

Note: A cue with no `offset` key has the same `at` and `word_at`. `verify` uses `word_at` after a build without
voice to find the click at the cued word, which
[the a/v value](/reference/verify#the-a/v-value) explains.

## `build/recordings/NN.json`

The recording log lists what `record` did for one page section, where narration t=0 sits in the webm, and how
the recording checked out. `record` writes the whole file once, when that section is finished, so the
measurement always belongs to the recording beside it and a long run can be read while it runs.

```json theme={null}
{
  "url": "http://project.localhost/deck/index.html?scene=1&cues=1.1title%400.5%2C1.1script%402.9%2C1.1deck%406.27%2C1.1word%4011.56&words=This%400.50%2Cis%400.98%2CDeckTalk%401.46%2CYou%401.94%2Cwrite%402.42%2Cwhat%402.90%2Cyou%403.38%2Cwill%403.87%2Csay%404.35%2Cand%404.83%2Cyou%405.31%2Cwrite%405.79%2Cthe%406.27%2Cslides%406.75%2Cthat%407.23%2Cgo%407.71%2Cwith%408.19%2Cit%408.67%2CThen%409.15%2Cevery%409.63%2Cpicture%4010.12%2Cwaits%4010.60%2Cfor%4011.08%2Cits%4011.56%2Cown%4012.04%2Cword%4012.52&t0=signal",
  "requested_seconds": 14.587,
  "settle_seconds": 1.449,
  "load_seconds": 0.054,
  "clock_start_seconds": 1.504,
  "assets": [
    "deck/index.html",
    "deck/katex/katex.min.css",
    "deck/katex/katex.min.js",
    "deck/decktalk-runtime.js"
  ],
  "external": [],
  "input_hash": "844a36af16cf6e9a",
  "t0_seconds": 1.44,
  "t0_method": "cover (36 magenta frames)",
  "t0_guessed": false,
  "checks": {
    "duration_seconds": 17.0,
    "wanted_seconds": 14.587,
    "luma": {
      "y10": 234.95,
      "y50": 199.75,
      "y90": 184.5,
      "max50": 243.0
    },
    "verdicts": []
  },
  "warnings": [],
  "page_errors": [],
  "frame_gaps": [],
  "spoken_log": [],
  "cue_log": [
    {
      "id": "1.1title",
      "due": 0.5,
      "ran": 0.5,
      "frame": 0.5,
      "describe": "the title, This is DeckTalk",
      "next": 0.508,
      "after": 0.517
    },
    {
      "id": "1.1script",
      "due": 2.9,
      "ran": 2.905,
      "frame": 2.905,
      "describe": "a card for script.md, the file that holds what you say",
      "next": 2.913,
      "after": 2.921
    },
    {
      "id": "1.1deck",
      "due": 6.27,
      "ran": 6.271,
      "frame": 6.271,
      "describe": "a card for deck/index.html, the file that holds the slides",
      "next": 6.28,
      "after": 6.287
    },
    {
      "id": "1.1word",
      "due": 11.56,
      "ran": 11.567,
      "frame": 11.567,
      "describe": "a band reading: every picture waits for its own word",
      "next": 11.575,
      "after": 11.583
    }
  ],
  "long_frames": []
}
```

| Field                 | Type             | Meaning                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                 | string           | Page URL that the recorder opened on the local origin, with `scene`, `cues`, `words`, `prevwords`, `t0=signal`, and any section `params`.                                                                                                                                                                                                         |
| `requested_seconds`   | number           | Recording length after narration t=0: the section span plus `record_margin_seconds`.                                                                                                                                                                                                                                                              |
| `settle_seconds`      | number           | Wall-clock seconds from the page's `load` event to narration t=0.                                                                                                                                                                                                                                                                                 |
| `load_seconds`        | number           | Wall-clock seconds from the recorder's start to the page's `load` event.                                                                                                                                                                                                                                                                          |
| `clock_start_seconds` | number           | Wall-clock seconds from the recorder's start to narration t=0. Not the same as `[verify] reference_lead_seconds`.                                                                                                                                                                                                                                 |
| `assets`              | array of strings | Every project file the page loaded, project-relative, in the order the page asked for it.                                                                                                                                                                                                                                                         |
| `external`            | array of strings | Every other origin the page reached for while it recorded.                                                                                                                                                                                                                                                                                        |
| `input_hash`          | string           | The digest of the page URL, the frame geometry, the markup of the one `[data-scene]` element this section plays, the rest of that page file, which every scene shares, and the content of every file in `assets`. `record` skips a section whose hash has not moved, so an edit inside one scene records the sections that play it and no others. |
| `t0_seconds`          | number or null   | Time of the first frame after the magenta cover, in the webm. `record` writes it, and `assemble` trims there.                                                                                                                                                                                                                                     |
| `t0_method`           | string or null   | One sentence naming how `record` found `t0_seconds`, for a reader of the log.                                                                                                                                                                                                                                                                     |
| `t0_guessed`          | boolean          | True when no magenta cover was found, so `t0_seconds` is an estimate and the section carries the `NO COVER` verdict.                                                                                                                                                                                                                              |
| `checks`              | table or null    | `{duration_seconds, wanted_seconds, luma, verdicts}`, what the frames were judged on. Each verdict is the `{code, label, certain}` object every `--json` payload carries, such as `{"code": "TRUNCATED", "label": "TRUNCATED", "certain": true}`.                                                                                                 |
| `warnings`            | array of strings | `window.__decktalk.warnings`, read after the recording, such as an unknown cue id.                                                                                                                                                                                                                                                                |
| `page_errors`         | array of strings | One line per uncaught exception, plus one line when the page has no runtime catalog.                                                                                                                                                                                                                                                              |
| `frame_gaps`          | array            | `[seconds, ms]` pairs from `window.__decktalk.frameGaps`, one per long gap between two page frames.                                                                                                                                                                                                                                               |
| `spoken_log`          | array of tables  | One `{ text, cue_at, run_at, words, first_shown }` table per `data-text="spoken"` element that matched. The page reports these fields in camelCase and the recorder is the boundary where they turn snake\_case.                                                                                                                                  |
| `cue_log`             | array of tables  | One `{ id, due, ran, frame, describe, next, after }` table per cue, from `window.__decktalk.cueLog`. Times are seconds after narration t=0, and `describe` is what the reveals of that cue say they show, or null.                                                                                                                                |
| `long_frames`         | array of tables  | One `{ start, ms, render, presented }` table per page frame over 50 ms after t=0, from `window.__decktalk.longFrames`.                                                                                                                                                                                                                            |

Note: `record` reports `PAGE ERROR` for any entry in `page_errors`, and `decktalk build` stops. It reports
`STALLED` when the part of a frame gap after t=0 is longer than `[record] stall_ms`.

## `build/sections/`

One mp4 per section, cut to its span, at the project's frame size and with no audio. `assemble`
writes them and `verify` adds them up to find where each section starts in the final video. Both
read only the files of sections in `decktalk.toml`, and both warn about any other file named like a
section video, which is what a build before a renumbering leaves behind.

## `build/out/`

The out directory holds everything a viewer receives: the final video, its captions, its chapters,
its cut list, its transcript page and its poster.

| File                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<name>.mp4`               | The final video, with one chapter per section, and both streams tagged with `[project] language`. Consecutive sections with the same chapter share one chapter. The container takes the ISO 639-2 three-letter code of that tag, and a language DeckTalk cannot map is written `und`.                                                                                                                    |
| `<name>-YYYYMMDD-HHMM.mp4` | A timestamped copy of the final video, written when `[output] timestamped_copy` is on.                                                                                                                                                                                                                                                                                                                   |
| `<name>.srt`, `<name>.vtt` | Captions from the word times, in final mp4 time, with the script's punctuation and case. A cue stays on screen for at least one second unless the next cue begins before that, no cue runs into the cue after it, and a cued sound that names a caption joins the cue it lands in, or the cue it has no second of room before, as a line of its own.                                                     |
| `<name>.chapters.txt`      | An ffmetadata file with one `[CHAPTER]` per section, titled from `decktalk.toml`. Consecutive sections with the same chapter share one `[CHAPTER]`.                                                                                                                                                                                                                                                      |
| `<name>-transcript.html`   | The whole video as one plain page: one heading per chapter, one paragraph per section under it in the order those sections play, and each reveal the page described. A clip that names a words file carries what is spoken inside it, and a section that spoke nothing carries a line saying what plays there instead. It is the media alternative for a viewer who cannot see or cannot hear the video. |
| `<name>-poster.png`        | A lossless PNG of the video's opening slide with every one of its reveals fired, drawn by the page in freeze mode and never taken from the mp4.                                                                                                                                                                                                                                                          |
| `cuts.json`                | The cut list: where every section plays, what it was cut from, and what stands in for it.                                                                                                                                                                                                                                                                                                                |
| `slates/NN-slate.png`      | The slate image of a clip section whose file is missing.                                                                                                                                                                                                                                                                                                                                                 |

### `cuts.json`

```json theme={null}
{
  "fps": 25,
  "total_seconds": 44.88,
  "sections": [
    {
      "section": 1,
      "kind": "page",
      "start": 0.0,
      "end": 14.28,
      "source": "build/recordings/01.webm",
      "substitute": null,
      "chapter": "Open",
      "dip_in": false,
      "dip_out": false
    }
  ]
}
```

| Field                          | Type           | Meaning                                                                                                      |
| ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `fps`                          | integer        | Frames per second of the final video, from `[video] fps`.                                                    |
| `total_seconds`                | number         | Length of the final video, the sum of every row.                                                             |
| `sections[].section`           | integer        | The section number, as `decktalk.toml` writes it.                                                            |
| `sections[].kind`              | string         | `page` or `clip`.                                                                                            |
| `sections[].start`, `end`      | number         | Where the section plays in the final video.                                                                  |
| `sections[].source`            | string         | The recording or the clip this section was cut from, relative to the project.                                |
| `sections[].substitute`        | string or null | `slate` when a missing clip played its slate, `black` when a missing recording played black, null otherwise. |
| `sections[].chapter`           | string         | The chapter title of the section.                                                                            |
| `sections[].dip_in`, `dip_out` | boolean        | Whether the section fades in from, or out to, the transition dip.                                            |

Captions break at sentence ends.

* A caption never spans two sections.
* A cued sound that sets `caption` under `[[mix.sfx]]` gets its own one-second cue, such as `[ball bounces]`, because captions carry the whole soundtrack and not only the dialogue.
* No caption covers a clip section, unless the section sets `words`. Those captions come from the clip's words file.
* A caption also ends before any silence of 1 s or more.
* Whole sentences share a caption when they fit. A sentence too long for one caption splits at the comma
  nearest its middle, or else between two words that are not short words like "of" or "the". Each part keeps at
  least three words.
* A caption holds at most two lines of 42 characters. The line break goes after a sentence end or a comma when the
  two lines stay balanced.
* No caption and no line is a single word, unless that word is a whole sentence.
* A caption starts at its first word and ends 0.2 s after its last word, or when the next caption starts.

```text build/out/my-lesson.srt theme={null}
1
00:00:00,500 --> 00:00:01,942
This is DeckTalk.

2
00:00:01,942 --> 00:00:09,154
You write what you will say,
and you write the slides that go with it.
```

```text build/out/my-lesson.chapters.txt theme={null}
;FFMETADATA1

[CHAPTER]
TIMEBASE=1/1000
START=0
END=14280
title=Open
```

## `build/progress.jsonl`

`decktalk build` truncates this file when a run starts and appends one JSON object per line as it
goes, so a reader that opens it mid-run sees everything that has happened and nothing else.
`--progress PATH` writes it somewhere else.

```json theme={null}
{"ts": "2026-09-19T01:58:52.241Z", "pid": 14207, "stage": "narrate", "stage_index": 1, "stage_count": 5, "section": null, "event": "start", "detail": "Narrating the script into one take per spoken section."}
{"ts": "2026-09-19T01:58:52.517Z", "pid": 14207, "stage": "narrate", "stage_index": 1, "stage_count": 5, "section": null, "event": "done", "detail": "Wrote 3 take(s) and reused the rest."}
```

| Field         | Type            | Meaning                                                                                                                                                                                                                                                |
| ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ts`          | string          | The event time, ISO 8601 in UTC.                                                                                                                                                                                                                       |
| `pid`         | integer         | The process that wrote the row, which is how a reader tells a live run from a dead one.                                                                                                                                                                |
| `stage`       | string          | One of `narrate`, `align`, `record`, `assemble` and `verify`.                                                                                                                                                                                          |
| `stage_index` | integer         | The stage's place in this run, counting from 1.                                                                                                                                                                                                        |
| `stage_count` | integer         | How many stages this run executes, which `--from` and `--to` decide.                                                                                                                                                                                   |
| `section`     | integer or null | The section the event is about, or null for a whole-stage event.                                                                                                                                                                                       |
| `event`       | string          | `start`, `done`, `skip` or `fail`. A section `record` kept unchanged is a `skip`. Every stage and every section writes a `start` row and a closing row, so a log whose last row is a `start` is a run that is still working or one whose process died. |
| `detail`      | string          | One sentence, such as how many sections a stage will work through or what a section's recording was judged to be.                                                                                                                                      |

## `build/screenshots/`

`decktalk screenshots` writes screenshots here. With two or more pages, it writes one folder per page, named after the
page file.

```text theme={null}
wrote build/screenshots/slide-1.1.png
wrote build/screenshots/slide-2.1.png
wrote build/screenshots/slide-3.1.png
```

| File                         | Written by                                                 |
| ---------------------------- | ---------------------------------------------------------- |
| `slide-<id>.png`             | `decktalk screenshots`, one per slide                      |
| `slide-<id>-after-<cue>.png` | `decktalk screenshots --slide ID --after CUE`, one per cue |
| `section-NN-at-<S>s.png`     | `decktalk screenshots --section N --at S`, one per time    |

Note: a project with one page, such as the starter above, writes no page folder. `--page` with one
page file writes none either, and a `--section` frame never goes in a page folder.

## How files are written

DeckTalk writes files so that a reader never sees half of one.

* Stages run one after another, and one build runs one Chromium.
* `takes.json`, `cue-times.json`, each words file, and each recording log go to a temporary file first.
  A rename then puts each one in place.
* The final mp4 is written to a work file, then renamed to `build/out/<name>.mp4`. The timestamped copy, when
  `[output] timestamped_copy` is on, comes after the rename.
* `narrate` saves the take index after each paid request, so an interrupted voiced run keeps the sections it paid
  for.
* An error is a `DeckTalkError` subclass that names the file or field. The command line prints it as
  `error[CODE]: …` on stderr and exits 3, and under `--json` it fills the envelope's `error` slot.

## Related

* **See how the stages use these files:** [How it works](/concepts/how-it-works)
* **Check the final video:** [Verify](/reference/verify)
* **Read the files from Python:** [Python API](/reference/python-api)


# Reference card for agents
Source: https://docs.decktalk.ai/reference/card

Look up the whole DeckTalk contract on one page, with a link to the page behind each rule.

This card lists the whole DeckTalk contract on one page, and each group links to the page that
explains it. Use it to look up one rule, option, or exit code, or give it to an agent that writes a
project.

Every doc page is also served as plain text at [llms.txt](https://docs.decktalk.ai/llms.txt). The
whole site is one file at [llms-full.txt](https://docs.decktalk.ai/llms-full.txt).

## Inputs

You write four files, in this order: `script.md`, `decktalk.toml`, `cues.json`, and the page. All of
them live in the project directory. [Your first deck](/guides/first-deck) writes each one.

### `script.md`

* `## N. Title` starts section `N`.
* `## N. Title — 0:40 to 1:10` adds a time budget.
* `---`, `# Title`, or `## Title` with no number ends the section.
* A page section needs a `## N.` heading. A clip section does not.
* `[any text]` and `[beat]` make a beat. The voice reads a dash there.
* `[pause N]` sends `<break time="Ns" />`. No other direction sends a break tag.
* A written `<break time="1s" />` passes through as written.
* `[CAPS_1]` is a placeholder. Its pattern is `[A-Z][A-Z0-9_]*`.
* `narrate` refuses a placeholder without `--allow-placeholders`.
* `narrate` removes Markdown formatting before it sends the text.
* DeckTalk places `lead_seconds` (0.5) of silence before every spoken section's first word.
* DeckTalk places exactly `min_tail_seconds` of silence after every section's last word.
* The default `min_tail_seconds` is 0.7. The starter sets 1.3.
* The `est` column assumes 140 words per minute.
* A build without voice assumes 150 words per minute plus 0.7 s per beat.

Full rules: [script.md](/reference/script-md).

### `decktalk.toml`

* `[project]` holds `name` and the optional `script`, `cues`, and `build` paths.
* `[voice]` holds voice settings. The voice id and key live in `.env`.
* Each `[[section]]` has a `number` and an optional `chapter`.
* A page section adds `page` and an optional `scene`. `scene` defaults to `number`.
* A clip section adds `clip`, and the optional `slate_seconds`, `optional`, and `words`.
* `words` names a words file of the speech inside the clip, and the captions add it.
* Consecutive sections with the same `chapter` share one chapter.
* A clip section with `optional = true` plays its slate under `--strict` too.
* A clip section can sit before, between, or after page sections.
* A page section can set its own `lead_seconds` and `tail_seconds`, and `hold_seconds` to add silence. A hold pauses the narration.
* `[transition]`, `[mix]`, `[soundscape]`, and the tuning tables are optional.
* An unknown top-level table fails the load.
* DeckTalk warns about an unknown key inside a table, then ignores the key.

Full rules: [decktalk.toml](/reference/decktalk-toml).

### `cues.json`

This shape shows the file. It is not a sample.

```jsonc theme={null}
{"sections": {"N": {"min_seconds"?: 12, "cues": [
  {"cue": "id", "on": "phrase" | "$start" | "$end",
   "offset"?: 0.2, "occurrence"?: 2, "case_sensitive"?: true, "verify"?: false}
]}}}
```

* Each section key is a section number as a string. It must exist in `decktalk.toml`.
* `$start` is 0.0 s. `$end` is the end of the section's last spoken word.
* Matching splits the phrase and the spoken words on whitespace only.
* A hyphenated word is one token.
* Each token keeps only A to Z, a to z, 0 to 9, and the straight apostrophe.
* Matching ignores case unless `case_sensitive` is true.
* The cue time is the matched word's start plus the offset key.
* `occurrence` picks a later match. The default is the first.
* A cue id must not contain a comma, because a comma breaks `?cues=`. DeckTalk does not check this.
* An `@` inside an id still works. By convention, ids have no `@`.
* `align` ignores a top-level key other than `sections`, such as `_comment`.

Full rules: [cues.json](/reference/cues-json) and [Cues](/concepts/cues).

### Pages

* A page is any HTML file that a `[[section]]` names.
* The starter has one page, `deck/index.html`, with three scenes. A project can have as many pages as it likes.
* Load `decktalk-runtime.js` before any `DeckTalk.scene` call.
* A `<div data-scene="N">` holding one `<template data-slide="N.1">` per slide declares a scene in markup, and needs no JavaScript.
* `DeckTalk.scene(N, {name, camera?, slides})` declares the same scene in script, for a slide that builds itself in code.
* Each slide is `{id, hold?, owns?, preview?, render, enter?, on?}`.
* `enter`, each `on[id]`, and `DeckTalk.on(id, fn)` receive `(slide, {id, at, frozen, slideId})`.
* An element appears on its cue with `data-cue="id"`, or at a time with `data-delay="s"`.
* `data-text="spoken"`, `data-text="count"`, and `data-text="type"` also need `data-cue` or `data-delay`.
* Inside `render` backticks, write every backslash twice.
* The runtime creates the stage element `#dt-stage` at 1920 by 1080.
* A slide owns a cue whose id is its own, one its `owns` list names, or one whose longest slide-id prefix it is. A `preview` entry is timing only and grants no ownership.

Full rules: [Runtime](/reference/runtime) and [Page contract](/concepts/page-contract).

### `.env`

* A voiced build needs `ELEVENLABS_API_KEY` and `ELEVENLABS_VOICE_ID`.
* An exported variable wins over `.env`.
* A value that starts with `<` counts as unset.
* A build without voice needs neither key.

### One number for each section

* The number `N` is the same in the script heading, `[[section]]`, and the `cues.json` key.
* A section can play a scene with another number, and a cue id starts with the id of the slide that owns it rather than with the section number.
* `align` exits 1 on a cue id that its page never quotes.
* `build` stops on such an id unless you pass `--allow-unknown-cues`.

[Cue mismatches](/concepts/cues#cue-mismatches) lists every page warning about cues.

### A minimal page

This page is the smallest page that plays one scene. For KaTeX, keep the `deck/katex/` directory that
`decktalk init` wrote, and keep its two tags before the runtime.

```html deck/index.html theme={null}
<!doctype html>
<meta charset="utf-8">
<link rel="stylesheet" href="./katex/katex.min.css">
<script src="./katex/katex.min.js"></script>
<style>
  html, body, #dt-stage { margin: 0; background: #ffffff; color: #0a0a0a; }
  .slide { position: absolute; inset: 0; }
</style>
<script src="decktalk-runtime.js"></script>
<script>
DeckTalk.scene(1, { name: "Open", slides: [
  { id: "1.1", hold: 8, preview: { "1.1a": 1 }, render: () => `
    <div class="slide"><h1 data-cue="1.1a">Hello</h1></div>` },
]});
</script>
```

The runtime mounts each slide as a `.dt-slide` with `position: absolute; inset: 0`. Set your own
background on `html, body` and `#dt-stage`.

## Commands

```console theme={null}
uv tool install decktalk                    # Python 3.12 or later. pipx install decktalk also works.
decktalk install                            # once per machine: Chromium and ffmpeg
decktalk doctor                             # each tool and its path. Exit 1 on any MISSING row.
decktalk init DIR [--name NAME] [--force]   # write the starter, with KaTeX in deck/katex/
decktalk init DIR --example lesson          # a packaged example instead. --no-skills leaves the skills out.
decktalk build --no-voice                   # every stage with a click track. No key.
decktalk build                              # the voiced video at build/out/<name>.mp4
decktalk build --only 3 --preset veryfast   # record section 3 again, with a fast encode
decktalk align                              # the cue time of every cue. Exit 1 on a missing phrase or id.
decktalk verify                             # section starts, cuts, and every cue in the final video
decktalk verify 1:1.1title 2:2.1code        # only these two cues
decktalk verify --json                      # the same result as one JSON object on stdout
decktalk screenshots                        # one PNG per slide
decktalk screenshots --slide 2.1 --after 2.1formula           # slide 2.1 frozen at cue 2.1formula
decktalk screenshots --section 2 --at 12.5  # a frame 12.5 s after narration t=0 in section 2
decktalk words --only 1                     # section 1's words, in seconds after the section starts
decktalk clip 1 --start 2.3 --end 8.4 --out media/count.mp4   # that span of section 1 as a clip and a words file
decktalk status [--json]                    # what the four input files say, and what disagrees
decktalk narrate --dry-run                  # the text, and which sections a voiced run voices. Sends nothing.
decktalk narrate --dry-run --json           # the same take plan as one JSON object
decktalk preflight                          # takes, cues, and frozen reveals before a voiced build
decktalk soundscape --dry-run               # every sound request. Sends nothing.
decktalk serve                              # the project on the local origin, so a page loads over http
```

* A project command takes `-p DIR`. The default is `DECKTALK_PROJECT`, then the current directory.
* `-v` and `-q` go before or after the command name.
* `-p` goes before the command name, or after it on every command except `init`, `install`, and `doctor`.
* `--only` takes a number, a list or a range, and repeats: `--only 3`, `--only 3,5`, `--only 7-9`.
* `--strict` fails on an uncertain finding, and on `assemble` and `build` on a missing recording or clip.
* A clip section with `optional = true` still plays its slate under `--strict`.

Every command prints one JSON envelope with `--json`, and each takes the exit options its own
findings can reach.

| Option        | Commands                                                              | Meaning                                                                 |
| ------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `--json`      | every command                                                         | One envelope on stdout, and nothing else there. An error prints it too. |
| `--strict`    | `align`, `preflight`, `record`, `assemble`, `verify`, `clip`, `build` | Also exits 1 on an uncertain finding.                                   |
| `--exit-zero` | the same commands, plus `doctor` and `status`                         | Exits 0 on findings. An error still exits 3.                            |

| Exit | Meaning                                                      |
| ---- | ------------------------------------------------------------ |
| 0    | Nothing found, or `--exit-zero`.                             |
| 1    | A finding. `error` is null, and the project is what to fix.  |
| 2    | A usage error. `error.code` is `USAGE`.                      |
| 3    | DeckTalk could not run. `error` names the error class. Stop. |
| 130  | Interrupted.                                                 |

Every option: [CLI](/reference/cli).

## Gate a script on the video

* `build` ends with the same five checks `decktalk verify` runs, cues included.
* `build` exits 1 on any certain finding, so `TRUNCATED`, `STALLED` and `NO COVER` each fail a run.
* To gate a script on the video with no key, run `decktalk build --no-voice`.
* The offset column must be between -80 ms and +80 ms.
* After a build without voice, the `a/v` column must be between -120 ms and +120 ms.
* `OFF CUE` prints no distance. Compare the columns with those limits.
* A `-` in the `a/v` column means no click was found. The JSON reason is `NO_CLICK`, and it does not fail.
* Every cut must be at most -40 dBFS in its last 0.15 s. Clip sections have no cut row.
* A build without voice skips the loudness pass.

| `skipped` reason        | Cause                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `OPTED_OUT`             | `"verify": false` in `cues.json`. Name the cue to measure it.                         |
| `REFERENCE_CLAMPED`     | The cue is too close to the section start. A `$start` cue with no offset key gets it. |
| `SECTION_NOT_ASSEMBLED` | `build/sections/NN.mp4` is missing.                                                   |
| `TOO_CLOSE_TO_END`      | The cue is less than 0.75 s before the section end.                                   |

A `skipped` row never fails. A named cue that is not in `cue-times.json` is `UNRESOLVED`, which fails.
Measurement details: [verify](/reference/verify).

To test a new project with no key, run these commands in order.

1. Run `decktalk build --no-voice`.
2. Run `decktalk verify`.
3. Run `decktalk screenshots`.

To see the cue times before anything records, run `decktalk narrate --no-voice` and then
`decktalk align`.

## Stages and artifacts

`build` runs `narrate`, `align`, `record`, `assemble` and `verify`, in that
order.

| Artifact                                          | Written by    | Holds                                                                                                                                                                            |
| ------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build/narration/<hash>.mp3`, `<hash>.words.json` | `narrate`     | One take's audio and its `[{word, start, end}]` list, named by the take's content hash.                                                                                          |
| `build/narration/takes.json`                      | `narrate`     | One entry per section, with its text hash and lengths, which is also the narration clock.                                                                                        |
| `build/narration/narration.mp3`                   | `narrate`     | Spoken sections back to back, with each section's silence joined around its take.                                                                                                |
| `build/cue-times.json`                            | `align`       | One row per cue with `cue`, `on`, `at` and `word_at`, in seconds after the section start.                                                                                        |
| `build/recordings/NN.webm`, `recordings/NN.json`  | `record`      | The recording and its recording log: t=0, its checks, warnings, page errors, and frame gaps.                                                                                     |
| `build/sections/NN.mp4`                           | `assemble`    | One section cut to its span, video only.                                                                                                                                         |
| `build/out/<name>.mp4`                            | `assemble`    | The video with chapters, and both streams tagged with `[project] language`. A second copy named with the date and time is written only when `[output] timestamped_copy` is true. |
| `build/out/<name>.srt`, `<name>.vtt`              | `assemble`    | Captions from the word times.                                                                                                                                                    |
| `build/out/<name>.chapters.txt`                   | `assemble`    | One chapter per section, or per run of sections with the same chapter.                                                                                                           |
| `build/screenshots/**/*.png`                      | `screenshots` | Review screenshots, in one folder per page when there are several pages.                                                                                                         |

After a clip between page sections, final-video times are later than narration times by the clip
lengths before them. [Time bases](/reference/artifacts#time-bases) gives each clock.
[Build artifacts](/reference/artifacts) gives every field.

## Settings

Settings come from five layers. Each layer overrides the layer before it.

1. DeckTalk's defaults.
2. The per-machine file at `DECKTALK_CONFIG`. It can hold tuning tables only.
3. Tables of the same name in `decktalk.toml`.
4. `DECKTALK_<TABLE>_<FIELD>` environment variables.
5. The options `--preset`, `--crf`, `--settle`, and `--model`.

The tuning tables are these seven.

* `[video]`
* `[narration]`
* `[record]`
* `[audio]`
* `[verify]`
* `[elevenlabs]`
* `[output]`

`DECKTALK_CACHE_DIR` moves the ffmpeg cache. `DECKTALK_FFMPEG` and `DECKTALK_FFPROBE` point at your
own binaries. Set both. [CLI](/reference/cli#environment-variables) gives the default paths, and
[Configuration](/reference/configuration) lists every field.

## Exit codes and errors

| Code | Meaning                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | Nothing found, or `--exit-zero` on a command with findings.                                                                             |
| 1    | A finding. `error` is null, and the project is what to fix. [Exit codes](/reference/cli#exit-codes) lists the findings of each command. |
| 2    | A usage error, such as an unknown option or a missing command. `error.code` is `USAGE`.                                                 |
| 3    | DeckTalk itself could not run. `error` names the error class, so stop.                                                                  |
| 130  | Interrupted.                                                                                                                            |

| Error               | `error.code`    | Meaning                                |
| ------------------- | --------------- | -------------------------------------- |
| `ConfigError`       | `CONFIG`        | An input is bad or inconsistent.       |
| `MissingInputError` | `MISSING_INPUT` | An earlier stage has not run.          |
| `ProviderError`     | `PROVIDER`      | The speech provider refused or failed. |
| `ToolError`         | `TOOL`          | ffmpeg or Chromium failed.             |

An error prints `error[CODE]: <message>` on stderr and exits 3, even with `--exit-zero`. Under
`--json` it fills the envelope's `error` slot instead. Logs go to stderr through the `decktalk`
logger. DeckTalk never prints a key.

## Python

This example builds a project silently and prints the final path.

```python theme={null}
import decktalk
project = decktalk.Project.load("my-lesson")
result = decktalk.build(project, silent=True)
print(result.assembly.final, result.verification.ok)
```

[Python API](/reference/python-api) lists every public name.

## Related

* **Look up an option:** [CLI](/reference/cli)
* **Fix a message:** [Troubleshooting](/help/troubleshooting)
* **Look up a term:** [Glossary](/reference/glossary)


# CLI
Source: https://docs.decktalk.ai/reference/cli

Look up every decktalk command, its options, its output and its exit codes.

The `decktalk` command runs each stage on its own, or the whole pipeline with `decktalk build`.
This page lists every command with its options, and it is generated from the parser, so a flag on
this page is a flag the command takes.

## Global options

These work with every command, before or after the command name.

| Option                            | Meaning                                                                                                                      |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `-p PROJECT`, `--project PROJECT` | The project directory. Defaults to `DECKTALK_PROJECT`, then the current directory. `init`, `install` and `doctor` ignore it. |
| `-v`, `--verbose`                 | Debug logging on stderr, including every ffmpeg command line and the traceback of a bug.                                     |
| `-q`, `--quiet`                   | Warnings and errors only on stderr.                                                                                          |
| `--json`                          | Print one JSON envelope on stdout and nothing else there. Every log line goes to stderr.                                     |
| `--strict`                        | An uncertain finding fails as a certain one does. Only on a command that can report one.                                     |
| `--exit-zero`                     | Exit 0 whatever was found, for a caller that reads the envelope itself. It never hides an error.                             |
| `--version`                       | Print the version and exit 0.                                                                                                |
| `-h`, `--help`                    | Print the usage and exit 0.                                                                                                  |

A `--only` value is a section number, a list or a range: `--only 3`, `--only 3,5`, `--only 7-9`.
The flag repeats, and the values gather into one list.

## Environment variables

| Variable                                    | Default             | Meaning                                                                                                                                                                   |
| ------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DECKTALK_PROJECT`                          | none                | Default project directory.                                                                                                                                                |
| `DECKTALK_CONFIG`                           | per platform, below | Per-machine settings file.                                                                                                                                                |
| `DECKTALK_CACHE_DIR`                        | per platform, below | ffmpeg cache. Playwright keeps Chromium in its own cache.                                                                                                                 |
| `DECKTALK_FFMPEG`, `DECKTALK_FFPROBE`       | none                | Paths to your own binaries. Set both. They win over the pinned build and `PATH`.                                                                                          |
| `DECKTALK_<TABLE>_<FIELD>`                  | none                | One tuning field, such as `DECKTALK_VIDEO_PRESET=veryfast`.                                                                                                               |
| `DECKTALK_ALLOW_ANY_API_BASE`               | unset               | Lets `[elevenlabs] api_base` name any host, for a local mock of the API. It is a switch and never a secret, and without it the key goes only to an https ElevenLabs host. |
| `ELEVENLABS_API_KEY`, `ELEVENLABS_VOICE_ID` | none                | Speech provider secrets. Also read from `.env`.                                                                                                                           |

| Default path         | Linux                                                                              | macOS                                                  | Windows                            |
| -------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------- |
| `DECKTALK_CONFIG`    | `$XDG_CONFIG_HOME/decktalk/decktalk.toml`, else `~/.config/decktalk/decktalk.toml` | `~/Library/Application Support/decktalk/decktalk.toml` | `%APPDATA%\decktalk\decktalk.toml` |
| `DECKTALK_CACHE_DIR` | `$XDG_CACHE_HOME/decktalk`, else `~/.cache/decktalk`                               | `~/Library/Caches/decktalk`                            | `%LOCALAPPDATA%\decktalk`          |

Note: a key value that starts with `<` counts as unset, so the placeholders in `.env.example` never
reach the provider. No value of any variable on this page is printed, logged or put in a payload. [Configuration](/reference/configuration) lists every tuning field.

## Exit codes

| Code | Meaning                                                            | How a caller tells                                       |
| ---- | ------------------------------------------------------------------ | -------------------------------------------------------- |
| 0    | The command ran and found nothing, or `--exit-zero` was passed.    | `ok` is true, or `exit_code` is 0 with findings present. |
| 1    | The command ran and found something.                               | `error` is null and a findings count is above zero.      |
| 2    | A usage error: an unknown command, an unknown flag or a bad value. | `error.code` is `USAGE`.                                 |
| 3    | DeckTalk itself could not run. Stop and tell the user.             | `error` is not null and names the error class.           |
| 130  | The run was interrupted. No envelope is promised.                  | The process was signalled.                               |

A non-zero exit with `error: null` is a finding, and the project is what to fix. A non-null
`error.code` is an error, and the run stops.

## The `--json` envelope

Every command prints exactly one object on stdout under `--json`, and an error prints it too.

| Field       | Type           | Meaning                                                                           |
| ----------- | -------------- | --------------------------------------------------------------------------------- |
| `schema`    | integer        | The envelope's shape version, 1 today. It moves only when the shape changes.      |
| `version`   | string         | The installed DeckTalk version.                                                   |
| `command`   | string         | The command as typed.                                                             |
| `ok`        | boolean        | True when the command found nothing and raised nothing. It ignores `--exit-zero`. |
| `exit_code` | integer        | The code the process is about to return.                                          |
| `summary`   | object         | The counts that lead the output. The keys are the command's own.                  |
| `findings`  | object         | `certain`, `uncertain` and `items`, the rows.                                     |
| `written`   | array          | Every file the command wrote, project-relative, in the order written.             |
| `error`     | object or null | `code`, `message`, `hint`, `path` and `line`. Null on success and on a finding.   |
| `<command>` | object         | The command's own payload, under the first word of its name.                      |

`findings.items[]` has one shape on every command, and the certain rows lead it.

| Key       | Type            | Meaning                                                                                                                                                |
| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `code`    | string          | The verdict code, such as `OFF_CUE`. Match on this. `MISSING` is a file that is not there and `UNREADABLE` is a file that is there and does not parse. |
| `label`   | string          | The printed label, such as `OFF CUE`. Nothing parses it.                                                                                               |
| `certain` | boolean         | True when the finding is certain.                                                                                                                      |
| `section` | integer or null | The section number.                                                                                                                                    |
| `cue`     | string or null  | The cue id.                                                                                                                                            |
| `where`   | string or null  | The file, page or artifact the row is about.                                                                                                           |
| `detail`  | string or null  | One sentence, with any measured number in it.                                                                                                          |

## The progress log

`decktalk build` truncates and then appends JSON Lines to `build/progress.jsonl`, relocatable with
`--progress PATH`, so a caller polls a file instead of tailing a log.

| Key           | Type            | Meaning                                                               |
| ------------- | --------------- | --------------------------------------------------------------------- |
| `ts`          | string          | The event time, as an ISO 8601 timestamp.                             |
| `pid`         | integer         | The process running the build, which is how `status` answers `alive`. |
| `stage`       | string          | A stage this run executes, named as `build` runs it.                  |
| `stage_index` | integer         | The stage's place in this run, counting from 1.                       |
| `stage_count` | integer         | How many stages this run will execute.                                |
| `section`     | integer or null | The section the event is about.                                       |
| `event`       | string          | `start`, `done`, `skip` or `fail`.                                    |
| `detail`      | string or null  | One sentence of detail.                                               |

`decktalk status --json` reads `build/progress.jsonl` and reports `run`, so a caller polls one
command instead of tailing a log. It is null when no build has written a log there, which is also
what a build started with `--progress PATH` leaves behind.

| Key              | Type            | Meaning                                                                    |
| ---------------- | --------------- | -------------------------------------------------------------------------- |
| `pid`            | integer or null | The process that wrote the log.                                            |
| `started`        | string or null  | When the run began.                                                        |
| `stage`          | string or null  | The stage the last event named.                                            |
| `sections_done`  | integer or null | Sections finished, and null until a stage reports per section.             |
| `sections_total` | integer or null | Sections the run will do, and null for the same reason.                    |
| `alive`          | boolean         | True while the run is unfinished and its process is still on this machine. |

## One machine

### `decktalk init`

Create a project: decktalk.toml, script.md, cues.json, a deck page and the runtime.

```text theme={null}
decktalk init [-h] [--name NAME] [--force] [--example NAME] [--no-skills] [-v] [-q] [--json] dir
```

| Option        | Default | Meaning                                                                                          |
| ------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `DIR`         |         | the directory to create, with a working starter deck                                             |
| `--name`      |         | project name (default: the directory name)                                                       |
| `--force`     | off     | write into a non-empty directory                                                                 |
| `--example`   |         | write a packaged example instead of the starter: lesson, product (reserved), tutorial (reserved) |
| `--no-skills` | off     | do not write the packaged skills into the project                                                |

It also takes `--json`, `-v` and `-q`.

### `decktalk install`

Fetch headless Chromium and ffmpeg, once per machine.

```text theme={null}
decktalk install [-h] [-v] [-q] [--json]
```

It also takes `--json`, `-v` and `-q`.

### `decktalk doctor`

Report what is installed and which build a run would use.

```text theme={null}
decktalk doctor [-h] [--report] [-v] [-q] [--json] [--exit-zero]
```

| Option     | Default | Meaning                                              |
| ---------- | ------- | ---------------------------------------------------- |
| `--report` | off     | print a pasteable environment block, with no secrets |

It also takes `--json`, `-v`, `-q` and `--exit-zero`.

## Before a build

### `decktalk status`

Report what the four input files say, what is built, what disagrees and whether a build runs.

```text theme={null}
decktalk status [-h] [-v] [-q] [--json] [--project PROJECT] [--exit-zero]
```

It also takes `-p`, `--json`, `-v`, `-q` and `--exit-zero`.

### `decktalk preflight`

Estimate the takes, resolve the cues and freeze every reveal, spending nothing.

```text theme={null}
decktalk preflight [-h] [--only N] [--no-frames] [--model MODEL] [--allow-unknown-cues] [-v] [-q] [--json] [--project PROJECT] [--strict] [--exit-zero]
```

| Option                 | Default | Meaning                                                                       |
| ---------------------- | ------- | ----------------------------------------------------------------------------- |
| `--only`               |         | only these sections: 3, 3,5 or 7-9, and the flag repeats                      |
| `--no-frames`          | off     | skip the frozen frames, so no browser starts                                  |
| `--model`              |         | speech model to check the narration cache for                                 |
| `--allow-unknown-cues` | off     | continue when a cue id in cues.json appears nowhere in the page that plays it |

It also takes `-p`, `--json`, `-v`, `-q`, `--strict` and `--exit-zero`.

### `decktalk words`

Print each spoken section's words, in seconds after the section starts.

```text theme={null}
decktalk words [-h] [--only N] [-v] [-q] [--json] [--project PROJECT]
```

| Option   | Default | Meaning                                                  |
| -------- | ------- | -------------------------------------------------------- |
| `--only` |         | only these sections: 3, 3,5 or 7-9, and the flag repeats |

It also takes `-p`, `--json`, `-v` and `-q`.

### `decktalk screenshots`

Write one PNG per slide, per cue of one slide, or per second of a playing section.

```text theme={null}
decktalk screenshots [-h] [--page PAGE] [--slide ID] [--after ID] [--before ID] [--section SECTION] [--at AT] [-v] [-q] [--json] [--project PROJECT]
```

| Option      | Default | Meaning                                          |
| ----------- | ------- | ------------------------------------------------ |
| `--page`    |         | page file (default: every page in decktalk.toml) |
| `--slide`   |         | only these slide ids                             |
| `--after`   |         | freeze the one --slide at this cue id (repeats)  |
| `--before`  |         | freeze the one --slide just before this cue id   |
| `--section` |         | play this section with its resolved cues         |
| `--at`      |         | seconds after narration t=0 (with --section)     |

It also takes `-p`, `--json`, `-v` and `-q`.

### `decktalk soundscape`

Generate the ambience, the sound effects and the music.

```text theme={null}
decktalk soundscape [-h] [--force] [--dry-run] [-v] [-q] [--json] [--project PROJECT] [NAME ...]
```

| Option      | Default | Meaning                                              |
| ----------- | ------- | ---------------------------------------------------- |
| `NAMES`     |         | only these items: ambience, music, or an effect name |
| `--force`   | off     | regenerate even if the file exists                   |
| `--dry-run` | off     | print every request without sending it               |

It also takes `-p`, `--json`, `-v` and `-q`.

### `decktalk clip`

Cut a span of a built section and its narration into a clip file and its words.

```text theme={null}
decktalk clip [-h] --start SECONDS --end SECONDS --out OUT [--words WORDS] [--gain DB] [--hold SECONDS] [--preset PRESET] [--crf CRF] [-v] [-q] [--json] [--project PROJECT] [--strict] [--exit-zero] section
```

| Option     | Default | Meaning                                                        |
| ---------- | ------- | -------------------------------------------------------------- |
| `SECTION`  |         | the page section to cut from                                   |
| `--start`  |         | start, after the section starts                                |
| `--end`    |         | end, after the section starts                                  |
| `--out`    |         | the clip file, relative to the project, such as media/open.mp4 |
| `--words`  |         | the words file (default: the clip's path with .words.json)     |
| `--gain`   | `0.0`   | gain on the clip's sound, in dB                                |
| `--hold`   | `0.0`   | hold the last frame this long, silent                          |
| `--preset` |         | x264 preset for this run (veryfast for drafts)                 |
| `--crf`    |         | x264 quality for this run                                      |

It also takes `-p`, `--json`, `-v`, `-q`, `--strict` and `--exit-zero`.

### `decktalk serve`

Serve the project on the local origin, so a page loads over http.

```text theme={null}
decktalk serve [-h] [--host HOST] [--port PORT] [--open] [-v] [-q] [--json] [--project PROJECT]
```

| Option   | Default     | Meaning                                   |
| -------- | ----------- | ----------------------------------------- |
| `--host` | `127.0.0.1` | the address to bind (default: 127.0.0.1)  |
| `--port` | `0`         | the port to bind (default: any free port) |
| `--open` | off         | open the first page in your browser       |

It also takes `-p`, `--json`, `-v` and `-q`.

## The pipeline

### `decktalk narrate`

Turn script.md into one take per section with its word timestamps.

```text theme={null}
decktalk narrate [-h] [--only N] [--force] [--allow-placeholders] [--dry-run] [--no-voice] [--model MODEL] [-v] [-q] [--json] [--project PROJECT]
```

| Option                 | Default | Meaning                                                      |
| ---------------------- | ------- | ------------------------------------------------------------ |
| `--only`               |         | only these sections: 3, 3,5 or 7-9, and the flag repeats     |
| `--force`              | off     | ignore the cache, and let --no-voice replace voiced takes    |
| `--allow-placeholders` | off     | synthesize a section that still has a \[CAPITAL] placeholder |
| `--dry-run`            | off     | print what a voiced run would send and spend, and stop       |
| `--no-voice`           | off     | placeholder narration with no API key and no spend           |
| `--model`              |         | speech model for this run                                    |

It also takes `-p`, `--json`, `-v` and `-q`.

### `decktalk align`

Resolve each cue phrase in cues.json to a second on its section clock.

```text theme={null}
decktalk align [-h] [--allow-unknown-cues] [-v] [-q] [--json] [--project PROJECT] [--strict] [--exit-zero]
```

| Option                 | Default | Meaning                                                                       |
| ---------------------- | ------- | ----------------------------------------------------------------------------- |
| `--allow-unknown-cues` | off     | continue when a cue id in cues.json appears nowhere in the page that plays it |

It also takes `-p`, `--json`, `-v`, `-q`, `--strict` and `--exit-zero`.

### `decktalk record`

Record each page section with headless Chromium, find narration t=0 and check the frames.

```text theme={null}
decktalk record [-h] [--only N] [--seconds SECONDS] [--settle SETTLE] [--no-cues] [-v] [-q] [--json] [--project PROJECT] [--strict] [--exit-zero]
```

| Option      | Default | Meaning                                                  |
| ----------- | ------- | -------------------------------------------------------- |
| `--only`    |         | only these sections: 3, 3,5 or 7-9, and the flag repeats |
| `--seconds` |         | override every duration (smoke tests)                    |
| `--settle`  |         | seconds after load before the clock starts               |
| `--no-cues` | off     | preview timing instead of ?cues=                         |

It also takes `-p`, `--json`, `-v`, `-q`, `--strict` and `--exit-zero`.

### `decktalk assemble`

Cut, mix and normalize the sections into the final mp4 and its captions.

```text theme={null}
decktalk assemble [-h] [--no-soundscape] [--no-loudness] [--preset PRESET] [--crf CRF] [-v] [-q] [--json] [--project PROJECT] [--strict] [--exit-zero]
```

| Option            | Default | Meaning                                           |
| ----------------- | ------- | ------------------------------------------------- |
| `--no-soundscape` | off     | narration only: no music, no ambience, no effects |
| `--no-loudness`   | off     | skip loudness normalization                       |
| `--preset`        |         | x264 preset for this run (veryfast for drafts)    |
| `--crf`           |         | x264 quality for this run                         |

It also takes `-p`, `--json`, `-v`, `-q`, `--strict` and `--exit-zero`.

### `decktalk verify`

Read the final mp4 and report every section start, cut, seam and cue landing.

```text theme={null}
decktalk verify [-h] [--only N] [-v] [-q] [--json] [--project PROJECT] [--strict] [--exit-zero] [SECTION:CUE ...]
```

| Option   | Default | Meaning                                                  |
| -------- | ------- | -------------------------------------------------------- |
| `CHECKS` |         | cues to check (default: every resolved cue)              |
| `--only` |         | only these sections: 3, 3,5 or 7-9, and the flag repeats |

It also takes `-p`, `--json`, `-v`, `-q`, `--strict` and `--exit-zero`.

## The whole run

### `decktalk build`

Run every stage in order, writing progress as it goes.

```text theme={null}
decktalk build [-h] [--no-voice] [--force] [--only N] [--no-soundscape] [--no-loudness] [--allow-unresolved-cues] [--allow-unknown-cues] [--progress PATH] [--from STAGE] [--to STAGE] [--dry-run] [--preset PRESET] [--crf CRF] [-v] [-q] [--json] [--project PROJECT] [--strict] [--exit-zero]
```

| Option                    | Default | Meaning                                                                       |
| ------------------------- | ------- | ----------------------------------------------------------------------------- |
| `--no-voice`              | off     | placeholder narration with no API key and no spend                            |
| `--force`                 | off     | ignore the cache, and let --no-voice replace voiced takes                     |
| `--only`                  |         | re-record only these sections: 3, 3,5 or 7-9, and the flag repeats            |
| `--no-soundscape`         | off     | narration only: no music, no ambience, no effects                             |
| `--no-loudness`           | off     | skip loudness normalization                                                   |
| `--allow-unresolved-cues` | off     | build even if a cue phrase was not found                                      |
| `--allow-unknown-cues`    | off     | continue when a cue id in cues.json appears nowhere in the page that plays it |
| `--progress`              |         | the progress log (default: build/progress.jsonl)                              |
| `--from`                  |         | start at this stage, inclusive: narrate, align, record, assemble, verify      |
| `--to`                    |         | stop after this stage, inclusive                                              |
| `--dry-run`               | off     | print the stages the run would execute, and stop                              |
| `--preset`                |         | x264 preset for this run (veryfast for drafts)                                |
| `--crf`                   |         | x264 quality for this run                                                     |

It also takes `-p`, `--json`, `-v`, `-q`, `--strict` and `--exit-zero`.

## See also

* [Configuration](/reference/configuration) lists every tuning field.
* [Python API](/reference/python-api) lists everything `decktalk.__all__` holds.


# Configuration
Source: https://docs.decktalk.ai/reference/configuration

Look up every DeckTalk tuning field, with its type, its default, and what it changes.

Tuning fields change how DeckTalk records, assembles, and checks a video. This page lists every
field, grouped by table, with its type, its default, and the values it accepts. A field whose Value
column is empty takes any value of its type, and a value outside the stated range fails the load
with the table and the field named.

A tuning table can go in the project's `decktalk.toml`. The same field can also come from an
environment variable.

```toml decktalk.toml theme={null}
[video]
preset = "veryfast"
```

```console theme={null}
DECKTALK_VIDEO_PRESET=veryfast decktalk build --no-voice
```

The scaffold builds with every default. Change `[video]` for faster drafts. Change `[verify]` when a
small reveal fails the cue check.

## Which value wins

Five layers can set a field. Each layer overrides the layers before it.

1. The default on this page.
2. The same table in the per-machine settings file.
3. The same table in the project's `decktalk.toml`.
4. An environment variable named `DECKTALK_<TABLE>_<FIELD>`, such as `DECKTALK_VIDEO_PRESET`.
5. A command-line flag, for one run.

The per-machine settings file is in a different place on each platform.

| Linux                                                                                                              | macOS                                                  | Windows                            |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ---------------------------------- |
| `$XDG_CONFIG_HOME/decktalk/decktalk.toml`, or `~/.config/decktalk/decktalk.toml` when `XDG_CONFIG_HOME` is not set | `~/Library/Application Support/decktalk/decktalk.toml` | `%APPDATA%\decktalk\decktalk.toml` |

Note: `DECKTALK_CONFIG` points at a different file. The per-machine file can hold only the tables on
this page, and any other table fails the load. `decktalk doctor` prints the path in its `config` row.

An environment variable for an array field takes comma-separated values, such as
`DECKTALK_VERIFY_PROBE_DELAYS=0.7,1.5`.

Four flags override a field for one run.

| Flag       | Commands            | Overrides                               |
| ---------- | ------------------- | --------------------------------------- |
| `--preset` | `assemble`, `build` | `[video] preset`                        |
| `--crf`    | `assemble`, `build` | `[video] crf`                           |
| `--settle` | `record`            | `[record] settle_seconds`               |
| `--model`  | `narrate`           | `[narration] model` and `[voice] model` |

Sections, the voice, mix levels, and soundscape prompts are project content, not tuning.
[decktalk.toml](/reference/decktalk-toml) lists those tables. Secrets go only in `.env`.

## `[video]`

These keys set the frame size and the encoding of every recording and of the final mp4. Environment variables start with `DECKTALK_VIDEO_`.

| Field           | Type      | Default      | Value                                                                                       | Meaning                                                                                                   |
| --------------- | --------- | ------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `width`         | `integer` | `1920`       | must be above zero                                                                          | Frame width in pixels, for every recording and the final mp4.                                             |
| `height`        | `integer` | `1080`       | must be above zero                                                                          | Frame height in pixels, for every recording and the final mp4.                                            |
| `fps`           | `integer` | `25`         | must be above zero                                                                          | Frames per second. Chromium records at 25 fps, so 25 avoids a pulldown that duplicates every sixth frame. |
| `preset`        | `string`  | `"medium"`   | must be one of ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow | x264 preset. Use veryfast for drafts.                                                                     |
| `crf`           | `integer` | `18`         | must be an x264 quality between 0 and 51                                                    | x264 quality. A lower value gives higher quality and a larger file.                                       |
| `audio_bitrate` | `string`  | `"192k"`     |                                                                                             | AAC bitrate of the final mp4.                                                                             |
| `sample_rate`   | `integer` | `48000`      | must be above zero                                                                          | Audio sample rate of the final mp4. Every audio input is resampled to it once.                            |
| `channels`      | `integer` | `2`          | must be above zero                                                                          | Audio channels of the final mp4.                                                                          |
| `slate_color`   | `string`  | `"0x0e1116"` |                                                                                             | Color of the plain frame that plays when a slate image cannot be rendered.                                |

## `[narration]`

These keys govern how the script is turned into audio. Environment variables start with `DECKTALK_NARRATION_`.

| Field                     | Type      | Default                    | Value                | Meaning                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------- | --------- | -------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                   | `string`  | `"eleven_multilingual_v2"` |                      | Speech model. `[voice] model` and `narrate --model` override it.                                                                                                                                                                                                                                                                                                     |
| `output_format`           | `string`  | `"mp3_44100_128"`          |                      | Audio format that the speech provider returns. It is part of the narration cache key.                                                                                                                                                                                                                                                                                |
| `mp3_bitrate`             | `string`  | `"128k"`                   |                      | Bitrate of the mp3 files that DeckTalk writes. They include click tracks and `narration.mp3`.                                                                                                                                                                                                                                                                        |
| `words_per_minute`        | `integer` | `140`                      | must be above zero   | Pacing of the estimated length in the `narrate` table.                                                                                                                                                                                                                                                                                                               |
| `silent_words_per_minute` | `integer` | `150`                      | must be above zero   | Pacing of the click track in a build without voice.                                                                                                                                                                                                                                                                                                                  |
| `lead_seconds`            | `number`  | `0.5`                      | must not be negative | Silence before the first word of every spoken section, so the picture changes before the voice speaks. A section's own `lead_seconds` replaces it.                                                                                                                                                                                                                   |
| `silent_beat_seconds`     | `number`  | `0.7`                      | must not be negative | Seconds each beat adds to a section's length in a build without voice.                                                                                                                                                                                                                                                                                               |
| `min_tail_seconds`        | `number`  | `0.7`                      | must not be negative | Silence after the last word of every spoken section, so a cut never falls on speech. The take is placed so that exactly this much follows its last sound. A section's own `tail_seconds` replaces it.                                                                                                                                                                |
| `cache_dir`               | `string`  | `""`                       |                      | Directory that holds the take files and their words files, each named by its content hash. It is empty for `build/narration/` inside the project, and a path here keeps the voiced takes when `build/` is deleted and lets many projects share one cache. The take index and the joined narration stay under `build/narration/`, because they belong to one project. |
| `context_chars`           | `integer` | `1500`                     | must not be negative | Characters of each neighbor section sent with a request, for continuous prosody.                                                                                                                                                                                                                                                                                     |
| `timeout_seconds`         | `integer` | `180`                      | must be above zero   | Seconds before a speech request times out.                                                                                                                                                                                                                                                                                                                           |

## `[record]`

These keys tune the headless Chromium recording, how narration t=0 is found in it, and its sanity check. Environment variables start with `DECKTALK_RECORD_`.

| Field                          | Type      | Default   | Value                                     | Meaning                                                                                                                                              |
| ------------------------------ | --------- | --------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `settle_seconds`               | `number`  | `0.5`     | must not be negative                      | Shortest wait after the page is ready and before narration t=0. `record --settle` overrides it.                                                      |
| `min_cover_seconds`            | `number`  | `1.5`     | must not be negative                      | Shortest time from the start of the recorder to narration t=0.                                                                                       |
| `browser_path`                 | `string`  | `""`      |                                           | Chromium executable that `record` drives. It is empty for the build that `decktalk install` fetched, and a path here is what a managed machine sets. |
| `color_scheme`                 | `string`  | `"light"` | must be one of light, dark, no-preference | Color scheme that Chromium reports to the page.                                                                                                      |
| `retries`                      | `integer` | `2`       | must not be negative                      | How many more times `record` records a section whose frames stalled.                                                                                 |
| `screenshot_settle_ms`         | `integer` | `400`     | must not be negative                      | Milliseconds that `decktalk screenshots` waits before each slide screenshot.                                                                         |
| `cover_scan_seconds`           | `number`  | `4.0`     | must not be negative                      | Seconds at the start of each recording that `record` scans for the magenta cover.                                                                    |
| `fallback_first_paint_seconds` | `number`  | `1.1`     | must not be negative                      | Guessed first paint if `record` finds no cover and no painted frame. `record` adds `settle_seconds` to it.                                           |
| `cover_luma_min`               | `number`  | `70`      | must be a luma between 0 and 255          | A cover frame has an average luma above this.                                                                                                        |
| `cover_luma_max`               | `number`  | `140`     | must be a luma between 0 and 255          | A cover frame has an average luma below this.                                                                                                        |
| `cover_chroma_min`             | `number`  | `165`     | must be a luma between 0 and 255          | A cover frame has an average U and an average V above this.                                                                                          |
| `painted_ymax`                 | `number`  | `60`      | must be a luma between 0 and 255          | A painted frame has a brightest luma above this.                                                                                                     |
| `painted_yavg_max`             | `number`  | `120`     | must be a luma between 0 and 255          | A painted frame has an average luma below this, so a white flash does not count.                                                                     |
| `black_ymax`                   | `number`  | `40`      | must be a luma between 0 and 255          | `record` reports `BLACK?` when the brightest luma of the middle frame is below this.                                                                 |
| `truncated_slack_seconds`      | `number`  | `0.5`     | must not be negative                      | Allowed shortfall of a recording against its requested length. A larger shortfall makes `record` report `TRUNCATED`.                                 |
| `stall_ms`                     | `integer` | `150`     | must be above zero                        | Longest frame gap after narration t=0, in milliseconds. A longer gap makes `record` try again and report `STALLED`.                                  |

## `[audio]`

These keys set the mix mechanics. Levels live in `[mix]` in `decktalk.toml`. Environment variables start with `DECKTALK_AUDIO_`.

| Field                       | Type     | Default | Value                | Meaning                                                              |
| --------------------------- | -------- | ------- | -------------------- | -------------------------------------------------------------------- |
| `duck_ramp_seconds`         | `number` | `0.5`   | must not be negative | Ramp of the music duck at each edge of a spoken span or a clip.      |
| `ambience_ramp_seconds`     | `number` | `1.0`   | must not be negative | Ramp of the ambience bed at each edge of its span.                   |
| `ambience_pad_seconds`      | `number` | `0.5`   | must not be negative | Seconds that the ambience bed extends past each edge of its section. |
| `marker_mute_ramp_seconds`  | `number` | `0.04`  | must not be negative | Ramp into and out of a marker's mute.                                |
| `marker_boost_ramp_seconds` | `number` | `0.3`   | must not be negative | Ramp into and out of a marker's swell.                               |

## `[verify]`

These keys tune the checks on the assembled mp4. Environment variables start with `DECKTALK_VERIFY_`.

| Field                    | Type               | Default      | Value                                  | Meaning                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------ | ------------------ | ------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `after_dip_seconds`      | `number`           | `0.2`        | must not be negative                   | Seconds after a section start to the frame that the start check reads.                                                                                                                                                                                                                                                                                                                         |
| `reference_lead_seconds` | `number`           | `0.1`        | must not be negative                   | Reference lead. It has an effect only above (`max_offset_frames` + 1.5) / `fps`, which is 0.14 s at the defaults.                                                                                                                                                                                                                                                                              |
| `probe_delays`           | `array of numbers` | `[0.7, 1.5]` | must be one or more delays above zero  | Seconds after the cue time for each probe. The later probe catches a slow reveal.                                                                                                                                                                                                                                                                                                              |
| `diff_level`             | `integer`          | `40`         | must be a luma between 0 and 255       | Luma difference that a pixel must exceed to count as changed, for probes and control shares.                                                                                                                                                                                                                                                                                                   |
| `min_changed_percent`    | `number`           | `0.1`        | must be a percentage between 0 and 100 | Smallest changed share, in percent, that the reported probe needs.                                                                                                                                                                                                                                                                                                                             |
| `min_margin_percent`     | `number`           | `0.1`        | must be a percentage between 0 and 100 | Smallest margin, in percentage points, that the reported probe needs.                                                                                                                                                                                                                                                                                                                          |
| `thin_change_factor`     | `number`           | `3.0`        | must be above zero                     | A passing cue whose changed share or margin is below this many times its floor reads `THIN CHANGE?`, an uncertain finding. 1 turns the warning off.                                                                                                                                                                                                                                            |
| `onset_percent`          | `number`           | `0.01`       | must be a percentage between 0 and 100 | Rise in changed share from one frame to the next that marks the onset. It is in percentage points. 0.01 is about 13 pixels.                                                                                                                                                                                                                                                                    |
| `onset_diff_level`       | `integer`          | `12`         | must be a luma between 0 and 255       | Luma difference that a pixel must exceed to count as changed, for the onset scan only.                                                                                                                                                                                                                                                                                                         |
| `click_search_seconds`   | `number`           | `0.25`       | must not be negative                   | Seconds on each side of the cued word's start that the click search covers.                                                                                                                                                                                                                                                                                                                    |
| `max_offset_frames`      | `integer`          | `2`          | must not be negative                   | Offset limit, in frames. The onset can sit this far from the cue time, early or late.                                                                                                                                                                                                                                                                                                          |
| `max_av_frames`          | `integer`          | `3`          | must not be negative                   | a/v limit, in frames, early or late. It is wider because the click carries encoding jitter too.                                                                                                                                                                                                                                                                                                |
| `visible_ymax`           | `number`           | `60`         | must be a luma between 0 and 255       | The start check reports `BLACK` when the brightest luma of its frame is at most this.                                                                                                                                                                                                                                                                                                          |
| `cut_window_seconds`     | `number`           | `0.15`       | must not be negative                   | Seconds of narration before each cut that the cut check measures.                                                                                                                                                                                                                                                                                                                              |
| `cut_max_db`             | `number`           | `-40.0`      |                                        | Loudest RMS level of the cut window, in dBFS, that passes the cut check.                                                                                                                                                                                                                                                                                                                       |
| `max_pop_percent`        | `number`           | `0.1`        | must be a percentage between 0 and 100 | Largest changed share, in percent, across the cut into a section that sets `seamless`. A larger share reads `POP AT CUT`.                                                                                                                                                                                                                                                                      |
| `probe_width`            | `integer`          | `480`        | must be above zero                     | Width in pixels that frames are scaled to before a comparison.                                                                                                                                                                                                                                                                                                                                 |
| `probe_height`           | `integer`          | `270`        | must be above zero                     | Height in pixels that frames are scaled to before a comparison.                                                                                                                                                                                                                                                                                                                                |
| `block_width`            | `integer`          | `240`        | must be above zero                     | Width in pixels of the block-averaged copy of each frame that confirms an onset. Each pixel then averages an 8 by 8 block of a 1080p frame, the size of an H.264 transform block. The encoder can shift a few pixels of a still picture by up to about 15 levels in the frames just before a change. The average cancels that ringing, so a frame is the onset only when a block also changed. |
| `block_height`           | `integer`          | `135`        | must be above zero                     | Height in pixels of the block-averaged copy of each frame that confirms an onset.                                                                                                                                                                                                                                                                                                              |

## `[elevenlabs]`

These keys point at the ElevenLabs API and size its soundscape requests. Environment variables start with `DECKTALK_ELEVENLABS_`.

| Field                       | Type      | Default                          | Value                   | Meaning                                                                                    |
| --------------------------- | --------- | -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
| `api_base`                  | `string`  | `"https://api.elevenlabs.io/v1"` |                         | Base URL of the ElevenLabs API.                                                            |
| `sound_model`               | `string`  | `"eleven_text_to_sound_v2"`      |                         | Model for ambience and sound effect requests. A soundscape table can name its own.         |
| `music_model`               | `string`  | `"music_v2"`                     |                         | Model for music requests. A soundscape table can name its own.                             |
| `music_bitrate`             | `string`  | `"192k"`                         |                         | Bitrate of the music file that `soundscape` joins from its chunks.                         |
| `max_music_chunk_seconds`   | `integer` | `300`                            | must be above zero      | Longest music request. Longer music is requested in chunks.                                |
| `music_crossfade_seconds`   | `integer` | `2`                              | must not be negative    | Crossfade between two music chunks.                                                        |
| `ambience_seconds`          | `number`  | `25.0`                           | must be above zero      | Length of a generated ambience bed. A soundscape table can set `duration_seconds` instead. |
| `ambience_prompt_influence` | `number`  | `0.3`                            | must be between 0 and 1 | Prompt influence of an ambience request. A soundscape table can set its own.               |
| `sfx_seconds`               | `number`  | `0.5`                            | must be above zero      | Length of a generated sound effect. A soundscape table can set `duration_seconds` instead. |
| `sfx_prompt_influence`      | `number`  | `0.5`                            | must be between 0 and 1 | Prompt influence of a sound effect request. A soundscape table can set its own.            |
| `timeout_seconds`           | `integer` | `600`                            | must be above zero      | Seconds before a sound or music request times out.                                         |

## `[output]`

These keys switch the files a build writes beside the final mp4. Environment variables start with `DECKTALK_OUTPUT_`.

| Field              | Type      | Default | Value | Meaning                                                            |
| ------------------ | --------- | ------- | ----- | ------------------------------------------------------------------ |
| `timestamped_copy` | `boolean` | `false` |       | Write a second copy of the final mp4 named with the date and time. |

## Related

* **Set sections, the voice, and the mix:** [decktalk.toml](/reference/decktalk-toml)
* **Understand the `[verify]` fields:** [Verify](/reference/verify)
* **Override a field for one run:** [CLI](/reference/cli)


# cues.json
Source: https://docs.decktalk.ai/reference/cues-json

Look up the shape and every key of the cue file, which names the spoken phrase for each cue.

`cues.json` is the cue file. It names the spoken phrase for each cue id, section by section. It is
optional. A project without it plays every page with the page's own preview timing. This page lists
every key.

```json cues.json theme={null}
{
  "sections": {
    "1": {
      "cues": [
        { "cue": "1.1title", "on": "This is DeckTalk", "occurrence": 1 },
        { "cue": "1.1script", "on": "what you will say", "occurrence": 1 },
        { "cue": "1.1deck", "on": "the slides", "occurrence": 1 },
        { "cue": "1.1word", "on": "its own word", "occurrence": 1 }
      ]
    },
    "2": {
      "cues": [
        { "cue": "2.1average", "on": "the average", "occurrence": 1 },
        { "cue": "2.1formula", "on": "the formula", "occurrence": 1 },
        { "cue": "2.1code", "on": "in code", "occurrence": 1 },
        { "cue": "2.1waited", "on": "waited", "occurrence": 1 }
      ]
    }
  }
}
```

Section 1 of the starter plays scene 1 of its page, and the scene holds one slide with the id `1.1`,
so every cue id of that section starts with `1.1`. A section can play a scene with another number,
and the cue ids follow the slide rather than the section. The block below is a shape, not the
starter's values. It shows the optional keys.

```json cues.json theme={null}
{
  "sections": {
    "<section number>": {
      "min_seconds": 30,
      "cues": [
        { "cue": "<cue id>", "on": "<phrase>", "offset": 0.2, "occurrence": 2, "case_sensitive": false, "verify": true }
      ]
    }
  }
}
```

## Shape

The file is one object with a `sections` key. The load ignores every other top-level key, such as
`_comment`. Each key of `sections` is a section number as a string, and it must name a
`[[section]]` in `decktalk.toml`. Each section is an object with an optional `min_seconds` and a
`cues` list.

Every cue id must appear in its page as a quoted literal, such as `data-cue="1.1title"` or a key of
a slide's `preview` object. [Cue mismatches](/concepts/cues#cue-mismatches) says what happens when an
id is missing.

## Section keys

| Key           | Type   | Default | Meaning                                                                                      |
| ------------- | ------ | ------- | -------------------------------------------------------------------------------------------- |
| `cues`        | array  | `[]`    | These are the cues of the section.                                                           |
| `min_seconds` | number | none    | This is how many seconds of speech the visuals need. Shorter speech is an uncertain finding. |

Note: for short speech, `decktalk align` prints the note
`speech <S>s is <D>s shorter than the visuals need`. `align --strict` exits 1 on it.

## Cue keys

| Key              | Type    | Default  | Meaning                                                                                                                    |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `cue`            | string  | required | This is the cue id.                                                                                                        |
| `on`             | string  | required | This is a word or a short phrase from the section's script, `$start`, or `$end`.                                           |
| `offset`         | number  | `0`      | This is the offset key. It adds seconds to the match, and it can be negative.                                              |
| `occurrence`     | integer | `1`      | This picks which match of the phrase to use. When the phrase occurs more than once and this key is not set, `align` warns. |
| `case_sensitive` | boolean | `false`  | The match reads case as written when this is true.                                                                         |
| `verify`         | boolean | `true`   | `false` leaves the cue out of a plain `decktalk verify`, which shows the row as `skipped` with `OPTED_OUT`.                |

Note: a cue id must not contain a comma, because commas separate the pairs in `?cues=`. DeckTalk
does not check this. An `@` in an id still works, because the page splits each pair at its last `@`.
Avoid `@` anyway, so ids stay easy to read.

Note: `decktalk verify` still checks a `"verify": false` cue that you name as `SECTION:CUE`.

Note: a key that no cue reads is ignored in silence, so check a spelling here against this table.

## Anchors

| Anchor   | Cue time                                                                                                                                 |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `$start` | The cue time is 0.0 s after the section start, plus the offset key. A negative result stays negative, and the page fires the cue at t=0. |
| `$end`   | The cue time is the end of the section's last spoken word, plus the offset key. It is not the end of the section's audio file.           |

Note: `decktalk verify` skips a `$start` cue with no offset key, as `REFERENCE_CLAMPED`.

Note: a section's `lead_seconds` moves every word, and so every phrase cue and `$end`, that much
later. `$start` stays at 0. [Skipped rows](/reference/verify#skipped-rows) explains why.

## Output files

`decktalk align` writes `build/cue-times.json`, with one row per resolved cue: the cue id, the
phrase it matched, its cue time, and the word start before the offset key.
[Build artifacts](/reference/artifacts#build-cue-times-json) has the shape of the file.

## Related

* **Learn the matching rules:** [Cues](/concepts/cues#matching-rules)
* **Write phrases that time well:** [Writing for the ear](/guides/writing-for-the-ear)
* **Learn which slide owns a cue:** [The page contract](/concepts/page-contract#cue-ownership)


# decktalk.toml
Source: https://docs.decktalk.ai/reference/decktalk-toml

Look up every table and key in the DeckTalk project file, with its type and default.

`decktalk.toml` is the project file. It maps each section to a page or a clip, and it sets the voice,
the transitions, and the sound. Use this page to look up a table or a key and its default.

The file sits in the project root. Every path in it is relative to that directory.

## Minimal file

The smallest file that loads has one page section.

```toml decktalk.toml theme={null}
[[section]]
number = 1
page = "deck/index.html"
```

`decktalk init` writes a three-section file with comments, and every section of it is a page section.
`decktalk init --example lesson` writes a one-section file instead. This fuller example adds a clip
section, a dip to black, and music.

```toml decktalk.toml theme={null}
[project]
name = "my-lesson"

[voice]
stability = 0.55

[[section]]
number = 0
chapter = "On camera"
clip = "media/open.mp4"

[[section]]
number = 1
chapter = "Open"
page = "deck/index.html"
scene = 1

[transition]
dips = [[0, 1]]

[mix]
music = "build/music/music.mp3"
```

## Load rules

Every project command loads `decktalk.toml` first. The load fails in each of these cases.

* A top-level table is unknown.
* The file has no `[[section]]` table.
* A required key is missing.
* A value has the wrong type. For example, `seconds = 120.5` under `[soundscape.music]` fails.
* Two sections share a `number`.
* A section has both `page` and `clip`, or neither.
* `record_margin_seconds`, `hold_seconds`, `lead_seconds`, or `tail_seconds` is below 0.
* `seamless` is set on the first section.
* A `dips` pair or a `[[mix.sfx]]` table names a section that does not exist.

The error names the table and the key.

```text theme={null}
decktalk.toml: [soundscape.music]: 'seconds' must be int, got float
```

An unknown key inside a table does not fail the load. DeckTalk prints a warning, ignores the key, and
continues. The same rule covers the tuning tables and the per-machine file.

```text theme={null}
decktalk.toml: [voice]: ignoring unknown key 'stabilty' (did you mean 'stability'?).
```

A page section key on a clip section, or a clip section key on a page section, gets its own warning.
The warning names the section kind that the key belongs to.

## Which value wins

* `--model` wins over `[voice] model`, which wins over `[narration] model`.
* A tuning table in `decktalk.toml` wins over the per-machine file. A `DECKTALK_<TABLE>_<FIELD>` variable and a command option win over both.
* The project tables on this page have no environment variables.

[Configuration](/reference/configuration) lists the five layers for tuning tables.

## `[project]`

| Key        | Type   | Default            | Meaning                                                                                                                                                       |
| ---------- | ------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`     | string | the directory name | Output name. The video is `build/out/<name>.mp4`.                                                                                                             |
| `script`   | path   | `script.md`        | Script file.                                                                                                                                                  |
| `cues`     | path   | `cues.json`        | Cue file. Optional. Without it, pages use their own timing.                                                                                                   |
| `build`    | path   | `build`            | Directory for generated files.                                                                                                                                |
| `language` | string | `en`               | The BCP 47 tag of the language the film is narrated in. It labels the mp4's two streams and the transcript page, which is what a player names the audio from. |

## `[voice]`

`[voice]` sets how the voice sounds. The API key and the voice id are secrets, so they live in `.env`
as `ELEVENLABS_API_KEY` and `ELEVENLABS_VOICE_ID`, or in the environment.

| Key                         | Type    | Default               | Meaning                                                                                                                                                           |
| --------------------------- | ------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`                  | string  | `elevenlabs`          | Registered speech provider name.                                                                                                                                  |
| `model`                     | string  | `= [narration] model` | Speech model id, such as `eleven_multilingual_v2`.                                                                                                                |
| `stability`                 | number  | 0.55                  | Lower values vary more between takes.                                                                                                                             |
| `similarity_boost`          | number  | 0.75                  | How closely the voice follows its source voice.                                                                                                                   |
| `style`                     | number  | 0.0                   | Style exaggeration. 0 is the most stable.                                                                                                                         |
| `speaker_boost`             | boolean | true                  | ElevenLabs speaker boost.                                                                                                                                         |
| `speed`                     | number  | 1.0                   | Speaking rate.                                                                                                                                                    |
| `price_per_1000_characters` | number  | 0.0                   | What your plan charges per 1,000 characters. `narrate --dry-run` prints dollars from it, and leaves the figure out when it is 0. It is not part of any cache key. |

Note: every key here but `price_per_1000_characters` is part of every take's content hash. After a change,
the next voiced build voices every section again. [What spends credits](/requirements#what-spends-credits) lists every change
that costs credits. An unregistered `provider` fails when `narrate` runs, not at load.

## `[[section]]`

Write one `[[section]]` table for each `## N.` section of the script. DeckTalk sorts sections by
`number`, so the order in the file does not matter. Each section is a page section or a clip section.

### Keys for every section

| Key        | Type    | Default                      | Meaning                                                                                                                                               |
| ---------- | ------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number`   | integer | required                     | Matches `## N.` in the script.                                                                                                                        |
| `chapter`  | string  | the script's `## N.` heading | Chapter title and slate title. A section with neither becomes `Section N`. Consecutive sections with the same chapter share one chapter marker.       |
| `seamless` | boolean | false                        | The section opens on the previous section's last picture. `verify` flags a visible jump at the cut as `POP AT CUT`. Not allowed on the first section. |

### Page section keys

| Key                     | Type              | Default                        | Meaning                                                                                        |
| ----------------------- | ----------------- | ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `page`                  | path              | required                       | HTML file, such as `deck/index.html`.                                                          |
| `scene`                 | integer or string | `= number`                     | Value the page receives as `?scene=`.                                                          |
| `record_margin_seconds` | number            | 0.3                            | Seconds the recording runs past the section span.                                              |
| `hold_seconds`          | number            | 0                              | Seconds the section's last frame holds after its narration. The narration pauses for the hold. |
| `lead_seconds`          | number            | `[narration] lead_seconds`     | Seconds of silence before the section's first word.                                            |
| `tail_seconds`          | number            | `[narration] min_tail_seconds` | Seconds of silence after the section's last word.                                              |
| `ambience`              | boolean           | false                          | Plays the ambience bed under this section.                                                     |
| `params`                | table             | none                           | Extra query parameters for the page, written as `[section.params]`.                            |

Note: `params` values become strings. A `cues` key replaces the cue times, a `scene` key replaces
`scene`, a `words` key replaces the spoken words, and a `prevwords` key replaces the previous section's words. `t0` is always `signal`, whatever `params` says.

### Silence in a section

Three keys set the silence of a page section. None of them is sent to the voice or changes the narration
cache, so a cached take stays cached. Every spoken section has a lead and a tail even when it sets neither,
from `[narration] lead_seconds` and `min_tail_seconds`, so the silence across every cut is one tail and then
one lead.

| Key            | Where the silence goes        | How DeckTalk adds it                                                                                                                                               |
| -------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lead_seconds` | Before the first word         | `narrate` places it in `narration.mp3` before the take. The take is not changed.                                                                                   |
| `tail_seconds` | After the last word           | `narrate` measures where the take's sound ends and cuts or pads the take in `narration.mp3` so that exactly this much silence follows it. The take is not changed. |
| `hold_seconds` | After the section's narration | `assemble` holds the last frame, and the narration waits.                                                                                                          |

* The section starts when its silence starts. So `lead_seconds` moves every word and every word cue of the
  section later, and `$start` stays at 0.
* The recording covers the lead, because the section's span on the narration clock includes it.
* `tail_seconds` is exact, like `min_tail_seconds`. A pause the voice left after its last word is cut to it or
  padded to it, so every take of the section ends the same way, voiced in this run or reused.
* A hold on any page section pauses the narration, as a clip between page sections does. The next section
  starts after the hold, on its own words.
* A `[pause N]` before a section's first words is removed. Use `lead_seconds` to open a section on silence.

```toml decktalk.toml theme={null}
[[section]]
number = 4
chapter = "The edit"
page = "deck/index.html"
lead_seconds = 1.5    # the page shows 1.5 s before the first word
hold_seconds = 2      # the last frame stays 2 s before section 5
```

Set `seamless = true` when a section continues the previous section's picture, such as a page that
opens where the last page ended. `verify` compares the two frames at the cut, outside any dip. A dip still
fades through black, so leave the pair out of `[transition] dips` for a cut that should not show.
[Cut continuity](/reference/verify#cut-continuity) defines the check.

### Clip section keys

| Key             | Type    | Default  | Meaning                                                                                       |
| --------------- | ------- | -------- | --------------------------------------------------------------------------------------------- |
| `clip`          | path    | required | Your video file. It keeps its own audio.                                                      |
| `slate_seconds` | number  | 5        | Seconds the titled slate plays when the file is missing.                                      |
| `optional`      | boolean | false    | Plays the slate for a missing clip, even under `--strict`.                                    |
| `words`         | path    | none     | A words file of the speech inside the clip. The captions add these words at the clip's start. |

A clip section follows three rules.

1. A clip section can sit before, between, or after page sections.
2. The narration pauses for a clip between page sections, and resumes with the next page section.
3. If the file is missing, a titled slate plays for `slate_seconds`. With `--strict`, `assemble` and `build` fail instead, unless the section sets `optional = true`.

Set `optional = true` while the clip is not ready. Delete that line after you add the clip.

DeckTalk scales and pads the clip to the frame size. A clip section has captions only when it sets `words`, and
chapters include the clip. [Add a clip section](/guides/clip-section) shows the whole task.

## `[transition]`

| Key             | Type                         | Default   | Meaning                                                                 |
| --------------- | ---------------------------- | --------- | ----------------------------------------------------------------------- |
| `dips`          | array of \[integer, integer] | every cut | Boundaries that dip to black, as `[[from, to], …]`.                     |
| `dip_seconds`   | number                       | 0.15      | Fade length, rounded to whole frames. Video only.                       |
| `page_fades_in` | boolean                      | true      | Pages fade themselves in, so the cut adds no fade-in to a page section. |

Note: leave out `dips` to dip at every cut. Set `dips = []` for no dips. Audio never dips.

## `[mix]`

`[mix]` is optional. Without it, the video carries narration and clip audio only.
[Sound](/concepts/sound) explains how the parts fit together.

| Key                      | Type   | Default          | Meaning                                                                                                             |
| ------------------------ | ------ | ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `music`                  | path   | none             | Music under the whole video. Loops, and ducks under speech and clips.                                               |
| `music_db`               | number | -24              | Music level in dB.                                                                                                  |
| `music_duck_db`          | number | -6               | Extra level change in dB under each spoken span and clip.                                                           |
| `music_fade_in_seconds`  | number | 2                | Fade-in seconds.                                                                                                    |
| `music_fade_out_seconds` | number | 3                | Fade-out seconds.                                                                                                   |
| `music_markers`          | path   | none             | This names a markers file, which swells and mutes the music at spoken phrases. See [`markers.json`](#markers-json). |
| `ambience`               | path   | none             | Ambience bed for sections that set `ambience = true`.                                                               |
| `ambience_db`            | number | -20              | Ambience level in dB.                                                                                               |
| `slate`                  | path   | a rendered slate | PNG for every missing clip, instead of the rendered titled slate.                                                   |

Note: a missing music or ambience file does not fail the build. `assemble` logs a warning, such
as `music missing (<path>); no music`, and plays the video without it.

### `[[mix.sfx]]`

Write one `[[mix.sfx]]` table for each sound effect.
[Put a sound effect on a cue](/guides/sfx-on-a-cue) shows the task.

| Key       | Type    | Default  | Meaning                                                                                                                                      |
| --------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`    | path    | required | Audio file.                                                                                                                                  |
| `section` | integer | required | Section whose cue places the sound effect. Must exist.                                                                                       |
| `cue`     | string  | required | Cue id that `align` resolved in that section.                                                                                                |
| `db`      | number  | -16      | Level in dB.                                                                                                                                 |
| `offset`  | number  | 0        | This adds seconds to the cue time.                                                                                                           |
| `caption` | string  | none     | This is the caption line a viewer reads when the sound plays, such as `ball bounces`. `assemble` gives it a line of its own in the captions. |

Note: this `offset` belongs to the sound effect, not to the cue. A missing file or an unresolved cue
does not fail the build. `assemble` logs `skipped` for that sound effect.

### `[mix.loudness]`

`[mix.loudness]` sets the targets of the loudness pass. [Loudness](/concepts/sound#loudness) explains
the pass.

| Key            | Type   | Default | Meaning                                                                 |
| -------------- | ------ | ------- | ----------------------------------------------------------------------- |
| `target_lufs`  | number | -16     | This is the integrated loudness target, in LUFS.                        |
| `true_peak_db` | number | -1.5    | This is the true-peak ceiling, in dBTP.                                 |
| `range_lu`     | number | 11      | This is the loudness range, in LU, and it is passed to the measurement. |

Note: the unit is part of each key name, so no abbreviation has to be looked up. A build without
voice skips the loudness pass, because a click track has no loudness worth matching.

### `markers.json`

A markers file swells or mutes the music at spoken phrases. `[mix] music_markers` names it. No
packaged project writes one, so the block below is a shape that a project adds by hand, and
`media/markers.json` is the usual place for it.

```json media/markers.json theme={null}
{
  "_comment": "Music structure. Each marker swells the bed by boost_db for boost_seconds at a spoken phrase (or $start/$end of a section); mute_seconds silences it for one beat first.",
  "boost_db": 3,
  "boost_seconds": 2,
  "markers": [
    { "name": "open", "section": 1, "on": "$start" }
  ]
}
```

| Key             | Type             | Default | Meaning                            |
| --------------- | ---------------- | ------- | ---------------------------------- |
| `boost_db`      | number           | 3       | dB the music rises at each marker. |
| `boost_seconds` | number           | 2       | Seconds each swell lasts.          |
| `markers`       | array of objects | none    | The markers.                       |

| Marker key       | Type    | Default  | Meaning                                       |
| ---------------- | ------- | -------- | --------------------------------------------- |
| `name`           | string  | none     | Name in warnings.                             |
| `section`        | integer | required | Section number.                               |
| `on`             | string  | `$start` | Spoken phrase, `$start`, or `$end`.           |
| `offset`         | number  | 0        | Seconds added to the marker time.             |
| `occurrence`     | integer | 1        | Which match of the phrase.                    |
| `case_sensitive` | boolean | false    | Matches case when true.                       |
| `mute_seconds`   | number  | 0        | Seconds the music is silent before the swell. |

* Markers apply only when the music file exists. `--no-soundscape` turns them off.
* `$start` works on any section. A phrase or `$end` needs a spoken section.
* A phrase matches by the same rules as a cue phrase.
* If the file is missing, `assemble` logs `markers file missing (<path>); music without structure`.
* If a marker does not resolve, `assemble` logs `marker '<name>' unresolved; skipped`.
* A file that is not valid JSON fails `assemble` with a `ConfigError`.

## `[soundscape]`

`[soundscape]` holds the prompts for `decktalk soundscape`, which generates sound with ElevenLabs.
Each item writes to a default path unless its `out` key names another.

* `[soundscape.ambience]` writes to `[mix] ambience`, else to `build/sfx/ambience.mp3`.
* `[soundscape.music]` writes to `[mix] music`, else to `build/music/music.mp3`.
* `[soundscape.sfx.<name>]` writes to `build/sfx/<name>.mp3`.

### `[soundscape.ambience]`

| Key                | Type   | Default                                          | Meaning                                   |
| ------------------ | ------ | ------------------------------------------------ | ----------------------------------------- |
| `text`             | string | required                                         | Prompt.                                   |
| `duration_seconds` | number | `= [elevenlabs] ambience_seconds` (25)           | Length to request. The bed loops.         |
| `prompt_influence` | number | `= [elevenlabs] ambience_prompt_influence` (0.3) | How closely the sound follows the prompt. |
| `model_id`         | string | `= [elevenlabs] sound_model`                     | Sound model id.                           |
| `out`              | path   | `= [mix] ambience`                               | Output file.                              |

### `[soundscape.sfx.<name>]`

| Key                | Type   | Default                                     | Meaning                                   |
| ------------------ | ------ | ------------------------------------------- | ----------------------------------------- |
| `text`             | string | required                                    | Prompt.                                   |
| `duration_seconds` | number | `= [elevenlabs] sfx_seconds` (0.5)          | Length to request.                        |
| `prompt_influence` | number | `= [elevenlabs] sfx_prompt_influence` (0.5) | How closely the sound follows the prompt. |
| `model_id`         | string | `= [elevenlabs] sound_model`                | Sound model id.                           |
| `out`              | path   | `build/sfx/<name>.mp3`                      | Output file.                              |

### `[soundscape.music]`

| Key                  | Type    | Default                      | Meaning                                                      |
| -------------------- | ------- | ---------------------------- | ------------------------------------------------------------ |
| `prompt`             | string  | required                     | Prompt.                                                      |
| `seconds`            | integer | 360                          | Length to request. A decimal such as `120.5` fails the load. |
| `force_instrumental` | boolean | true                         | No vocals when true.                                         |
| `model_id`           | string  | `= [elevenlabs] music_model` | Music model id.                                              |
| `out`                | path    | `= [mix] music`              | Output file.                                                 |

Note: a length above `[elevenlabs] max_music_chunk_seconds` (300) is requested in parts, and DeckTalk
crossfades the parts. No packaged project sets a `[soundscape]` table, so a project that wants
generated sound writes one itself.

## Tuning tables

`decktalk.toml` can also hold the tuning tables, such as `[video]` or `[record]`. A tuning table in
the project overrides the per-machine file. [Configuration](/reference/configuration) lists every
field with its default.

## Related

* **Write the script:** [script.md](/reference/script-md)
* **Tie a reveal to a phrase:** [cues.json](/reference/cues-json)
* **Tune a build:** [Configuration](/reference/configuration)


# Glossary
Source: https://docs.decktalk.ai/reference/glossary

The one meaning of each DeckTalk term and the page that explains it.

This page gives each DeckTalk term its one meaning in these docs. Use it when a word on another page is unclear, or when you write docs or a project for DeckTalk.

Each table lists the term, its meaning, and the page that explains it. Write the term, and write it in that meaning alone. Write it whole, because a short form such as bed, effect, span, offset, lead, or stage belongs to no one term.

## Pipeline and project

| Term                | Meaning                                                                                                                                                                        | Explained in                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| build               | One run of `decktalk build` through all five stages. A *plain build* has no `--only`.                                                                                          | [How it works](/concepts/how-it-works)                          |
| preflight           | `decktalk preflight`. Plans the takes, resolves the cues, and estimates each reveal from frozen frames, with no credits and no recording.                                      | [CLI](/reference/cli#decktalk-preflight)                        |
| build without voice | A build with `--no-voice`. It uses estimated word times, writes a click track, and needs no account.                                                                           | [How it works](/concepts/how-it-works)                          |
| voiced build        | A build without `--no-voice`. The speech provider voices the script and the run spends.                                                                                        | [How it works](/concepts/how-it-works)                          |
| stage               | One of `narrate`, `align`, `record`, `assemble`, `verify`, always in that order.                                                                                               | [How it works](/concepts/how-it-works)                          |
| project file        | `decktalk.toml`.                                                                                                                                                               | [decktalk.toml](/reference/decktalk-toml)                       |
| input files         | The four files you write, in this order: `script.md`, `decktalk.toml`, `cues.json`, and the page.                                                                              | [How it works](/concepts/how-it-works)                          |
| starter             | The three-section project that `decktalk init` writes by default.                                                                                                              | [Quickstart](/quickstart)                                       |
| example             | A whole project packaged in the wheel, which `decktalk init --example NAME` writes instead of the starter.                                                                     | [CLI](/reference/cli#decktalk-init)                             |
| install             | `decktalk install`. Fetches headless Chromium and ffmpeg, once per machine.                                                                                                    | [CLI](/reference/cli#decktalk-install)                          |
| local origin        | The virtual http origin that DeckTalk serves a project's own files from, so a page loads over http instead of `file://`. `decktalk serve` opens the same origin for a browser. | [What leaves your machine](/reference/what-leaves-your-machine) |
| JSON envelope       | The one object that every command prints on stdout with `--json`.                                                                                                              | [CLI](/reference/cli#exit-codes)                                |
| progress log        | `build/progress.jsonl`. One JSON line per stage and section event of a run.                                                                                                    | [Build artifacts](/reference/artifacts#build-progress-jsonl)    |
| section             | A numbered part of the script (`## N.`) and its `[[section]]` table. Either a *page section* or a *clip section*.                                                              | [decktalk.toml](/reference/decktalk-toml)                       |
| clip                | A video file of your own that a clip section plays, with its own audio.                                                                                                        | [Add a clip section](/guides/clip-section)                      |
| slate               | The titled image that plays for `slate_seconds` when a clip file is missing.                                                                                                   | [Add a clip section](/guides/clip-section)                      |

## Page and runtime

| Term                    | Meaning                                                                                                                                    | Explained in                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| page                    | An HTML file that page sections play, such as `deck/index.html`.                                                                           | [The page contract](/concepts/page-contract)                             |
| stage element           | The 1920 by 1080 `#dt-stage` element that holds the slide.                                                                                 | [Runtime](/reference/runtime)                                            |
| scene                   | One `DeckTalk.scene(N, …)` in a page. A page section plays one scene.                                                                      | [The page contract](/concepts/page-contract)                             |
| slide                   | One entry in a scene's `slides`, and the HTML it renders.                                                                                  | [The page contract](/concepts/page-contract)                             |
| mount                   | A slide enters the page.                                                                                                                   | [Runtime](/reference/runtime)                                            |
| mode                    | `index`, `preview`, `cue`, or `freeze`. In prose: index mode, preview, cue mode, freeze mode.                                              | [Runtime](/reference/runtime#modes)                                      |
| browser preview         | A page opened in a browser without `?cues=`. It plays in preview.                                                                          | [The page contract](/concepts/page-contract)                             |
| own                     | A slide owns a cue by the three ownership rules.                                                                                           | [The page contract](/concepts/page-contract#cue-ownership)               |
| `hold` / `hold_seconds` | `hold` is the slide key for preview seconds. `hold_seconds` is the section key that holds a page section's last frame after its narration. | [Runtime](/reference/runtime), [decktalk.toml](/reference/decktalk-toml) |
| handler                 | A function in a slide's `on` object, or one registered with `DeckTalk.on(id, fn)`.                                                         | [Runtime](/reference/runtime)                                            |
| page contract           | What `decktalk-runtime.js` gives a page: its scenes, slides, cues, clock and reveals.                                                      | [The page contract](/concepts/page-contract)                             |
| recorder probe          | `decktalk-probe.js`, which a DeckTalk command injects into a page before it loads. It is never a `<script>` tag and no page references it. | [Runtime](/reference/runtime)                                            |
| catalog                 | `window.__decktalk.catalog`. One entry per scene, with its slides and their cue ids.                                                       | [Runtime](/reference/runtime#the-catalog)                                |
| description string      | The `data-describe` value of a reveal, which the transcript page reads.                                                                    | [Runtime](/reference/runtime)                                            |

## Cues and timing

| Term              | Meaning                                                                                                    | Explained in                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
| cue               | One entry in `cues.json`. Pairs a cue id with a cue phrase.                                                | [Cues](/concepts/cues)            |
| cue id            | The id that ties a cue to the page, such as `1.1bowl`. A slide id plus a short word.                       | [Cues](/concepts/cues)            |
| cue phrase        | The `on` value. A spoken phrase, `$start`, or `$end`.                                                      | [Cues](/concepts/cues)            |
| `$start` / `$end` | `$start` is 0.0 s after the section start. `$end` is the end of the section's last spoken word.            | [cues.json](/reference/cues-json) |
| resolve           | The `align` stage turns a cue phrase into a cue time. "Match" is only for comparing words.                 | [Cues](/concepts/cues)            |
| cue time          | The start of the cued word plus the offset key, rounded to hundredths, in seconds after the section start. | [Cues](/concepts/cues)            |
| fire              | The page runs a cue at its cue time.                                                                       | [Runtime](/reference/runtime)     |
| reveal            | An element becoming visible, with its reveal effect.                                                       | [Runtime](/reference/runtime)     |
| appear            | What an element does at its reveal.                                                                        | [Runtime](/reference/runtime)     |
| starts on         | A reveal starts on its word when its onset is within the offset limit of its cue time.                     | [Verify](/reference/verify)       |
| offset key        | The cue's `offset` in `cues.json`. A positive offset key moves the cue time later.                         | [cues.json](/reference/cues-json) |
| stage direction   | Bracketed script text that the voice does not speak.                                                       | [script.md](/reference/script-md) |
| beat              | The pause that `[beat]` or a plain stage direction makes. The voice reads a dash there.                    | [script.md](/reference/script-md) |
| timed pause       | `[pause N]`, which sends a break tag to the voice.                                                         | [script.md](/reference/script-md) |
| placeholder       | Text you must replace before a voiced build. `[CAPS]` in the script, or `<placeholder>` in `.env`.         | [script.md](/reference/script-md) |

## Audio

| Term                      | Meaning                                                                                                                                            | Explained in                                                       |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| script                    | The text of `script.md`.                                                                                                                           | [script.md](/reference/script-md)                                  |
| narration                 | The spoken audio: each section's mp3 and `narration.mp3`.                                                                                          | [How it works](/concepts/how-it-works)                             |
| voice (noun)              | The voice that speaks the script. The voice id picks it.                                                                                           | [Requirements and costs](/requirements)                            |
| speech provider           | The module and service that return audio and word times. ElevenLabs is the built-in one.                                                           | [Python API](/reference/python-api)                                |
| voice (verb), voice again | Make a section's narration with the speech provider.                                                                                               | [Rebuild one section](/guides/rebuild-one-section)                 |
| click track               | The audio that a build without voice writes. A soft click at every estimated word start. Log strings say "silent placeholder".                     | [How it works](/concepts/how-it-works)                             |
| click                     | One tick in the click track.                                                                                                                       | [Verify](/reference/verify)                                        |
| words file                | `build/narration/<hash>.words.json`.                                                                                                               | [Build artifacts](/reference/artifacts)                            |
| word times                | The start and end of each spoken word.                                                                                                             | [Build artifacts](/reference/artifacts)                            |
| spoken words              | The words in the words file. Matching and `?words=` use them.                                                                                      | [Cues](/concepts/cues)                                             |
| take                      | One section's recorded narration, named by the content hash of everything that changes its audio. Two sections with the same words share one take. | [Build artifacts](/reference/artifacts#build-narration-takes-json) |
| take index                | `build/narration/takes.json`. Which take each section plays, and where each section sits in `narration.mp3`.                                       | [Build artifacts](/reference/artifacts#build-narration-takes-json) |
| content hash              | The digest of everything that changes a take's audio, which names its files and is its identity.                                                   | [Build artifacts](/reference/artifacts#build-narration-takes-json) |
| generate                  | Make soundscape audio with `decktalk soundscape`.                                                                                                  | [Sound](/concepts/sound)                                           |
| music                     | The music under the whole video (`[mix] music`).                                                                                                   | [Sound](/concepts/sound)                                           |
| ambience bed              | The `[mix] ambience` audio.                                                                                                                        | [Sound](/concepts/sound)                                           |
| sound effect              | A one-shot audio file on a cue (`[[mix.sfx]]`).                                                                                                    | [Sound](/concepts/sound)                                           |
| reveal effect             | A `data-reveal` animation.                                                                                                                         | [Runtime](/reference/runtime)                                      |
| soundscape                | The optional audio parts: music, ambience bed, and sound effects.                                                                                  | [Sound](/concepts/sound)                                           |
| mix                       | Narration, clip audio, and soundscape summed, then passed through the loudness pass.                                                               | [Sound](/concepts/sound#loudness)                                  |
| duck                      | The music gets quieter under a spoken span or a clip.                                                                                              | [Sound](/concepts/sound)                                           |

## Recording, assembly, and verification

| Term                    | Meaning                                                                                                                                                | Explained in                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| recording               | The webm that `record` writes for a page section.                                                                                                      | [How it works](/concepts/how-it-works)                           |
| recording log           | `build/recordings/NN.json`. What `record` did for one section, and everything it judged about the result.                                              | [Build artifacts](/reference/artifacts#build-recordings-nn-json) |
| input hash              | The digest of a page, its words, its cues and every project file the page loads. `record` skips a section whose input hash has not moved.              | [Build artifacts](/reference/artifacts#build-recordings-nn-json) |
| cut list                | `build/out/cuts.json`. Where every section sits in the finished film.                                                                                  | [Build artifacts](/reference/artifacts#cuts-json)                |
| transcript page         | `build/out/<name>-transcript.html`. The whole video as one plain page, with a paragraph per section and each reveal the page described.                | [Build artifacts](/reference/artifacts)                          |
| poster                  | `build/out/<name>-poster.png`. A lossless PNG of the opening slide with every one of its reveals fired, drawn by the page.                             | [Build artifacts](/reference/artifacts)                          |
| seam                    | The cut into a section that sets `seamless`, which the continuity check measures.                                                                      | [Verify](/reference/verify#cut-continuity)                       |
| cover                   | The magenta overlay that hides the page until narration t=0.                                                                                           | [The page contract](/concepts/page-contract#the-handshake)       |
| narration t=0           | The moment `DeckTalk.startClock()` runs. The first frame after the cover. After the first use on a page, write t=0.                                    | [The page contract](/concepts/page-contract#the-handshake)       |
| recorder wait           | `max(settle_seconds, min_cover_seconds - elapsed)`. The wait before the recorder removes the cover.                                                    | [The page contract](/concepts/page-contract#the-handshake)       |
| settle                  | The `settle_seconds` wait, and nothing else.                                                                                                           | [The page contract](/concepts/page-contract)                     |
| trim                    | Remove the frames before t=0.                                                                                                                          | [How it works](/concepts/how-it-works)                           |
| cut (noun)              | The boundary between two sections in the final video.                                                                                                  | [How it works](/concepts/how-it-works)                           |
| cut (verb)              | `assemble` cutting a recording to its section span.                                                                                                    | [How it works](/concepts/how-it-works)                           |
| section span            | A section's start to its end on the narration clock, including the silence joined either side of its take.                                             | [Verify](/reference/verify)                                      |
| spoken span             | A section's `start` to its speech end.                                                                                                                 | [Sound](/concepts/sound)                                         |
| speech end              | The end of a section's last spoken word, in seconds after the section start.                                                                           | [Verify](/reference/verify)                                      |
| verify stage            | The `verify` stage inside `build`. Checks section starts, cuts, and cut continuity only.                                                               | [Verify](/reference/verify)                                      |
| `decktalk verify`       | The command. Checks section starts, cuts, and cues.                                                                                                    | [CLI](/reference/cli#decktalk-verify)                            |
| cue check               | One row of the cue table of `decktalk verify`.                                                                                                         | [Verify](/reference/verify#cues)                                 |
| changed share           | The percentage of pixels, at 480 by 270, whose luma differs by more than a level between two frames.                                                   | [Verify](/reference/verify#changed-share)                        |
| reference lead          | How far before the cue time `verify` sets the reference time. 0.14 s at the defaults.                                                                  | [Verify](/reference/verify#reference-frame)                      |
| reference frame         | The frame at the reference time, the picture before the cue.                                                                                           | [Verify](/reference/verify#reference-frame)                      |
| probe                   | The frame `d` seconds after the cue, for each `d` in `probe_delays`.                                                                                   | [Verify](/reference/verify#probes)                               |
| fitted probe            | A probe shortened to fit between close cues, so that no other cue's reveal falls in its span or in every control span.                                 | [Verify](/reference/verify#close-cues)                           |
| control share           | The smaller changed share of two back-to-back spans that end at the reference.                                                                         | [Verify](/reference/verify#control-share)                        |
| margin                  | A probe's changed share minus its control share.                                                                                                       | [Verify](/reference/verify#change-test)                          |
| change test             | Passes when the reported probe's changed share is at least `min_changed_percent` and its margin is at least `min_margin_percent`.                      | [Verify](/reference/verify#change-test)                          |
| thin change             | A pass of the change test by less than `thin_change_factor` times a floor. The row reads `THIN CHANGE?`.                                               | [Verify](/reference/verify#change-test)                          |
| onset                   | The first frame of a reveal, as the onset rule defines it.                                                                                             | [Verify](/reference/verify#onset-and-offset)                     |
| offset column           | The onset time minus the cue time, in whole milliseconds. Negative means early.                                                                        | [Verify](/reference/verify#onset-and-offset)                     |
| click distance          | The click time minus the cued word's start, in signed milliseconds.                                                                                    | [Verify](/reference/verify#the-a/v-value)                        |
| a/v                     | The offset column minus the click distance, in milliseconds. Exists only after a build without voice.                                                  | [Verify](/reference/verify#the-a/v-value)                        |
| offset limit, a/v limit | `max_offset_frames` (80 ms at 25 fps) and `max_av_frames` (120 ms at 25 fps).                                                                          | [Verify](/reference/verify#limits)                               |
| verdict                 | The word or words that a table prints for a row.                                                                                                       | [CLI](/reference/cli)                                            |
| finding                 | A verdict or note that counts toward the exit code. *Certain* exits 1. *Uncertain* ends in `?` and exits 1 only with `--strict`.                       | [CLI](/reference/cli#exit-codes)                                 |
| error                   | A `DeckTalkError`, printed as `error[CODE]: …` on stderr. It exits 3 even with `--exit-zero`, and it fills the envelope's `error` slot under `--json`. | [CLI](/reference/cli#exit-codes)                                 |

Note: the lesson example also says "error", for how wrong a guess is. That word is lesson content, not a DeckTalk term. [What does the lesson example mean by error?](/help/faq#what-does-the-lesson-example-mean-by-error) gives the precise meaning.

## Words with one meaning

These docs use each of these words in one sense only.

| Word       | Meaning in these docs               | For other senses, write                                  |
| ---------- | ----------------------------------- | -------------------------------------------------------- |
| once       | One time                            | "after" or "when"                                        |
| since      | A point in time, as in "since t=0"  | "because"                                                |
| while      | During the time that                | "but" for a contrast                                     |
| as         | In the way that                     | "because" for a cause, "when" for a time                 |
| drop       | Only the `drop` reveal effect       | "remove", "ignore", or "put"                             |
| may, might | Not used                            | "can" for an option, or state the risk                   |
| should     | Advice to the reader                | "must" for a requirement, the present tense for behavior |
| instead of | The one contrast phrase             | not "rather than"                                        |
| step       | Only a numbered item in a procedure | "slide" for a page slide, "stage" for a pipeline stage   |

## Related

* **Terms by page:** [How it works](/concepts/how-it-works)
* **Every command and verdict:** [CLI](/reference/cli)
* **How to write docs for DeckTalk:** [CONTRIBUTING.md](https://github.com/jacobcbeaudin/decktalk/blob/main/CONTRIBUTING.md)


# Python API
Source: https://docs.decktalk.ai/reference/python-api

Call the DeckTalk pipeline from Python, with each public name, its parameters, its result, and its errors.

The `decktalk` package runs the same pipeline as the command line. This page lists every public name, with its
signature, its result, and the errors it raises.

```python theme={null}
import decktalk

project = decktalk.Project.load("my-lesson")       # reads and validates decktalk.toml
result = decktalk.build(project, silent=True)
print(result.assembly.final, result.verification.ok)
```

Each stage function takes a `Project` and returns a typed result. It logs progress to the `decktalk` logger. It
raises a `DeckTalkError` subclass when it fails, and it never calls `sys.exit`.

## Public names

The package exports these names. Every other name is internal.

| Kind           | Names                                                                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project        | `Project`, `Section`, `PageSection`, `ClipSection`, `Settings`, `load_settings`                                                                                                                          |
| Project tables | `Voice`, `Transition`, `Mix`, `Loudness`, `Sfx`, `Soundscape`, `SoundSpec`, `MusicSpec`                                                                                                                  |
| Artifacts      | `Takes`, `CueTimes`, `Word`, `RecordingLog`, `Cuts`                                                                                                                                                      |
| Stages         | `narrate`, `align`, `preflight`, `record`, `assemble`, `verify`, `screenshots`, `soundscape`, `build`, `status`, `clip`, `words`                                                                         |
| Errors         | `DeckTalkError`, `ConfigError`, `MissingInputError`, `ProviderError`, `ToolError`                                                                                                                        |
| Vocabulary     | `Stage`, `Verdict`, `Certainty`, `SkipReason`, `ErrorCode`                                                                                                                                               |
| Results        | `NarrateResult`, `AlignResult`, `RecordResult`, `AssembleResult`, `VerifyResult`, `PreflightResult`, `ScreenshotsResult`, `WordsResult`, `ClipResult`, `StatusResult`, `SoundscapeResult`, `BuildResult` |
| Speech         | `SpeechProvider`, `SpeechRequest`, `register_speech_provider`                                                                                                                                            |
| Version        | `__version__`                                                                                                                                                                                            |

Note: `Section` is the union `ClipSection | PageSection` rather than a class of its own, so
`isinstance(section, decktalk.PageSection)` is how a caller tells the two apart.

Note: `decktalk.__all__` is the whole supported Python API. One word names the command, the Python call, the type
it returns and its `--json` key, so each command's result class sits in `__all__` beside the function that returns
it. Everything under `decktalk.media`, `decktalk.artifacts`, `decktalk.model`, `decktalk.stages` and
`decktalk.toolchain` is internal, so is everything under `decktalk.speech` except the three speech
names, and so is every name whose first character is `_`. The row classes those results hold, such as
`SectionRecording` and `CueCheck`, are read through the result that carries them.

## `Project`

```python theme={null}
decktalk.Project.load(where=None, *, environ=None) -> Project
decktalk.Project.from_toml(root, doc, *, environ=None) -> Project
```

`Project.load` reads and validates `decktalk.toml`. `Project.from_toml` builds a project from a mapping you have
already parsed.

| Parameter | Default                                        | Meaning                                                  |
| --------- | ---------------------------------------------- | -------------------------------------------------------- |
| `where`   | `DECKTALK_PROJECT`, then the current directory | Project directory, or the path of its `decktalk.toml`.   |
| `root`    | required                                       | Project directory, for `from_toml`.                      |
| `doc`     | required                                       | Parsed `decktalk.toml`, for `from_toml`.                 |
| `environ` | `os.environ`                                   | Mapping that supplies the `DECKTALK_*` tuning variables. |

**Raises** `ConfigError` when `decktalk.toml` is missing, cannot be parsed, or fails validation. The message names
the table and the field.

| Member                                                                                                                 | Kind     | Meaning                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `root`, `document`, `workspace`, `env`, `settings`                                                                     | field    | The project directory and the four parts it composes: the parsed `decktalk.toml`, the paths under `build/`, the secrets, and the tuning.                                             |
| `name`, `script`, `cues`, `build`                                                                                      | property | The project name and the paths from `[project]`, each read from the document.                                                                                                        |
| `sections`                                                                                                             | property | Every `PageSection` and `ClipSection`, in number order.                                                                                                                              |
| `voice`, `transition`, `mix`, `soundscape`                                                                             | property | The project tables, as frozen dataclasses with the keys of [decktalk.toml](/reference/decktalk-toml).                                                                                |
| `build`, `narration_dir`, `takes_dir`, `recordings_dir`, `sections_dir`, `out_dir`, `screenshots_dir`, `preflight_dir` | property | The `build/` directory and its subdirectories. `takes_dir` is `narration_dir` unless `[narration] cache_dir` moves the take files out of `build/`.                                   |
| `takes_path`, `narration_path`, `cue_times_path`, `cuts_path`, `progress_path`, `final`                                | property | Paths of the take index, which is also the narration clock, the joined narration track, the cue times file, the cut list, the progress log, and the final mp4.                       |
| `takes()`, `cue_times()`, `cuts()`                                                                                     | method   | Loads the artifact. `takes()` and `cuts()` return `None` when the file does not exist, and `cue_times()` returns an empty `CueTimes`.                                                |
| `section(number)`                                                                                                      | method   | Returns the section with that number, or `None`.                                                                                                                                     |
| `page_sections`, `clip_sections`, `clip_numbers`, `page_files`                                                         | property | The page sections, the clip sections, the clip numbers, and the page files in first-use order.                                                                                       |
| `recording(section)`, `recording_log(section)`, `section_video(section)`                                               | method   | Returns the path of the section's webm, of its recording log, or of its `sections/NN.mp4`.                                                                                           |
| `recording_log_of(section)`                                                                                            | method   | Loads that section's `RecordingLog`, or `None` when it has none.                                                                                                                     |
| `stray_section_videos(keys)`, `stray_section_warnings(command)`                                                        | method   | The `sections/NN.mp4` files that belong to no section, and one warning sentence per file.                                                                                            |
| `lead_seconds(key)`, `tail_seconds(key)`                                                                               | method   | The silence placed before a section's first word and after its last sound: the section's own key, else `[narration] lead_seconds` or `min_tail_seconds`. A clip section has neither. |
| `path(rel)`                                                                                                            | method   | Returns `rel` as an absolute path under `root`.                                                                                                                                      |
| `chapters()`                                                                                                           | method   | One chapter title per section: its own `chapter`, its script heading, or its number.                                                                                                 |
| `env.get(key)`                                                                                                         | method   | Returns the variable as an opaque value that prints as its own name. Call `reveal()` for the string. It is falsy when the value is unset or starts with `<`.                         |
| `require_env(*keys)`                                                                                                   | method   | Returns those same opaque values in order. Raises `ConfigError` that names every missing key and no value.                                                                           |
| `section_words(key, words_file)`, `narration_words(key, words_file, *, at)`                                            | method   | A take's words in seconds after its section starts, or shifted to `at` on the narration clock.                                                                                       |
| `script_sections()`, `cue_specs()`, `markers()`                                                                        | method   | Parses `script.md`, `cues.json` and the markers file, each checked against `decktalk.toml`.                                                                                          |

`load_settings(root=None, *, toml=None, environ=None, user=None)` builds a `Settings` from the defaults, the
per-machine file, the project's tables, and the environment.

## `build`

```python theme={null}
decktalk.build(project, *, silent=False, force=False, only=None, soundscape=True, loudness=True,
               strict=False, allow_unresolved_cues=False, allow_unknown_cues=False,
               from_stage=None, to_stage=None, progress_path=None, report=None) -> BuildResult
```

`build` runs the five stages in order: `narrate`, `align`, `record`, `assemble`, and `verify`.

| Parameter                | Default | Meaning                                                                                                                                                          |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `silent`                 | `False` | Uses a click track and estimated word times. Needs no API key. Raises `ConfigError` when `build/narration/takes.json` holds voiced takes, unless `force` is set. |
| `force`                  | `False` | Voices every section again, and ignores the narration cache. With `silent`, replaces voiced takes.                                                               |
| `only`                   | `None`  | Section numbers for `record`. The other stages still use every section.                                                                                          |
| `soundscape`             | `True`  | Mixes the music, the ambience bed, and the sound effects. `False` leaves them out.                                                                               |
| `loudness`               | `True`  | Runs the loudness pass.                                                                                                                                          |
| `strict`                 | `False` | Raises on a missing clip, a missing recording, or a loudness miss. A clip section with `optional = true` still plays its slate.                                  |
| `from_stage`, `to_stage` | `None`  | The first and last `Stage` to run, both ends inclusive, such as `decktalk.Stage.RECORD`.                                                                         |
| `progress_path`          | `None`  | Where to write the progress log. The default is `build/progress.jsonl`.                                                                                          |
| `allow_unresolved_cues`  | `False` | Continues when a cue phrase is not found.                                                                                                                        |
| `allow_unknown_cues`     | `False` | Continues when a cue id appears nowhere in its page.                                                                                                             |
| `report`                 | `None`  | A function that `build` calls as `report(stage, None)` when a stage opens and `report(stage, result)` when it closes. `stage` is a `Stage`.                      |

**Returns** a `BuildResult` with `stages`, the `Stage` members this run executed, one field per stage in
`narration`, `align`, `recordings`, `assembly` and `verification`, and `progress`, the path of the
progress log. A field is `None` for a stage the run did not reach. Its `ran` lists the stages that
produced a result, and its `ok` is true when the video was assembled and `verification.ok` is true.
The verification runs all five checks, cues included.

**Raises**

| Error               | When                                                                                                                                                        |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ConfigError`       | A cue phrase is not found and `allow_unresolved_cues` is false. A page threw an error during its recording. An input file is not valid.                     |
| `MissingInputError` | `strict` is true and a clip or recording is missing, or an earlier output is missing. `build --from` started at a stage past an artifact that is not there. |
| `ToolError`         | ffmpeg or Chromium failed, or `strict` is true and the loudness missed its target.                                                                          |
| `ProviderError`     | The speech provider refused or failed a request.                                                                                                            |

Note: a cue id that appears nowhere in its page is an ordinary finding rather than an exception. The
row carries the `UNKNOWN_CUE` verdict, `align` and `build` exit 1 on it, and `allow_unknown_cues`
lets the run continue.

## `verify`

```python theme={null}
decktalk.verify(project, checks=None, only=None) -> VerifyResult
```

`verify` checks section starts, cuts, and cues on the final mp4. [Verify](/reference/verify) defines every
measurement.

| Parameter | Default | Meaning                                                                                                                                                                             |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checks`  | `None`  | `None` checks every cue in `cue-times.json` that `cues.json` does not opt out. An empty list checks no cue. A list of `SECTION:CUE` strings checks those cues, even opted-out ones. |
| `only`    | `None`  | Section numbers whose cues to keep. Section starts, cuts, and cut continuity are always checked.                                                                                    |

**Returns** a `VerifyResult`.

| Member                                           | Meaning                                                                                                                                                                                                   |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `final`, `total_seconds`, `silent`               | Path of the final mp4, its length, and whether the build carries placeholder narration.                                                                                                                   |
| `recordings`                                     | One `LoggedRecording` per recorded page section, with `key`, `verdicts`, `page_errors`, `t0_method`, `where`, and `ok`. `verify` repeats these rather than measuring them.                                |
| `starts`                                         | One `StartCheck` per section, with `key`, `start`, `probe_at`, `yavg`, `ymax`, `ok`, and `verdict`.                                                                                                       |
| `cuts`                                           | One `CutCheck` per spoken section, with `key`, `cut_at`, `rms_db`, `ok`, and `verdict`.                                                                                                                   |
| `seams`                                          | One `SeamCheck` per section with `seamless = true`, with `key`, `cut_at`, `last_at`, `first_at`, `changed_percent`, `ok`, and `verdict`.                                                                  |
| `cues`                                           | One `CueCheck` per cue row, with `check`, `section`, `cue`, `cue_seconds`, `final_seconds`, `changed_percent`, `control_percent`, `offset_ms`, `av_ms`, `ok`, `note`, `verdict`, `reason`, and `skipped`. |
| `black_starts`                                   | Count of section starts that read `BLACK`.                                                                                                                                                                |
| `recorded_findings`, `film_findings`, `findings` | What the recording logs judged, what this run measured on the film, and the two added together.                                                                                                           |
| `ok`                                             | True when every recording, start, cut, seam, and measured cue passed. A skipped row never counts against it.                                                                                              |
| `to_dict(root)`                                  | The result as JSON-ready data.                                                                                                                                                                            |

**Raises** `MissingInputError` when the section mp4s or the final mp4 are missing. **Raises** `ConfigError` when a
check does not start with a section number.

## Other stages

These functions run one stage each, or read the project. Every result carries `findings`, the tally of what the
run judged, and `to_dict(root)`, the same thing as JSON-ready data with every path relative to the project root.

| Function                                                                                                         | Returns                                                                                                                                                                                                                                                                                                                                | Raises                                              |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `narrate(project, *, only=None, force=False, allow_placeholders=False, silent=False, model=None, dry_run=False)` | `NarrateResult` with `plans`, each a `TakePlan`, and `voice`, `narration`, `rate`, `rows`, `note`, `takes`, `synthesized`, `cached` and the `segments` property. With `dry_run`, `takes` is `None` and nothing is written.                                                                                                             | `ConfigError`, `MissingInputError`, `ProviderError` |
| `align(project, *, allow_unknown_cues=False)`                                                                    | `AlignResult` with `cue_times`, `sections`, `unresolved`, `estimated`, `unknown`, `uncued`, `cue_times_file`, `allow_unknown_cues`, and the `short`, `problems` and `unknown_problems` properties                                                                                                                                      | `ConfigError`, `MissingInputError`                  |
| `preflight(project, *, only=None, frames=True, model=None, allow_unknown_cues=False)`                            | `PreflightResult` with `voice`, `narration`, `takes`, `note`, `align`, `estimated`, `rate`, `cues`, `seams`, `frames`, `page_warnings`, `root`, `allow_unknown_cues`, and the `placeholders` and `short` properties                                                                                                                    | `ConfigError`, `MissingInputError`, `ToolError`     |
| `record(project, *, only=None, seconds=None, use_cues=True, opening=None, report=None)`                          | `RecordResult` with `sections`, each a `SectionRecording` with `section`, `path`, `log`, `kept`, and the `key`, `verdicts`, `ok` and `label` properties, plus the `kept_sections` and `page_errors` properties                                                                                                                         | `ConfigError`, `MissingInputError`, `ToolError`     |
| `assemble(project, *, soundscape=True, loudness=True, strict=False)`                                             | `AssembleResult` with `final`, `stamped`, which is `None` unless `[output] timestamped_copy` is on, and `duration`, `sections`, `warnings`, `loudness`, `loudness_problems`, `cuts`, `cuts_file`, `captions_srt`, `captions_vtt`, `chapters`, `transcript`, `poster`, plus the `substituted`, `substitutions` and `written` properties | `ConfigError`, `MissingInputError`, `ToolError`     |
| `screenshots(project, *, pages=None, slides=None, section=None, at=None, cues=None)`                             | `ScreenshotsResult` with `files`, each a `Screenshot` with `path`, `page`, `slide`, `cue`, `section`, `at` and `page_errors`, plus the `paths` property for the written files alone                                                                                                                                                    | `ConfigError`                                       |
| `soundscape(project, *, only=None, force=False, dry_run=False)`                                                  | `SoundscapeResult` with `items`, each a `SoundscapeItem` with `name`, `out`, `endpoint`, `requests`, `status`, and `duration_seconds`                                                                                                                                                                                                  | `ConfigError`, `ProviderError`                      |
| `status(project)`                                                                                                | `StatusResult` with `root`, `name`, `script`, `script_exists`, `cues`, `cues_exists`, `sections`, `takes`, `cue_times_exists`, `cue_times_sections`, `final`, `final_exists`, `final_duration`, `outputs`, `problems` and `run`. It reads what exists and runs nothing.                                                                | none                                                |
| `words(project, only=None)`                                                                                      | `WordsResult` with `sections`, each a `SectionWords` with `key`, `title`, `lead_seconds`, `duration`, `estimated`, `words`, `texts` and the `section` property                                                                                                                                                                         | `ConfigError`, `MissingInputError`                  |
| `clip(project, number, *, start, end, out, words_out=None, gain_db=0.0, hold_seconds=0.0)`                       | `ClipResult` with `section`, `video`, `words_file`, `start`, `end`, `first_frame`, `last_frame`, `hold_seconds`, `duration`, `gain_db`, `estimated`, `words`, and `cut_words`                                                                                                                                                          | `ConfigError`, `MissingInputError`, `ToolError`     |

* `record` with `seconds` records every section for that long. With `use_cues=False`, the pages play in preview. One call records, measures and checks each section, and writes its whole log before it opens the next page.
* `screenshots` with `section` takes frames from a playing section at each time in `at`, 0.5 s by default.
* `screenshots` with `cues` needs exactly one slide in `slides`.
* `words` gives each word in seconds after its section starts. `words` keeps the voice's spelling, and `texts`
  gives the same words with the script's punctuation and case.
* `clip` resolves a relative `out` or `words_out` against the project. `words_out` defaults to `out` with
  `.words.json`. [`decktalk clip`](/reference/cli#decktalk-clip) describes the cut.

Every result has `to_dict(root)`. It returns the data
that the command line prints under `--json`. Numbers stay numbers, and paths are relative to `root` with forward
slashes. Pass `project.root`.

```python theme={null}
import json
import decktalk

project = decktalk.Project.load("my-lesson")
result = decktalk.verify(project)
print(json.dumps(result.to_dict(project.root), indent=2))
```

## Vocabulary

A verdict, its certainty, a skip reason, a stage and an error code are members of plain enums, so a
string never compares equal to one. Compare a row with a member, as in
`row.verdict is decktalk.Verdict.OFF_CUE`, and read a word from JSON into a member before comparing it.

| Name         | Members                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Verdict`    | One member per verdict [Verify](/reference/verify) lists. `name` is the code, `label` is what a table prints, `certain` and `passing` say which kind of verdict it is, `to_dict()` gives the `{code, label, certain}` object every payload carries, and `Verdict.from_dict(data)` reads one back and raises `ValueError` on an object that names no verdict or disagrees with its code. |
| `SkipReason` | Why a row measured nothing, such as `SkipReason.OPTED_OUT`. `value` is the code.                                                                                                                                                                                                                                                                                                        |
| `Stage`      | The five stages, in the order a build runs them. `value` is the name that `--from`, `--to`, the progress log and the `build` payload use, and `Stage("record")` reads one.                                                                                                                                                                                                              |
| `Certainty`  | How sure a verdict is, which `Verdict.certainty` holds: `CERTAIN`, `UNCERTAIN` or `PASSING`.                                                                                                                                                                                                                                                                                            |
| `ErrorCode`  | What an error's `code` is, such as `decktalk.ConfigError.code is decktalk.ErrorCode.CONFIG`. `value` is the code the command line prints and the envelope's `error.code`.                                                                                                                                                                                                               |

A take plan's `status`, a soundscape item's `status`, and a `Cut`'s `kind` and `substitute` are
members of plain enums too. Their enums are not exported, so read the word with `.value`, which is
the word the JSON carries: `synthesize`, `cached` or `unknown`, `planned`, `unchanged` or
`generated`, `page` or `clip`, and `slate` or `black`. A `Cut` with nothing standing in for it has
`substitute` set to `None`.

## Artifacts

These classes read and write the files under `build/`. [Build artifacts](/reference/artifacts) gives every field,
and names the files that no public class reads.

| Class          | Members                                                                                                                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Word`         | `word`, `start`, `end`                                                                                                                                                                                         |
| `Takes`        | The take index and the narration clock. `load(path)` returns `None` when the file does not exist, `save(path)`, `keys`, `voiced_keys`, `span(key)`, `start(key)`, `end(key)`, `starts`, and `speech_end(key)`. |
| `CueTimes`     | The resolved cues per section, as `CueTime` rows. `load(path)`, `save(path)`, `query(key)` for the `?cues=` string, `times(key)`, `get(key, cue)`, and `word_at(key, cue)`.                                    |
| `RecordingLog` | What the recorder did for one section. `load(path)` returns `None` when the file does not exist, `save(path)`, `trim_seconds`, and `worst_stall_ms`.                                                           |
| `Cuts`         | The cut list, as `Cut` rows. `load(path)` returns `None` when the file does not exist, `save(path)`, `to_dict()`, `substituted`, and `at(seconds)` for the section playing at a second of the film.            |

## Errors and logging

Every error that DeckTalk raises on purpose is a `DeckTalkError`.

Each one carries `hint`, the smallest next action, `path`, the project file it is about, and `line`,
the line inside that file, and each of the three is `None` when nothing knows it. The command line
prints an error as `error[CODE]: <message>` on stderr and exits 3, and under `--json` it fills the
envelope's `error` slot. `error.code` is an `ErrorCode`, and the table gives its `value`.

| Error               | `error.code`    | Raised when                                                                                 |
| ------------------- | --------------- | ------------------------------------------------------------------------------------------- |
| `DeckTalkError`     | `INTERNAL`      | Base class of every error below. Raised on its own it is unplanned.                         |
| `ConfigError`       | `CONFIG`        | `decktalk.toml`, `cues.json`, or `.env` is missing, cannot be parsed, or is not consistent. |
| `MissingInputError` | `MISSING_INPUT` | A stage needs an output that an earlier stage has not written yet.                          |
| `ProviderError`     | `PROVIDER`      | An external API, such as ElevenLabs, refused or failed a request.                           |
| `ToolError`         | `TOOL`          | ffmpeg, ffprobe, or Chromium is not available or failed.                                    |

The stages log progress to the `decktalk` logger at the INFO level. Attach a handler to see it. `__version__` is
the installed version string.

## Speech providers

A speech provider returns audio and a start and end time for every word. ElevenLabs is the built-in provider.

| Name                                      | Meaning                                                                                                                                                                                          |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SpeechProvider`                          | A protocol with `name`, `speak(request)`, and `cache_key(request)`. `speak` returns the audio bytes and a list of `Word`. `cache_key` returns everything except the text that changes the audio. |
| `SpeechRequest`                           | A frozen dataclass with `text`, `model`, `voice_settings`, `output_format`, `previous_text`, and `next_text`. `text` holds break tags.                                                           |
| `register_speech_provider(name, factory)` | Makes a provider selectable as `[voice] provider = "name"`. The factory receives a `VoiceContext`, which carries the settings and the project's secrets, and returns a provider.                 |

Registering a name again replaces the earlier factory. DeckTalk loads no plugins. For a provider that the command
line can use, open a pull request that adds a module under `src/decktalk/speech/` and names it in the registry.

## Stability

The file formats and the page contract are the stable surface: `decktalk.toml`, `cues.json`, the build artifacts,
and the page runtime. A change to them raises the minor version. The Python names can still change.

## Related

* **Look up the files that the stages write:** [Build artifacts](/reference/artifacts)
* **Look up a tuning field:** [Configuration](/reference/configuration)
* **Run the same stages from a shell:** [CLI](/reference/cli)


# Runtime
Source: https://docs.decktalk.ai/reference/runtime

Look up every mode, URL parameter, function, data attribute, field, and warning of decktalk-runtime.js.

`decktalk-runtime.js` is the script that plays a DeckTalk page. It mounts the slides of a scene and
makes elements appear on their cues. This page lists its modes, URL parameters, functions, data
attributes, fields, CSS hooks, and warnings. [The page contract](/concepts/page-contract) explains
how the parts work together.

A DeckTalk command that opens a page injects a second file, `decktalk-probe.js`, before the page
loads. It carries what a command needs and a reader does not: the cover over the first paint, the
helper the command waits on, the boxes of the measured catalog, and the freeze that stops at one
cue. It is never a `<script>` tag, `decktalk init` never writes it, and the rows below say which of
the two files each thing belongs to.

Include the runtime in the head of the page. A project keeps the copy that `decktalk init` wrote
into `deck/`. A scene is markup, and a page that needs no behaviour needs no JavaScript at all.

```html deck/index.html theme={null}
<script src="decktalk-runtime.js"></script>

<div data-scene="2" data-name="How it works">
  <template data-slide="2.1" data-hold="16">
    <p class="eyebrow">How it works</p>
    <div class="title" data-cue="2.1average" data-describe="the heading, the average of n numbers">
      <h1>The average of n numbers.</h1>
    </div>
    <p data-cue="2.1formula" data-tex="\bar{x}=\frac{1}{n}\sum_{i=1}^{n} x_i" data-tex-display>
      the mean of n numbers
    </p>
  </template>
</div>
```

A slide that needs code keeps its markup and adds a handler, or replaces the `<template>` with a
`render` function.

```html deck/index.html theme={null}
<script>
  DeckTalk.on("2.1formula", (slide) => slide.querySelector(".rule").classList.add("run"));
</script>
```

## Slides in markup

A `[data-scene]` element declares a scene, and every `<template data-slide>` inside it declares one
slide, in document order. The wrapper never draws, and the runtime clones a template's content each
time its slide mounts. Markup is not a JavaScript string, so a backslash is written once and `${`
and a backtick are ordinary characters.

| Attribute      | On             | Default      | Meaning                                                                         |
| -------------- | -------------- | ------------ | ------------------------------------------------------------------------------- |
| `data-scene`   | the wrapper    | none         | The scene id.                                                                   |
| `data-name`    | the wrapper    | `Scene <id>` | The scene name, shown in the index and the catalog.                             |
| `data-camera`  | the wrapper    | none         | `push` runs the camera push.                                                    |
| `data-slide`   | a `<template>` | required     | The slide id.                                                                   |
| `data-hold`    | a `<template>` | `8`          | Seconds the slide holds in preview.                                             |
| `data-owns`    | a `<template>` | none         | Cue ids this slide owns that do not start with its own id, separated by spaces. |
| `data-preview` | a `<template>` | none         | `id@seconds` pairs, separated by spaces: when each cue fires in preview.        |

Note: A scene that a script registered keeps its definition, and each of its slides that defines no
`render` takes the markup of the template with its id. A template whose slide id the script never
declared joins the end of that scene. A slide that has both a `render` and a template warns, and the
template is unused.

Note: A scene in markup needs no `preview` object. The cue ids of a `<template>` slide, and their
order, come from its own `data-cue` attributes in document order. A `render` slide has no markup to
read before it mounts, so its order comes from `preview` and then `owns`.

## Modes

The URL picks the mode. In prose these docs write index mode, preview, cue mode, and freeze mode.

| Mode        | `mode` value | URL                                                                                    | Clock starts                                     | What mounts                                    | Used by                                             |
| ----------- | ------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------- | --------------------------------------------------- |
| Index mode  | `index`      | no `scene`, `cues`, or `slide`, or an unknown scene or slide                           | not used                                         | a list of scenes and slides                    | a person who picks a scene                          |
| Preview     | `preview`    | `?scene=N`                                                                             | at `load`                                        | each slide in turn, for `hold / speed` seconds | a browser preview                                   |
| Cue mode    | `cue`        | `?cues=…`, usually with `scene`                                                        | at `load`, or at `startClock()` with `t0=signal` | each slide at the earliest cue it owns         | `decktalk record`, `decktalk screenshots --section` |
| Freeze mode | `freeze`     | `?slide=ID`, optionally with `&after=CUE` or `&before=CUE` (the probe reads those two) | at `load`, after the slide has mounted           | one slide, with its reveals in their end state | `decktalk screenshots`, `decktalk preflight`        |

Note: `slide` wins over `scene` and `cues`. With `cues` and no registered `scene`, the scene that
owns the earliest cue plays. [Cue ownership](/concepts/page-contract#cue-ownership) gives the
ownership and mount rules of cue mode.

## URL parameters

| Parameter   | Type               | Default | Meaning                                                                                                                                                                                                                                                                      |
| ----------- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scene`     | string             | none    | Plays this scene. `DeckTalk.scene(3, …)` registers `"3"`.                                                                                                                                                                                                                    |
| `cues`      | string             | none    | Turns on cue mode. Comma-separated `id@seconds` pairs, in seconds after narration t=0.                                                                                                                                                                                       |
| `t0`        | number or `signal` | `0`     | Seconds after `load` at which narration t=0 falls. `signal` waits for `DeckTalk.startClock()`.                                                                                                                                                                               |
| `words`     | string             | none    | The section's spoken words, as comma-separated `word@seconds` pairs. `data-text="spoken"` uses them.                                                                                                                                                                         |
| `prevwords` | string             | none    | The spoken words of the section just before this one in the narration, in the same form, in seconds after that section starts. The runtime ignores them. A page that opens on the previous section's last frame can read them, so a value it carries across the cut matches. |
| `slide`     | string             | none    | Turns on freeze mode for this slide.                                                                                                                                                                                                                                         |
| `after`     | string             | none    | With `slide`, fires the slide's cues up to and including this one. Elements of later cues stay hidden.                                                                                                                                                                       |
| `before`    | string             | none    | With `slide` and no `after`, fires the slide's cues before this one. Elements of this cue and later cues stay hidden.                                                                                                                                                        |
| `speed`     | number             | `1`     | Divides preview time. The minimum is 0.05. Cue mode ignores it.                                                                                                                                                                                                              |
| `hud`       | `1`                | off     | Shows the mode, scene, slide, and clock in the top left corner. Never use it in a recording.                                                                                                                                                                                 |

Note: An unknown `scene` shows the index with the note `unknown scene N`. An unknown `slide` shows
the index with the note `unknown slide ID`. Neither adds a warning. The catalog still exists, so the
recorder records the index with no `PAGE ERROR`.

Note: The runtime sorts the `cues` pairs by time and splits each pair at its last `@`. It skips a
pair whose seconds are not a number. Write every pair as `id@seconds`.

Note: The recorder builds `words` from the words file of the take that section plays, in seconds after
the section start. It removes commas and `@` from each word. It builds `prevwords` the same way from the
section before, and only for a section that sets `seamless = true`. It leaves it out for every other
section, and when the section before has no words.

Note: In freeze mode, the slide's cues fire in preview order: the cues of the `preview` object by
their seconds, then the cues of the markup in document order and the cues of `owns`. Animations take no time. A count-up shows its final value, a
typewriter shows its full text, and a `data-text="spoken"` element shows whole.

Note: `after` and `before` belong to `decktalk-probe.js`, so a page opened by hand at `?slide=ID`
shows every reveal and ignores both. With `after` or `before`, only the cues that fire run their handlers. An `after` or `before` id
that is not one of the slide's cues adds the warning `cue "<id>" is not one of slide <slide>'s cues`,
the whole slide freezes, and every cue fires. `enter` still gets `ctx.frozen` as true, so a figure
that `enter` draws in its end state shows that state at every cue. In the starter,
`?slide=2.1&after=2.1formula` shows the heading and the typeset equation and hides the code beside
it, which waits for `2.1code`. `decktalk screenshots --slide 2.1 --after 2.1formula` opens that URL.

## Seamless sections

`seamless = true` on a `[[section]]` in `decktalk.toml` changes nothing in the runtime. The scene still
mounts its own first slide, with no animation, before the clock starts, and nothing of the previous
scene is carried across the cut. The key changes what the page is given and what is checked:

* The recorder adds `prevwords` to the section's URL, the previous section's spoken words in seconds
  after that section starts.
* `decktalk verify` compares the previous section's last frame before any dip with this section's
  first frame after any dip, and reads `POP AT CUT` when their changed share is above
  `[verify] max_pop_percent`, 0.1 % by default. `decktalk preflight` compares the previous scene's last
  frozen state with this scene's first one.

A scene opens on the previous scene's last picture only when its first state draws that picture
again. Copy the previous scene's last slide into the new scene's first `<template data-slide>`, drop
`data-cue` and `data-delay` from the copied elements so they show on the first frame, keep their classes
and styles, then add the new elements with their own `data-cue`:

```html theme={null}
<div data-scene="1">
  <template data-slide="1.1">
    <div class="box" data-cue="1.1a">One</div>
    <div class="box right" data-cue="1.1b">Two</div>
  </template>
</div>
<div data-scene="2">
  <template data-slide="2.1">
    <div class="box">One</div>
    <div class="box right">Two</div>
    <div class="box below" data-cue="2.1c">Three</div>
  </template>
</div>
```

Leave `data-camera="push"` off both scenes, because the previous scene ends pushed in, and leave the
pair out of `[transition] dips`. In the example, slide 2.1 draws scene 1's last picture again from its first
frame, and only `Three` waits for its word. [Page contract](/concepts/page-contract#a-seamless-cut) and
[Cut continuity](/reference/verify#cut-continuity) say more.

## `DeckTalk.scene(id, definition)`

`DeckTalk.scene` registers a scene and returns `DeckTalk`, so calls chain. The runtime starts on
`DOMContentLoaded`: it reads the scenes in markup, builds the catalog, and starts the mode the URL
asks for. A page needs `DeckTalk.scene` only for a slide that builds itself in code.

### Scene fields

| Field    | Type               | Default      | Meaning                                                            |
| -------- | ------------------ | ------------ | ------------------------------------------------------------------ |
| `name`   | string             | `Scene <id>` | Name in the index and the catalog.                                 |
| `camera` | `"push"` or `null` | `null`       | `"push"` zooms the stage element from 100% to 103% over the scene. |
| `slides` | array              | `[]`         | The slides, in order, as objects with the slide fields below.      |

Note: A push lasts the preview total in preview, or the last cue time plus 8 s in cue mode. It
lasts at least 4 s. Freeze mode shows no push. [Add a camera push](/guides/design-a-slide#add-a-camera-push)
says when to use one.

### Slide fields

| Field     | Type             | Default       | Meaning                                                                                                                                                      |
| --------- | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`      | string           | `<scene>.<n>` | The slide id, which is also a cue id. `n` counts from 1.                                                                                                     |
| `hold`    | number           | `8`           | Seconds before the next slide mounts, in preview. Cue mode ignores it.                                                                                       |
| `owns`    | array of strings | none          | Cue ids the slide owns that do not start with its own id. Rare, because the id prefix is the ownership rule.                                                 |
| `preview` | object           | none          | `{ id: seconds }`. When each cue fires in preview, in seconds after the mount. It grants no ownership.                                                       |
| `render`  | function         | none          | `({ scene, slide, frozen }) => string`. Returns the HTML of the slide. A slide with no `render` takes the markup of the `<template data-slide>` with its id. |
| `enter`   | function         | none          | `(slide, ctx) => void`. Runs after the slide is in the DOM, for preparation in code.                                                                         |
| `on`      | object           | `{}`          | `{ [cueId]: (slide, ctx) => void }`. Handlers for this slide's cues.                                                                                         |

Note: In preview, a `data-cue` element appears when the slide's `preview` object fires its cue, and
an element with `data-delay` and no cue appears that many seconds after the mount. A cued element
with no `preview` entry stays hidden through the preview, which is what a browser preview of a page
whose timing lives in `cues.json` shows.

Note: In preview, a time in `preview` at or past `hold` adds a warning, because that cue fires after
the next slide mounts. The last slide of a scene never warns. A seconds value that is not a number
counts as 0.

Note: `render` gets the runtime's own scene and slide objects. Inside its template literal, write
every backslash twice, and write no `${` or backtick that is not meant as one
([`data-tex`](#data-tex)). Markup in a `<template data-slide>` has none of those traps.

Note: `enter` gets the [handler context](#handler-context) with `id` and `slideId` set to the slide id,
and `at` set to the mount time. Keep the state that cue handlers need on the slide element, as in
`slide.fig = install(slide, ctx.frozen)`. An `enter` that throws becomes a warning, and the scene
goes on.

## Handler context

A slide's `enter`, its `on[id]` handlers, and every `DeckTalk.on(id, fn)` handler get two arguments.
The first is the element of the mounted slide. The second is a context object with these
fields. A handler that takes no arguments still works.

| Field     | Type             | Meaning                                                                                                                                            |
| --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`      | string           | The cue id. For `enter`, the slide id.                                                                                                             |
| `at`      | number           | The value of `now()`, rounded to the millisecond, when the cue fired or the slide mounted. `-Infinity` before the clock starts, so in freeze mode. |
| `frozen`  | boolean          | `true` in freeze mode. A handler then shows its end state at once.                                                                                 |
| `slideId` | string or `null` | The id of the mounted slide. The first argument is already the slide element, so this field is a string.                                           |

```js deck/index.html theme={null}
DeckTalk.on("2.1formula", (slide, ctx) => {
  slide.querySelector(".rule").classList.toggle("run", !ctx.frozen);
});
```

## `DeckTalk` methods and properties

| Signature               | Returns                      | Meaning                                                                                                                       |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `scene(id, definition)` | `DeckTalk`                   | Registers a scene.                                                                                                            |
| `on(id, fn)`            | `DeckTalk`                   | Registers a global handler for cue `id`, called as `fn(slide, ctx)`. Several handlers can share an id.                        |
| `start()`               | `undefined`                  | Reads the scenes in markup, then the URL, and starts the mode. Runs on `DOMContentLoaded`. A second call does nothing.        |
| `startClock()`          | `undefined`                  | Starts the clock now. The recorder calls it one time, when the URL has `t0=signal`. Does nothing after the clock has started. |
| `reveal(element)`       | `undefined`                  | Makes one element appear now, with its count-up, typewriter, or word sync. Does nothing to an element that has appeared.      |
| `fire(id)`              | `undefined`                  | Fires a cue now, as [When a cue fires](/concepts/page-contract#when-a-cue-fires) describes.                                   |
| `findSlide(slideId)`    | `{ scene, slide }` or `null` | Finds a slide id in any scene. Returns the runtime's own objects.                                                             |
| `waitFor(promise)`      | `DeckTalk`                   | Adds one more condition to `window.__decktalk.ready`. Call it for every wait of your own instead of replacing the promise.    |
| `version`               | string                       | The version of DeckTalk this runtime file shipped with.                                                                       |
| `scenes`                | `Map`                        | Every registered scene, by id.                                                                                                |
| `params`                | `URLSearchParams`            | The page's query parameters, including `params` from the `[[section]]` table.                                                 |

Note: A handler that `DeckTalk.on` registers also stops the `unknown cue id` warning for its id, as
long as it is registered before `DOMContentLoaded`. Call `DeckTalk.start()` yourself only for a
scene you register later.

## Data attributes

Put these attributes on elements inside the HTML of a slide.

| Attribute            | Value                                                      | Default             | Meaning                                                                                                          |
| -------------------- | ---------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `data-cue`           | cue id                                                     | none                | Appears when this cue fires.                                                                                     |
| `data-delay`         | seconds                                                    | `0`                 | Appears this many seconds after the slide mounts. For an element with no cue.                                    |
| `data-reveal`        | `rise`, `fade`, `draw`, `drop`, `pop`, `dim`, or `instant` | `rise`              | The reveal effect. See [`data-reveal`](#data-reveal).                                                            |
| `data-duration`      | seconds                                                    | the effect's length | Length of the reveal effect and of a count-up.                                                                   |
| `data-describe`      | a sentence                                                 | none                | What this reveal shows. The transcript output reads it, and it travels in the catalog.                           |
| `data-text="count"`  | empty or `first`                                           | off                 | Counts the last number in the text up from 0. `first` counts the first number.                                   |
| `data-text="type"`   | milliseconds                                               | `40`                | Types the text at this many milliseconds per character.                                                          |
| `data-text="spoken"` | flag                                                       | off                 | Shows the text one word at a time, as the voice says each word. See [`data-text="spoken"`](#data-text="spoken"). |
| `data-tex`           | TeX                                                        | none                | Typesets this TeX with KaTeX. See [`data-tex`](#data-tex).                                                       |
| `data-tex-display`   | flag                                                       | off                 | With `data-tex`, typesets in display mode.                                                                       |

Note: `data-cue` and `data-delay` are two triggers for one element, so an element that carries both
adds a warning and the delay is ignored.

Note: In cue mode, a `data-cue` that `?cues=` does not list adds a warning, and its element appears
as soon as the slide mounts rather than staying invisible. In freeze mode every element appears at
once, except the elements of cues after the `after` or `before` parameter.

Note: `data-text="count"`, `data-text="type"`, and `data-text="spoken"` run when their element appears. Each one needs
`data-cue` or `data-delay` on the same element. Without either, the effect never runs, and the page
warns.

Note: `data-text="count"` keeps the decimal places and thousands commas of the number, so `1,250.5`
counts with one decimal and a comma. The rest of the text stays in place. The count eases out over
`data-duration`, or 0.9 s. `data-text="type"` keeps the element at the size of its finished text, so nothing
around it moves.

### `data-reveal`

| Effect    | Length        | Animation                                              |
| --------- | ------------- | ------------------------------------------------------ |
| `rise`    | 0.3 s         | Fades in and moves up 10 px.                           |
| `fade`    | 0.3 s         | Fades in.                                              |
| `draw`    | 0.3 s, linear | Draws the stroke of an SVG path with `pathLength="1"`. |
| `drop`    | 0.35 s        | Fades in and moves down 24 px.                         |
| `pop`     | 0.5 s         | Fades in and scales from 60% past 108% to 100%.        |
| `dim`     | 1.2 s         | Starts visible and fades to 16% opacity.               |
| `instant` | none          | Appears on the frame of its cue.                       |

[Choose a reveal effect](/guides/design-a-slide#choose-a-reveal-effect) says where each effect works
well.

### `data-text="spoken"`

An element with `data-text="spoken"` shows its words one at a time, each at the moment the voice says it.
These rules apply:

1. The element also needs `data-cue` or `data-delay`. Without either, the words never sync, and the page warns.
2. The text must match the spoken words, word for word. Matching ignores case and every character except a to z and 0 to 9.
3. Apostrophes do not count in this match. The `align` stage keeps apostrophes when it matches a cue phrase.
4. If the text occurs more than once, the runtime uses the first match that starts at most 1.5 s before the element appears. If every match starts earlier, it uses the last match.
5. If nothing matches, the element appears whole, and the page warns.
6. Each word appears 20 ms before its start time, with a 0.12 s fade.
7. The element gets `data-reveal="instant"` unless it sets its own `data-reveal`. A reveal effect on the whole element would hide the timing of the words.
8. Without a `words` parameter, as in a browser preview, the element appears whole. It also appears whole in freeze mode.

### `data-tex`

The runtime typesets the value of `data-tex` with KaTeX when `window.katex` exists. The typeset math
replaces the element's text. Without KaTeX, the text stays, so write it as a readable fallback.
KaTeX shows a TeX string that it cannot parse in red, and the page warns.

Inside a `<template data-slide>` the value is markup, so every backslash is written once.

```html deck/index.html theme={null}
<p data-tex="\frac{d}{dx}\,x^2 = 2x" data-tex-display>d/dx x^2 = 2x</p>
```

Inside a `render` template literal, write every backslash twice. JavaScript reads `\f`, `\t`, `\u`,
and `\x` as escapes. For example, `\frac` becomes a form feed, and `\theta` becomes a tab.
`\underbrace` and `\xrightarrow` become syntax errors, and a syntax error blanks the page. This is
the reason to write an equation as markup.

```js deck/index.html theme={null}
render: () => `<p data-tex="\\frac{d}{dx}\\,x^2 = 2x" data-tex-display>d/dx x^2 = 2x</p>`
```

If a slide mounts a `data-tex` element and KaTeX is missing, the runtime checks again 5 s later. If
the element is still plain text, the page warns.

## `window.__decktalk`

`window.__decktalk` holds read-only state for the recorder, `decktalk screenshots`, and your own tools.

| Field        | Type             | Meaning                                                                                                                                                                                                                                        |
| ------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`    | string           | The version of DeckTalk this runtime file shipped with.                                                                                                                                                                                        |
| `mode`       | string           | `index`, `preview`, `cue`, or `freeze`. `live`, the playback mode that follows an audio element, is a reserved name and is not implemented.                                                                                                    |
| `scene`      | string or `null` | The id of the playing scene.                                                                                                                                                                                                                   |
| `slide`      | string or `null` | The id of the mounted slide.                                                                                                                                                                                                                   |
| `cues`       | array            | The parsed `cues` pairs, as `{ id, t }` objects in time order.                                                                                                                                                                                 |
| `fired`      | array of strings | Cue ids fired so far, in order. `decktalk screenshots --section` logs it with each frame.                                                                                                                                                      |
| `catalog`    | array            | One `{ scene, name, camera, slides, cues }` object per scene, plus `elements` in index mode when the probe is there. `slides` lists the slide ids. `cues` maps each slide id to its cue ids in preview order. See [the catalog](#the-catalog). |
| `warnings`   | array of strings | Everything the runtime could not do, each listed one time.                                                                                                                                                                                     |
| `now()`      | function         | Seconds since the clock started, or `-Infinity` before it starts.                                                                                                                                                                              |
| `frameGaps`  | array            | One `{ at, ms }` object for each gap over 100 ms between two animation frames. Cue mode only.                                                                                                                                                  |
| `spokenLog`  | array            | One `{ text, cueAt, runAt, n, firstOn }` object for each `data-text="spoken"` element that matched.                                                                                                                                            |
| `cueLog`     | array            | One `{ id, due, ran, frame, describe, next, after }` object for each cue that fired from `cues`. Cue mode only.                                                                                                                                |
| `longFrames` | array            | One `{ start, ms, render, presented }` object for each animation frame over 50 ms after t=0. Cue mode only.                                                                                                                                    |

Note: After a recording, the recorder reads `catalog`, `warnings`, `frameGaps`, `spokenLog`, `cueLog`, and `longFrames`. A
missing or empty `catalog` is a page error. `decktalk screenshots` reads `catalog` to find every slide.

### The catalog

In index mode, and in index mode alone, `decktalk-probe.js` lays every slide out once in a hidden
layer of the stage, measures it, and throws it away. Each catalog entry then carries `elements`,
which maps a slide id to one row per element, so a check that cannot look at a picture still knows
where every reveal sits. A page opened without a command driving it carries no `elements` at all.

| Field      | Type             | Meaning                                                                           |
| ---------- | ---------------- | --------------------------------------------------------------------------------- |
| `cue`      | string or `null` | The element's `data-cue`. `null` for an element that is on screen from the mount. |
| `delay`    | number or `null` | The element's `data-delay` in seconds, or `null`.                                 |
| `reveal`   | string or `null` | The element's `data-reveal`.                                                      |
| `describe` | string or `null` | The element's `data-describe`.                                                    |
| `tex`      | string or `null` | The element's `data-tex`.                                                         |
| `text`     | string           | The element's text, collapsed and cut to 80 characters.                           |
| `box`      | object           | `{ x, y, w, h }` in stage pixels, where the stage is 1920 by 1080.                |

Note: Every element with `data-cue` or `data-delay` gets a row, in document order, and so does every
direct child of the slide that has neither and holds neither. A row with no `cue` and no `delay` is
content that is on screen from the mount, before any word. `preflight` reads these rows and raises
three findings from them, with no picture: `OFF STAGE` for a cued box that is not wholly inside the
stage, `IN CAPTION BAND?` for one that reaches into the bottom fifteen percent, and `CUES OVERLAP?`
for two cues of a section closer together than a reveal plays for. They arrive in
`preflight`'s `page_scan` and in `findings.items[]` like any other row.

Note: Measuring mounts every slide, so it never runs in a mode a recording can be made in. In cue
mode, preview, and freeze mode the catalog carries no `elements`, and neither does any mode of a
page that no command injected the probe into.

Note: With a numeric `t0`, the clock starts at `load`, so narration t=0 is where `now()` equals
`t0`. With `t0=signal`, `now()` counts from narration t=0.

Note: In `frameGaps`, `at` is the value of `now()` when the gap ended. A gap under the cover has
`at` equal to `-Infinity`, and the recording log field `frame_gaps` writes it as `null`. Only the part of
a gap after t=0 counts toward `STALLED` ([decktalk record](/reference/cli#decktalk-record)). So a page
can do slow first work before t=0, such as drawing a canvas figure or a large SVG.

Note: In `spokenLog`, `text` is the first 24 characters of the text. `cueAt` is the time the element
appeared, and `runAt` is the start of its first matched word. `n` is the number of words, and
`firstOn` is the time the first word appeared. The recording log field is `spoken_log`.

Note: In `cueLog`, every time is in seconds on the narration clock. `due` is the cue's time, and `ran`
is when the runtime fired it. `frame` is the start of the animation frame that fired it, and `next`
and `after` are the starts of the two frames after it. A cue with `ran` well past `due` was held up
before its frame. A cue that ran on time but whose `next` frame started late was held up while its
frame was drawn, and `describe` is the `data-describe` of the reveals that cue fired, joined into one
sentence, or null when none of them carries it. The transcript page is what reads it. The recording
log field is `cue_log`.

Note: In `longFrames`, `start`, `render`, and `presented` are seconds on the narration clock, and `ms`
is the frame's length. `presented` is when Chromium showed the frame, or `null` when the browser does
not report it. The recording log field is `long_frames`.

The runtime also sets `document.body.dataset.done` to `"1"` when the last slide of a played scene has
mounted, or when a freeze has fired its cues.

## `window.__decktalk.ready`

`window.__decktalk.ready` is a Promise, and the runtime owns it. The recorder awaits it before it
starts the clock. It waits for these things, in order:

1. `document.fonts.ready`.
2. KaTeX, when the document has a `[data-tex]` element or a `<script>` whose `src` contains `katex`. The runtime checks for `window.katex` every 100 ms, for up to 5 s. Then it typesets the mounted slide. If KaTeX never loads, the page warns, and the elements keep their text.
3. Every promise the page handed to `DeckTalk.waitFor`.
4. In index mode, the catalog the probe measures, when a command injected it.

The first slide of a played scene is mounted before the clock starts, so in every mode a slide is on
the stage before the wait ends. The recorder waits with no time limit. It ignores a rejected Promise
and starts the clock anyway.

A page adds a condition of its own with `DeckTalk.waitFor`, which takes a promise and returns
`DeckTalk`. Two scripts can each add one, and neither can clobber the other's.

```js deck/index.html theme={null}
const faces = ['600 64px "Inter Tight"', '500 30px Inter'];
DeckTalk.waitFor(
  Promise.all(faces.map((f) => document.fonts.load(f))).then(
    () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))),
  ),
);
```

[Wait for a screenshot to load](/guides/slide-recipes#wait-for-a-screenshot-to-load) shows the same
call for an image.

## CSS hooks

The runtime prepends a `<style id="dt-style">` element to `<head>`, and every selector in it sits
inside `:where()`. Its rules therefore carry no specificity and lose to any rule the page writes,
whichever order the two stylesheets are in. Its names all start with `dt-`.

| Hook                                  | Meaning                                                                                                                                         |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `#dt-stage`                           | The stage element. 1920 by 1080 CSS pixels, scaled to fit the window and centered. The runtime creates it if the page has none.                 |
| `#dt-camera`, `#dt-pan`               | Layers that the runtime adds inside the stage element. Each slide is a `.dt-slide` child of `#dt-pan`.                                          |
| `.dt-slide`, `.dt-enter`, `.dt-leave` | A slide, a slide that crossfades in, and a slide that leaves. The runtime removes a leaving slide after 400 ms.                                 |
| `.dt-reveal`, `.dt-shown`             | An element with `data-cue` or `data-delay`, and an element that has appeared.                                                                   |
| `.dt-word`                            | One word of a `data-text="spoken"` element. It gains `.dt-shown` when the voice says the word.                                                  |
| `.dt-push`                            | Set on `#dt-camera` during the camera push.                                                                                                     |
| `.dt-frozen`                          | Set on `<html>` in freeze mode. Every animation takes no time.                                                                                  |
| `#dt-hud`, `#dt-index`, `.dt-slides`  | The overlay and the index.                                                                                                                      |
| `#dt-style`                           | The runtime's own stylesheet, prepended to `<head>` so a page rule of equal weight wins on order.                                               |
| `--dt-xfade`                          | The crossfade length between two slides, which a page may set. The default is 0.35 s.                                                           |
| `--dt-scene-dur`                      | The camera push's length, which the runtime sets on `#dt-camera` for each played scene.                                                         |
| `#dt-measure`                         | The hidden layer `decktalk-probe.js` measures the catalog in, in index mode. It carries its own style and is removed before any frame is drawn. |

Note: A page can supply its own `#dt-stage`, as the lesson example's `deck/lesson.html` does. The runtime
adds `#dt-camera` after the page's content, so the slides draw on top of it.

Note: The first slide of a played scene is mounted before the clock starts, and it enters with no
animation. The recorder covers the page until narration t=0, so a first slide that mounted on the
clock, or faded in, would give the recording one frame of empty stage. Every later slide crossfades
over `--dt-xfade`.

## Warnings

The runtime lists each warning one time in `window.__decktalk.warnings`. The console prints it with
the prefix `decktalk: `. In the messages below, `<id>`, `<slide>`, and `<n>` stand for real values.

| Message                                                                                                   | Cause                                                                                                                                                            | Fix                                                                                                                                |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `unknown cue id <id> (no slide id or owns list matches it)`                                               | No slide of the playing scene owns a cue in `cues`, and no `DeckTalk.on` handler exists for it.                                                                  | Give the cue its slide's id as a prefix in `cues.json`, or name the id in that slide's `owns`.                                     |
| `no slide owns any listed cue, so nothing will mount`                                                     | No cue in `cues` has an owner. The recording shows an empty stage element.                                                                                       | Check that the section's `scene` names the scene whose slides own the cues.                                                        |
| `slide "<slide>" owns no cue in ?cues=, so it never appears`                                              | A slide of the playing scene owns none of the cues in `cues`.                                                                                                    | Add a cue for the slide to `cues.json`, or remove the slide.                                                                       |
| `cue "<id>" matches no element, handler, or slide`                                                        | A cue fired, but no `data-cue` element on the mounted slide, handler, or slide id matches it.                                                                    | Make the id the same in `cues.json`, the slide's `owns`, and `data-cue`.                                                           |
| `data-cue "<id>" is not in ?cues=, so it shows as soon as the slide mounts`                               | In cue mode, an element waits for a cue that `cues` does not list. The cue is missing from `cues.json`, or `--allow-unresolved-cues` left it out.                | Add the cue to `cues.json`, or fix its phrase.                                                                                     |
| `data-cue "<id>" is on an element that also sets data-delay, so the delay is ignored`                     | One element carries both triggers.                                                                                                                               | Keep `data-cue` for a reveal that waits for a word, and `data-delay` for one that does not.                                        |
| `scene "<id>" holds no &lt;template data-slide&gt; element`                                               | A `[data-scene]` wrapper declares a scene with no slides in it.                                                                                                  | Put one `<template data-slide="<id>.1">` inside the wrapper.                                                                       |
| `slide "<slide>" has both a render function and a &lt;template data-slide&gt;, so the template is unused` | A scene registered in script gives the slide a `render`, and a template names the same slide id.                                                                 | Delete one of the two.                                                                                                             |
| `data-text="spoken" on an element without data-cue or data-delay never reveals, so add data-delay="0"`    | An element has `data-text="spoken"`, `data-text="count"`, or `data-text="type"` but no trigger. The message names the attribute.                                 | Add `data-cue`, or add `data-delay="0"`.                                                                                           |
| `data-text="spoken" text not found in the spoken words: "…"`                                              | The element's text matches no run of the `words` list. The slide and the script usually differ by a word. The element appeared whole.                            | Make the text match the script, word for word.                                                                                     |
| `KaTeX did not load within 5 s, so [data-tex] elements stay plain text`                                   | The page needs KaTeX, and `window.katex` never appeared. `record` reports `KATEX NOT LOADED`, and `verify` reports it again.                                     | Make sure the page loads KaTeX before the runtime, as the starter's `deck/index.html` does.                                        |
| `data-tex could not be parsed: "…"`                                                                       | KaTeX showed a `data-tex` value in red. `record` reports `KATEX ERROR`.                                                                                          | Fix the TeX. Inside a `render` template literal, write every backslash twice, and inside a `<template data-slide>`, write it once. |
| `slide "<slide>" fires "<id>" at <n> s but holds <n> s, so it fires on the next slide`                    | In preview, a time in the slide's `preview` object is at or past its `hold`.                                                                                     | Raise `hold`, or lower the cue's seconds.                                                                                          |
| `cue "<id>" is not one of slide <slide>'s cues`                                                           | The `after` or `before` parameter names an id the frozen slide does not have. The whole slide freezes.                                                           | Fix the parameter, or add the id to the slide's markup.                                                                            |
| `scene "<id>" holds a &lt;template data-slide&gt; with no id, so it is ignored`                           | A `<template>` inside a `[data-scene]` wrapper has no `data-slide` value.                                                                                        | Give the template a slide id, as in `<template data-slide="3.1">`.                                                                 |
| `slide "<slide>" is declared in script, so its template's hold, owns and preview are ignored`             | A script registered the slide, and its `<template data-slide>` also sets `data-hold`, `data-owns` or `data-preview`. Only the markup is taken from the template. | Move those values into the `DeckTalk.scene` call, or drop them from the template.                                                  |
| `slide "<slide>" has a render function that threw: <error>`                                               | The slide's `render` raised. The slide mounts with whatever HTML was set before the throw.                                                                       | Fix the `render` function. Inside its template literal, write every backslash twice.                                               |
| `slide "<slide>" has an enter function that threw: <error>`                                               | The slide's `enter` raised after the slide was in the DOM.                                                                                                       | Fix the `enter` function.                                                                                                          |
| `cue "<id>" has a slide handler that threw: <error>`                                                      | The slide's own `on[id]` handler raised when the cue fired.                                                                                                      | Fix that handler.                                                                                                                  |
| `cue "<id>" has a handler that threw: <error>`                                                            | A handler registered with `DeckTalk.on(id, fn)` raised when the cue fired.                                                                                       | Fix that handler.                                                                                                                  |
| `a DeckTalk.waitFor promise rejected: <error>`                                                            | A promise the page handed to `DeckTalk.waitFor` rejected. Readiness treats it as settled.                                                                        | Fix the promise, or resolve it on failure.                                                                                         |
| `a DeckTalk.waitFor promise did not settle within 5 s`                                                    | A promise the page handed to `DeckTalk.waitFor` neither resolved nor rejected in five seconds. Readiness gives up and the page is drawn.                         | Settle the promise, or drop the wait.                                                                                              |

A slide's `render`, its `enter` and every cue handler are page callbacks, so what one of them throws
becomes a warning in the table above rather than an uncaught error. Nothing a page's own code does
reaches the console alone, because a recording log that says a page ran clean has to mean it. An
uncaught error outside those callbacks is still a page error, which the recorder logs and `record`
reports as `PAGE ERROR`.

## Related

* **Learn how a page plays:** [The page contract](/concepts/page-contract)
* **Size a slide and choose reveal effects:** [Design a slide](/guides/design-a-slide)
* **Write a page without the runtime:** [Write a page by hand](/guides/page-by-hand)


# script.md
Source: https://docs.decktalk.ai/reference/script-md

Look up the rules for DeckTalk's narration script, from section headings to pauses, placeholders, and length.

`script.md` holds the words that the voice says, split into numbered sections. This page lists
its heading rules, its stage directions, and how DeckTalk cleans the text before the voice
receives it.

```md script.md theme={null}
## 1. Open

[Scene 1. The title, then a card for each of the two files, then the promise.]

This is DeckTalk. [beat] You write what you will say, [beat] and you write the slides that go with it.
[beat] Then every picture waits for its own word.

## 2. How it works

[Scene 2. The heading, then the formula, then the same thing in code, then the closing line.]

Here is the average of a list of numbers. [beat] This is the formula, [beat] and this is the same
thing in code. [beat] Each one waited for the words I just said.
```

## Headings

A numbered heading starts a section. Any other heading ends it.

| Line                         | Effect                                                                                                                                                      |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `## N. Title`                | This starts section `N`. The title names the chapter and appears in the tables. A take is named by its content hash, so retitling a section voices nothing. |
| `## N. Title — 0:40 to 1:10` | This starts section `N` with a time budget. The dash can be an em dash, an en dash, or hyphens.                                                             |
| `## Title` with no number    | This ends the section, and the text after it is not spoken.                                                                                                 |
| `# Title`                    | This ends the section.                                                                                                                                      |
| `---` on its own line        | This ends the section.                                                                                                                                      |

Note: the times in a budget are `M:SS`. The budget's length is the `target` column of the narrate
table. A `###` heading inside a section does not end it. `narrate` removes the `###` marks and the
voice speaks the heading text.

The script and `decktalk.toml` must agree on section numbers.

* The script needs at least one numbered heading.
* Every numbered heading needs a `[[section]]` table with the same `number`. If one is missing,
  `narrate` fails with `script sections [N] have no [[section]] in decktalk.toml`.
* A page section needs a `## N.` heading. Without one, `record` skips the section and `assemble`
  fails.
* A clip section does not need a heading. `narrate` never voices a clip section, so its body can
  describe what plays.
* Text before the first numbered heading is never spoken. The starter keeps its notes there,
  above a `---` line.

## Directions and placeholders

Text in square brackets is not spoken.

| Text                                        | Spoken  | Effect                                                                                   |
| ------------------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `[Scene 1. The title, then the two cards.]` | no      | This is a stage direction on a line of its own, and it makes a beat.                     |
| `[beat]`                                    | no      | This makes a beat.                                                                       |
| `[pause 3]` or `[pause 2.5]`                | no      | This is a timed pause, and it sends `<break time="3s" />`.                               |
| `[NUMBER]`, `[CLIENT_NAME]`                 | refused | This is a placeholder. It matches `[A-Z][A-Z0-9_]*`, so it starts with a capital letter. |
| `<break time="1.0s" />`                     | no      | This is a break tag, and it is sent as written.                                          |

A direction splits the text at its place. A beat adds a dash to the text before it, and the voice
pauses at the dash. A timed pause adds a break tag instead. `[pause N]` is the only direction that
sends a break tag. [Writing for the ear](/guides/writing-for-the-ear) explains when to use each.

`narrate` refuses a section that still has a placeholder. Pass `--allow-placeholders` to voice it
anyway. `decktalk narrate --dry-run` lists every placeholder.

### What a script may not hold

A stage direction goes on a line of its own. Inside a paragraph only `[beat]`, `[pause N]`, a `[CAPS]`
placeholder, and a markdown link are bracketed text, and `narrate` refuses anything else in brackets,
because it would silently become a pause you never asked for. It also refuses an HTML comment and a brace,
because the voice reads both out. Each refusal names the line.

```text theme={null}
script.md has 2 thing(s) the voice must not receive:
  line 12: an HTML comment, which the voice reads out
  line 14: [maybe cut this] inside a paragraph, which becomes a pause nobody asked for
A stage direction goes on a line of its own. Inside a paragraph, write [beat] or [pause N] and nothing else.
```

### How directions combine

| Directions                          | Result                                                                                  |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| Before the first prose of a section | The direction is removed and makes no pause. Set `lead_seconds` on the section instead. |
| After the last prose of a section   | The direction is removed and makes no pause.                                            |
| Two or more in a row                | They make one pause, which is the longest of them.                                      |
| A beat next to `[pause N]`          | The timed pause wins.                                                                   |

### Silence that DeckTalk adds

Every spoken section opens on a lead of silence and closes on a tail of silence, so the silence across every
cut is one section's tail and then the next one's lead, and the picture always changes before the voice
speaks.

| Where                            | Key in `[narration]` | Default                       |
| -------------------------------- | -------------------- | ----------------------------- |
| Before each section's first word | `lead_seconds`       | 0.5                           |
| After each section's last word   | `min_tail_seconds`   | 0.7, and the starter sets 1.3 |

A page section in `decktalk.toml` can set its own.

| Where                           | Key in `[[section]]` | Default                    |
| ------------------------------- | -------------------- | -------------------------- |
| Before the section's first word | `lead_seconds`       | `[narration] lead_seconds` |
| After the section's last word   | `tail_seconds`       | `min_tail_seconds`         |

ffmpeg places this silence when it joins the takes into `narration.mp3`. The speech provider does not
receive it, and a take never holds it: each mp3 stays exactly as the voice returned it, which is what lets
one take serve whatever section number it ends up under. `narrate` measures where the sound of each take
ends, puts the lead before the take, and cuts or pads the take so that exactly the tail follows that sound,
whatever pause the voice left after its last word. The lead and the tail depend on the take and on the
section's own keys and on nothing else, so a section lands the same way whether this run voiced its take or
reused it, and an edit to one section never moves another.

Neither is part of the narration cache. If you change a lead or a tail, the next `narrate` places each
cached take again and sends no request. A silence that ends within 0.06 s or one mp3 frame of the end of
the file counts as running to the end, because the mp3 encoder adds up to 50 ms of padding there.
[Configuration](/reference/configuration) lists every `[narration]` key.

## Markdown stripping

`narrate` cleans the text of each section in this order.

1. `narrate` replaces a link `[text](url)` with its text.
2. `narrate` turns each direction into a pause mark.
3. `narrate` removes the markers of inline code, bold, and emphasis.
4. `narrate` removes heading marks, list bullets, and list numbers at the start of a line.
5. `narrate` joins the lines of a paragraph with single spaces. A blank line separates paragraphs.
6. `narrate` replaces each pause mark with a dash or a break tag at the end of the text before it.

The speech provider receives the text with its dashes and break tags. The spoken words have neither. Cue
matching and captions use the spoken words, so write each cue phrase with plain words.
`decktalk narrate --dry-run` prints the exact text for each section.

## Length

The narrate table and a build without voice estimate each section's length with these formulas.

```text theme={null}
est column            = words / words_per_minute * 60
silent section length = words / silent_words_per_minute * 60
                      + timed pause seconds
                      + beat_directions * silent_beat_seconds
section span          = lead + section length + tail
```

`words` is the number of spoken words. Timed pause seconds add up every `[pause N]` and every
written break tag. The lead is the section's `lead_seconds`, or `[narration] lead_seconds`, and the
tail is its `tail_seconds`, or `min_tail_seconds`. The defaults are 140 for `words_per_minute`, 150
for `silent_words_per_minute`, 0.7 for `silent_beat_seconds` and `min_tail_seconds`, and 0.5 for
`lead_seconds`.

Note: an em dash with a space before it counts as a beat, even when you type it in the prose. A
voiced section lasts for its lead, the audio that the speech provider returns up to where its sound
ends, and its tail.

## Numbers and symbols

Write numbers and symbols the way the voice should say them. Cue phrases in `cues.json` match
spoken words, so the script and the cue must use the same words. `narrate` reports a section whose spoken
words hold a digit or a symbol as `SPOKEN SYMBOL?`, an uncertain finding that names the first few
words it found. It is a note rather than a refusal, because "41" may be exactly what you want the
voice to try.

The starter writes "decktalk dot AI" in the script and shows decktalk.ai on the slide. A cue on
"decktalk dot AI" resolves. A cue on "decktalk.ai" matches nothing, because matching removes the
dot and leaves one token.

## Related

* **Plan a script by ear:** [Writing for the ear](/guides/writing-for-the-ear)
* **Map sections to pages:** [decktalk.toml](/reference/decktalk-toml)
* **Tie a reveal to a phrase:** [cues.json](/reference/cues-json)


# Verify
Source: https://docs.decktalk.ai/reference/verify

Look up how decktalk verify measures section starts, cuts, cut continuity, and cues, and what each result means.

`decktalk verify` is the one read-only checker after a build. It repeats what each recording log
judged, and then checks the final mp4 in three ways: section starts, cuts, and cues. A section that
sets `seamless` adds a fourth check, cut continuity. This page defines each measurement, limit, and
result, in the order that `verify` computes them, and lists
[every verdict](#every-verdict) with its cause and its fix.

```text theme={null}
check                 cue       at   chg %   ctl %   offset     a/v  result
1:1.1title           0.50     0.50    1.87    0.00    -20ms   -24ms  changed
2:2.1code            9.43    23.71   10.79    0.00    +10ms    -1ms  changed
3:3.1make            8.71    38.87   10.85    0.00    +10ms    -6ms  changed
```

Every field named on this page is a key under `[verify]` in [Configuration](/reference/configuration#verify),
unless the page names another table. The defaults assume 25 fps, so one frame lasts 40 ms.

## Which checks run

The verify stage inside `decktalk build` runs the same five checks as the command: the recordings,
the section starts, the cuts, cut continuity and every cue. It names no cue, so it checks every cue
in `cue-times.json` that `cues.json` does not opt out.

* With no cue named, `verify` checks every cue in `cue-times.json`, in section order and then cue time.
* With no cue named, `verify` skips a cue that `cues.json` marks `"verify": false`.
* Named cues run in the order given.
* A named cue runs even when `cues.json` marks it `"verify": false`.
* `--only N` keeps only the cues of section `N`, named cues included. A named cue outside `--only` gets no row.
* Section starts, cuts, and cut continuity are always checked, whatever `--only` names. `--only` does keep the recordings table to the sections it names.

A named cue has the form `SECTION:CUE`, such as `2:2.1formula`. `SECTION` is the section number and
not the scene number, and a section can play a scene with another number. A name that does not start
with a section number is an error (`malformed check`), and the command exits 1.

## Recordings

Each page section's recording log holds the verdicts `record` reached when it made the recording, and
`verify` reports them again, so a page that threw or an equation that was never typeset is still a
finding long after the build.

```text theme={null}
sec  recording
 01  ok
 02  ok
 03  ok
```

A row carries every verdict its recording log holds, and `ok` when it holds none. A section with no
recording log gets no row, and a clip section never has one. `verify` measures none of this. It
reads the log that `record` wrote and repeats the judgement, which is why a rebuild of one section
is the only thing that clears such a row.

## Section starts

The start check confirms that each section opens on a visible frame.

```text theme={null}
sec    start    probe   YAVG   YMAX  result
 01     0.00     0.20    235    242  ok
 02    14.28    14.48    235    242  ok
 03    30.16    30.36    235    240  ok
total 44.88s, 0 black section start(s)
```

A section's start is the total length of the `build/sections/NN.mp4` of every earlier section in `decktalk.toml`.
The check reads one frame after each start.

`verify` reads only the sections in `decktalk.toml`. A file that matches `sections/NN.mp4` but belongs to no section,
such as one left after you renumber sections, is ignored, and `verify` warns about it.

```text theme={null}
probe  = section start + after_dip_seconds                 # 0.2 s
BLACK  when  YMAX of the probe frame <= visible_ymax        # 60
```

* `YMAX` is the brightest luma in the frame, and `YAVG` is the average. A mid-gray slide with no pixel above 60
  reads `BLACK`.
* The probe sits 0.2 s after the start, whatever the dip length. The default `[transition] dip_seconds` of
  0.15 s rounds to 4 frames, 0.16 s. If you set a longer dip, raise `after_dip_seconds` too.
* A clip section has a row too. The starter has no clip section, so every row of the sample above is a page section.

## Cuts

The cut check confirms that the narration is quiet just before each cut.

```text theme={null}
sec   cut at  before cut  result
 01    14.29   -120.0 dB  quiet
 02    30.17   -120.0 dB  quiet
 03    43.35   -120.0 dB  quiet
```

`cut at` is where the section's narration ends in the final mp4. The check measures the narration track in the
window before it.

```text theme={null}
cut at         = section start + its span on the narration clock
window         = min(cut_window_seconds, section duration)            # 0.15 s
SPEECH AT CUT  when  RMS of narration.mp3 over the window > cut_max_db  # -40 dBFS
```

* The check reads `narration.mp3` alone. Music or a sound effect at a cut does not count.
* A level of exactly -40 dBFS passes.
* A clip section has no row, because it has no narration.
* A page section's `hold_seconds` comes after its `cut at`. In the sample, the starter's section `03`
  sets `hold_seconds = 1.5`, so it holds its last slide from 43.35 s to the end of the video.

## Cut continuity

The continuity check confirms that the cut into a section that sets `seamless = true` in
`decktalk.toml` does not show. It runs only for those sections.

```text theme={null}
sec   cut at   chg %  result
 02    14.28   27.60  POP AT CUT
 03    30.16   23.59  POP AT CUT
```

The starter's three scenes each open on a picture of their own, so setting `seamless` on sections 2
and 3 is a claim the pages do not keep, and the check says so. A section whose page really does open
on the previous section's last picture reads `ok` with a changed share near zero.

`cut at` is the section start in the final mp4. `chg %` is the [changed share](#changed-share) of two
frames at `diff_level`: the previous section's last frame before any dip, and this section's first
frame after any dip.

```text theme={null}
last frame   = the frame 1 frame before (cut at - the dip, when the previous section fades out)
first frame  = the frame at (cut at + the dip, when this section fades in)
POP AT CUT   when  changed share(last frame, first frame) > max_pop_percent        # 0.1
```

* The frames sit outside the dip, so a fade through black is never a pop. A dip still shows on screen, so leave
  the pair out of `[transition] dips` for a cut that should not show.
* The default of 0.1 matches `min_changed_percent`, so any change that would pass as a reveal is a pop.
* A section with no `sections/NN.mp4`, or whose previous section has none, gets no row.
* `POP AT CUT` is a certain finding, so `decktalk verify` and `decktalk build` exit 1 on it.

## Cues

The cue check confirms that the picture changes on each cue, at the cue time.

```text theme={null}
check                 cue       at   chg %   ctl %   offset     a/v  result
2:2.1code            9.43    23.71   10.79    0.00    +10ms    -1ms  changed
```

A voiced build prints the same columns and leaves `a/v` out, because its audio carries speech rather
than clicks.

Each column maps to one term. The terms below come in the order that `verify` computes them.

| Column   | JSON field          | Term                                                  | Unit                            |
| -------- | ------------------- | ----------------------------------------------------- | ------------------------------- |
| `check`  | `section`, `cue`    | the named cue                                         | none                            |
| `cue`    | `cue_seconds`       | [Cue time](#cue-time)                                 | seconds after the section start |
| `at`     | `final_seconds`     | the cue time in the final mp4                         | seconds                         |
| `chg %`  | `changed_percent`   | [Changed share](#changed-share) of the reported probe | percent                         |
| `ctl %`  | `control_percent`   | [Control share](#control-share) of the reported probe | percent                         |
| `offset` | `offset_ms`         | [Offset column](#onset-and-offset)                    | milliseconds                    |
| `a/v`    | `av_ms`             | [The a/v value](#the-a/v-value)                       | milliseconds                    |
| `result` | `verdict`, `reason` | [Results](#results)                                   | none                            |

Note: The table prints the `a/v` column only when at least one row has an a/v value. The JSON `silent` key
says whether the build was silent.

### Cue time

The cue time is the start of the cued word plus the offset key. It is rounded to hundredths, in seconds after
the section start.

```text theme={null}
cue time  = round(word start + offset key, 2)
at        = section start in the final mp4 + cue time
```

* `$start` has a word start of 0.0 s. `$end` has the end of the section's last spoken word.
* Each row of `build/cue-times.json` keeps its word start in `word_at`, without the offset key, also rounded to hundredths.
* A `$start` cue with a negative offset key keeps its negative cue time.

Example: section 2 starts at 14.28 s, and `2:2.1code` has a cue time of 9.43 s. Its `at` is 23.71 s.

### Changed share

The changed share of two frames is the percentage of pixels whose luma differs by more than a level.
`verify` scales both frames to `probe_width` by `probe_height` first, which is 480 by 270.

```text theme={null}
changed share(a, b, level) = 100 * (pixels where |luma of a - luma of b| > level) / (probe_width * probe_height)
```

* Every share is on a 0 to 100 scale. At 480 by 270, a share of 0.1 is about 130 pixels.
* The share compares luma only. A reveal that changes only color at the same brightness reads `NO CHANGE`.
  Mark such a cue `"verify": false` in `cues.json`.
* Probes and control shares use `diff_level` (40). The onset scan uses `onset_diff_level` (12). It also reads a
  block share at `block_width` by `block_height` (240 by 135). [Onset and offset](#onset-and-offset) says why.
* A pixel counts only when its difference is strictly greater than the level.

Example: the `chg %` of 10.79 for `2:2.1code` is about 13,990 of 129,600 pixels.

### Reference frame

The reference frame is the picture before the cue. Every probe is compared with it.

```text theme={null}
lead       = max(lead_seconds, (max_offset_frames + 1.5) / fps)    # max(0.1, 0.14) = 0.14 s
floor      = section start, plus the dip when the cut fades the section in
reference  = the first frame at or after max(floor, at - lead)
skipped REFERENCE_CLAMPED  when  max(floor, at - lead) > at - 1 / fps
```

* `[verify] reference_lead_seconds` has an effect only above (`max_offset_frames` + 1.5) / `fps`, which is 0.14 s at the
  defaults.
* `[verify] reference_lead_seconds` is not the recording log's `clock_start_seconds`. The recording log value is the recorder's wall-clock
  wait before narration t=0.
* The lead keeps every frame inside the offset limit after the reference, so an early reveal is not already in
  it. A reveal earlier than the reference frame usually reads `NO CHANGE`.
* With `[transition] page_fades_in = true`, the default, the cut adds no fade-in to a page section. The floor of
  a page section is then its first frame.
* A clip section gets the dip when a dip comes before it. So does a page section when `page_fades_in` is false.
* A row is `REFERENCE_CLAMPED` when its cue time is under 0.04 s with no fade-in, or under 0.20 s with the
  default fade-in. A named cue is still skipped.
* The reference time is at least one frame before the cue. The reference frame can be closer when the cue time
  is off the frame grid.

Example: for `2:2.1code`, the reference time is 23.71 - 0.14 = 23.57 s. The reference frame is the
next frame on the 40 ms grid, at 23.60 s. That frame is 110 ms before the cue.

### Probes

A probe is the frame a fixed delay after the cue. `verify` takes one probe for each delay in `probe_delays`.

```text theme={null}
probe(d)  = at + d                       for each d in probe_delays    # 0.7 s and 1.5 s
dropped   when  probe(d) > section end - 0.05
```

* The section end is the next section's start in the final mp4, or the video length for the last section.
* The later probe catches a slow reveal.
* The row is `TOO_CLOSE_TO_END` only when every probe is dropped. At the defaults, that is a cue less than
  0.75 s before the section end.

### Control share

The control share measures motion that has nothing to do with the cue. Each probe gets its own control share.

<Frame>
  <img alt="A time axis around cue 8:7.1checked. A dashed line marks the reference time, 0.14 s before the cue. Bars run from it to probes 0.7 s and 1.3 s after the cue, which changed 0.83% and 0.83%. The 0.7 s probe is marked reported. Its two back-to-back control spans of 0.84 s run back from the reference, and each changed 0.00%." />

  <img alt="A time axis around cue 8:7.1checked. A dashed line marks the reference time, 0.14 s before the cue. Bars run from it to probes 0.7 s and 1.3 s after the cue, which changed 0.83% and 0.83%. The 0.7 s probe is marked reported. Its two back-to-back control spans of 0.84 s run back from the reference, and each changed 0.00%." />
</Frame>

```text theme={null}
span     = probe(d) - reference time
control  = min(changed share(reference - 2 * span, reference - span),
               changed share(reference - span, reference))              # at diff_level
```

* Each span compares only its first and its last frame.
* A span that starts before the floor is dropped. If both spans are dropped, the control share is 0.
* Steady motion, such as a camera push, shows in both spans. An earlier reveal that is still finishing shows in
  only one, so the smaller share leaves it out.

### Close cues

A cue close to another cue gets probes that fit the gap between them. Otherwise the other cue's reveal would
count as this cue's change, or as motion in every control span.

```text theme={null}
neighbor       = another cue of the section, more than the reference lead from this cue   # 0.14 s
window         = the neighbor's cue time, plus or minus the reference lead
spoiled probe  when  a window overlaps the span from the reference to the probe,
               or    a window overlaps every control span that is measured
fitted probe   = the longest delay below the probe's delay that is not spoiled,
                 at least (max_offset_frames + 1) / fps                              # 0.12 s
```

* A probe that is not spoiled is used as it is. A cue whose probes are all unspoiled is measured exactly as
  the sections above describe.
* A fitted probe has shorter control spans, because each span still lasts as long as the probe's span.
* Two probes fitted to the same delay count once. The probes are then taken in order of delay.
* If no probe can be fitted, `verify` uses `probe_delays` as they are.
* A cue within the reference lead of another is part of the same reveal, so it is not a neighbor.
* Every cue of the section in `cue-times.json` can be a neighbor, including a cue that the run does not check.
* `verify` logs `another cue is close, so the probes are fitted to <delays> s after the cue` for each such cue.

Example: a count reveals a box on each of four cues, at 4.42, 5.11, 5.62, and 6.18 s. The last cue's reference
time is 6.04 s. Its 0.7 s probe has control spans from 5.20 to 6.04 s and from 4.36 to 5.20 s. The 5.62 s window
overlaps the first span, and the 4.42 s window overlaps the second, so the probe is spoiled. The probe is
fitted to 0.14 s. Its first control span, from 5.76 to 6.04 s, clears the 5.62 s window, which ends at 5.76 s.

### Change test

The change test decides whether the picture changed because of the cue.

```text theme={null}
margin(d)       = changed share(d) - control share(d)
reported probe  = the probe with the largest margin, the earlier probe on a tie
passes when     changed share >= min_changed_percent  and  margin >= min_margin_percent   # 0.1 and 0.1
thin when       changed share < thin_change_factor * min_changed_percent                  # 3 * 0.1
                or  margin < thin_change_factor * min_margin_percent                      # 3 * 0.1
```

* If the reported probe fails the change test, the row is `NO CHANGE`.
* A row that passes by a thin change reads `THIN CHANGE?` instead of `changed`. The change is thin when the
  changed share is below `thin_change_factor` times `min_changed_percent`, or the margin is below
  `thin_change_factor` times `min_margin_percent`. At the default factor of 3, both limits are 0.3.
* `THIN CHANGE?` is an uncertain finding. The cue passed, but a slightly smaller reveal or a little more motion
  would fail it. `verify` exits 1 on it only with `--strict`. Set `thin_change_factor` to 1 to turn it off.
* The `chg %` and `ctl %` columns show the reported probe, which is not always the probe that changed most.
* `min_changed_percent` applies to the raw changed share. A camera push raises that share too.

Example: `2:2.1code` has a changed share of 10.79 and a control share of 0.00. Its margin is 10.79, so
it passes, and the change is not thin. The next cue, `2.1waited`, fires 1.88 s later, so both probes
clear it and `verify` reports the probe with the larger margin.

### Onset and offset

After a cue passes the change test, `verify` finds its onset, the first frame of the reveal.

1. `verify` measures the changed share of each frame from the reference frame up to the reported probe. It
   compares each frame with the reference frame, at `onset_diff_level`. It also measures a block share of each
   frame, the same comparison with both frames scaled to `block_width` by `block_height` (240 by 135).
2. The onset is the first frame after the reference whose share rises by at least `onset_percent` over the
   frame before it, and whose block share is above 0.
3. If no frame rises that much, the onset is the first frame after the reference whose share is above a
   threshold, and whose block share is above 0.
4. If no frame is above the threshold, the row has no onset.

<Frame>
  <img alt="Seven frames 40 ms apart around cue 8:7.1checked. The first is the reference frame, 110 ms before the cue. The frames at 70 and 30 ms before the cue changed 0.00%. The frame 10 ms after the cue changed 1.24% and is outlined as the onset. A shaded band spans 80 ms on each side of the cue." />

  <img alt="Seven frames 40 ms apart around cue 8:7.1checked. The first is the reference frame, 110 ms before the cue. The frames at 70 and 30 ms before the cue changed 0.00%. The frame 10 ms after the cue changed 1.24% and is outlined as the onset. A shaded band spans 80 ms on each side of the cue." />
</Frame>

The figure carries the numbers of the cue it draws. Its shares use `onset_diff_level` (12), which is
why its onset frame reads a larger share than the `chg %` column of the same cue: the change test
uses `diff_level` (40), at the probe 0.7 s after the cue.

```text theme={null}
series[0]      = 0                                                   # the reference frame itself
series[i]      = changed share(reference frame, frame i, onset_diff_level)
blocks[i]      = the same share, with both frames scaled to block_width by block_height
onset          = first i >= 1 with series[i] - series[i-1] >= onset_percent and blocks[i] > 0   # 0.01
threshold      = max(onset_percent, largest series[i] at or before at - (max_offset_frames + 0.5) / fps)
fallback onset = first i >= 1 with series[i] > threshold and blocks[i] > 0
offset column  = round(1000 * (onset time - at))                    # whole ms, negative means early
```

* A rise is in percentage points of share. At 480 by 270, 0.01 points is about 13 pixels.
* At 240 by 135, each pixel averages an 8 by 8 block of a 1080p frame, the size of an H.264 transform block.
  The x264 encoder leaves a little ringing on a still picture in the one or two frames before a change: a few
  pixels, up to about 15 luma levels apart at 480 by 270. Alone, that ringing read as a reveal 40 to 100 ms
  before it happened, while the recording showed the reveal on time. Ringing is as much lighter as darker, so
  it cancels over a block and leaves the block share at 0. A reveal changes whole blocks, so its first frame
  has a block share above 0.
* A reveal changes the picture in one jump. Steady motion, such as a camera push or a line that was already drawing
  before the reference, grows a little every frame. That motion does not count as an onset, but it can change
  frames before the onset.
* The onset threshold is far below `min_changed_percent` on purpose. A fade starts on its cue but takes many
  frames to change 0.1 percent of the pixels.
* The fallback catches a reveal that grows slowly, such as text that types in. At the defaults, its window ends
  100 ms before the cue.
* The onset can come before the cue time.
* A cue with no onset reads `changed`. Its offset column shows `-`, its `a/v` is blank, and neither limit
  applies. No `NO_CLICK` reason is set.

Example: `2:2.1code` has an offset column of +10 ms, so its onset frame is at 23.72 s.

### The a/v value

After a build without voice, `verify` also compares the picture with the sound in the final mp4. The click track of a
build without voice has a click at every word start, and one where the section's last word ends.

```text theme={null}
click           = the loudest sample within click_search_seconds of the word start, inside the cue's section
click found     when  |sample| >= 400 of 32768                      # about -38 dBFS
click distance  = round(1000 * (click time - word start))
a/v             = offset column - click distance
                = (onset - click) - offset key                     # milliseconds
```

* The word start comes from the row's `word_at`, so the offset key does not add to `a/v`. An `a/v` of 0 means
  the picture changes one offset key after the click.
* The offset column compares the picture with the cue time in `cue-times.json`. The `a/v` value compares the
  picture with the audio in the final file.
* An `a/v` near 0 shows that these steps kept sound and picture together: the recording, the trim at narration
  t=0, the cut, the join, and the mix.
* The search window never reaches past the cue's own section, so the audio of a clip next to it is never the
  click.
* A sound effect or music that is louder than the click inside the window becomes the click. A
  `decktalk build --no-voice --no-soundscape` leaves them out of the mix.
* The clicks stay at -24 dBFS, because a build without voice skips the [loudness pass](/concepts/sound#loudness).
* If no sample reaches the level, the row gets the reason `NO_CLICK`, and its `a/v` is blank. The row keeps its
  offset result.
* `NO_CLICK` is usual for a `$end` cue whose last word is longer than `click_search_seconds`. `$end` anchors on
  the end of the last word, and clicks sit on word starts. A shorter last word gives an `a/v` that is off by the
  word's length.
* A voiced build has no `a/v`. Its JSON `silent` is `false`, and every `av_ms` is `null`.

Example: `2:2.1code` has an offset column of +10 ms and an `a/v` of -1 ms, so its click distance is
+11 ms.

### Limits

Two limits turn a measured row into `OFF CUE`. Both apply to early and late values.

```text theme={null}
offset limit  = 1000 * max_offset_frames / fps     # 80 ms
a/v limit     = 1000 * max_av_frames / fps         # 120 ms
OFF CUE  when  |offset column| > offset limit + 0.5,  or  |a/v| > a/v limit + 0.5
```

* The a/v limit is one frame wider, because the click carries encoding jitter too.
* The table prints only the result. Compare the offset column with the offset limit and `a/v` with the a/v
  limit to see which one failed.
* A slower machine can put a reveal two or three frames late. [Build in CI and offline](/guides/ci-and-offline)
  shows how to widen the limits on one runner.

This example shows the format of an `OFF CUE` row.

```text theme={null}
check                 cue       at   chg %   ctl %   offset     a/v  result
2:2.1formula         5.81    20.09    1.86    0.00    -90ms  -101ms  OFF CUE
```

This row is `OFF CUE` because its offset column, -90 ms, is past the 80 ms offset limit. Its `a/v` of
-101 ms is inside the 120 ms a/v limit. The offset key moved the cue time 0.14 s later than the
reveal the page already recorded, which is what a cue phrase on the wrong word looks like.

## Results

Each cue row gets its result from the first rule that matches.

1. If the run names no cue and `cues.json` marks the cue `"verify": false`, the row is `skipped` with the reason
   `OPTED_OUT`.
2. If a named cue is not in `cue-times.json`, the row is `UNRESOLVED`.
3. If the section has no `sections/NN.mp4`, the row is `skipped` with the reason `SECTION_NOT_ASSEMBLED`.
4. If no reference frame fits, the row is `skipped` with the reason `REFERENCE_CLAMPED`.
5. If every probe is dropped, the row is `skipped` with the reason `TOO_CLOSE_TO_END`. A cue close to another
   cue gets [fitted probes](#close-cues) first.
6. If the reported probe fails the change test, the row is `NO CHANGE`.
7. If the scan finds no onset, the row is `changed`, with `-` in the offset column and no `a/v`. A thin change
   reads `THIN CHANGE?` instead.
8. If the offset column is past the offset limit, the row is `OFF CUE`.
9. After a build without voice, if no click is found, the row gets the reason `NO_CLICK` and keeps the result of rule 8.
10. After a build without voice, if the `a/v` is past the a/v limit, the row is `OFF CUE`.
11. Otherwise, the row is `changed`, or `THIN CHANGE?` when the change is thin.

## Every verdict

This is every verdict `decktalk verify` can print, with what makes it and what to do about it. A
certain verdict exits 1 on its own. An uncertain verdict ends in a question mark and exits 1 only
with `--strict`. A passing verdict is never a finding. Match a verdict by its code, which is the
`code` field of the JSON object, and never by its label.

| Verdict            | Code               | Kind      | Table                     | Cause                                                                                                               | Fix                                                                                                                                                                 |
| ------------------ | ------------------ | --------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAGE ERROR`       | `PAGE_ERROR`       | certain   | recordings                | The page threw an uncaught error while it recorded, or it never exposed the runtime catalog.                        | Open the page in a browser and fix the error. [Warnings](/reference/runtime#warnings) lists what the runtime reports on its own.                                    |
| `STALLED`          | `STALLED`          | certain   | recordings                | Page frames froze for longer than `[record] stall_ms` after narration t=0.                                          | Make the slide cheaper to draw, or do the slow work before t=0, where the cover hides it.                                                                           |
| `TRUNCATED`        | `TRUNCATED`        | certain   | recordings                | The recording is shorter than the length `record` asked for, by more than `[record] truncated_slack_seconds`.       | Record the section again. A repeat usually means the machine could not keep up.                                                                                     |
| `NO COVER`         | `NO_COVER`         | certain   | recordings                | `record` found no magenta cover, so narration t=0 is an estimate and every reveal in the section moves with it.     | Record the section again. A page that paints late can raise `[record] cover_scan_seconds`.                                                                          |
| `KATEX ERROR`      | `KATEX_ERROR`      | certain   | recordings                | KaTeX refused a `data-tex` value, so the slide shows red source.                                                    | Fix the TeX. Inside a `render` template literal, write every backslash twice.                                                                                       |
| `KATEX NOT LOADED` | `KATEX_NOT_LOADED` | certain   | recordings                | The page asked for KaTeX and it never arrived, so the source stayed plain.                                          | Load KaTeX before the runtime, from the `deck/katex/` directory `decktalk init` wrote.                                                                              |
| `BLACK?`           | `BLACK_UNSURE`     | uncertain | recordings                | The brightest luma of the recording's middle frame is below `[record] black_ymax`.                                  | Look at the section. A dark slide on purpose needs no change.                                                                                                       |
| `BLACK`            | `BLACK`            | certain   | starts                    | The brightest luma of the frame `after_dip_seconds` into the section is at most `[verify] visible_ymax`.            | Give the section's first slide something visible at its start, or raise `after_dip_seconds` past a longer dip.                                                      |
| `SPEECH AT CUT`    | `SPEECH_AT_CUT`    | certain   | cuts                      | The narration is louder than `[verify] cut_max_db` in the `cut_window_seconds` before the cut.                      | Raise the section's `tail_seconds`, or end the section on a shorter last word.                                                                                      |
| `POP AT CUT`       | `POP_AT_CUT`       | certain   | seams                     | A section sets `seamless = true`, and the two frames across its cut differ by more than `[verify] max_pop_percent`. | Make the page open on the previous section's last picture, or drop `seamless`.                                                                                      |
| `OFF CUE`          | `OFF_CUE`          | certain   | cues                      | The offset column is past the offset limit, or the `a/v` value is past the a/v limit.                               | Check the cue phrase against the spoken words. A whole run that is late is a slow machine, and [Build in CI and offline](/guides/ci-and-offline) widens the limits. |
| `NO CHANGE`        | `NO_CHANGE`        | certain   | cues                      | The reported probe failed the change test, so nothing measurable happened at the cue.                               | Make the reveal larger, or mark the cue `"verify": false` and check it by eye. A reveal that changes only color at the same brightness always reads this way.       |
| `THIN CHANGE?`     | `THIN_CHANGE`      | uncertain | cues                      | The cue passed the change test by less than `thin_change_factor` times a floor.                                     | Make the reveal larger, or set `thin_change_factor` to 1 to turn the warning off.                                                                                   |
| `UNRESOLVED`       | `UNRESOLVED`       | certain   | cues                      | A named cue is not in `build/cue-times.json`.                                                                       | Run `decktalk align`, or fix the cue phrase that never matched.                                                                                                     |
| `changed`          | `CHANGED`          | passing   | cues                      | The picture changed on the cue, inside both limits.                                                                 | Nothing to do.                                                                                                                                                      |
| `quiet`            | `QUIET`            | passing   | cuts                      | The narration is quiet before the cut.                                                                              | Nothing to do.                                                                                                                                                      |
| `ok`               | `OK`               | passing   | recordings, starts, seams | The row was measured and nothing is wrong.                                                                          | Nothing to do.                                                                                                                                                      |
| `skipped`          | `SKIPPED`          | passing   | cues                      | The row measured nothing, and its `reason` says why.                                                                | [Skipped rows](#skipped-rows) gives each reason.                                                                                                                    |

`decktalk verify` exits 1 on any certain verdict above, and on an uncertain one with `--strict`. A
`skipped` row never fails. [Exit codes](/reference/cli#exit-codes) lists the codes for every command.

## Skipped rows

A skipped row measured nothing. The table prints `skipped`, the reason, and a short note.

| Reason                  | Cause                                                                                             | Fix                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `OPTED_OUT`             | `cues.json` marks the cue `"verify": false`, and the run named no cue.                            | Name the cue, such as `decktalk verify 2:2.1formula`, to measure it anyway. |
| `SECTION_NOT_ASSEMBLED` | The section has no `build/sections/NN.mp4`.                                                       | Run `decktalk assemble`.                                                    |
| `REFERENCE_CLAMPED`     | No reference frame fits between the floor and one frame before the cue. Usual for a `$start` cue. | Check the reveal by eye with `decktalk screenshots --slide ID --after CUE`. |
| `TOO_CLOSE_TO_END`      | Every probe falls later than 0.05 s before the section end.                                       | Check the reveal by eye with `decktalk screenshots --slide ID --after CUE`. |

Note: `NO_CLICK` is a reason on a measured row, not a skipped row. [The a/v value](#the-a/v-value) explains it.

A reveal that is too small or too slow for a frame difference, such as a thin arrow, can fail the change test.
Mark such a cue `"verify": false`, and check it by eye with `decktalk screenshots --slide ID --after CUE`.

## JSON fields

`decktalk verify --json` prints one JSON object on stdout. The measurements are under the `verify` key.

```json theme={null}
    "cues": [
      {
        "section": 2,
        "cue": "2.1formula",
        "where": "build/out/my-lesson.mp4",
        "cue_seconds": 5.81,
        "final_seconds": 20.09,
        "changed_percent": 1.86,
        "control_percent": 0.0,
        "offset_ms": -90,
        "av_ms": -101,
        "verdict": {
          "code": "OFF_CUE",
          "label": "OFF CUE",
          "certain": true
        },
        "reason": null,
        "detail": "the reveal at cue '2.1formula' first changed -90 ms from its cue, outside the 80 ms limit."
      }
    ]
```

| Field                                    | Type    | Meaning                                                                                                                                                                |
| ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `command`                                | string  | Always `"verify"`.                                                                                                                                                     |
| `version`                                | string  | The installed DeckTalk version.                                                                                                                                        |
| `ok`                                     | boolean | True when the command found nothing and raised nothing. It ignores `--exit-zero`.                                                                                      |
| `findings.certain`, `findings.uncertain` | integer | Counts of certain and uncertain findings.                                                                                                                              |
| `verify.final`                           | string  | Path of the final mp4, relative to the project.                                                                                                                        |
| `verify.total_seconds`                   | number  | Length of the video, the sum of the `sections/NN.mp4` of every section in `decktalk.toml`.                                                                             |
| `verify.silent`                          | boolean | True after a build without voice. Only then can `av_ms` hold a value.                                                                                                  |
| `verify.recordings[]`                    | array   | One object per recorded page section, with `key`, `where`, which is its recording log, `t0_method`, `verdicts`, which is a list of verdict objects, and `page_errors`. |
| `verify.starts[]`                        | array   | One object per section start, with `key`, `start`, `probe_at`, `yavg`, `ymax`, and `verdict`.                                                                          |
| `verify.cuts[]`                          | array   | One object per cut, with `key`, `cut_at`, `rms_db`, and `verdict`.                                                                                                     |
| `verify.seams[]`                         | array   | One object per section that sets `seamless`, with `key`, `cut_at`, `last_at`, `first_at`, `changed_percent`, and `verdict`, whose code is `OK` or `POP_AT_CUT`.        |
| `verify.cues[]`                          | array   | One object per cue row, with the fields of the next table.                                                                                                             |

| Cue field         | Type            | Meaning                                                                                                                                                      |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `section`         | integer         | Section number.                                                                                                                                              |
| `cue`             | string          | Cue id.                                                                                                                                                      |
| `where`           | string          | The finished film the row was measured in, relative to the project.                                                                                          |
| `cue_seconds`     | number or null  | Cue time, in seconds after the section start.                                                                                                                |
| `final_seconds`   | number or null  | Cue time in the final mp4.                                                                                                                                   |
| `changed_percent` | number or null  | Changed share of the reported probe.                                                                                                                         |
| `control_percent` | number or null  | Control share of the reported probe.                                                                                                                         |
| `offset_ms`       | integer or null | Offset column. Null when the row has no onset.                                                                                                               |
| `av_ms`           | integer or null | `a/v` value. Null after a voiced build, with no onset, or with `NO_CLICK`.                                                                                   |
| `verdict`         | object          | `{code, label, certain}`. The code is `CHANGED`, `THIN_CHANGE`, `OFF_CUE`, `NO_CHANGE`, `UNRESOLVED` or `SKIPPED`. Match on the code and never on the label. |
| `reason`          | string or null  | The skip reason, or `NO_CLICK` on a measured row.                                                                                                            |
| `detail`          | string or null  | One sentence that says what the row found, with the measured number in it. Null on a row that passed.                                                        |

Note: Seconds are rounded to three decimals, and shares to two. A skipped row has null measurements. Every row of `starts[]`, `cuts[]` and `seams[]` carries `where` and `detail` too.

## Related

* **Run the command and read its options:** [CLI](/reference/cli#decktalk-verify)
* **Fix a failed check:** [Troubleshooting](/help/troubleshooting)
* **Change a limit:** [Configuration](/reference/configuration#verify)


# What leaves your machine
Source: https://docs.decktalk.ai/reference/what-leaves-your-machine

Every host DeckTalk contacts, what each request carries, and how to build with no network at all.

This page is the whole list. DeckTalk contacts the hosts below and no others, and it sends no
telemetry, no usage report and no crash report anywhere. A host that is not named on this page is a
host DeckTalk does not contact.

Hand this page to a reviewer who has to approve DeckTalk on a managed machine. The two facts that
decide most reviews are that a cloud speech service receives your script, and that the first run
downloads a browser and a media tool.

## Requests that carry your content

These requests carry text from your project. Every one of them is made only by a command you run on
purpose, and every one of them needs an API key that you supply.

| Host              | Request                    | Sent by                                                  | What DeckTalk sends                                                                                                                                                                                                                                                                                                                                  |
| ----------------- | -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api.elevenlabs.io | Narration                  | `decktalk narrate`, and `decktalk build` on a voiced run | The section's spoken text, the voice id, the model name and the audio format, together with up to `context_chars` characters of the previous section and up to `context_chars` of the next section as speaking context. The default for `context_chars` is 1500 characters, and `context_chars = 0` keeps the neighbouring sections on your machine. |
| api.elevenlabs.io | Sound effects and ambience | `decktalk soundscape`                                    | The prompt string written in a `[soundscape.ambience]` or `[soundscape.sfx.<name>]` table, the length you asked for and the audio format. No part of `script.md` is sent.                                                                                                                                                                            |
| api.elevenlabs.io | Music                      | `decktalk soundscape`                                    | The prompt string written in the `[soundscape.music]` table, the length you asked for and the audio format. No part of `script.md` is sent.                                                                                                                                                                                                          |

**Narration to `api.elevenlabs.io`.** The request carries the value of `ELEVENLABS_API_KEY` in a header. Rebuilding one section still sends that section's neighbours, because the voice reads them for intonation. A run with `--no-voice` sends nothing at all.

**Sound effects and ambience to `api.elevenlabs.io`.** The request carries the value of `ELEVENLABS_API_KEY` in a header. The prompt is text you wrote in `decktalk.toml`, so you decide what it describes.

**Music to `api.elevenlabs.io`.** The request carries the value of `ELEVENLABS_API_KEY` in a header. The music file is generated once and then reused from `build/`.

### Reading a request before you make it

`decktalk narrate --dry-run --json` plans a voiced run with no API key and no request. It reports
the sections it would voice, their character counts and the host, so a reviewer can read exactly
what would be sent before anything is sent. `decktalk build` stops at the same point and names the
host and the character count before it spends a credit.

Set `context_chars = 0` under `[elevenlabs]` when the neighbouring sections must stay on the
machine. Each section is then sent on its own, with no surrounding text.

## One-time downloads

`decktalk install` fetches the tools a recording needs, once per machine. These requests carry
nothing from your project, and after they succeed a build without voice needs no network at all.

| Host                   | What it holds                              | Fetched by         | What DeckTalk sends                                                  |
| ---------------------- | ------------------------------------------ | ------------------ | -------------------------------------------------------------------- |
| cdn.playwright.dev     | Headless Chromium                          | `decktalk install` | A download request for the pinned browser build, and nothing else.   |
| github.com             | ffmpeg and ffprobe on Linux and on Windows | `decktalk install` | A download request for one pinned release archive, and nothing else. |
| evermeet.cx            | ffmpeg and ffprobe on an Intel Mac         | `decktalk install` | A download request for two pinned archives, and nothing else.        |
| ffmpeg.martin-riedl.de | ffmpeg and ffprobe on an Apple silicon Mac | `decktalk install` | A download request for two pinned archives, and nothing else.        |

**`cdn.playwright.dev`.** This is Playwright's own download host. `PLAYWRIGHT_DOWNLOAD_HOST` points it at a mirror, and `[record] browser_path` skips the download by recording with a browser the machine already has.

**`github.com`.** GitHub answers a release download with a redirect to its asset host, so a proxy rule needs both. The archive is checked against a pinned SHA-256 digest and discarded when the digest does not match.

**`evermeet.cx`.** The archives are checked against pinned SHA-256 digests and discarded when a digest does not match.

**`ffmpeg.martin-riedl.de`.** The archives are checked against pinned SHA-256 digests and discarded when a digest does not match.

## What never leaves

DeckTalk has no telemetry. It reports no usage, no errors and no project contents to its authors,
and it has no update check. Nothing about a build is sent anywhere unless a command in the first
table above sends it.

No DeckTalk environment variable has its value printed, logged or placed in a request body. The one
exception is `DECKTALK_ALLOW_ANY_API_BASE`, which is a switch and never a secret. An error message
that quotes a reply from a service has every credential in it replaced before the quote is cut to
length.

KaTeX ships inside the wheel, so an equation needs no download and no content delivery network.

## The agent is a second service

The six DeckTalk skills run inside your coding agent. When you ask an agent to write a script,
place cues or fix a finding, the agent puts your `script.md`, your `decktalk.toml`, your `cues.json`
and the JSON that DeckTalk prints in front of whatever model that agent runs. That model is a cloud
service of its own, under its vendor's terms and not under DeckTalk's, and a policy review that
covers the speech service should cover it too. Running DeckTalk from the command line alone contacts
no model.

## On a managed machine

A laptop with an intercepting proxy, no administrator rights and a policy review needs four things,
and none of them is a DeckTalk feature you have to wait for.

* **Build with no voice and no key.** `decktalk build --no-voice` writes placeholder narration and
  makes a complete video. It contacts no service, so you can show a finished internal video before
  any approval comes back.
* **Use the browser the machine already has.** Set `[record] browser_path` in `decktalk.toml`, or
  point `PLAYWRIGHT_BROWSERS_PATH` at a location your administrators have already filled. The
  pinned build is the reference, and a managed browser is supported and unverified.
* **Use the ffmpeg the machine already has.** `DECKTALK_FFMPEG` and `DECKTALK_FFPROBE` name
  executables directly, and a build that finds them downloads nothing from the second table.
* **Ask the proxy to leave the local origin alone.** Pages record over a virtual origin on the
  loopback address, so the proxy rules need a bypass for it. `decktalk serve` binds to the loopback
  address and takes `--host` and `--port`.

[Requirements and costs](/requirements) has the full managed-machine section, with the package index
mirror, `PLAYWRIGHT_BROWSERS_PATH`, `DECKTALK_FFMPEG` and `DECKTALK_CACHE_DIR`.

`decktalk doctor` reports what is installed and which browser and media build a run would use,
without fetching anything, and `decktalk doctor --report` prints a redacted block you can paste into
a ticket.


# Requirements and costs
Source: https://docs.decktalk.ai/requirements

What DeckTalk needs, what install downloads, and which commands spend ElevenLabs credits.

This page lists what DeckTalk needs, what `decktalk install` downloads, and which commands spend ElevenLabs credits. Read it before you set up a new machine or a CI runner, and before your first voiced build.

## Software

DeckTalk needs Python 3.12 or later. It runs on Linux, macOS, and Windows.

* DeckTalk has one Python dependency, Playwright. Your installer adds it.
* Playwright includes its own browser driver, so you do not need Node.
* `decktalk install` downloads Chromium and ffmpeg. KaTeX ships inside the wheel, and you install nothing else by hand.

The [quickstart](/quickstart) installs DeckTalk with uv, pipx, or pip.

## Accounts

A build without voice needs no account and no API key. A voiced build needs two values from ElevenLabs.

| Variable              | Value               | Needed by                                                 |
| --------------------- | ------------------- | --------------------------------------------------------- |
| `ELEVENLABS_API_KEY`  | your API key        | a voiced build, `decktalk narrate`, `decktalk soundscape` |
| `ELEVENLABS_VOICE_ID` | the id of the voice | a voiced build, `decktalk narrate`                        |

Put both values in `.env` in the project directory, or set them in the environment. A value that starts with `<`, such as `<your-elevenlabs-key>`, counts as unset. [Part 3 of the quickstart](/quickstart#part-3-add-your-voice-and-change-a-sentence) shows where the values go.

## What spends credits

Only two parts of DeckTalk call ElevenLabs. The `narrate` stage calls the text-to-speech endpoint, and `decktalk soundscape` calls the sound effects and music endpoints.

| Command or change                                          | When it spends credits                                                                                                                             |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `decktalk build` without `--no-voice`                      | It voices each section whose text, title, or voice changed since the last voiced build. It voices every section when the narration cache is empty. |
| `decktalk narrate` without `--no-voice`                    | It voices the same sections as a build. `--only` limits it to the sections you name.                                                               |
| `--force` on `build` or `narrate`                          | It voices every section again, even if nothing changed.                                                                                            |
| A new voice id, model, output format, or `[voice]` setting | The next voiced build voices every section again, because the cache key includes all of them.                                                      |
| `decktalk soundscape`                                      | It generates each part whose request changed or whose file is missing. `--force` generates every part again.                                       |

A voiced section costs the characters of its whole text. An edit therefore costs every changed section in full, not only the changed sentences. A ten-minute narration is about 9,000 characters.

A build without voice stops when the project has voiced takes. With `--force`, it empties the narration cache, so the next voiced build voices every section again. [A build without voice and a voiced build](/guides/rebuild-one-section#a-build-without-voice-and-a-voiced-build) explains the cache.

To see a run before it spends credits, use `--dry-run` or `preflight`. None of these commands calls the API:

* `decktalk narrate --dry-run` prints the text of each section, and which sections a voiced run would voice, with their characters.
* `decktalk preflight` prints the same plan, resolves every cue, and estimates each reveal from frozen frames.
* `decktalk soundscape --dry-run` prints every request.

These commands never spend credits: a build without voice, `install`, `init`, `doctor`, `preflight`, `align`, `record`, `assemble`, `verify`, `screenshots`, `words`, `clip`, `serve`, and `status`.

### ElevenLabs plans

Every ElevenLabs plan can call the API, including the free plan. The free plan has three limits for a video you publish:

* It has no commercial license.
* The title of published content must include "elevenlabs.io" or "11.ai".
* It cannot use Voice Library voices through the API.

For a video you publish, start with the Starter plan.

## What install downloads

`decktalk install` makes two downloads, one time per machine. `decktalk doctor` then reports on each download.

| Download           | How `install` gets it                                                                                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chromium           | `install` runs `playwright install chromium`.                                                                                                                                     |
| ffmpeg and ffprobe | `install` downloads one pinned GPL build, checks each archive against the SHA-256 DeckTalk records for it, and unpacks it into `ffmpeg/<version>-<platform>` in DeckTalk's cache. |

KaTeX is not downloaded. The pinned release ships inside the wheel, and `decktalk init` copies it into
`deck/katex/`, so a project typesets its equations with no network and no CDN tag.

| Cache      | Linux                                                | macOS                            | Windows                        |
| ---------- | ---------------------------------------------------- | -------------------------------- | ------------------------------ |
| Playwright | `~/.cache/ms-playwright`                             | `~/Library/Caches/ms-playwright` | `%LOCALAPPDATA%\ms-playwright` |
| DeckTalk   | `$XDG_CACHE_HOME/decktalk`, else `~/.cache/decktalk` | `~/Library/Caches/decktalk`      | `%LOCALAPPDATA%\decktalk`      |

To move DeckTalk's cache, set `DECKTALK_CACHE_DIR`.

### Linux system libraries

On Linux, `install` passes `--with-deps` to Playwright, and Playwright installs Chromium's system libraries with apt-get.

1. Playwright runs apt-get through sudo.
2. If sudo is missing, it uses `su root -c`.
3. If `install` runs as root, it uses neither.

If the distribution has no apt-get, this download fails. `install` then stops before it downloads ffmpeg.

### If a download is missing

* **The wheel's KaTeX copy is incomplete.** `doctor` prints `MISSING` in the `katex` row and names each absent file. Reinstall DeckTalk.
* **`install` never ran.** DeckTalk downloads the pinned build the first time it needs ffmpeg.
* **DeckTalk pins no build for your platform, or the download cannot run.** DeckTalk uses the ffmpeg on your PATH. A download whose digest does not match is discarded and never falls back.

`DECKTALK_FFMPEG` and `DECKTALK_FFPROBE` override every ffmpeg source above.

## Install on a managed machine

A machine with no admin rights, an index mirror, or an intercepting proxy can still record. Five settings cover the cases that come up, and none of them needs a change to the project.

| What the machine blocks                         | What to set                                                                                                                                                                                                      |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The package index                               | Point your installer at your mirror, the way uv, pipx, or pip already does it. DeckTalk needs one runtime dependency, Playwright.                                                                                |
| The Chromium download host                      | Set `PLAYWRIGHT_DOWNLOAD_HOST` to your mirror before `decktalk install`, as Playwright documents.                                                                                                                |
| A shared browser directory, or a read-only home | Set `PLAYWRIGHT_BROWSERS_PATH` to a directory you can write. Playwright reads it on the download and on every launch, so set it in both places.                                                                  |
| The ffmpeg download                             | Put an approved `ffmpeg` and `ffprobe` on the machine and name them in `DECKTALK_FFMPEG` and `DECKTALK_FFPROBE`. Those two override every other ffmpeg source, so `install` reports them and downloads no build. |
| A write to the default cache                    | Set `DECKTALK_CACHE_DIR` to a directory you can write. Everything DeckTalk downloads goes under it.                                                                                                              |

If the machine already has an approved Chrome or Chromium, record with it instead of the downloaded build. Name its executable in `[record] browser_path`.

```toml decktalk.toml theme={null}
[record]
browser_path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
```

The pinned Playwright build is the reference build, and DeckTalk's timing limits are measured against it. A browser of your own is supported and unverified, so check a first video's reveals with `decktalk verify` before you trust the limits.

A proxy needs no rule of its own. `record`, `screenshots`, and `preflight` open every page at `http://project.localhost/` and answer each request from your project directory through Playwright's request routing, which runs before the network stack. No proxy ever sees that host, and every other request a recorded page makes goes the way the machine sends it. `decktalk serve` binds 127.0.0.1 and picks a free port, and `--host` and `--port` move it.

`decktalk doctor` prints the Chromium revision and the ffmpeg build a run would use, so the machine's owner can read what a recording will launch before it runs.

## Time

Recording runs in real time, one section after another. A first build without voice of the starter took about 64 seconds on a MacBook Pro with Apple M5 Pro and 64 GB memory. The video it made is 44.88 seconds long, so most of the time is the recording and the encode.

A slower machine takes longer. [Rebuild one section](/guides/rebuild-one-section) shows how to record only the sections that changed.

## The ffmpeg license

The ffmpeg builds that `install` downloads are GPL builds. DeckTalk runs ffmpeg as a separate process and does not link against it. [THIRD\_PARTY\_NOTICES.md](https://github.com/jacobcbeaudin/decktalk/blob/main/THIRD_PARTY_NOTICES.md) lists the license of each build.

To use an ffmpeg build of your own, set `DECKTALK_FFMPEG` and `DECKTALK_FFPROBE` to its two executables.

## Next

* **Install and build your first video:** [Quickstart](/quickstart)
* **Build in CI or with no network:** [Build in CI and offline](/guides/ci-and-offline)
* **Understand the costs of an edit:** [Rebuild one section](/guides/rebuild-one-section)


# Lessons
Source: https://docs.decktalk.ai/use-cases/lessons

Teach an idea where each part appears as it is spoken, with equations typeset on the page and nothing read ahead.

A viewer follows an explanation in which each idea appears as it is spoken, so nothing is read
ahead.

A lesson fails when the slide says everything at once. The room reads the whole slide, finishes
before the teacher does, and stops listening. DeckTalk holds each part of a diagram back until the
voice reaches the word for it, so attention has nowhere else to go.

## What a viewer gets

* One idea at a time, in the order the explanation needs, because a reveal waits for its word.
* Equations typeset on the page from a `data-tex` attribute, drawn as the voice says them and never
  spelled out as symbols.
* A sentence that appears word by word under the voice, through `data-text="spoken"`, when the
  wording itself is the point.
* Chapters a learner can jump between, a transcript page to read afterwards, and captions for a
  viewer who needs them.

## What the author writes

| File            | What it holds                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `script.md`     | The explanation, one heading per section, with a time budget that keeps a section to one idea. |
| `decktalk.toml` | The sections and their chapter names, which default to the script headings.                    |
| `cues.json`     | The phrase each part of the diagram waits for.                                                 |
| The deck page   | The diagram, the equations and the chapter cards.                                              |

KaTeX ships inside the wheel, so an equation needs no download and no content delivery network. A
diagram is plain HTML and CSS with `data-cue` and `data-reveal` attributes on the parts that appear,
and `data-describe` gives each of those parts one sentence that the transcript prints.

## The workflow

<Steps>
  <Step title="Start a lesson project">
    `decktalk init --example lesson` writes a worked lesson with an equation, which is the fastest
    way to see the shape of one.
  </Step>

  <Step title="Write the explanation, then the diagram">
    Say the thing, then draw the thing. Every reveal needs a word in `script.md` that names it,
    which is what [Writing for the ear](/guides/writing-for-the-ear) is about.
  </Step>

  <Step title="Build it without voice">
    `decktalk build --no-voice` paces the whole lesson with placeholder narration, so the timing is
    settled before a credit is spent.
  </Step>

  <Step title="Check every landing">
    `decktalk verify` reports each reveal that came late, early or not at all, and
    `decktalk screenshots` writes a PNG per slide so the text contrast and the crowding can be read.
  </Step>

  <Step title="Reteach one section">
    A better sentence is an edit and `decktalk build --only 2`. The rest of the lesson keeps its
    takes.
  </Step>
</Steps>

Read [Quickstart](/quickstart) for the first build, [Design a slide](/guides/design-a-slide) for the
reveal effects and the camera, and [Accessible video](/guides/accessible-video) for the captions,
the chapters and the transcript a course platform asks for.

The other two use cases with worked examples are
[technical tutorials](/use-cases/technical-tutorials) and [product demos](/use-cases/product-demos).


# Product demos
Source: https://docs.decktalk.ai/use-cases/product-demos

Narrate a feature over the screen it runs on, and rebuild the one section a product change touched.

A viewer sees the feature narrated over the screen it runs on, with every callout landing on the
word that names it.

A demo ages faster than anything else a company publishes, because the product moves every week. In
DeckTalk the demo is text and code, so a renamed button is a one-line edit and a rebuild of the
section that shows it. Nothing else is recorded again, and nothing else is voiced again.

## What a viewer gets

* Each callout, arrow and highlight appears on the word that names it, so the eye is never hunting
  for what the voice is talking about.
* Real product footage, because a section can be a screen recording rather than a page.
* A cut with no dead air, because DeckTalk cuts the video to the narration and not the other way
  round.
* Captions, chapters and a transcript page, which a demo needs on a site where most viewers watch
  with the sound off.

## What the author writes

| File            | What it holds                                                                              |
| --------------- | ------------------------------------------------------------------------------------------ |
| `script.md`     | The pitch, one heading per section, with a time budget that keeps the whole demo short.    |
| `decktalk.toml` | The sections, the voice and the `clip` value on any section that plays a screen recording. |
| `cues.json`     | The phrase each callout starts on.                                                         |
| The deck page   | The title cards, the callouts and the closing card.                                        |

A screen recording enters the video as a clip section. The section names its file in
`decktalk.toml`, and `decktalk clip` cuts a span of a built section and its narration into a clip
file and its words file. A sound effect lands on a cue through a `[[mix.sfx]]` entry, and the music
bed comes from the `[soundscape.music]` table.

## The workflow

<Steps>
  <Step title="Write the pitch first">
    Write `script.md` before the slides, because the words decide the cuts. Keep each section to its
    budget and read it aloud once.
  </Step>

  <Step title="Build it without voice">
    `decktalk build --no-voice` gives a complete video with placeholder narration, which is enough
    to judge the pacing before anyone spends a credit.
  </Step>

  <Step title="Drop the product footage in">
    Add a clip section for each screen recording, then run `decktalk verify` to see every seam
    between a page section and a clip section.
  </Step>

  <Step title="Voice it and check the landings">
    `decktalk preflight` freezes every reveal and estimates the run, then a voiced build writes the
    takes. `decktalk verify` reports every cue that did not land on its word.
  </Step>

  <Step title="Rebuild the section the product change touched">
    Edit the sentence or the callout, then run `decktalk build --only 3`. Every other section keeps
    its take and its recording.
  </Step>
</Steps>

Read [Quickstart](/quickstart) for the first build, [Add a clip section](/guides/clip-section) for
screen recordings, and [Put a sound effect on a cue](/guides/sfx-on-a-cue) for the accents a demo
lives on.

The other two use cases with worked examples are
[technical tutorials](/use-cases/technical-tutorials) and [lessons](/use-cases/lessons).


# Technical tutorials
Source: https://docs.decktalk.ai/use-cases/technical-tutorials

Keep a narrated walkthrough correct when the library it teaches changes, by editing text and rebuilding one section.

A viewer watches a walkthrough whose commands and screenshots match the version she just installed.

This is the use case DeckTalk is built around. A tutorial goes stale the week the API it teaches
changes, and re-recording it costs a day, so most authors stop making them. In DeckTalk the whole
video is text and code, so a change to the library is a change to a few lines, and only the sections
whose words changed are voiced again.

## What a viewer gets

* Every reveal starts on the word that names it, so a command appears as the voice says it and
  nothing is read ahead.
* The commands and the screenshots on screen are the ones the project rendered on the day it was
  built, not the ones an author remembered while recording.
* Captions, chapters and a transcript page 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 screen recording instead of a page, cut and
  mixed with the same narration.

## What the author writes

Four files hold the whole tutorial.

| File            | What it holds                                                                         |
| --------------- | ------------------------------------------------------------------------------------- |
| `script.md`     | One heading per section and the words the voice says, with a time budget per section. |
| `decktalk.toml` | The project, the voice, the sections and their pages.                                 |
| `cues.json`     | One entry per cue, naming the phrase the reveal starts on.                            |
| The deck page   | The slides, as HTML with `data-slide`, `data-cue` and `data-reveal` attributes.       |

A code slide is markup. An equation is a `data-tex` attribute typeset by the KaTeX files the wheel
carries. A screenshot is a file the page loads, and `decktalk screenshots` writes one PNG per slide
so the author can read what the recorder will see.

## The workflow

<Steps>
  <Step title="Start a tutorial project">
    `decktalk init --example tutorial` writes the four files, the runtime and the skills. Add
    `--no-skills` to leave the skills out.
  </Step>

  <Step title="Build it without voice">
    `decktalk build --no-voice` runs the five stages, which are `narrate`, `align`, `record`,
    `assemble` and `verify`. It writes placeholder narration, so it spends nothing and needs no key.
  </Step>

  <Step title="Place the cues">
    `decktalk align` resolves each cue phrase to a second on its section clock, and `decktalk verify`
    reports every reveal that landed late, early or not at all.
  </Step>

  <Step title="Plan the spend, then voice it">
    `decktalk preflight` freezes every reveal and estimates the takes without spending a credit, and
    `decktalk narrate --dry-run` prints the characters and the dollars a voiced run would cost.
  </Step>

  <Step title="Rebuild one section when the library changes">
    Edit the sentence, the slide or the cue, then run `decktalk build --only 4`. A section whose
    words did not change keeps its take, so it is never voiced twice.
  </Step>
</Steps>

Read [Quickstart](/quickstart) for the first build, [Your first deck](/guides/first-deck) for one
section written end to end, and [Slide recipes](/guides/slide-recipes) for the slides a tutorial
needs most.

## 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 downloads a browser and a media tool.
[What leaves your machine](/reference/what-leaves-your-machine) names every host and every request
body, and [Requirements and costs](/requirements) covers the package index mirror, the browser path
and the cache directory that a managed machine needs. A build with `--no-voice` contacts no service
at all, so a finished video can exist before any approval does.

## Also fits

Internal presentations, estimation and interview prep run the same pipeline, and none of them has a
shipped example yet. The two use cases with worked examples beside this one are
[product demos](/use-cases/product-demos) and [lessons](/use-cases/lessons).