Configuration

A setting is a number or a word a project could reasonably hold differently, and which some judgement names when it fails. Every one below publishes the range that is safe to turn it through, its true unit, the file it belongs in, and the findings its value moves. The range is the range the loader enforces: a value outside it is refused by name, with the range it left, before any stage runs, because a published bound you can cross into nonsense is worse than no bound at all. Bind the schema to your project file and an editor completes every key as you type it.

decktalk.toml

#:schema https://raw.githubusercontent.com/jacobcbeaudin/decktalk/main/schemas/v1/decktalk.json

[verify]
cue_offset_max_ms = 120

Which value wins

Every key has a scope, in the Scope column below, and the scope names the one file that may set it. A project key is set by these, each overriding the ones before it:

The default in the table below.
The same table in the project’s decktalk.toml.
The environment variable each key publishes, such as DECKTALK_VIDEO_PRESET.
--set table.key=value, for one run, on status, check, words, storyboard, serve, narrate, cue, record, score, assemble, verify, build and clip.

A machine key is set the same way, with the per-machine settings file in place of decktalk.toml. decktalk config explain KEY prints the value in force and the layer it comes from, so you never have to work out which one that is. Each file refuses a key of the other scope by name. A key about the film in the per-machine file is refused because the file that ships has to carry whatever the machine running it believes. DECKTALK_MACHINE_FILE names a different per-machine file.

Linux	macOS	Windows
`$XDG_CONFIG_HOME/decktalk/machine.toml`, or `~/.config/decktalk/machine.toml`	`~/Library/Application Support/decktalk/machine.toml`	`%APPDATA%\decktalk\machine.toml`

Keys only a machine may set

These keys describe the machine rather than the film: where a tool or a cache lives, and how hard this machine may be driven. A project file that sets one is refused by name, because a project travels and a path or a limit that is right on one machine is wrong on the next. Write one into this machine’s file with decktalk config set KEY VALUE --scope machine, or set its environment variable. narration.concurrency, narration.retries, narration.store_dir, record.page_policy, record.programs, record.concurrency, record.chunk_frames_min, record.chunk_startup_seconds, record.step_seconds, record.page_deadline_seconds, record.deadline_slowdown, record.renderer_retries, record.encode_threads, elevenlabs.base_url, dtsp.base_url, dtsp.handshake_seconds, events.max_bytes, tools.chromium, tools.ffmpeg, tools.ffprobe, tools.timeout_seconds, tools.fix_timeout_seconds and tools.cache_dir.

Which key moves which failure

A finding names the key that decided it. This is the same index in reverse, for the case where you have a code and want the candidates before you run anything.

Finding	Keys that move it
`CUE_NO_CHANGE`	`video.crf`, `verify.probe_delays_seconds`, `verify.probe_diff_luma`, `verify.changed_share_min_percent`, `verify.margin_min_points`
`CUE_NO_ONSET`	`verify.onset_rise_points`, `verify.onset_diff_luma`
`CUE_OFF`	`verify.reference_lead_extra_ms`, `verify.onset_rise_points`, `verify.onset_diff_luma`, `verify.click_search_seconds`, `verify.click_floor_dbfs`, `verify.cue_offset_max_ms`, `verify.av_offset_max_ms`
`CUE_THIN_CHANGE`	`video.crf`, `verify.probe_diff_luma`, `verify.changed_share_min_percent`, `verify.margin_min_points`, `verify.thin_change_factor`
`CUT_POP`	`verify.cut_change_max_percent`
`CUT_SPEECH`	`narration.tail_seconds`, `narration.sound_end_noise_dbfs`, `narration.sound_end_min_run_seconds`, `verify.cut_window_seconds`, `verify.cut_max_dbfs`
`MIX_LOUDNESS`	`audio.target_lufs`, `audio.true_peak_max_dbtp`
`MOTION_MASK_LARGE`	`verify.motion_mask_max_percent`
`MOTION_NO_EDGE`	`verify.cue_offset_max_ms`, `verify.motion_floor_percent`
`MOTION_OFF`	`verify.cue_offset_max_ms`, `verify.motion_floor_percent`
`PAGE_CLASS_NOT_REDUCED`	`motion.reduce`
`PAGE_MOTION_OVERRUN`	`motion.scale`
`PAGE_STAGGER_OVERRUN`	`motion.scale`
`PAGE_THIN_DRAW`	`video.crf`, `verify.changed_share_min_percent`
`RECORD_BLACK`	`verify.after_dip_seconds`, `verify.black_max_luma`
`TAKE_SILENT`	`narration.sound_end_noise_dbfs`, `narration.sound_end_min_run_seconds`
`TAKE_WORD_CUT`	`narration.sound_end_noise_dbfs`, `narration.sound_end_min_run_seconds`

`[video]`

These keys set the frame size and the encoding of every recording and of the final mp4.

Key	Type	Default	Safe range	Unit	Scope	Decides	Meaning
`size`	string	`"wide"`	must match the pattern ^(?:wide\|square\|vertical\|(?:(?:2[4-9]\|[3-9][0-9]\|[1-6][0-9]\|7[0-5][0-9]\|76[0-7])[02468]\|7680)x(?:(?:2[4-9]\|[3-9][0-9]\|[1-6][0-9]\|7[0-5][0-9]\|76[0-7])[02468]\|7680))$	pixels	project		The frame of every recording and of the final mp4: wide (1920 by 1080), square (1080 by 1080), vertical (1080 by 1920), or WIDTHxHEIGHT in pixels. A page is laid out on a canvas of the frame’s shape whose short side is 1080 CSS pixels, which it reads as —dt-width and —dt-height, so a square copy of a project is the project copied with this one key changed.
`fps`	integer	`25`	must be one of 25, 30, 50, 60	frames per second	project		Frame rate of every recording and of the final mp4. The recorder steps the section clock one frame of this rate at a time, so every frame of a film is the page at its own second.
`preset`	string	`"medium"`	must be one of ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow		project		x264 preset. Use veryfast for drafts.
`crf`	integer	`18`	must be between 0 and 32		project	`CUE_NO_CHANGE`, `CUE_THIN_CHANGE`, `PAGE_THIN_DRAW`	x264 quality. A lower value gives higher quality and a larger file.
`slate_color`	string	`"0x0e1116"`	must match the pattern ^(#\|0[xX])[0-9A-Fa-f]$		project		Color of the plain frame that plays when a slate image cannot be rendered, as #RRGGBB or 0xRRGGBB.

video.size An odd side cannot be encoded, because the film’s colour is stored at half the frame’s width and height, and a side past the range is a frame Chromium and x264 are not held to drawing.video.crf Above about 32 the encoder’s own ringing is larger than a small reveal, so a cue that played reads as no change and the check that would have caught it passes instead.video.slate_color The colour is placed inside an ffmpeg filter graph and the slate page’s stylesheet, so any other text could add a filter that opens a file or a rule that loads a URL.

`[narration]`

These keys govern how the script is turned into audio.

Key	Type	Default	Safe range	Unit	Scope	Decides	Meaning
`voice`	string	`"narrator"`	must match the pattern ^[a-z][a-z0-9]*$		project		The default voice: the voice that reads every section no voice direction in the script names, and every turn of a section that names none. It names a [voices.NAME] table, and with no such table written it is a voice at every default.
`concurrency`	integer	`2`	must be between 1 and 8		machine		How many turns `narrate` voices at once.
`retries`	integer	`3`	must be between 0 and 10		machine		How many more times `narrate` asks again when the voice provider or the aligner answers that it is busy or failed.
`mp3_bitrate`	string	`"128k"`	must be one of 64k, 96k, 128k, 160k, 192k, 256k		project		Bitrate of the mp3 files that DeckTalk writes, which are the placeholders and the joined narration.
`words_per_minute`	integer	`140`	must be between 60 and 300	words per minute	project		Pacing of the estimated length in the narrate table.
`placeholder_words_per_minute`	integer	`150`	must be between 60 and 300	words per minute	project		Pacing of a placeholder, the click audio a section plays until its take is voiced.
`lead_seconds`	number	`0.5`	must be between 0 and 5	seconds	project		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.
`turn_gap_seconds`	number	`0.3`	must be between 0 and 5	seconds	project		Silence between two turns of a section when no timed pause is written where the voice changes. A [pause N] written there replaces it, and neither is part of either turn’s take.
`placeholder_beat_seconds`	number	`0.7`	must be between 0 and 10	seconds	project		Seconds each beat adds to the length of a placeholder take.
`tail_seconds`	number	`0.7`	must be between 0 and 10	seconds	project	`CUT_SPEECH`	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.
`takes_dir`	string	`"takes"`	must match the pattern ^.+$	path	project		Directory inside the project that holds every take the film plays and the words its voice sent with each, which you commit so a fresh clone builds the film with no key. The take index stays under the build, because it is a cache built again from the takes. A take is looked for here first and in the machine’s take store, `store_dir`, second, and a take this project voices or finds there is written here.
`store_dir`	string	`""`	takes any value of its type	path	machine		The take store: a folder outside every project where this machine keeps a second copy of every voiced take it makes and its provider words, each named by its digest. A take is looked for here after `takes_dir`, and one found here is checked and copied into `takes_dir`, so a deck with the same words as another plays it without buying it, and a take nobody committed yet survives a `git clean`. Each take is written here once, and a store that already holds a good copy keeps it. It is empty for the `takes` folder in the per-user data folder, such as `~/Library/Application Support/decktalk/takes` on macOS.
`context_characters`	integer	`1500`	must be between 0 and 5000	characters	project		Characters of the neighbouring turns sent with a request, for continuous prosody: the end of the turn before and the start of the turn after that the same voice reads among the turns the run selects. 0 sends no neighbouring text, so each turn is sent on its own.
`timeout_seconds`	integer	`180`	must be between 10 and 1800	seconds	project		Seconds before a speech or alignment request times out. With `retries` it also sets how long a run waits while another run on this machine voices the same take into the take store: one whole take request, every attempt this long with the waits between them, before it is refused as locked.
`sound_end_noise_dbfs`	number	`-35.0`	must be between -60 and -25	dBFS	project	`CUT_SPEECH`, `TAKE_WORD_CUT`, `TAKE_SILENT`	Level under which the tail of a take counts as silence, which is where the take’s sound ends.
`sound_end_min_run_seconds`	number	`0.05`	must be between 0.02 and 0.5	seconds	project	`CUT_SPEECH`, `TAKE_WORD_CUT`, `TAKE_SILENT`	Shortest run under the noise level that counts as the end of a take’s sound.

narration.concurrency A voice provider limits requests per account, and a busy answer is retried rather than paid twice.narration.takes_dir An empty value, a directory outside the project, an absolute path, the project directory itself, a directory inside the build directory or one that holds it is refused when the project loads, because a voiced take must land in a folder the project keeps, and a project someone else wrote would otherwise choose where this machine reads and writes its takes.narration.store_dir It holds the spoken words of every script voiced on this machine, so keep it out of a synced or shared folder. A relative path, a folder inside the project or one inside the tool cache is refused when the project loads. Write an absolute path or one that starts with ~.narration.sound_end_noise_dbfs Above about -25 dBFS the scan calls quiet speech silence, so the take is placed early and the cut that follows it lands on a word.

`[record]`

These keys tune how record opens each page section in headless Chromium and steps it frame by frame.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`color_scheme`	string	`"light"`	must be one of light, dark, no-preference		project	Color scheme that Chromium reports to the page.
`page_policy`	string	`"trusted"`	must be one of trusted, untrusted		machine	How far `record`, `check` and `storyboard` trust a page. `trusted` lets a page reach the network as a browser would. `untrusted` turns the Chromium sandbox on and refuses every request that is not for the project’s own origin, through every channel a page can open. It is the machine’s to set, so a project someone else wrote cannot trust its own page.
`programs`	string	`"refuse"`	must be one of refuse, ask, run		machine	Whether `record` runs the programs a project names, which are its render sections’ `render_command`. A program runs with your user’s rights and can read every file you can, the project’s `.env` included. `refuse` runs none of them. `ask` lists every program the run would start and runs them only when a person at a terminal answers yes, and refuses without a terminal, under `--no-input` and under `--json`. `run` runs them without asking. Under the `untrusted` page policy no program runs whatever this says. It is the machine’s to set, so a project cannot allow its own programs.
`concurrency`	integer	`0`	must be between 0 and 16		machine	How many recorders `record` runs at once, each a Chromium of its own that records one chunk of a section after another. Zero chooses from the CPU this process may use, which inside a container is its quota rather than the host’s core count.
`chunk_frames_min`	integer	`50`	must be between 1 and 100000	frames	machine	Fewest frames `record` puts in one chunk when it splits a section across its recorders. A section shorter than two chunks of this length is recorded whole by one recorder.
`chunk_startup_seconds`	number	`0.2`	must be above 0 and must be at most 60	seconds	machine	How long one chunk takes to start on this machine: a page opened and loaded in a recorder’s Chromium and stepped to the chunk’s first frame. `record` splits a section into about sqrt(step_seconds * steps * recorders / chunk_startup_seconds) chunks, never more than the recorders, where steps are what its last recording took.
`step_seconds`	number	`0.014`	must be above 0 and must be at most 10	seconds	machine	How long one recorder takes to step its page once on this machine, the capture of the frame it lands on included, which `record` weighs against `chunk_startup_seconds` when it splits a section.
`page_deadline_seconds`	number	`15.0`	must be between 1 and 600	seconds	machine	Longest one call into a page may take before DeckTalk closes the page and stops with a TOOL error naming where it was stuck: a load, a step, a capture, a still or a report. `record` names the section and the frame, and `check`, `storyboard`, `cue` and `assemble` hold the pages they open to it too. It is many times the longest a step measures, so only a page that stopped answering reaches it, such as one that spins its main thread or waits on a font or an image that never arrives.
`deadline_slowdown`	number	`30.0`	must be between 1 and 10000		machine	How many times slower than this machine’s `chunk_startup_seconds` and `step_seconds` a recording may run before `record` stops it. A chunk may take `page_deadline_seconds` plus this many times chunk_startup_seconds + step_seconds * frames, and the whole run this many times the time its chunks take spread over the recorders, plus its longest chunk, so a page that answers every call and never gets on still ends with a TOOL error.
`renderer_retries`	integer	`1`	must be between 0 and 5		machine	How many more times `record` records a chunk, in a fresh page, when the page’s renderer crashed or its page was closed under it. A frame is a function of its index, so a chunk recorded again is the same frames.
`encode_threads`	integer	`0`	must be between 0 and 64		machine	Threads each recorder’s lossless encode runs on. Zero shares this process’s CPUs among the recorders at once, at least one each. Every piece of a run is encoded with the same number, and the frames are the same whatever it is.
`skip_still`	boolean	`true`	takes any value of its type		project	Write a frame again rather than capture it when the page reports that nothing it draws changed since the frame before, which is most frames of a narrated slide, and write every frame before the next change the page reports without stepping the page to each. The frames are the same either way, so it changes how long `record` takes and nothing it writes.

record.page_policy A service that renders pages other people wrote sets untrusted on its machine, because a trusted page can reach anything the machine can, including a cloud metadata endpoint.record.programs run executes whatever a project’s decktalk.toml names as soon as record or build reaches it, so set it only on a machine that builds projects whose programs you have read.record.concurrency Each recorder steps its own Chromium and its own encode, so a number above the machine’s share makes every chunk wait on the others and the run slower rather than faster.record.chunk_frames_min Every chunk loads the page again, so chunks much shorter than a page load spend the machine on loading rather than on frames.record.chunk_startup_seconds A start-up stated far too low splits short sections into chunks that each spend more loading the page than recording it.record.page_deadline_seconds A deadline set near the time a frame takes stops healthy recordings on a busy machine.record.deadline_slowdown A value near one stops a recording that a loaded machine is merely slow to make, because the two calibrations are this machine’s speed when it is idle.record.encode_threads x264 buffers frames for every thread it runs, so a large number costs each recorder hundreds of megabytes and buys no speed, because the encode is never what a recording waits on.

`[audio]`

These keys are the final audio: its encoding, and the loudness it is normalised to and judged against.

Key	Type	Default	Safe range	Unit	Scope	Decides	Meaning
`bitrate`	string	`"192k"`	must be one of 96k, 128k, 160k, 192k, 256k, 320k		project		AAC bitrate of the final mp4.
`sample_rate`	integer	`48000`	must be one of 44100, 48000	hertz	project		Audio sample rate of the final mp4. Every audio input is resampled to it once.
`channels`	integer	`2`	must be one of 1, 2		project		Audio channels of the final mp4.
`target_lufs`	number	`-16.0`	must be between -30 and -9	LUFS	project	`MIX_LOUDNESS`	Programme loudness the final mp4 is normalised to.
`true_peak_max_dbtp`	number	`-1.5`	must be between -9 and -0.1	dBTP	project	`MIX_LOUDNESS`	Highest true peak the normalised mix may reach.
`range_max_lu`	number	`11.0`	must be between 1 and 20	LU	project		The loudness range the measurement is made against. It is not a limit, and no mix fails on it.

audio.true_peak_max_dbtp Four times oversampling under-reads a true peak and the AAC encode overshoots on top of that, so a ceiling above about -1 dBTP reports a clean mix that clips on a listener’s decoder.

`[verify]`

These keys are the limits verify judges the assembled mp4 against.

Key	Type	Default	Safe range	Unit	Scope	Decides	Meaning
`after_dip_seconds`	number	`0.2`	must be between 0 and 2	seconds	project	`RECORD_BLACK`	Seconds after a section start to the frame that the start check reads.
`reference_lead_extra_ms`	number	`0.0`	must be between 0 and 80	milliseconds	project	`CUE_OFF`	Extra lead added to the reference frame beyond the one the offset limit implies.
`probe_delays_seconds`	array	`[0.7, 1.5]`	must hold at least 1 and must hold values that each must be above 0 and must be at most 10	seconds	project	`CUE_NO_CHANGE`	Seconds after the cue time for each probe. The later probe catches a slow reveal.
`probe_diff_luma`	integer	`40`	must be between 4 and 200	luma	project	`CUE_NO_CHANGE`, `CUE_THIN_CHANGE`	Luma difference a pixel must exceed to count as changed, for the probes and the control shares.
`changed_share_min_percent`	number	`0.1`	must be between 0.001 and 5	percent	project	`CUE_NO_CHANGE`, `CUE_THIN_CHANGE`, `PAGE_THIN_DRAW`	Smallest share of the frame, in percent, that the reported probe must find changed.
`margin_min_points`	number	`0.1`	must be between 0.001 and 5	percentage points	project	`CUE_NO_CHANGE`, `CUE_THIN_CHANGE`	Smallest margin, in percentage points, between the reported probe and its control.
`thin_change_factor`	number	`3.0`	must be between 1 and 10		project	`CUE_THIN_CHANGE`	A passing cue whose changed share or margin is under this many times its floor is a warning rather than clean. A value of 1 turns that second opinion off.
`onset_rise_points`	number	`0.01`	must be between 0.001 and 1	percentage points	project	`CUE_OFF`, `CUE_NO_ONSET`	Rise in the changed share from one frame to the next that marks the onset, in percentage points.
`onset_diff_luma`	integer	`12`	must be between 2 and 60	luma	project	`CUE_OFF`, `CUE_NO_ONSET`	Luma difference a pixel must exceed to count as changed, for the onset scan alone.
`click_search_seconds`	number	`0.25`	must be between 0.02 and 2	seconds	project	`CUE_OFF`	Seconds on each side of the cued word’s start that the click search covers.
`click_floor_dbfs`	number	`-38.0`	must be between -60 and -24	dBFS	project	`CUE_OFF`	Level a sample must exceed for the click search to call it the click.
`cue_offset_max_ms`	number	`80.0`	must be between 20 and 400	milliseconds	project	`CUE_OFF`, `MOTION_OFF`, `MOTION_NO_EDGE`	How far the measured onset may sit from the cue time, early or late.
`motion_floor_percent`	number	`0.5`	must be between 0.05 and 20	percent	project	`MOTION_OFF`, `MOTION_NO_EDGE`	How much of a moving element’s own area must change from one frame to the next for verify to read it as moving, which is where a motion’s departure and arrival are found.
`motion_mask_max_percent`	number	`40.0`	must be between 5 and 90	percent	project	`MOTION_MASK_LARGE`	The most of the frame verify may mask out of a cue’s measurement before it says it measured less of the picture than usual.
`av_offset_max_ms`	number	`120.0`	must be between 80 and 500	milliseconds	project	`CUE_OFF`	How far the click may sit from the word it marks, early or late. It is wider than the cue limit because the click carries the encoder’s own jitter as well.
`black_max_luma`	number	`60.0`	must be between 1 and 200	luma	project	`RECORD_BLACK`	A frame whose brightest luma is at most this is black, whether `record` or `verify` reads it.
`cut_window_seconds`	number	`0.15`	must be between 0.01 and 2	seconds	project	`CUT_SPEECH`	Seconds of narration before each cut that the cut check measures.
`cut_max_dbfs`	number	`-40.0`	must be between -90 and -20	dBFS	project	`CUT_SPEECH`	Loudest level the cut window may reach before the cut counts as falling on speech.
`cut_change_max_percent`	number	`0.1`	must be between 0.001 and 10	percent	project	`CUT_POP`	Largest share of the frame, in percent, that may change across a cut into a seamless section.

verify.reference_lead_extra_ms The lead is already the offset limit plus the grid guard, so extra lead is only ever the escape hatch for a deck whose reference frame is still inside its own reveal. Above about 80 milliseconds the reference frame reaches back into the previous cue and the check compares two changes rather than one.verify.probe_diff_luma A high value counts only a change that crosses most of the range, so a reveal that fades in or moves a light element on a light slide reads as no change at all.verify.changed_share_min_percent Above about 5 percent only a change across most of the slide passes, so every small reveal in the deck reports a failure it cannot fix.verify.onset_rise_points The rise is measured over a quarter-size frame, so one point is already tens of thousands of pixels. Above about one point no frame ever qualifies, every cue reports a null offset, and the check that names a late reveal stops running while the run still exits clean.verify.click_floor_dbfs DeckTalk generates its own click at -24 dBFS, so a floor at or above that level finds no click at all and every a/v row measures nothing while reporting no failure.verify.cue_offset_max_ms A viewer sees a reveal land late at about a fifth of a second, so above roughly 200 milliseconds the limit passes films whose pictures visibly miss their words.verify.motion_floor_percent Above a few percent the slow last frames of a firm arrival read as still, so its arrival is measured early and a motion that landed on its word fails.verify.motion_mask_max_percent Near the top of the range a cue is judged on a sliver of the frame, so a reveal under a large declared motion passes on very little evidence.verify.av_offset_max_ms An mp3 frame smears a transient across about 26 milliseconds and the encode adds its own, so a limit under 80 milliseconds reports a failure that no edit to the film can clear.

`[mix]`

The settings half of [mix], which is how each layer is ramped. Its files and levels are project content.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`duck_ramp_seconds`	number	`0.5`	must be between 0 and 5	seconds	project	Ramp of the music duck at each edge of a spoken span or a clip.
`ambience_ramp_seconds`	number	`1.0`	must be between 0 and 10	seconds	project	Ramp of the ambience bed at each edge of its span.
`ambience_pad_seconds`	number	`0.5`	must be between 0 and 10	seconds	project	Seconds that the ambience bed extends past each edge of its section.
`marker_mute_ramp_seconds`	number	`0.04`	must be between 0 and 1	seconds	project	Ramp into and out of a marker’s mute.
`marker_boost_ramp_seconds`	number	`0.3`	must be between 0 and 5	seconds	project	Ramp into and out of a marker’s swell.

`[motion]`

These keys decide how much motion a build renders, which changes the film it produces.

Key	Type	Default	Safe range	Unit	Scope	Decides	Meaning
`reduce`	boolean	`false`	takes any value of its type		project	`PAGE_CLASS_NOT_REDUCED`	Render every slide as the reduced-motion variant, which is the film a viewer who asks for less motion should be given.
`scale`	number	`1.0`	must be between 0.25 and 4		project	`PAGE_MOTION_OVERRUN`, `PAGE_STAGGER_OVERRUN`	Multiplier on every declared motion span and duration in the deck.

motion.scale A scale above one slows motion down, and a span slowed past the measurable ceiling makes its own cue unmeasurable, so each scaled span is clamped at that ceiling rather than obeyed.

`[elevenlabs]`

These keys are ElevenLabs’s own: its speech fields, its model, its rate, its output format and its API. The key it is bought with is ELEVENLABS_API_KEY, and base_url is the machine’s to set. The score stage buys from the same API with the same key.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`model`	string	`"eleven_multilingual_v2"`	takes any value of its type		project	The ElevenLabs model every ElevenLabs voice reads with, unless its own `[voices.NAME]` table names another.
`stability`	number	`0.55`	must be between 0 and 1		project	How closely the voice holds one delivery across takes.
`similarity_boost`	number	`0.75`	must be between 0 and 1		project	How closely the voice holds to the original recording it was cloned from.
`style`	number	`0.0`	must be between 0 and 1		project	How much expressive style the voice adds beyond the words.
`speaker_boost`	boolean	`true`	takes any value of its type		project	Whether ElevenLabs applies the boost it calls use_speaker_boost to the take.
`dollars_per_1000_characters`	number	`0.0`	must be between 0 and 100	US dollars per 1000 characters	project	What this project’s ElevenLabs plan charges in US dollars per thousand characters of speech.
`output_format`	string	`"mp3_44100_128"`	must be one of mp3_22050_32, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192		project	Audio format ElevenLabs returns each take in, as its own codec_rate_bitrate token. It is part of every take’s digest, and its codec names the take’s file.
`base_url`	string	`"https://api.elevenlabs.io/v1"`	takes any value of its type		machine	Base URL of the ElevenLabs API, which the voice and the score both send their requests and the key to.

elevenlabs.stability ElevenLabs takes a share and refuses anything else, so a value read as a percentage fails the request rather than the load.elevenlabs.dollars_per_1000_characters It is zero until somebody states it, and --max-cost refuses a run while the price is still the default, because DeckTalk would otherwise be capping a spend against a number it invented. ElevenLabs bills per character, so a zero somebody stated still asks before it buys.elevenlabs.output_format Every take already bought was bought in the format named here, so another one buys every take again.elevenlabs.base_url The script, and for a provider that bills the API key, travels to whatever host this names, so only the machine names it and a project file that sets it is refused.

`[dtsp]`

These keys are the dtsp provider’s own: where its local server listens, the model it reads with, and how long the server has to say which aligner it serves. dtsp speaks the DeckTalk speech protocol to decktalk-voice, a separate local server that is not part of this repository and is not yet public. The same server times the words of a take whose voice sent none. It needs no key, bills nothing, and base_url is the machine’s to set.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`base_url`	string	`"http://127.0.0.1:9361"`	takes any value of its type		machine	Base URL of decktalk-voice, the local server that reads the script for `dtsp` and times the words of a take that came without them. Port 9361 is assigned to nothing at IANA and listed in no /etc/services, so no other service is expected to answer there.
`handshake_seconds`	integer	`5`	must be between 1 and 60	seconds	machine	Seconds the local server has to say which aligner it serves, asked at most once per run and only when a take has no aligned words kept. It is short because a server that is up answers at once, so a port held by a process that never answers costs this wait and not `[narration] timeout_seconds`.
`model`	string	`"kokoro-82m"`	takes any value of its type		project	The model the local server reads every `dtsp` voice with, as the server names it, unless the voice’s own `[voices.NAME]` table names another.

dtsp.base_url The script, and for a provider that bills the API key, travels to whatever host this names, so only the machine names it and a project file that sets it is refused.

`[score]`

The settings half of [score]: how the music, the ambience and the effects are asked for. Each item’s own table holds its prompt and its file, which are project content, beside the settings that size its request, so a key is spelled the same way the item it sizes spells it.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`dir`	string	`"score"`	must match the pattern ^.+$	path	project	Directory inside the project that holds every sound the score bought and the ledger that records them, each named by its item, which you commit so a fresh clone mixes the film with no key. Music bought in parts keeps its parts here, and the piece joined from them is a cache under the build.
`provider`	string	`"elevenlabs"`	takes any value of its type		project	The sound provider the music, the ambience and the effects are bought from, which is a name the machine’s own sound table answers. ElevenLabs is the only sound provider DeckTalk ships, and it buys with the key and `base_url` of `[elevenlabs]`.
`output_format`	string	`"mp3_44100_128"`	takes any value of its type		project	Audio format the music, the ambience and the effects are asked for in. A take’s format is its provider’s own, such as `[elevenlabs] output_format`.
`timeout_seconds`	integer	`600`	must be between 10 and 3600	seconds	project	Seconds before a sound or music request times out.

score.dir An empty value, a directory outside the project, an absolute path, the project directory itself, a directory inside the build directory or one that holds it is refused when the project loads, because a bought sound must land in a folder the project keeps, and a project someone else wrote would otherwise choose where this machine writes what it buys.

`[score.ambience]`

The settings half of [score.ambience]: how the ambience bed is asked for. Its prompt and file are content.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`model`	string	`"eleven_text_to_sound_v2"`	takes any value of its type		project	Model the ambience bed is asked for from.
`duration_seconds`	number	`25.0`	must be between 1 and 60	seconds	project	Length of the ambience bed that is asked for, which `[mix]` loops under its sections.
`prompt_influence`	number	`0.3`	must be between 0 and 1		project	How closely the ambience bed follows its prompt.
`dollars_per_minute`	number	`0.0`	must be between 0 and 100	US dollars per minute of audio	project	What this project’s sound plan charges in US dollars per minute of ambience audio, which is priced by the second of audio asked for.

score.ambience.dollars_per_minute It is zero until somebody states it, and --max-cost refuses a score while any rate it buys at is still the default, because DeckTalk would otherwise be capping a spend against a number it invented.

`[score.effects]`

The settings half of [score.effects]: how each effect is asked for unless its own table says.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`model`	string	`"eleven_text_to_sound_v2"`	takes any value of its type		project	Model every effect is asked for from, unless its own table names one.
`duration_seconds`	number	`0.5`	must be between 0.1 and 30	seconds	project	Length of every effect that is asked for, unless its own table sets one.
`prompt_influence`	number	`0.5`	must be between 0 and 1		project	How closely every effect follows its prompt, unless its own table sets how closely.
`dollars_per_minute`	number	`0.0`	must be between 0 and 100	US dollars per minute of audio	project	What this project’s sound plan charges in US dollars per minute of effect audio, which is priced by the second of audio asked for.

score.effects.dollars_per_minute It is zero until somebody states it, and --max-cost refuses a score while any rate it buys at is still the default, because DeckTalk would otherwise be capping a spend against a number it invented.

`[score.music]`

The settings half of [score.music]: how the music is asked for and joined. Its prompt is content.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`model`	string	`"music_v2"`	takes any value of its type		project	Model the music is asked for from.
`duration_seconds`	integer	`360`	must be between 1 and 3600	seconds	project	Length of the music that is asked for, which `[mix]` fades out at the end of the film.
`bitrate`	string	`"192k"`	must be one of 96k, 128k, 160k, 192k, 256k, 320k		project	Bitrate of the music file that `score` joins from its chunks.
`chunk_max_seconds`	integer	`300`	must be between 30 and 600	seconds	project	Longest music request. Longer music is requested in chunks and crossfaded.
`crossfade_seconds`	integer	`2`	must be between 0 and 30	seconds	project	Crossfade between two music chunks.
`dollars_per_minute`	number	`0.0`	must be between 0 and 100	US dollars per minute of audio	project	What this project’s sound plan charges in US dollars per minute of music audio, which is priced by the second of audio asked for.

score.music.dollars_per_minute It is zero until somebody states it, and --max-cost refuses a score while any rate it buys at is still the default, because DeckTalk would otherwise be capping a spend against a number it invented.

`[output]`

These keys switch the files a build writes beside the final mp4.

Key	Type	Default	Safe range	Scope	Meaning
`timestamped_copy`	boolean	`false`	takes any value of its type	project	Write a second copy of the final mp4 named with the date and time.
`caption_voices`	boolean	`false`	takes any value of its type	project	Name the voice of every caption in a section spoken in more than one voice: a WebVTT voice span such as `<v narrator>` in the .vtt, and the name before the line, such as `narrator:` , in the .srt. Off, the captions carry the words alone, and the transcript names the voices of a dialogue either way.
`captioned`	boolean	`false`	takes any value of its type	project	Also write `<name>-captioned.mp4`, the film with its captions drawn into the picture, for a place that cannot load a caption file. The page draws each caption in its own fonts and styles, and places it by the voice that says it without naming the voice. The film, its caption files and its transcript are the same either way.

`[events]`

These keys bound the events files a run writes under build/events/.

Key	Type	Default	Safe range	Unit	Scope	Decides	Meaning
`keep_runs`	integer	`20`	must be between 1 and 1000	runs	project		How many runs of event files `build/events/` keeps before the oldest is deleted.
`max_bytes`	integer	`8388608`	must be between 65536 and 1073741824	bytes	machine		Bytes one run’s events file may reach before progress lines, download lines and debug and info lines are left out of it. Warnings and errors are left out once it reaches twice this. Lines about the run, its stages, its sections, its findings and its costs are always kept.

events.max_bytes A file with no bound grows with every tool call a long film makes, on a disk a host shares.

`[tools]`

These keys name the tools DeckTalk drives, for a machine that supplies its own.

Key	Type	Default	Safe range	Unit	Scope	Meaning
`chromium`	string	`""`	takes any value of its type	path	machine	Chromium executable that `record`, `check` and `storyboard` drive. It is empty for the build DeckTalk fetches itself, and a path here is what a managed machine sets: a named executable that will not launch is never a reason to download another.
`ffmpeg`	string	`""`	takes any value of its type	path	machine	ffmpeg executable. It is empty for the build DeckTalk fetches itself.
`ffprobe`	string	`""`	takes any value of its type	path	machine	ffprobe executable. It is empty for the build DeckTalk fetches itself.
`timeout_seconds`	number	`600.0`	must be between 10 and 7200	seconds	machine	Longest one ffmpeg or ffprobe call, or one wait on another fetch of ffmpeg, may run before it is stopped.
`fix_timeout_seconds`	number	`1800.0`	must be between 60 and 7200	seconds	machine	Longest one DeckTalk command a fix runs, such as the fetch of a browser and an encoder, may run before it is stopped.
`cache_dir`	string	`""`	takes any value of its type	path	machine	Directory the fetched Chromium and ffmpeg builds live in, Chromium in its ms-playwright folder. It is empty for the standard per-user cache.

tools.fix_timeout_seconds A fix that fetches a browser and an encoder downloads a few hundred megabytes, so under a minute a slow link stops it part way every time.tools.cache_dir A relative path is refused when the machine loads. Write an absolute path or one that starts with ~.

`[voices]`

Every voice of the project, one table per voice, each named by the name a voice direction in the script calls it by. The table [narration] voice names is the default voice. These keys are the three every voice has: which provider reads its turns, in which voice and at what pace. Each voice is one [voices.NAME] table. Everything a provider is particular about, its own fields, its model and its rate, is in that provider’s own table, and a voice may state any of that table’s chosen keys for itself alone, so changing provider never sends one vendor’s fields or model to another. Write one table per voice, named by the name the script’s voice directions use, such as [voices.guest]. A voice name is a lower-case letter followed by lower-case letters and digits. Each key below is set for that voice alone, and its variable spells the voice’s name, such as DECKTALK_VOICES_GUEST_ID. A key that names a provider table’s key reads that table’s value until the voice states its own.

Key	Type	Default	Safe range	Scope	Meaning
`provider`	string	`"elevenlabs"`	takes any value of its type	project	The speech provider that reads this voice’s turns, which is a name the machine’s own map answers. An unregistered name loads, and fails only when a run asks it for a take, which a run that does not spend never does. DeckTalk ships `elevenlabs`, the cloud voice whose own keys are `[elevenlabs]`, and `dtsp`, a provider served by a local server, whose own keys are `[dtsp]`.
`id`	string	`""`	must match the pattern ^[A-Za-z0-9_-]*$	project	The voice that reads this voice’s turns, as the provider names it. It is a published name rather than a credential, so it is committed with the project, and it is one of the inputs every take is named by. `DECKTALK_VOICES_<NAME>_ID` overrides it for anyone who keeps it out of the file.
`speed`	number	`1.0`	must be between 0.7 and 1.2	project	How fast the voice speaks, as a multiple of its natural pace.
`model`	string	`elevenlabs.model` or `dtsp.model`	takes any value of its type	project	This voice’s own model, over [elevenlabs or dtsp] model, which every voice of that provider reads unless it sets its own.
`stability`	number	`elevenlabs.stability`	must be between 0 and 1	project	This voice’s own stability, over [elevenlabs] stability, which every voice of that provider reads unless it sets its own.
`similarity_boost`	number	`elevenlabs.similarity_boost`	must be between 0 and 1	project	This voice’s own similarity_boost, over [elevenlabs] similarity_boost, which every voice of that provider reads unless it sets its own.
`style`	number	`elevenlabs.style`	must be between 0 and 1	project	This voice’s own style, over [elevenlabs] style, which every voice of that provider reads unless it sets its own.
`speaker_boost`	boolean	`elevenlabs.speaker_boost`	takes any value of its type	project	This voice’s own speaker_boost, over [elevenlabs] speaker_boost, which every voice of that provider reads unless it sets its own.
`output_format`	string	`elevenlabs.output_format`	must be one of mp3_22050_32, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192	project	This voice’s own output_format, over [elevenlabs] output_format, which every voice of that provider reads unless it sets its own.

voices.<name>.id The id is placed in the path of every speech request, so a value that could hold a slash, a dot or a query would let a project somebody else wrote send the key to another endpoint of the service.voices.<name>.speed The provider refuses a multiple outside its own range, so a slower read is a script change rather than a setting.voices.<name>.stability ElevenLabs takes a share and refuses anything else, so a value read as a percentage fails the request rather than the load.voices.<name>.output_format Every take already bought was bought in the format named here, so another one buys every take again.

The numbers that are not settings

These are the numbers that decide something and are still not settings. A derived number is written as its expression, so it follows the keys it reads at every frame size and every rate. A constant is a fact about a codec, a standard, or a tool DeckTalk drives, and it is fixed for the same reason a sample rate is. Neither can be set, and both are here so that a setting you cannot find is a number you can read.

Number	Kind	Formula	At the defaults	Why
`verify.probe_width`	derived	`the frame width video.size names // PROBE_SCALE`	480 pixels	Derived: every share is measured over the frame scaled down by PROBE_SCALE, at every frame size.
`verify.probe_height`	derived	`the frame height video.size names // PROBE_SCALE`	270 pixels	Derived: every share is measured over the frame scaled down by PROBE_SCALE, at every frame size.
`verify.block_width`	derived	`the frame width video.size names // BLOCK_PX`	240 pixels	Derived: one pixel per H.264 transform block, so the block average cancels the encoder’s ringing at every frame size rather than only at 1080p.
`verify.block_height`	derived	`the frame height video.size names // BLOCK_PX`	135 pixels	Derived: one pixel per H.264 transform block, so the block average cancels the encoder’s ringing at every frame size rather than only at 1080p.
`verify.reference_lead_seconds`	derived	`verify.cue_offset_max_ms / 1000 + GUARD_FRAMES / video.fps + verify.reference_lead_extra_ms / 1000`	0.14 seconds	Derived: the reference frame has to sit outside the window the offset limit allows, or the check compares a cue against a frame the same cue had already changed.
`record.truncated_slack_seconds`	derived	`1 / video.fps`	0.04 seconds	Derived: the recorder writes a section’s span rounded to the nearest whole frame, so a whole recording runs at most half a frame under it, and one more than a frame under it stopped early.
`SLOWEST_FPS`	constant	`25`	25 frames per second	Truth: the slowest rate a film is recorded at, whose frame is the step every page range is written in.
`PROBE_SCALE`	constant	`4`	4 times	Calibration: a frame a quarter the film’s size keeps every share a cue can move while comparing a sixteenth of the pixels.
`BLOCK_PX`	constant	`8`	8 pixels	Truth: the H.264 transform block the block-averaged copy of a frame cancels ringing over.
`GUARD_FRAMES`	constant	`1.5`	1.5 frames	Truth: half a frame of rounding guard on each side of the window the offset limit allows.
`CLICK_LEVEL_DBFS`	constant	`-24.0`	-24.0 dBFS	Truth: the level DeckTalk generates its own click at, which every click floor sits under.
`MEASURABLE_SPAN_SECONDS`	constant	`0.5`	0.5 seconds	Truth: the span at which an effect covers its own cue, which is the ceiling every declared span, every scaled span and every staggered total is held under.

Set the sections, the voice and the mix: decktalk.toml
Read the [verify] limits in context: Verify
Turn a key for one run: CLI

Get started

Use cases

Concepts

Guides

Reference

Agents

Design decisions

Help

Which value wins

Keys only a machine may set

Which key moves which failure

`[video]`

`[narration]`

`[record]`

`[audio]`

`[verify]`

`[mix]`

`[motion]`

`[elevenlabs]`

`[dtsp]`

`[score]`

`[score.ambience]`

`[score.effects]`

`[score.music]`

`[output]`

`[events]`

`[tools]`

`[voices]`

The numbers that are not settings

​Which value wins

​Keys only a machine may set

​Which key moves which failure

​[video]

​[narration]

​[record]

​[audio]

​[verify]

​[mix]

​[motion]

​[elevenlabs]

​[dtsp]

​[score]

​[score.ambience]

​[score.effects]

​[score.music]

​[output]

​[events]

​[tools]

​[voices]

​The numbers that are not settings

​Related

Which value wins

Keys only a machine may set

Which key moves which failure

`[video]`

`[narration]`

`[record]`

`[audio]`

`[verify]`

`[mix]`

`[motion]`

`[elevenlabs]`

`[dtsp]`

`[score]`

`[score.ambience]`

`[score.effects]`

`[score.music]`

`[output]`

`[events]`

`[tools]`

`[voices]`

The numbers that are not settings

Related