Python API

The decktalk package runs the same pipeline as the command line. This page lists every public name, with its signature, its result, and the errors it raises.

import decktalk

project = decktalk.Project.load("my-lesson")       # reads and validates decktalk.toml
project.settings.video.preset = "veryfast"
result = decktalk.build(project, silent=True)
print(result.assembly.final, result.verification.ok)

Each stage function takes a Project and returns a typed result. It logs progress to the decktalk logger. It raises a DeckTalkError subclass when it fails, and it never calls sys.exit.

Public names

The package exports these names. Every other name is internal.

Kind	Names
Project	`Project`, `Section`, `PageSection`, `ClipSection`, `Settings`, `load_settings`
Project tables	`Voice`, `Transition`, `Mix`, `Soundscape`
Artifacts	`Manifest`, `Timeline`, `Beats`, `Word`, `Sidecar`
Stages	`narrate`, `resolve_beats`, `preflight`, `record`, `measure`, `check`, `assemble`, `verify`, `shoot`, `soundscape`, `build`, `status`, `cut_clip`, `spoken_words`
Results	`NarrateResult`, `BeatsResult`, `PreflightResult`, `Recording`, `LeadMeasurement`, `RecordingCheck`, `AssembleResult`, `VerifyResult`, `SoundscapeItem`, `BuildResult`, `StatusReport`, `ClipResult`, `SectionWords`
Errors	`DeckTalkError`, `ConfigError`, `MissingInputError`, `ProviderError`, `ToolError`
Speech	`SpeechProvider`, `SpeechRequest`, `register`
Version	`__version__`

Note: Everything under decktalk.media is internal. So is everything under decktalk.providers except the three speech names, and every name that starts with an underscore.

`Project`

decktalk.Project.load(where=None, *, environ=None) -> Project
decktalk.Project.from_toml(root, doc, *, environ=None) -> Project

Project.load reads and validates decktalk.toml. Project.from_toml builds a project from a mapping you have already parsed.

Parameter	Default	Meaning
`where`	`DECKTALK_PROJECT`, then the current directory	Project directory, or the path of its `decktalk.toml`.
`root`	required	Project directory, for `from_toml`.
`doc`	required	Parsed `decktalk.toml`, for `from_toml`.
`environ`	`os.environ`	Mapping that supplies the `DECKTALK_*` tuning variables.

Raises ConfigError when decktalk.toml is missing, cannot be parsed, or fails validation. The message names the table and the field.

Member	Kind	Meaning
`root`, `name`, `script`, `cues`, `build`	field	Project directory, project name, and the paths from `[project]`.
`sections`	field	Every `PageSection` and `ClipSection`, in number order.
`voice`, `transition`, `mix`, `soundscape`	field	The project tables, as frozen dataclasses with the keys of decktalk.toml.
`settings`	field	The tuning tree, a `Settings`. Configuration lists every field.
`audio_dir`, `rec_dir`, `out_dir`, `shots_dir`	property	The `build/` subdirectories.
`manifest_path`, `timeline_path`, `beats_path`, `final`, `env_file`	property	Paths of the manifest, timeline, beats file, final mp4, and `.env`.
`manifest()`, `timeline()`, `beats()`	method	Loads the artifact. `manifest()` and `timeline()` return `None` when the file does not exist.
`section(number)`	method	Returns the section with that number, or `None`.
`page_sections`, `clip_sections`, `clip_numbers`, `page_files`	property	The page sections, the clip sections, the clip numbers, and the page files in first-use order.
`recording(section)`, `section_video(section)`	method	Returns the path of the section’s webm or its `NN-section.mp4`.
`path(rel)`	method	Returns `rel` as an absolute path under `root`.
`env(key)`	method	Returns the value from the environment or `.env`. Returns `""` when the value is unset or starts with `<`.
`require_env(*keys)`	method	Returns the values in order. Raises `ConfigError` that names every missing key.

load_settings(root=None, *, toml=None, environ=None, user=None) builds a Settings from the defaults, the per-machine file, the project’s tables, and the environment.

`build`

decktalk.build(project, *, silent=False, force=False, only=None, nomix=False, loudnorm=True,
               strict=False, allow_unresolved=False, allow_unknown=False, report=None) -> BuildResult

build runs the seven stages in order: narrate, resolve_beats, record, measure, check, assemble, and verify.

Parameter	Default	Meaning
`silent`	`False`	Uses a click track and estimated word times. Needs no API key. Raises `ConfigError` when `build/audio/manifest.json` holds voiced takes, unless `force` is set.
`force`	`False`	Voices every section again, and ignores the narration cache. With `silent`, replaces voiced takes.
`only`	`None`	Section numbers for `record`, `measure`, and `check`. The other stages still use every section.
`nomix`	`False`	Leaves the soundscape out of the mix.
`loudnorm`	`True`	Runs the loudness pass.
`strict`	`False`	Raises on a missing clip, a missing recording, or a loudness miss. A clip section with `optional = true` still plays its slate.
`allow_unresolved`	`False`	Continues when a cue phrase is not found.
`allow_unknown`	`False`	Continues when a cue id appears nowhere in its page.
`report`	`None`	A function that `build` calls as `report(stage, result)` after each stage.

Returns a BuildResult with one field per stage: narration, beats, recordings, leads, checks, assembly, and verification. Its ok is true when the video was assembled and verification.ok is true. The verification checks section starts, cuts, and cut continuity, and no cue. Raises

Error	When
`ConfigError`	A cue phrase is not found and `allow_unresolved` is false. A page threw an error during its recording. An input file is not valid.
`UnknownCueError`	A cue id appears nowhere in its page, and `allow_unknown` is false.
`MissingInputError`	`strict` is true and a clip or recording is missing, or an earlier output is missing.
`ToolError`	ffmpeg or Chromium failed, or `strict` is true and the loudness missed its target.
`ProviderError`	The speech provider refused or failed a request.

Note: UnknownCueError is a ConfigError. Import it from decktalk.stages.beats. Its result holds the full BeatsResult, and beats.json is already written.

`verify`

decktalk.verify(project, checks=None, only=None) -> VerifyResult

verify checks section starts, cuts, and cues on the final mp4. Verify defines every measurement.

Parameter	Default	Meaning
`checks`	`None`	`None` checks every cue in `beats.json` that `cues.json` does not opt out. An empty list checks no cue. A list of `SECTION:CUE` strings checks those cues, even opted-out ones.
`only`	`None`	Section numbers whose cues to keep. Section starts, cuts, and cut continuity are always checked.

Returns a VerifyResult.

Member	Meaning
`final`, `total_seconds`, `silent`	Path of the final mp4, its length, and whether the build was silent.
`starts`	One `StartCheck` per section, with `key`, `start`, `probe_at`, `yavg`, `ymax`, `ok`, and `verdict`.
`cuts`	One `CutCheck` per spoken section, with `key`, `cut_at`, `rms_db`, `ok`, and `verdict`.
`carries`	One `CarryCheck` per section with `carries_previous = true`, with `key`, `cut_at`, `last_at`, `first_at`, `changed_percent`, `ok`, and `verdict`.
`cues`	One `CueCheck` per cue row, with `check`, `section`, `cue`, `cue_seconds`, `final_seconds`, `changed_percent`, `control_percent`, `offset_ms`, `av_ms`, `ok`, `verdict`, `reason`, and `skipped`.
`black_starts`	Count of section starts that read `BLACK`.
`ok`	True when every start, cut, and measured cue passed. A skipped row never counts against it.
`to_dict(root)`	The result as JSON-ready data.

Raises MissingInputError when the section mp4s or the final mp4 are missing. Raises ConfigError when a check does not start with a section number.

Other stages

These functions run one stage each, or read the project.

Function	Returns	Raises
`narrate(project, *, only=None, force=False, allow_placeholders=False, silent=False, model=None)`	`NarrateResult` with `manifest`, `timeline`, `segments`, `synthesized`, and `cached`	`ConfigError`, `MissingInputError`, `ProviderError`
`resolve_beats(project, *, allow_unknown=False)`	`BeatsResult` with `beats`, `sections`, `unresolved`, `estimated`, `unknown`, `beats_file`, `problems`, and `to_dict(root)`	`ConfigError`, `MissingInputError`, `UnknownCueError`
`preflight(project, *, only=None, frames=True, model=None)`	`PreflightResult` with `takes`, `note`, `beats`, `estimated`, `cues`, `carries`, `frames`, `placeholders`, `findings(allow_unknown=False)`, and `to_dict(root)`	`ConfigError`, `MissingInputError`, `ToolError`
`record(project, *, only=None, seconds=None, use_beats=True)`	A list of `Recording`, each with `section`, `path`, `sidecar`, and `seconds`	`ConfigError`, `MissingInputError`, `ToolError`
`measure(project, only=None)`	A list of `LeadMeasurement`, each with `key`, `lead_in_seconds`, `wallclock_seconds`, and `method`	`MissingInputError`
`check(project, only=None)`	A list of `RecordingCheck`, each with `key`, `duration`, `wanted`, `y10`, `y50`, `y90`, `max50`, `verdict`, `page_errors`, `file`, `ok`, and `to_dict(root)`	`MissingInputError`
`assemble(project, *, nomix=False, loudnorm=True, strict=False)`	`AssembleResult` with `final`, `stamped`, `duration`, `sections`, `warnings`, `loudness`, `captions_srt`, `captions_vtt`, and `chapters`	`ConfigError`, `MissingInputError`, `ToolError`
`shoot(project, *, pages=None, steps=None, section=None, at=None, cues=None)`	A list of screenshot paths	`ConfigError`
`soundscape(project, *, only=None, force=False, dry_run=False)`	A list of `SoundscapeItem`, each with `name`, `out`, `endpoint`, `requests`, `status`, and `duration_seconds`	`ConfigError`, `ProviderError`
`status(project)`	`StatusReport`, which reads what exists and runs nothing	none
`spoken_words(project, only=None)`	A list of `SectionWords`, each with `key`, `section`, `title`, `lead_seconds`, `duration`, `estimated`, `words`, `texts`, and `to_dict()`	`ConfigError`, `MissingInputError`
`cut_clip(project, number, *, start, end, out, words_out=None, gain_db=0.0, hold_seconds=0.0)`	`ClipResult` with `section`, `video`, `words_file`, `start`, `end`, `first_frame`, `last_frame`, `hold_seconds`, `duration`, `gain_db`, `estimated`, `words`, and `cut_words`	`ConfigError`, `MissingInputError`, `ToolError`

record with seconds records every section for that long. With use_beats=False, the pages play in autoplay.
shoot with section takes frames from a playing section at each time in at, 0.5 s by default.
shoot with cues needs exactly one step in steps.
spoken_words gives each word in seconds after its section starts. words keeps the voice’s spelling, and texts gives the same words with the script’s punctuation and case.
cut_clip resolves a relative out or words_out against the project. words_out defaults to out with .words.json. decktalk clip describes the cut.

BeatsResult, PreflightResult, RecordingCheck, VerifyResult, and StatusReport each have to_dict(root). It returns the data that the command line prints under --json. Numbers stay numbers, and paths are relative to root with forward slashes. Pass project.root.

import json
import decktalk

project = decktalk.Project.load("my-lesson")
result = decktalk.verify(project)
print(json.dumps(result.to_dict(project.root), indent=2))

Artifacts

These classes read and write the files under build/. Build artifacts gives every field.

Class	Members
`Word`	`word`, `start`, `end`
`Manifest`	The narration cache. `load(path)` returns `None` when the file does not exist. `save(path)`.
`Timeline`	Section and word times in `narration.mp3`. `load(path)`, `save(path)`, `span(key)`, and `keys`.
`Beats`	Cue times per section. `load(path)`, `save(path)`, `query(key)` for the `?beats=` string, and `get(key, cue)`.
`Sidecar`	What the recorder did for one section. `load(path)`, `save(path)`, `trim_seconds`, and `worst_stall_ms`.

Errors and logging

Every error that DeckTalk raises on purpose is a DeckTalkError.

Error	Raised when
`DeckTalkError`	Base class of every error below.
`ConfigError`	`decktalk.toml`, `cues.json`, or `.env` is missing, cannot be parsed, or is not consistent.
`MissingInputError`	A stage needs an output that an earlier stage has not written yet.
`ProviderError`	An external API, such as ElevenLabs, refused or failed a request.
`ToolError`	ffmpeg, ffprobe, or Chromium is not available or failed.

The stages log progress to the decktalk logger at the INFO level. Attach a handler to see it. __version__ is the installed version string.

Speech providers

A speech provider returns audio and a start and end time for every word. ElevenLabs is the built-in provider.

Name	Meaning
`SpeechProvider`	A protocol with `name`, `speak(request)`, and `cache_key(request)`. `speak` returns the audio bytes and a list of `Word`. `cache_key` returns everything except the text that changes the audio.
`SpeechRequest`	A frozen dataclass with `text`, `model`, `voice_settings`, `output_format`, `previous_text`, and `next_text`. `text` holds break tags.
`register(name, factory)`	Makes a provider selectable as `[voice] provider = "name"`. The factory receives the loaded `Project` and returns a provider.

Registering a name again replaces the earlier factory. DeckTalk loads no plugins. For a provider that the command line can use, open a pull request that adds a module under src/decktalk/providers/ and registers it.

Stability

The file formats and the page contract are the stable surface: decktalk.toml, cues.json, the build artifacts, and the page runtime. A change to them comes with a migration note in the changelog. The Python names can still change, and the changelog records each rename.

Look up the files that the stages write: Build artifacts
Look up a tuning field: Configuration
Run the same stages from a shell: CLI

Get started

Guides

Concepts

Reference

Help

Public names

`Project`

`build`

`verify`

Other stages

Artifacts

Errors and logging

Speech providers

Stability

​Public names

​Project

​build

​verify

​Other stages

​Artifacts

​Errors and logging

​Speech providers

​Stability

​Related

Public names

`Project`

`build`

`verify`

Other stages

Artifacts

Errors and logging

Speech providers

Stability

Related