The project and the script
| Word | Meaning | Not | Explained in |
|---|---|---|---|
| project | One directory holding script.md, decktalk.toml, cues.json, the deck pages and the build/ directory those four produce. | decktalk.toml | |
| section | One ## N. heading of the script and the [[section]] table that pairs it with a scene, a program that draws it or a clip. | segment | decktalk.toml |
| render section | A section whose picture a program draws, which render_command names. It is narrated like a page section and names no page and no scene. | Things that move | |
| motion document | build/recordings/render/NN/motion.json, the frame rate, the size, the length, every spoken word and every cue’s second that record hands a render section’s program. | Things that move | |
| section key | The two-digit "01" that names a section’s files and its rows in cues.json. | cues.json | |
| chapter | The title a section shows in the chapter markers, the transcript and a slate. | decktalk.toml | |
| script | script.md, which the voice reads once it is cleaned into spoken text. | script.md | |
| direction | A bracketed instruction the voice does not speak, such as [beat], [pause 2] or [voice guest]. | stage direction | script.md |
| unfinished text | An unfilled blank such as [NUMBER], or other text a voice would read out or swallow, which check reports as SCRIPT_UNFINISHED. It is never called a placeholder, because a placeholder is a take. | script.md |
The page and the cues
| Word | Meaning | Not | Explained in |
|---|---|---|---|
| deck page | An HTML file under deck/ that a page section records. | The page contract | |
| scene | One [data-scene] wrapper in a deck page, holding the slides a section plays. | The page contract | |
| slide | One <template data-slide> inside a scene, which the runtime clones when the slide mounts. A deck page is never called a slide. | The page contract | |
| preview seconds | How long the preview rests on a slide, which data-preview-seconds writes. No recording reads it. | data-hold | The page contract |
| freeze | One slide drawn with its cues already fired and nothing in motion, which ?freeze=ID asks the page for. | ?slide | The runtime |
| container | An element whose children carry moments, so one cue can stagger them or a spotlight can walk them. | The page contract | |
| moment | One of the four things an element does, which are data-in, data-back, data-front and data-out. A moment is never an event, a cue name or a time. | The page contract | |
| motion | Something an element does for longer than a moment, from the cue it departs on to the cue it arrives on, declared with data-motion or DeckTalk.motion. Its length is the seconds between the two cues and is never written on the page. | The page contract | |
| ease | How a motion moves between its two cues: firm, glide, settle or spring. | Things that move | |
| firm arrival | An arrival that keeps a little speed into its last frame, so it stops on a frame edge verify can measure. firm and glide arrive firm. | Things that move | |
| ease to rest | An arrival that slows to nothing, which settle and spring make. It has no edge to measure, so its cue must be marked "verify": false. | Things that move | |
| loop | An element that turns through its @keyframes for as long as its slide is on screen, declared with data-loop. It names no cue. | Things that move | |
| frame hook | A function DeckTalk.frame calls on every frame with the section second, which draws something from that second alone. | The runtime | |
| region | The element a frame hook draws inside, which DeckTalk.frame names in region and verify masks. | Things that move | |
| composition page | A deck page that draws its whole picture itself, in a canvas, WebGL or three.js, from a frame hook and the runtime’s cues and words. It plays in an ordinary page section. | Things that move | |
| lane | One declared motion, loop or region as the recorder saw it: the box it swept, its size, when it moved and the cues it lands on. Verify masks a lane out of every cue and measures a motion’s landings on it. | The page contract | |
| landing | One cue a motion lands on, either its departure, depart, or its arrival, arrive. | Verify | |
| cue name | The name a moment attribute writes, such as expand, which means something inside its own slide alone. | local name | The page contract |
| cue id | The slide id, a colon and the cue name. data-in="expand" inside <template data-slide="4.1"> is the cue id 4.1:expand. | wire id | Cues |
| cue | One row of cues.json, pairing a cue id with the phrase its moment waits for. | cues.json | |
| phrase | The spoken words a cue lands on, which its row writes in phrase, or $start or $end. | cues.json | |
| description | The text an author writes in data-describe and its kin, which the transcript is written from. It is never called a phrase. | The page contract | |
| cue time | The second a cue lands on, counted on its section clock. | Cues | |
| section clock | The seconds since a section starts, which its words, its cues and its page all run on. | narration clock | Cues |
| stepped clock | The section clock as the recorder moves it, one frame at a time, so frame k of a recording is the page at second k / fps. | The recorder steps the clock | |
| chunk | A range of one page section’s frames that one recorder records in a page of its own, into a lossless file that starts on a keyframe. record splits a long section into chunks so several recorders share it, and joins the files into the section’s recording without an encode. | Requirements and costs | |
| film clock | The seconds since the film starts, which verify reports on. | Verify | |
| canvas | The surface the runtime draws on, which is #dt-canvas on the page: the shape of the frame [video] size names, with a short side of 1080 CSS pixels, so 1920 by 1080 for a wide project. | #dt-stage, stage pixels | The runtime |
| runtime | decktalk-runtime.js, the page’s script, which the engine serves beside every deck. The recorder reads it through window.__decktalkProbe. | __dtprobe | The runtime |
The six stages
They run in this order, and each is both a command and a call on aProject.
| Word | Meaning | Not | Explained in |
|---|---|---|---|
| narrate | The stage that turns the script into one take per turn and its words. It writes a voiced take into the takes directory, a placeholder into build/narrate/, and the take index build/narrate/takes.json. | How it works | |
| cue | The stage that turns each cue phrase into a second on its section clock. It writes build/cue-times.json. | Cues | |
| record | The stage that records each page section in headless Chromium against those seconds. It writes build/recordings/. | How it works | |
| score | The music, the ambience bed and the effects beside the narration, and the stage that composes them. It keeps what it buys in the score directory and joins the music under build/score/. | soundscape | Sound |
| assemble | The stage that cuts, mixes and encodes the sections into one film. It writes build/final/. | How it works | |
| verify | The stage that measures the finished film against the clock the earlier stages promised. It writes no artifact, only its events file and the build lock. | Verify | |
| build | The command that runs the stages in order, or a span of them. A rebuild is always incremental. | CLI | |
| force | --force, which builds every cache again from nothing and never spends. | Rebuild one section |
A run and what it reports
| Word | Meaning | Not | Explained in |
|---|---|---|---|
| run | One call that opens work, named by a run id that every result and every event carries. | The JSON contract | |
| event | One JSON line of build/events/<run>.jsonl, saying what happened while the run was going. --events prints the same lines on stderr. | The JSON contract | |
| result | The one object a command prints with --json, and a call returns in Python. | The JSON contract | |
| outcome | How a stage, a section or one take ended in a run. A stage or a section ran, was kept, skipped, stopped or failed. A take was voiced, kept or a placeholder, and a score item was planned, kept or generated. | take status, sound status | The JSON contract |
| status | The command that reads the project off disk and says what to run next, and the result and rows it prints. It never names what a run did. | CLI | |
| finding | One judgement DeckTalk made about the project, carrying a code, a sentence, a severity, a place and often a fix. | CLI | |
| severity | Whether a finding fails the default run: an error does, and a warning is reported and passes. --fail-on names the threshold a run fails at. | certainty | The JSON contract |
| fix | A change a finding carries that would resolve it, which edits a file, changes a setting or runs a command. A fix shown and never applied is a suggestion. | The JSON contract | |
| elapsed seconds | How long a call took, as wall time on a result or a *.done event. | The JSON contract | |
| seconds | How long a piece of media runs. | Build artifacts | |
| machine | This computer and this process, which hold the toolchain, the machine file and the API key. | Python API | |
| host | An application that runs DeckTalk as a library. | Python API | |
| stability promise | What build/ and --json promise a caller: the results, the events, build/final/ and the exit codes. | The stability promise |
The voice and the takes
| Word | Meaning | Not | Explained in |
|---|---|---|---|
| provider | The service that makes a voice’s takes, which that voice’s provider names: elevenlabs or dtsp. One film may mix providers. | Requirements and costs | |
| voice | One [voices.NAME] table of decktalk.toml: a provider, its voice id, a speed and any of that provider’s voice settings, under the name the script calls it by. | speaker, utterance | decktalk.toml |
| voice name | The name a voice is written under, such as guest in [voices.guest], which a voice direction and DECKTALK_VOICES_GUEST_ID both spell. It is never part of a take’s digest, so renaming a voice voices nothing. | decktalk.toml | |
| voice id | The provider’s own name for a voice, which its id key holds. It is a published name rather than a secret. | Requirements and costs | |
| default voice | The voice [narration] voice names, which reads every section no voice direction names. | script.md | |
| voice direction | A line holding only [voice NAME], which hands the turns after it to that voice until the next one or the next section. | script.md | |
| turn | The stretch of one section that one voice reads, from one voice direction to the next. A section one voice reads is one turn. A turn is never called a line, which is a line of a file. | script.md | |
| voice in force | What one voice resolves to on this machine: its provider, voice id, model, settings, and what that provider declares about its output and its bill. Every take’s digest and every price is read from the voice in force of its turn. | Requirements and costs | |
| API key | The secret a provider that bills needs. doctor reports one row per shipped provider that needs one under api_keys, each set or missing. | voice key | Requirements and costs |
| take | One turn’s spoken audio, named by its digest. Two turns with the same text and the same voice in force share one take. | Build artifacts | |
| voiced take | A take a provider spoke, whether that provider bills or is free. | paid take, bought take | Rebuild one section |
| rejected take | A voiced take that narrate --turn, --take or --replace-voiced bought again, set aside with its words file in the takes directory’s rejected/ folder as <digest>.<n>, counting from 1. Moving the pair back under its digest plays it again. | re-roll | Rebuild one section |
| placeholder | A take made with no provider: click audio sized from the script’s pace, which a run that does not spend plays where a take is missing. | silent take, click track, build without voice | How it works |
| take index | build/narrate/takes.json, every take row and the narration track’s layout. It is a cache, rebuilt from the takes on disk. | Build artifacts | |
| takes directory | The folder inside the project that holds every take the film plays and its words, takes/ unless [narration] takes_dir names another. You commit it, so a clone builds the film with no key. | Rebuild one section | |
| take store | The folder outside every project where this machine keeps a second copy of every voiced take it makes, which [narration] store_dir names. A take missing from the takes directory is checked and copied in from here, and nothing plays from it directly. | Rebuild one section | |
| take state | What the disk holds for one turn, judged against its current text and voice in force: voiced, unchecked, stale, placeholder or missing, each with the clause that says why. A section reports the worst of its turns. decktalk status prints each section’s, and decktalk --json status carries every turn’s under turns too. | Rebuild one section | |
| stale | Made from inputs that have changed since. A stale take is a voiced take of this turn still held under an older text, voice, model or voice settings, which a voiced run would replace. A recording, a section video and a score item go stale the same way. | outdated | Rebuild one section |
| unchecked | The take state of a voiced take of a turn’s text when its voice has no voice id, so it cannot be matched until [voices.NAME] id or DECKTALK_VOICES_<NAME>_ID names one. A run keeps it and never buys it again on a guess. | unmatched | Rebuild one section |
| missing | The take state of a turn with nothing it could play held. A TAKE_MISSING finding is wider: it is raised for every section that plays a placeholder for want of a voiced take of its current inputs. | Rebuild one section | |
| digest | A take’s name. For a voiced take it is the first 16 hex digits of a sha256 over everything that changes the take. | input hash | Build artifacts |
| words | Every spoken word of a take with its start and its end on the take’s own clock, kept in a words file beside the take, or in takes/aligned/ when an aligner timed them. A stage reads them on the section clock, which adds the section’s lead. | word clock | Build artifacts |
| provider words | The words a provider sent back with a voiced take. They are a paid record, because only voicing the take again gives them back. | voiced words, bought words | Build artifacts |
| estimated words | The words DeckTalk timed from the script’s pace, for a placeholder or for a take no aligner could time. They cost nothing to make again. | placeholder words | Build artifacts |
| aligner | What times the words of a take whose voice sent none, from its audio and the script’s words. DeckTalk ships one, the local server [dtsp] base_url names. | Providers | |
| aligned words | The words an aligner measured in a take, kept in takes/aligned/ under a key of the take and the aligner. They cost nothing to make again. | Build artifacts | |
| clip words | The words of one clip, cut from its section’s words, or the words file beside a clip section’s clip as <clip>.words.json, each word with the voice and the turn that say it when the file names them. A built film writes its own as <name>.words.json. | Play a clip |
Money and records
| Word | Meaning | Not | Explained in |
|---|---|---|---|
| spend | Whether a run may buy from a provider that bills: --spend/--no-spend, and spend in Python and in the JSON. A free provider needs no spend. | spending | Requirements and costs |
| cost | What a run costs or would cost, carried as cost with its state, its dollars, its ceiling and its rate in US dollars. It pairs with --max-cost, and holds one row per stage that buys, in cost.stages. | credits | Requirements and costs |
| cost state | Whether a cost is an estimate or was charged. | Requirements and costs | |
| billing | How a provider charges: per character, per second, free, undeclared or mixed. | Requirements and costs | |
| buy | To pay a provider for a take or a sound. A *.charged event is written for each bill that is not free. | purchase | The JSON contract |
| paid record | A file only remaking can replace, which is refused with a sentence when it does not read and is never rebuilt or deleted. Remaking it costs money on a provider that bills. | The stability promise | |
| cache | A file DeckTalk rebuilds for free. Everything under build/ is a cache except what the stability promise names. | The stability promise | |
| ledger | score/ledger.json, every request the score stage has bought. | Sound |
Sound and film
| Word | Meaning | Not | Explained in |
|---|---|---|---|
| score item | One named sound in [score]: the music, an ambience bed or an effect. | Sound | |
| sound effect | An effect item placed on a cue by [[mix.effect]]. The runtime uses “effect” alone for motion. | Put a sound effect on a cue | |
| score directory | The folder inside the project that holds every sound the score bought and the ledger, each named by its item, score/ unless [score] dir names another. You commit it, so a clone mixes the film with no key. | Sound | |
| section video | One section encoded to its own span, build/sections/NN.mp4, which assemble joins into the film. | Build artifacts | |
| film | The finished mp4, build/final/<name>.mp4. | Build artifacts | |
| captioned copy | The film with its captions drawn into the picture by the page, build/final/<name>-captioned.mp4, which [output] captioned asks for. | Accessible video | |
| clip | A video file with its own audio, which a clip section plays full frame: one of your own, a film DeckTalk built, or the file decktalk clip cuts out of a built section. | Play a clip | |
| slate | The titled frame a missing clip plays. | placeholder frame | Play a clip |
| cut | The boundary where one section ends and the next starts. | Verify | |
| seam | A cut a seamless section claims shows nothing. | Verify | |
| placement | A section as placed in the film, which is one row of build/final/placements.json. | Build artifacts | |
| still | A slide frozen at a cue. | CLI | |
| storyboard | The page at build/storyboard.html that freezes every slide at every cue, which is the checkpoint a person reads before anything is bought. | CLI |
The settings
| Word | Meaning | Not | Explained in |
|---|---|---|---|
| setting | One published value with a default, a safe range, a unit and a hazard, addressed by its dotted key, which decktalk config explain prints whole. | knob, tunable | Configuration |
| number | A published value config explain shows and nobody sets, with the formula or the fact that fixes it. | Configuration | |
| layer | One of the places a setting’s value can come from. A project key is set by its default, decktalk.toml, its environment variable and --set, and a machine key by its default, the machine file, its variable and --set, each over the ones before it. | Configuration | |
| provenance | What every layer said about every key, which is where a value in force is traced from. | Configuration | |
| scope | Which file a write lands in, project or machine, which config set --scope names. | Configuration | |
| machine file | machine.toml, the per-machine settings file. | Configuration |
Related
- Look up a command: CLI
- Look up a setting: Configuration
- The whole contract on one page: Reference card