CLI - DeckTalk

The decktalk command runs one stage, the whole pipeline, or one reading of the project or the machine. Every command prints one flat JSON object with --json, carrying its own fields beside schema, ok, findings and error, and the two declared fields run and written on the commands that open a run or write a file.

Global options

These work with every command, before the command name or after the whole command, as in decktalk --json status or decktalk config list --json. --version is the one exception, and it works before a command name alone.

Option	Meaning
`-p`, `--project` `DIR`	The project directory. Default: DECKTALK_PROJECT, else the current directory.
`--json`	Print one JSON object on stdout and nothing else there.
`--events`	Print one JSON line per progress event on stderr.
`--color` `WHEN`	auto, always or never. Default: auto.
`--no-input`	Never prompt. Take the safe default, or refuse and name the flag that would have answered.
`-v`, `--verbose`	Debug lines on stderr, and the traceback of a bug.
`-q`, `--quiet`	Warnings and errors only on stderr.
`--version`	Print the version and exit.

Exit codes

Exit	Meaning
0	The command ran and found nothing at or above the threshold —fail-on set.
1	The command ran and found something at or above the threshold —fail-on set.
2	The command line was refused, which is USAGE or APPROVAL.
3	The command could not run, which is every other error code.
130	The caller stopped the run.

Error codes

An error means DeckTalk could not run or did not finish. A result that carries an error beside its own fields is a run that stopped after it made something, and its cost and findings say what it made. A finding is the other thing entirely, which is a judgement about a film that did get made.

Code	Exit	Meaning
`INPUT`	3	An input is missing, unreadable or malformed.
`NOT_BUILT`	3	A file a stage needs was never built.
`PROVIDER`	3	A provider could not be reached, refused the request, or failed it.
`TOOL`	3	A tool DeckTalk runs is missing or failed: ffmpeg, Chromium, a page that stopped answering or ran past its deadline, a program the project names, a fix install runs, the preview server’s address, or the mix of a strict assemble that missed its loudness.
`LOCKED`	3	Another writer holds this project’s build directory.
`APPROVAL`	2	A step was not approved, by a flag or by a person at a terminal: a spend, a spend —max-cost refuses or cannot price, an init into a directory that holds files, a password install asks for, or an untrusted page in a run that may spend.
`CANCELLED`	130	The caller stopped the run.
`USAGE`	2	The command line was refused, and a retry as written fails again.
`INTERNAL`	3	A bug in DeckTalk, with a traceback under -v.

Finding codes

A finding carries its code, its sentence, its severity and often a fix an agent can apply. --allow CODE carries on past one, and --fail-on decides which of them fails a run.

Code	Severity	Meaning
`PAGE_ATTR_UNKNOWN`	error	An element carries a data attribute the contract does not declare, so nothing reads it.
`PAGE_BAD_VALUE`	error	An attribute’s value is outside the range the contract publishes for it.
`PAGE_MOMENT_UNKNOWN`	error	An element outside every slide template names a moment, so no slide owns its cue and it never plays.
`PAGE_MOMENT_ORDER`	error	An element’s exit is declared at or before its own entrance, so the exit never plays.
`PAGE_CUE_UNKNOWN`	error	A cue fired that no reveal, no handler and no slide in the deck declares, so nothing answered it.
`PAGE_NO_OWNER`	error	A cue the scene plays is owned by none of its slides, so nothing is mounted for it.
`PAGE_SCENE_EMPTY`	error	A scene holds no slide template, so its section has no slide to show.
`PAGE_SLIDE_NO_ID`	error	A slide template carries no id, so no cue and no section can name it.
`PAGE_SLIDE_DOUBLED`	error	Two slide templates carry the same id, so a cue that names it is ambiguous.
`PAGE_SLIDE_UNUSED`	error	No section plays this slide, so nothing on it reaches the film.
`PAGE_TEMPLATE_IGNORED`	error	A template nested inside a slide declares no slide of its own, so nothing ever mounts it.
`PAGE_WORDS_NOT_FOUND`	error	An element syncs to words the transcript does not hold, so word timing cannot start.
`PAGE_KATEX_MISSING`	error	The page asks for KaTeX and the library is not loaded, so every formula shows its source.
`PAGE_KATEX_ERROR`	error	KaTeX refused a formula, so the element shows the readable text the author wrote in its place.
`PAGE_FREEZE_CUE_UNKNOWN`	error	A freeze was asked for a cue the slide does not declare, so no frame could be made.
`PAGE_RENDER_THREW`	error	A slide’s render threw, so the slide is drawn without what the render would have written.
`PAGE_ENTER_THREW`	error	A slide’s enter threw, so its opening moment never ran.
`PAGE_SLIDE_HANDLER_THREW`	error	A slide’s own moment handler threw, so that moment did not play.
`PAGE_HANDLER_THREW`	error	A moment handler threw, so the change it was to make never happened.
`PAGE_MOTION_UNDECLARED`	error	Something on the page keeps moving and declares no motion, loop or region, so verify cannot mask it.
`PAGE_MOTION_CUE_UNKNOWN`	error	A motion names a cue no slide declares, so it never starts or never lands.
`PAGE_REALTIME_MEDIA`	error	A page holds a video or an audio element, which plays at its own rate and not on the stepped clock.
`PAGE_FRAME_THREW`	error	A frame hook threw, so whatever it drew stopped moving from that frame on.
`PAGE_WAIT_REJECTED`	error	A wait the page declared was rejected, so the runtime carried on without what it waited for.
`PAGE_WAIT_UNSETTLED`	error	A wait the page declared never settled inside its budget, so the runtime carried on without it.
`PAGE_CLASS_UNDESCRIBED`	error	An element changes class with no description, so the transcript cannot say what changed.
`PAGE_CLASS_NOT_REDUCED`	error	A class change declares no reduced form, so a reduced render would animate anyway.
`PAGE_SWAP_AMBIGUOUS`	error	A swap finds no element or several elements leaving at its cue, so it cannot tell which one it replaces.
`PAGE_PREVIEW_AMBIGUOUS`	error	Two sections name one scene, so a preview cannot choose whose cue times to play.
`PAGE_APPEAR_TOO_LONG`	error	A line shown with data-words=appear holds more words than one cue can carry one at a time.
`PAGE_STAGGER_EMPTY`	error	An element staggers its children and has none, so the stagger plays nothing.
`PAGE_SPOTLIGHT_EMPTY`	error	A spotlight container has no child with a cue, so nothing comes to the front.
`PAGE_MOTION_UNFINISHED`	error	A script motion still changes its picture after it arrives, and nothing draws it past its arrival, so the picture stops where the arrival left it.
`PAGE_MOTION_OVERRUN`	error	A motion span runs past the measurable ceiling, so the cue it carries cannot be verified.
`PAGE_STAGGER_OVERRUN`	error	A staggered entrance totals past the measurable ceiling, and the arithmetic that says so is exact.
`PAGE_THIN_DRAW`	warning	A frozen slide draws less of the picture than a change must cross to be seen.
`PAGE_NO_DESCRIPTION`	error	An element changes the picture and describes nothing, so the transcript loses the change.
`PAGE_SWAP_APART`	warning	A swap’s two halves land far enough apart that a viewer sees the gap between them.
`PAGE_CDN_ASSET`	error	The page loads an asset from a network origin, so the film depends on somebody else’s server.
`PAGE_CHANGE_UNDECLARED`	error	A script changed the picture outside every cue, motion, loop and frame hook, so verify cannot mask it and may read it as a reveal.
`RECORD_BLACK`	error	A recorded frame is black, so the film shows nothing at that moment.
`RECORD_TRUNCATED`	error	A recording stopped before its section’s clock ran out, so the film is short of picture.
`MOTION_EASE_UNMEASURABLE`	error	A motion eases to rest on an arrival verify would measure, and an ease to rest has no edge to measure.
`MOTION_OFF`	error	A declared motion departed or arrived outside the offset limit of the word it was promised to.
`MOTION_NO_EDGE`	error	A declared motion came to rest before its word, so it has no edge on its cue a viewer sees it land on.
`MOTION_MASK_LARGE`	warning	Declared motion covered so much of the frame at a cue that verify measured less of the picture than usual.
`CUE_UNLISTED`	error	The page declares a moment that cues.json does not list, so nothing gives it a second.
`CUE_UNKNOWN`	error	cues.json lists a cue no page declares, so nothing plays it.
`CUE_UNRESOLVED`	error	The cue’s phrase is not spoken in its section, so there is no second to place it at.
`CUE_STALE`	error	The cue times on disk were placed from a different cues.json than the project’s, so the film is judged against moments nobody asked for until the project is built again.
`CUE_OFF`	error	The change lands further from its word than verify.cue_offset_max_ms allows.
`CUE_NO_ONSET`	warning	A cue has no onset DeckTalk can measure: its phrase resolved to its section’s start rather than to a word, or the picture changed at it and no frame rose as far as an onset must.
`CUE_NO_CHANGE`	error	Nothing in the picture changed at the cue’s second, so the reveal never happened.
`CUE_THIN_CHANGE`	warning	Less of the picture changed at the cue than a visible reveal must cross.
`CUE_OVERLAP`	warning	Two cues resolve close enough together that a viewer cannot tell them apart.
`SCRIPT_UNFINISHED`	error	The script still holds an unfilled blank such as [NUMBER], so a voiced run would read it out.
`SCRIPT_SPOKEN_SYMBOL`	warning	The script holds a symbol the voice reads as its name rather than as the thing it means.
`SCRIPT_PAUSE_DROPPED`	error	The script asks for a timed pause the voice’s model does not render, so a voiced run would drop it.
`SCRIPT_VOICE_UNKNOWN`	error	A voice direction names no voice the project declares, or a line opens with the word voice and is not a voice direction.
`SCRIPT_VOICE_UNMARKED`	error	A section that names a voice starts a turn no voice direction names.
`SCRIPT_VOICE_BARE`	warning	A note is exactly the name of a voice the project declares, so it plays as a beat rather than handing the turns after it to that voice.
`VOICE_UNUSED`	warning	The project declares a voice no turn of the script is read by.
`TAKE_MISSING`	warning	A section’s take is not on disk, so a placeholder plays in its place until its voice makes one.
`TAKE_UNALIGNED`	warning	A take came with no word times and no aligner timed them, so its section plays estimated words. Only narrate raises it.
`TAKE_WORD_CUT`	warning	A take’s words place a word after the take’s sound ends, where the narration cuts the take, so the word is never heard. Only narrate raises it.
`TAKE_SILENT`	warning	A voiced take holds no sound above the level its sound end is measured at, so its turn plays silence. Only narrate raises it, on the run that makes the take.
`CUT_SPEECH`	error	Speech is still sounding at a section cut, so the film slices a word in two.
`CUT_POP`	error	The picture steps at a section cut, so the film pops on the seam.
`MIX_LOUDNESS`	warning	The mixed film misses the loudness it was mastered to.
`SOUND_MISSING`	warning	A sound the `[score]` table declares has not been bought, so silence plays where it would until a run with —spend buys it.
`FILE_MISSING`	error	A file the project names is not on disk.
`PROGRAM_NAMED`	warning	The project names a program that recording starts with your user’s rights, so it can read every file you can, .env included.

Commands

Set up this machine

`decktalk init`

Create a project with a deck that already builds.

decktalk init [OPTIONS] DIR

It answers with the init result: decktalk schema init.

Option	Meaning
`--name` `NAME`	The project’s name.
`--example` `NAME`	The packaged project to write, starter by default: starter, lesson, interview, motion.
`--no-skills`	Leave the packaged skills out.
`--overwrite`	Write into a directory that already holds files.

`decktalk install`

Fetch Chromium and ffmpeg before a build needs them.

decktalk install [OPTIONS]

It answers with the install result: decktalk schema install.

`decktalk doctor`

Report what is installed and what a run would use.

decktalk doctor [OPTIONS]

It answers with the doctor result: decktalk schema doctor.

Option	Meaning
`--fix`, `--no-fix`	Apply every safe fix, or apply none. An unsafe fix is printed either way and never applied.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

Read the project, buying nothing

`decktalk status`

Report what is written, what is built and what is stale.

decktalk status [OPTIONS]

It answers with the status result: decktalk schema status.

Option	Meaning
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.

`decktalk check`

Judge script.md, cues.json and the pages before a build.

decktalk check [OPTIONS] [PATH...]

It answers with the check result: decktalk schema check.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--pages`, `--no-pages`	Open the pages in a browser, or judge the written files alone and say what was not reached.
`--frames`, `--no-frames`	Freeze and compare the slides, or keep the browser and drop that.
`--fix`, `--no-fix`	Apply every safe fix, or apply none. An unsafe fix is printed either way and never applied.
`--turn` `N.T`	Price voicing this turn again, such as 4.2, and judge its section. Repeats.
`--take` `DIGEST`	Price voicing again the turn that plays this take, by its digest or its start. Repeats.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

`decktalk words`

Print every spoken word with its start and end.

decktalk words [OPTIONS]

It answers with the words result: decktalk schema words.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.

`decktalk storyboard`

Freeze every slide at every cue onto one page.

decktalk storyboard [OPTIONS]

It answers with the storyboard result: decktalk schema storyboard.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--slide` `ID`	Only these slides, by the id the page declares. Repeats.
`--after` `CUE`	Freeze the slide at the moment this cue fires. Repeats.
`--before` `CUE`	Freeze the slide just before this cue fires. Repeats.
`--at` `SECONDS`	Freeze whatever is on screen this many seconds into its section. Repeats.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

`decktalk serve`

Serve the project on a local origin over http.

decktalk serve [OPTIONS]

It answers with the serve result: decktalk schema serve.

Option	Meaning
`--host` `HOST`	The interface to listen on.
`--port` `PORT`	The port to listen on, or 0 for any.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.

Read the settings and the schemas

`decktalk schema`

Print the JSON Schema of a command, a setting or an event.

decktalk schema [OPTIONS] [NAME]

Option	Meaning
`--scope` `SCOPE`	With setting, the keys one file may hold: project or machine.

`decktalk config list`

Print every key, its value and the layer that set it.

decktalk config list [OPTIONS] [TABLE]

It answers with the config-list result: decktalk schema config-list.

Option	Meaning
`--defaults`	List the defaults rather than what is set.
`--changed`	List only the keys something overrode.

`decktalk config get`

Print one key’s value and the layer that set it.

decktalk config get [OPTIONS] KEY

It answers with the config-get result: decktalk schema config-get.

Option	Meaning

`decktalk config set`

Write one key into decktalk.toml or into this machine’s file.

decktalk config set [OPTIONS] KEY VALUE

It answers with the config-set result: decktalk schema config-set.

Option	Meaning
`--scope` `SCOPE`	project writes decktalk.toml, machine writes this machine’s file.
`--dry-run`	Report the change and write nothing.

`decktalk config unset`

Remove one key so the layer below it wins again.

decktalk config unset [OPTIONS] KEY

It answers with the config-unset result: decktalk schema config-unset.

Option	Meaning
`--scope` `SCOPE`	project writes decktalk.toml, machine writes this machine’s file.
`--table`	Remove a whole table rather than one key.

`decktalk config explain`

Print one key whole: what it does, what may be set, and what set it.

decktalk config explain [OPTIONS] KEY

It answers with the config-explain result: decktalk schema config-explain.

Option	Meaning
`--candidate` `N`	A candidate value, held to the same range.

Run one stage, in this order

`decktalk narrate`

Voice each turn of script.md and time every word.

decktalk narrate [OPTIONS]

It answers with the narrate result: decktalk schema narrate.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--force`	Build every placeholder again, keep every voiced take, and ask the aligner again for every take whose voice sent no word times.
`--replace-voiced`	Set aside each voiced take: voice it again with —spend, or play a placeholder with —no-spend.
`--turn` `N.T`	Voice this turn again as a new take and nothing else, such as 4.2 for section 4’s second turn. Repeats.
`--take` `DIGEST`	Voice again the turn that plays this take, named by its digest or enough of its start. Repeats.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--spend`, `--no-spend`	Buy what is missing without asking, or buy nothing and play a placeholder where a voiced take is missing. A free provider such as dtsp makes its takes either way once a voice is named. Unset, a terminal is asked and a run without one is refused.
`--max-cost` `N`	Refuse before the first call if the most this run can cost is over N US dollars.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

`decktalk cue`

Turn each cue phrase into a second on its section clock.

decktalk cue [OPTIONS]

It answers with the cue result: decktalk schema cue.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

`decktalk record`

Record each page in headless Chromium and run each render program.

decktalk record [OPTIONS]

It answers with the record result: decktalk schema record.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--force`	Record every section again, even one whose recording still matches its page.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

`decktalk score`

Compose the music, the ambience bed and the effects.

decktalk score [OPTIONS]

It answers with the score result: decktalk schema score.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--replace-score`	Buy each bought sound again with —spend. Without —spend it keeps every bought sound.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--spend`, `--no-spend`	Buy what needs it without asking first, or buy nothing: report the plan and write nothing.
`--max-cost` `N`	Refuse before the first call if the most this run can cost is over N US dollars.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

`decktalk assemble`

Cut, mix and encode the sections into one mp4.

decktalk assemble [OPTIONS]

It answers with the assemble result: decktalk schema assemble.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--skip` `STAGE`	Mix without this stage’s audio. score is the one stage assemble can leave out.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

`decktalk verify`

Measure the finished mp4: every start, cut, seam and landing.

decktalk verify [OPTIONS]

It answers with the verify result: decktalk schema verify.

Option	Meaning
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

Run them all, or cut one piece out

`decktalk build`

Run every stage in order, or a span of them.

decktalk build [OPTIONS]

It answers with the build result: decktalk schema build.

Option	Meaning
`--from` `STAGE`	Start at this stage: narrate, cue, record, score, assemble or verify.
`--to` `STAGE`	Stop after this stage, inclusive.
`--skip` `STAGE`	Run every stage but this one. Repeats.
`--section` `N`	Only these sections: 3, 3,5 or 7-9. Repeats.
`--fix`, `--no-fix`	Apply every safe fix, or apply none. An unsafe fix is printed either way and never applied.
`--force`	Build again from nothing, keeping every voiced take and every bought sound, and measure the film again.
`--replace-voiced`	Set aside each voiced take: voice it again with —spend, or play a placeholder with —no-spend.
`--replace-score`	Buy each bought sound again with —spend. Without —spend it keeps every bought sound.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.
`--watch`	Stay running, rebuild the changed section, never spend.
`--spend`, `--no-spend`	Buy what is missing without asking, or buy nothing and play a placeholder where a voiced take is missing. A free provider such as dtsp makes its takes either way once a voice is named. Unset, a terminal is asked and a run without one is refused.
`--max-cost` `N`	Refuse before the first call if the most this run can cost is over N US dollars.
`--fail-on` `WHEN`	error fails on an error, warning fails on any finding, never fails on none. Default error.
`--allow` `CODE`	Carry on past this finding code. Repeats.

`decktalk clip`

Cut a span of a built section into its own file.

decktalk clip [OPTIONS]

It answers with the clip result: decktalk schema clip.

Option	Meaning
`--section` `N`	The one section to cut the clip from, such as 3.
`--start` `SECONDS`	Where the clip starts.
`--end` `SECONDS`	Where the clip ends, after —start. Required.
`--out` `FILE`	Where to write the clip. Default: clip-N.mp4, for section N.
`--gain-db` `DB`	Lift or cut the clip’s audio.
`--hold-seconds` `SECONDS`	Hold the last frame this long.
`--set` `KEY=VALUE`	Override one setting here. Repeats. See config explain.

The schemas

decktalk schema prints the whole instruction set. decktalk schema NAME takes apply, assemble, build, check, clip, config-explain, config-get, config-list, config-set, config-unset, cue, doctor, error, init, install, narrate, record, score, serve, status, storyboard, verify, words, event, finding, cues, page, setting.

​Global options

​Exit codes

​Error codes

​Finding codes

​Commands

​Set up this machine

​decktalk init

​decktalk install

​decktalk doctor

​Read the project, buying nothing

​decktalk status

​decktalk check

​decktalk words

​decktalk storyboard

​decktalk serve

​Read the settings and the schemas

​decktalk schema

​decktalk config list

​decktalk config get

​decktalk config set

​decktalk config unset

​decktalk config explain

​Run one stage, in this order

​decktalk narrate

​decktalk cue

​decktalk record

​decktalk score

​decktalk assemble

​decktalk verify

​Run them all, or cut one piece out

​decktalk build

​decktalk clip

​The schemas