decktalk.toml

decktalk.toml is the project file. It maps each section to a page or a clip, and it sets the voice, the transitions, and the sound. Use this page to look up a table or a key and its default. The file sits in the project root. Every path in it is relative to that directory.

Minimal file

The smallest file that loads has one page section.

decktalk.toml

[[section]]
number = 1
page = "deck/index.html"

decktalk init writes a nine-section file with comments. Sections 5 and 7 are optional clip sections. This fuller example adds a clip section, a dip to black, and an underscore.

decktalk.toml

[project]
name = "my-lesson"

[voice]
stability = 0.55

[[section]]
number = 0
title = "On camera"
clip = "media/open.mp4"

[[section]]
number = 1
title = "Open"
page = "deck/index.html"
scene = 1

[transition]
dips = [[0, 1]]

[mix]
underscore = "build/music/underscore.mp3"

Load rules

Every project command loads decktalk.toml first. The load fails in each of these cases.

A top-level table is unknown.
The file has no [[section]] table.
A required key is missing.
A value has the wrong type. For example, seconds = 120.5 under [soundscape.music] fails.
Two sections share a number.
A section has both page and clip, or neither.
extra_seconds, hold_seconds, lead_seconds, or tail_seconds is below 0.
carries_previous is set on the first section.
A dips pair or a [[mix.sfx]] table names a section that does not exist.

The error names the table and the key.

decktalk.toml: [soundscape.music]: 'seconds' must be int, got float

An unknown key inside a table does not fail the load. DeckTalk prints a warning, ignores the key, and continues. The same rule covers the tuning tables and the per-machine file.

decktalk.toml: [voice]: ignoring unknown key 'stabilty' (did you mean 'stability'?)

A page section key on a clip section, or a clip section key on a page section, gets its own warning. The warning names the section kind that the key belongs to.

Which value wins

--model wins over [voice] model, which wins over [narration] model.
A tuning table in decktalk.toml wins over the per-machine file. A DECKTALK_<TABLE>_<FIELD> variable and a command option win over both.
The project tables on this page have no environment variables.

Configuration lists the five layers for tuning tables.

`[project]`

Key	Type	Default	Meaning
`name`	string	the directory name	Output name. The video is `build/out/<name>.mp4`.
`script`	path	`script.md`	Script file.
`cues`	path	`cues.json`	Cue file. Optional. Without it, pages use their own timing.
`build`	path	`build`	Directory for generated files.

`[voice]`

[voice] sets how the voice sounds. The API key and the voice id are secrets, so they live in .env as ELEVENLABS_API_KEY and ELEVENLABS_VOICE_ID, or in the environment.

Key	Type	Default	Meaning
`provider`	string	`elevenlabs`	Registered speech provider name.
`model`	string	`= [narration] model`	Speech model id, such as `eleven_multilingual_v2`.
`stability`	number	0.55	Lower values vary more between takes.
`similarity_boost`	number	0.75	How closely the voice follows its source voice.
`style`	number	0.0	Style exaggeration. 0 is the most stable.
`speaker_boost`	boolean	true	ElevenLabs speaker boost.
`speed`	number	1.0	Speaking rate.

Note: each key is part of every section’s cache key. After a change, the next voiced build voices every section again. What spends credits lists every change that costs credits. An unregistered provider fails when narrate runs, not at load.

`[[section]]`

Write one [[section]] table for each ## N. section of the script. DeckTalk sorts sections by number, so the order in the file does not matter. Each section is a page section or a clip section.

Keys for every section

Key	Type	Default	Meaning
`number`	integer	required	Matches `## N.` in the script.
`title`	string	empty	Chapter title and slate title. An empty title becomes `Section N`. Consecutive sections with the same title share one chapter.
`carries_previous`	boolean	false	The section opens on the previous section’s last picture. `verify` flags a visible jump at the cut as `POP AT CUT`. Not allowed on the first section.

Page section keys

Key	Type	Default	Meaning
`page`	path	required	HTML file, such as `deck/index.html`.
`scene`	integer or string	`= number`	Value the page receives as `?scene=`.
`extra_seconds`	number	0.3	Seconds the recording runs past the section span.
`hold_seconds`	number	0	Seconds the section’s last frame holds after its narration. The narration pauses for the hold.
`lead_seconds`	number	0	Seconds of silence before the section’s first word.
`tail_seconds`	number	`[narration] min_tail_seconds`	Shortest silence after the section’s last word.
`ambience`	boolean	false	Plays the ambience bed under this section.
`params`	table	none	Extra query parameters for the page, written as `[section.params]`.

Note: params values become strings. A beats key replaces the cue times, a scene key replaces scene, a words key replaces the spoken words, and a prevwords key replaces the previous section’s words. t0 is always signal, whatever params says.

Silence in a section

Three keys add silence to a page section. None of them is sent to the voice or changes the narration cache, so a cached take stays cached.

Key	Where the silence goes	How DeckTalk adds it
`lead_seconds`	Before the first word	`narrate` joins it into `narration.mp3` before the take. The take is not changed.
`tail_seconds`	After the last word	`narrate` pads the take, as it does for `min_tail_seconds`.
`hold_seconds`	After the section’s narration	`assemble` holds the last frame, and the narration waits.

The section starts when its silence starts. So lead_seconds moves every word and every word cue of the section later, and $start stays at 0.
The recording covers the lead, because the section span in timeline.json includes it.
tail_seconds is a least value, like min_tail_seconds. A take that already has a longer tail keeps it.
A hold on any page section pauses the narration, as a clip between page sections does. The next section starts after the hold, on its own words.
A [pause N] before a section’s first words is removed. Use lead_seconds to open a section on silence.

decktalk.toml

[[section]]
number = 4
title = "The edit"
page = "deck/index.html"
lead_seconds = 1.5    # the page shows 1.5 s before the first word
hold_seconds = 2      # the last frame stays 2 s before section 5

Set carries_previous = true when a section continues the previous section’s picture, such as a page that opens where the last page ended. verify compares the two frames at the cut, outside any dip. A dip still fades through black, so leave the pair out of [transition] dips for a cut that should not show. Cut continuity defines the check.

Clip section keys

Key	Type	Default	Meaning
`clip`	path	required	Your video file. It keeps its own audio.
`slate_seconds`	number	5	Seconds the titled slate plays when the file is missing.
`optional`	boolean	false	Plays the slate for a missing clip, even under `--strict`.
`words`	path	none	A words file of the speech inside the clip. The captions add these words at the clip’s start.

A clip section follows three rules.

A clip section can sit before, between, or after page sections.
The narration pauses for a clip between page sections, and resumes with the next page section.
If the file is missing, a titled slate plays for slate_seconds. With --strict, assemble and build fail instead, unless the section sets optional = true.

Set optional = true while the clip is not ready. Delete that line after you add the clip. DeckTalk scales and pads the clip to the frame size. A clip section has captions only when it sets words, and chapters include the clip. Add a clip section shows the whole task.

`[transition]`

Key	Type	Default	Meaning
`dips`	array of [integer, integer]	every cut	Boundaries that dip to black, as `[[from, to], …]`.
`dip_seconds`	number	0.15	Fade length, rounded to whole frames. Video only.
`page_fades_in`	boolean	true	Pages fade themselves in, so the cut adds no fade-in to a page section.

Note: leave out dips to dip at every cut. Set dips = [] for no dips. Audio never dips.

`[mix]`

[mix] is optional. Without it, the video carries narration and clip audio only. Sound explains how the parts fit together.

Key	Type	Default	Meaning
`underscore`	path	none	Music under the whole video. Loops, and ducks under speech and clips.
`underscore_db`	number	-24	Underscore level in dB.
`underscore_duck_db`	number	-6	Extra level change in dB under each spoken span and clip.
`underscore_fade_in`	number	2	Fade-in seconds.
`underscore_fade_out`	number	3	Fade-out seconds.
`markers`	path	none	A markers file. See `markers.json`.
`ambience`	path	none	Ambience bed for sections that set `ambience = true`.
`ambience_db`	number	-20	Ambience level in dB.
`slate`	path	a rendered slate	PNG for every missing clip, instead of the rendered titled slate.

Note: a missing underscore or ambience file does not fail the build. assemble logs a warning, such as underscore missing (<path>); no music, and plays the video without it.

`[[mix.sfx]]`

Write one [[mix.sfx]] table for each sound effect. Put a sound effect on a cue shows the task.

Key	Type	Default	Meaning
`file`	path	required	Audio file.
`section`	integer	required	Section whose cue places the sound effect. Must exist.
`cue`	string	required	Cue id that `beats` resolved in that section.
`db`	number	-16	Level in dB.
`offset`	number	0	Seconds added to the cue time.

Note: this offset belongs to the sound effect, not to the cue. A missing file or an unresolved cue does not fail the build. assemble logs skipped for that sound effect.

`[mix.loudnorm]`

[mix.loudnorm] sets the targets of the loudness pass. Loudness explains the pass.

Key	Type	Default	Meaning
`I`	number	-16	Integrated loudness target in LUFS.
`TP`	number	-1.5	True-peak ceiling in dBTP.
`LRA`	number	11	Loudness range in LU, passed to the measurement.

Note: the keys work in upper or lower case. A silent build skips the loudness pass.

`markers.json`

A markers file swells or mutes the underscore at spoken phrases. [mix] markers names it, and the scaffold’s file is media/markers.json.

media/markers.json

{
  "_comment": "Underscore structure. Each marker swells the bed by boost_db for boost_seconds at a spoken phrase (or $start/$end of a section); mute_seconds silences it for one beat first.",
  "boost_db": 3,
  "boost_seconds": 2,
  "markers": [
    { "name": "open", "section": 1, "on": "$start" }
  ]
}

Key	Type	Default	Meaning
`boost_db`	number	3	dB the underscore rises at each marker.
`boost_seconds`	number	2	Seconds each swell lasts.
`markers`	array of objects	none	The markers.

Marker key	Type	Default	Meaning
`name`	string	none	Name in warnings.
`section`	integer	required	Section number.
`on`	string	`$start`	Spoken phrase, `$start`, or `$end`.
`offset`	number	0	Seconds added to the marker time.
`occurrence`	integer	1	Which match of the phrase.
`case_sensitive`	boolean	false	Matches case when true.
`mute_seconds`	number	0	Seconds the underscore is silent before the swell.

Markers apply only when the underscore file exists. --nomix turns them off.
$start works on any section. A phrase or $end needs a spoken section.
A phrase matches by the same rules as a cue phrase.
If the file is missing, assemble logs markers file missing (<path>); underscore without structure.
If a marker does not resolve, assemble logs marker '<name>' unresolved; skipped.
A file that is not valid JSON fails assemble with a ConfigError.

`[soundscape]`

[soundscape] holds the prompts for decktalk soundscape, which generates sound with ElevenLabs. Each item writes to a default path unless its out key names another.

[soundscape.ambience] writes to [mix] ambience, else to build/sfx/ambience.mp3.
[soundscape.music] writes to [mix] underscore, else to build/music/underscore.mp3.
[soundscape.sfx.<name>] writes to build/sfx/<name>.mp3.

`[soundscape.ambience]`

Key	Type	Default	Meaning
`text`	string	required	Prompt.
`duration_seconds`	number	`= [elevenlabs] ambience_seconds` (25)	Length to request. The bed loops.
`prompt_influence`	number	`= [elevenlabs] ambience_prompt_influence` (0.3)	How closely the sound follows the prompt.
`model_id`	string	`= [elevenlabs] sound_model`	Sound model id.
`out`	path	`= [mix] ambience`	Output file.

`[soundscape.sfx.<name>]`

Key	Type	Default	Meaning
`text`	string	required	Prompt.
`duration_seconds`	number	`= [elevenlabs] sfx_seconds` (0.5)	Length to request.
`prompt_influence`	number	`= [elevenlabs] sfx_prompt_influence` (0.5)	How closely the sound follows the prompt.
`model_id`	string	`= [elevenlabs] sound_model`	Sound model id.
`out`	path	`build/sfx/<name>.mp3`	Output file.

`[soundscape.music]`

Key	Type	Default	Meaning
`prompt`	string	required	Prompt.
`seconds`	integer	360	Length to request. A decimal such as `120.5` fails the load.
`force_instrumental`	boolean	true	No vocals when true.
`model_id`	string	`= [elevenlabs] music_model`	Music model id.
`out`	path	`= [mix] underscore`	Output file.

Note: a length above [elevenlabs] max_music_chunk_seconds (300) is requested in parts, and DeckTalk crossfades the parts. The scaffold sets seconds = 120.

Tuning tables

decktalk.toml can also hold the tuning tables, such as [video] or [record]. A tuning table in the project overrides the per-machine file. Configuration lists every field with its default.

Write the script: script.md
Tie a reveal to a phrase: cues.json
Tune a build: Configuration

Get started

Guides

Concepts

Reference

Help

Minimal file

Load rules

Which value wins

`[project]`

`[voice]`

`[[section]]`

Keys for every section

Page section keys

Silence in a section

Clip section keys

`[transition]`

`[mix]`

`[[mix.sfx]]`

`[mix.loudnorm]`

`markers.json`

`[soundscape]`

`[soundscape.ambience]`

`[soundscape.sfx.<name>]`

`[soundscape.music]`

Tuning tables

​Minimal file

​Load rules

​Which value wins

​[project]

​[voice]

​[[section]]

​Keys for every section

​Page section keys

​Silence in a section

​Clip section keys

​[transition]

​[mix]

​[[mix.sfx]]

​[mix.loudnorm]

​markers.json

​[soundscape]

​[soundscape.ambience]

​[soundscape.sfx.<name>]

​[soundscape.music]

​Tuning tables

​Related

Minimal file

Load rules

Which value wins

`[project]`

`[voice]`

`[[section]]`

Keys for every section

Page section keys

Silence in a section

Clip section keys

`[transition]`

`[mix]`

`[[mix.sfx]]`

`[mix.loudnorm]`

`markers.json`

`[soundscape]`

`[soundscape.ambience]`

`[soundscape.sfx.<name>]`

`[soundscape.music]`

Tuning tables

Related