Configuration

Tuning fields change how DeckTalk records, assembles, and checks a video. This page lists every field, grouped by table, with its type and its default. A tuning table can go in the project’s decktalk.toml. The same field can also come from an environment variable.

decktalk.toml

[video]
preset = "veryfast"

DECKTALK_VIDEO_PRESET=veryfast decktalk build --silent

The scaffold builds with every default. Change [video] for faster drafts. Change [verify] when a small reveal fails the cue check.

Which value wins

Five layers can set a field. Each layer overrides the layers before it.

The default on this page.
The same table in the per-machine settings file.
The same table in the project’s decktalk.toml.
An environment variable named DECKTALK_<TABLE>_<FIELD>, such as DECKTALK_VIDEO_PRESET.
A command-line flag, for one run.

The per-machine settings file is in a different place on each platform.

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

Note: DECKTALK_CONFIG points at a different file. The per-machine file can hold only the tables on this page, and any other table fails the load. decktalk doctor prints the path in its config row. An environment variable for an array field takes comma-separated values, such as DECKTALK_VERIFY_PROBE_DELAYS=0.7,1.5. Four flags override a field for one run.

Flag	Commands	Overrides
`--preset`	`assemble`, `build`	`[video] preset`
`--crf`	`assemble`, `build`	`[video] crf`
`--settle`	`record`	`[record] settle_seconds`
`--model`	`narrate`	`[narration] model` and `[voice] model`

Sections, the voice, mix levels, and soundscape prompts are project content, not tuning. decktalk.toml lists those tables. Secrets go only in .env.

`[video]`

These keys set the frame size and the encoding of every recording and of the final mp4. Environment variables start with DECKTALK_VIDEO_.

Field	Type	Default	Meaning
`width`	`integer`	`1920`	Frame width in pixels, for every recording and the final mp4.
`height`	`integer`	`1080`	Frame height in pixels, for every recording and the final mp4.
`fps`	`integer`	`25`	Frames per second. Chromium records at 25 fps, so 25 avoids a pulldown that duplicates every sixth frame.
`preset`	`string`	`"medium"`	x264 preset. Use veryfast for drafts.
`crf`	`integer`	`18`	x264 quality. A lower value gives higher quality and a larger file.
`audio_bitrate`	`string`	`"192k"`	AAC bitrate of the final mp4.
`sample_rate`	`integer`	`48000`	Audio sample rate of the final mp4. Every audio input is resampled to it once.
`channels`	`integer`	`2`	Audio channels of the final mp4.
`slate_color`	`string`	`"0x0e1116"`	Color of the plain frame that plays when a slate image cannot be rendered.

`[narration]`

These keys govern how the script is turned into audio. Environment variables start with DECKTALK_NARRATION_.

Field	Type	Default	Meaning
`model`	`string`	`"eleven_multilingual_v2"`	Speech model. `[voice] model` and `narrate --model` override it.
`output_format`	`string`	`"mp3_44100_128"`	Audio format that the speech provider returns. It is part of the narration cache key.
`mp3_bitrate`	`string`	`"128k"`	Bitrate of the mp3 files that DeckTalk writes. They include click tracks and `narration.mp3`.
`words_per_minute`	`integer`	`140`	Pacing of the estimated length in the `narrate` table.
`silent_words_per_minute`	`integer`	`150`	Pacing of the click track in a silent build.
`lead_break_seconds`	`number`	`0.7`	Silence before the first spoken section.
`direction_break_seconds`	`number`	`0.7`	Seconds that each beat adds to the length of a silent build’s section.
`min_tail_seconds`	`number`	`0.7`	Shortest silence after the last word of a section, so a cut never falls on speech.
`tail_slack_seconds`	`number`	`0.05`	Extra silence added when `narrate` pads a short tail.
`context_chars`	`integer`	`1500`	Characters of each neighbor section sent with a request, for continuous prosody.
`timeout_seconds`	`integer`	`180`	Seconds before a speech request times out.

`[record]`

These keys tune the headless Chromium recording. Environment variables start with DECKTALK_RECORD_.

Field	Type	Default	Meaning
`settle_seconds`	`number`	`0.5`	Shortest wait after the page is ready and before narration t=0. `record --settle` overrides it.
`min_lead_seconds`	`number`	`1.5`	Shortest time from the start of the recorder to narration t=0.
`color_scheme`	`string`	`"light"`	Color scheme that Chromium reports to the page, such as `light` or `dark`.
`retries`	`integer`	`2`	How many more times `record` records a section whose frames stalled.
`shot_settle_ms`	`integer`	`400`	Milliseconds that `decktalk shots` waits before each step screenshot.

`[align]`

These keys tune how narration t=0 is found in a recording, and the recording sanity check. Environment variables start with DECKTALK_ALIGN_.

Field	Type	Default	Meaning
`scan_seconds`	`number`	`4.0`	Seconds at the start of each recording that `measure` scans for the magenta cover.
`fallback_first_paint_seconds`	`number`	`1.1`	Guessed first paint if `measure` finds no cover and no painted frame. `measure` adds `settle_seconds` to it.
`magenta_luma_min`	`number`	`70`	A cover frame has an average luma above this.
`magenta_luma_max`	`number`	`140`	A cover frame has an average luma below this.
`magenta_chroma_min`	`number`	`165`	A cover frame has an average U and an average V above this.
`painted_ymax`	`number`	`60`	A painted frame has a brightest luma above this.
`painted_yavg_max`	`number`	`120`	A painted frame has an average luma below this, so a white flash does not count.
`black_ymax`	`number`	`40`	`check` reports `BLACK?` when the brightest luma of the middle frame is below this.
`truncated_slack_seconds`	`number`	`0.5`	Allowed shortfall of a recording against its requested length. A larger shortfall makes `check` report `TRUNCATED`.
`stall_ms`	`integer`	`150`	Longest frame gap after narration t=0, in milliseconds. A longer gap makes `record` try again and `check` report `STALLED`.

`[audio]`

These keys set the mix mechanics. Levels live in [mix] in decktalk.toml. Environment variables start with DECKTALK_AUDIO_.

Field	Type	Default	Meaning
`duck_ramp_seconds`	`number`	`0.5`	Ramp of the underscore duck at each edge of a spoken span or a clip.
`ambience_ramp_seconds`	`number`	`1.0`	Ramp of the ambience bed at each edge of its span.
`ambience_pad_seconds`	`number`	`0.5`	Seconds that the ambience bed extends past each edge of its section.
`marker_mute_ramp_seconds`	`number`	`0.04`	Ramp into and out of a marker’s mute.
`marker_boost_ramp_seconds`	`number`	`0.3`	Ramp into and out of a marker’s swell.

`[verify]`

These keys tune the checks on the assembled mp4. Environment variables start with DECKTALK_VERIFY_.

Field	Type	Default	Meaning
`after_dip_seconds`	`number`	`0.2`	Seconds after a section start to the frame that the start check reads.
`lead_seconds`	`number`	`0.1`	Reference lead. It has an effect only above (`max_offset_frames` + 1.5) / `fps`, which is 0.14 s at the defaults.
`probe_delays`	`array of numbers`	`[0.7, 1.5]`	Seconds after the cue time for each probe. The later probe catches a slow reveal.
`diff_level`	`integer`	`40`	Luma difference that a pixel must exceed to count as changed, for probes and control shares.
`min_changed_percent`	`number`	`0.1`	Smallest changed share, in percent, that the reported probe needs.
`min_margin_percent`	`number`	`0.1`	Smallest margin, in percentage points, that the reported probe needs.
`thin_change_factor`	`number`	`3.0`	A passing cue whose changed share or margin is below this many times its floor reads `THIN CHANGE?`, an uncertain finding. 1 turns the warning off.
`onset_percent`	`number`	`0.01`	Rise in changed share from one frame to the next that marks the onset. It is in percentage points. 0.01 is about 13 pixels.
`onset_diff_level`	`integer`	`12`	Luma difference that a pixel must exceed to count as changed, for the onset scan only.
`click_search_seconds`	`number`	`0.25`	Seconds on each side of the cued word’s start that the click search covers.
`max_offset_frames`	`integer`	`2`	Offset limit, in frames. The onset can sit this far from the cue time, early or late.
`max_av_frames`	`integer`	`3`	a/v limit, in frames, early or late. It is wider because the click carries encoding jitter too.
`visible_ymax`	`number`	`60`	The start check reports `BLACK` when the brightest luma of its frame is at most this.
`cut_window_seconds`	`number`	`0.15`	Seconds of narration before each cut that the cut check measures.
`cut_max_db`	`number`	`-40.0`	Loudest RMS level of the cut window, in dBFS, that passes the cut check.
`max_pop_percent`	`number`	`0.1`	Largest changed share, in percent, across the cut into a section that sets `carries_previous`. A larger share reads `POP AT CUT`.
`probe_width`	`integer`	`480`	Width in pixels that frames are scaled to before a comparison.
`probe_height`	`integer`	`270`	Height in pixels that frames are scaled to before a comparison.
`block_width`	`integer`	`240`	Width in pixels of the block-averaged copy of each frame that confirms an onset. Each pixel then averages an 8 by 8 block of a 1080p frame, the size of an H.264 transform block. The encoder can shift a few pixels of a still picture by up to about 15 levels in the frames just before a change. The average cancels that ringing, so a frame is the onset only when a block also changed.
`block_height`	`integer`	`135`	Height in pixels of the block-averaged copy of each frame that confirms an onset.

`[elevenlabs]`

These keys point at the ElevenLabs API and size its soundscape requests. Environment variables start with DECKTALK_ELEVENLABS_.

Field	Type	Default	Meaning
`api_base`	`string`	`"https://api.elevenlabs.io/v1"`	Base URL of the ElevenLabs API.
`sound_model`	`string`	`"eleven_text_to_sound_v2"`	Model for ambience and sound effect requests. A soundscape table can name its own.
`music_model`	`string`	`"music_v2"`	Model for music requests. A soundscape table can name its own.
`music_bitrate`	`string`	`"192k"`	Bitrate of the music file that `soundscape` joins from its chunks.
`max_music_chunk_seconds`	`integer`	`300`	Longest music request. Longer music is requested in chunks.
`music_crossfade_seconds`	`integer`	`2`	Crossfade between two music chunks.
`ambience_seconds`	`number`	`25.0`	Length of a generated ambience bed. A soundscape table can set `duration_seconds` instead.
`ambience_prompt_influence`	`number`	`0.3`	Prompt influence of an ambience request. A soundscape table can set its own.
`sfx_seconds`	`number`	`0.5`	Length of a generated sound effect. A soundscape table can set `duration_seconds` instead.
`sfx_prompt_influence`	`number`	`0.5`	Prompt influence of a sound effect request. A soundscape table can set its own.
`timeout_seconds`	`integer`	`600`	Seconds before a sound or music request times out.

Set sections, the voice, and the mix: decktalk.toml
Understand the [verify] fields: Verify
Override a field for one run: CLI

Get started

Guides

Concepts

Reference

Help

Which value wins

`[video]`

`[narration]`

`[record]`

`[align]`

`[audio]`

`[verify]`

`[elevenlabs]`

​Which value wins

​[video]

​[narration]

​[record]

​[align]

​[audio]

​[verify]

​[elevenlabs]

​Related

Which value wins

`[video]`

`[narration]`

`[record]`

`[align]`

`[audio]`

`[verify]`

`[elevenlabs]`

Related