The project file

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. 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 = 1
title = "Open"
page = "deck/index.html"

[[section]]
number = 2
title = "On camera"
clip = "media/interview.mp4"

[transition]
dips = [[1, 2]]

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

`[project]`

Key	Default	Meaning
`name`	the directory name	The output name. The film lands at `build/out/<name>.mp4`.
`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]`

These are the voice settings for this presentation. The model key overrides the tool default, which is eleven_multilingual_v2 unless [narration] says otherwise.

Key	Default	Meaning
`provider`	`elevenlabs`	The speech provider. ElevenLabs is the only one today.
`model`	the tool default	The ElevenLabs model id.
`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.

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.

`[[section]]`

Write one table per ## N. section of the script. The order does not matter, because DeckTalk sorts them by number. Every script section must have one. A section is either a page or a clip.

Key	Applies to	Default	Meaning
`number`	both	required	The number that matches `## N.` in the script.
`title`	both	empty	The title shown on slates and in the status report.
`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 an undrawn frame.
`hold_seconds`	page	0	How long the last frame holds. 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"`.
`clip`	clip	required	Your video file, with its own audio.
`slate_seconds`	clip	5	How long the titled slate plays when the clip file is missing.

A clip that is not 1920 by 1080 is scaled and padded to fit. 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.
`dip_seconds`	0.15	The fade length. 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 film 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`, `underscore_fade_out`	2, 3	The fade lengths 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]]`	none	One-shot effects. Each has `file`, `section`, `cue`, `db` (default -16), and `offset` (default 0).
`[mix.loudnorm]`	`I = -16`, `TP = -1.5`, `LRA = 11`	The EBU R128 targets for the final mix.

`[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 sound effect writes to build/sfx/<name>.mp3 unless its out key says otherwise.

Table	Keys
`[soundscape.ambience]`	`text` (required), `duration_seconds` (25), `prompt_influence` (0.3), `model_id`, `out`
`[soundscape.sfx.<name>]`	`text` (required), `duration_seconds` (0.5), `prompt_influence` (0.5), `model_id`, `out`
`[soundscape.music]`	`prompt` (required), `seconds` (360), `force_instrumental` (true), `model_id`, `out`

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.

`script.md`

The script is markdown with one rule. Each ## N. Title heading starts section N, and the text under it is what the voice says for that section.

Text in square brackets, such as [Deck scene 3.], is a stage direction. It is not spoken, and a short pause is left where it sat.
A bracket in capitals, such as [NAME], is a placeholder. The narrate stage refuses to synthesize a section that still has one unless you pass --allow-placeholders.
A tag such as <break time="1.0s"/> inserts a pause of that length.
Other markdown, such as emphasis, is stripped before synthesis.

`cues.json`

The cue file names the spoken phrase that each visual lands on. Cues describes its shape and the matching rules.

Get started

Concepts

Reference

Help

`[project]`

`[voice]`

`[[section]]`

`[transition]`

`[mix]`

`[soundscape]`

Tuning tables

`script.md`

`cues.json`

​[project]

​[voice]

​[[section]]

​[transition]

​[mix]

​[soundscape]

​Tuning tables

​script.md

​cues.json

`[project]`

`[voice]`

`[[section]]`

`[transition]`

`[mix]`

`[soundscape]`

Tuning tables

`script.md`

`cues.json`