decktalk.toml

Each project has one decktalk.toml. Every path in it is relative to the project directory. An unknown top-level table fails the load, so a typo cannot silently do nothing, and a value of the wrong type fails with the table and key named. The file has two kinds of content. The document tables on this page describe the presentation. The tuning tables change how DeckTalk renders and are rarely needed.

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"

`[project]`

Key	Default	Meaning
`name`	the directory name	The output name. The video lands at `build/out/<name>.mp4`, with `<name>.srt`, `<name>.vtt`, and `<name>.chapters.txt` beside it.
`script`	`script.md`	The narration file.
`cues`	`cues.json`	The cue file. It is optional, and without it pages run their built-in timing.
`build`	`build`	The directory for generated files.

`[voice]`

The voice settings for this presentation. The voice id and the API key are secrets, so they live in .env as ELEVENLABS_VOICE_ID and ELEVENLABS_API_KEY, or in the environment.

Key	Default	Meaning
`provider`	`elevenlabs`	The speech provider, by the name it registered. ElevenLabs is the only one today.
`model`	`[narration]` `model`, which defaults to `eleven_multilingual_v2`	The ElevenLabs model id. The `--model` flag overrides it for one run.
`stability`	0.55	Lower values vary more between takes.
`similarity_boost`	0.75	How closely the voice follows the clone.
`style`	0.0	Style exaggeration. Zero is the most stable.
`speaker_boost`	true	ElevenLabs’ speaker boost.
`speed`	1.0	Speaking rate.

A change to any of these changes the cache key of every section, so the next build synthesizes everything again.

`[[section]]`

Write one table per ## N. section of the script. The order in the file does not matter, because DeckTalk sorts them by number, and a duplicate number fails the load. Every script section must have one. A section is either a page or a clip, and a table with both keys fails.

Key	Applies to	Default	Meaning
`number`	both	required	The number that matches `## N.` in the script.
`title`	both	empty	The title shown on slates, in the status report, and as the chapter title.
`page`	page	required	The HTML file, for example `deck/index.html`.
`scene`	page	the section number	The value the page receives as `?scene=`. It may be a number or a string.
`extra_seconds`	page	0.3	How long the recording runs past the narration. The margin keeps the cut off a frame that was never drawn.
`hold_seconds`	page	0	How long the last frame holds after the narration, by cloning it. Only the last page section may hold, because the narration is continuous and an earlier hold would push every later visual off its words.
`ambience`	page	false	Whether the ambience bed plays under this section.
`params`	page	none	Extra query parameters for the page, written as a table such as `[section.params]` with `theme = "dark"`. A `beats` key here replaces the resolved cues.
`clip`	clip	required	Your video file, with its own audio. It is scaled and padded to the frame size. Add a clip section says where a clip may sit.
`slate_seconds`	clip	5	How long the titled slate plays when the clip file is missing.

A missing clip is not an error unless you pass --strict. A titled slate plays for slate_seconds in its place, so a project builds before every asset exists.

`[transition]`

Key	Default	Meaning
`dips`	every cut	The boundaries that dip to black, written as `[[from, to], …]` section numbers. Leave the key out to dip at every cut, or set `[]` for no dips. A pair that names a section that does not exist fails the load.
`dip_seconds`	0.15	The fade length, quantized to whole frames. It applies to video only, and audio never dips.
`page_fades_in`	true	Pages fade themselves up, so DeckTalk adds no fade-in on their side of a dip.

`[mix]`

The mix is optional. Without this table the video carries narration and clip audio only. Sound explains how the parts fit together.

Key	Default	Meaning
`underscore`	none	The music bed. DeckTalk loops it and ducks it under speech.
`underscore_db`	-24	The bed level.
`underscore_duck_db`	-6	The additional attenuation under speech.
`underscore_fade_in`	2	The fade-in length in seconds.
`underscore_fade_out`	3	The fade-out length in seconds.
`markers`	none	A JSON file that swells or mutes the bed at spoken phrases.
`ambience`	none	The ambience bed. It plays under sections that set `ambience = true`.
`ambience_db`	-20	The ambience level.
`slate`	rendered	A PNG to use instead of the rendered titled slate.

`[[mix.sfx]]`

One table per one-shot effect. Put a sound effect on a cue walks through one.

Key	Default	Meaning
`file`	required	The audio file.
`section`	required	The section number whose cue places it. It must exist.
`cue`	required	A cue id that `beats` resolved for that section.
`db`	-16	The level.
`offset`	0	Seconds added to the cue time.

`[mix.loudnorm]`

The targets for the loudness pass, which How it works describes. The keys are accepted in upper or lower case.

Key	Default	Meaning
`I`	-16	Integrated loudness in LUFS.
`TP`	-1.5	The true-peak ceiling in dBTP.
`LRA`	11	The loudness range in LU, passed to the measurement.

`[soundscape]`

These tables hold the prompts for decktalk soundscape, which generates sound with ElevenLabs. Ambience and music write to the ambience and underscore paths named in [mix]. When [mix] names none, they write to build/sfx/ambience.mp3 and build/music/underscore.mp3. Each effect writes to build/sfx/<name>.mp3 unless its out key says otherwise.

`[soundscape.ambience]`

Key	Default	Meaning
`text`	required	The prompt.
`duration_seconds`	`[elevenlabs]` `ambience_seconds`, 25	The length to request. The bed loops.
`prompt_influence`	`[elevenlabs]` `ambience_prompt_influence`, 0.3	How closely the sound follows the prompt.
`model_id`	`[elevenlabs]` `sound_model`	The sound model.
`out`	the `[mix]` path	Where to write the file.

`[soundscape.sfx.<name>]`

Key	Default	Meaning
`text`	required	The prompt.
`duration_seconds`	`[elevenlabs]` `sfx_seconds`, 0.5	The length to request.
`prompt_influence`	`[elevenlabs]` `sfx_prompt_influence`, 0.5	How closely the sound follows the prompt.
`model_id`	`[elevenlabs]` `sound_model`	The sound model.
`out`	`build/sfx/<name>.mp3`	Where to write the file.

`[soundscape.music]`

Key	Default	Meaning
`prompt`	required	The prompt.
`seconds`	360	The length to request. Longer than `max_music_chunk_seconds` is requested in chunks and crossfaded.
`force_instrumental`	true	No vocals.
`model_id`	`[elevenlabs]` `music_model`	The music model.
`out`	the `[mix]` path	Where to write the file.

Tuning tables

Any settings section can be overridden per project with a table of the same name, such as [video] or [record], or per shell with a DECKTALK_<SECTION>_<FIELD> variable. Configuration lists every field with its default.

Get started

Guides

Concepts

Reference

Help

`[project]`

`[voice]`

`[[section]]`

`[transition]`

`[mix]`

`[[mix.sfx]]`

`[mix.loudnorm]`

`[soundscape]`

`[soundscape.ambience]`

`[soundscape.sfx.<name>]`

`[soundscape.music]`

Tuning tables

​[project]

​[voice]

​[[section]]

​[transition]

​[mix]

​[[mix.sfx]]

​[mix.loudnorm]

​[soundscape]

​[soundscape.ambience]

​[soundscape.sfx.<name>]

​[soundscape.music]

​Tuning tables

`[project]`

`[voice]`

`[[section]]`

`[transition]`

`[mix]`

`[[mix.sfx]]`

`[mix.loudnorm]`

`[soundscape]`

`[soundscape.ambience]`

`[soundscape.sfx.<name>]`

`[soundscape.music]`

Tuning tables