> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decktalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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