> ## Documentation Index > Fetch the complete documentation index at: https://docs.decktalk.app/llms.txt > Use this file to discover all available pages before exploring further. # Python API > Every public name in the DeckTalk Python package, with Project, Settings, the section and artifact types, the stage functions and their results, the errors, and the speech provider protocol. The CLI is a thin layer over these names. Stage functions take a `Project`, log progress to the `decktalk` logger, return a typed result, and raise `DeckTalkError` subclasses. They never call `sys.exit` and never print. ```python theme={null} import decktalk project = decktalk.Project.load("my-lesson") # validates decktalk.toml and loads the settings project.settings.video.preset = "veryfast" result = decktalk.build(project, silent=True) print(result.assembly.final, result.verification.ok) ``` ## The project | Name | What it is | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Project.load(dir=None, *, environ=None)` | Parses and validates `decktalk.toml`. The directory defaults to `DECKTALK_PROJECT`, then the current directory, and a path to the file itself is accepted. It raises `ConfigError` with the table and field named. `Project.from_toml(root, doc)` builds one from a parsed mapping. | | `Project` | The loaded document: `root`, `name`, `script`, `cues`, `build`, `sections`, `voice`, `transition`, `mix`, `soundscape`, `settings`, plus the paths `audio_dir`, `rec_dir`, `out_dir`, `shots_dir`, `manifest_path`, `timeline_path`, `beats_path`, `final`, `env_file`, and the loaders `manifest()`, `timeline()`, `beats()`. | | `Section`, `PageSection`, `ClipSection` | The two kinds of section and their union. `project.sections` holds them in number order, and `page_sections`, `clip_sections`, `clip_numbers`, and `page_files` filter them. | | `Voice`, `Transition`, `Mix`, `Soundscape` | The document tables, as frozen dataclasses with the same keys as [decktalk.toml](/reference/decktalk-toml). | | `Settings`, `load_settings(root, *, toml, environ)` | The tuning tree, built from the defaults, then the TOML tables, then the `DECKTALK_*` environment. [Configuration](/reference/configuration) lists every field. | ## Artifacts | Name | What it is | | ---------- | ----------------------------------------------------------------------------------------------------------- | | `Word` | `word`, `start`, `end`. | | `Manifest` | The narration cache, with `load(path)` and `save(path)`. | | `Timeline` | Section and word times absolute in `narration.mp3`, with `load`, `save`, `span(key)`, and `keys`. | | `Beats` | Resolved cues per section, with `load`, `save`, `query(key)` for the `?beats=` string, and `get(key, cue)`. | | `Sidecar` | What the recorder did for one section, with `load`, `save`, `trim_seconds`, and `warnings`. | [Build artifacts](/reference/artifacts) gives every field of every file. ## Stages and results | Function | Returns | | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `narrate(project, *, only, force, allow_placeholders, silent, model)` | `NarrateResult` with `manifest`, `timeline`, `segments`, `synthesized`, and `cached`. | | `resolve_beats(project)` | `BeatsResult` with `beats`, `sections`, `unresolved`, `estimated`, and `problems`. | | `record(project, *, only, seconds, use_beats)` | A list of `Recording`, each with `section`, `path`, `sidecar`, and `seconds`. | | `measure(project, only)` | A list of `LeadMeasurement`, each with `key`, `lead_in_seconds`, `wallclock_seconds`, and `method`. | | `check(project, only)` | A list of `RecordingCheck`, each with the luma fields, `verdict`, and `ok`. | | `assemble(project, *, nomix, loudnorm, strict)` | `AssembleResult` with `final`, `stamped`, `duration`, `sections`, `warnings`, `loudness`, `captions_srt`, `captions_vtt`, and `chapters`. | | `verify(project, checks)` | `VerifyResult` with `total_seconds`, `starts`, `cues`, `ok`, and `black_starts`. | | `shoot(project, *, pages, steps, section, at)` | The screenshot paths. | | `soundscape(project, *, only, force, dry_run)` | A list of `SoundscapeItem`, each with `name`, `out`, `endpoint`, `requests`, `status`, and `duration_seconds`. | | `build(project, *, silent, force, only, nomix, loudnorm, strict, allow_unresolved, report)` | `BuildResult` with one field per stage and `ok`, which mirrors the CLI's exit code. `report(stage, result)` is called after each stage. | ## Errors and logging | Error | Meaning | | ------------------- | ------------------------------------------------------------------------------- | | `DeckTalkError` | The base class of every error DeckTalk raises on purpose. | | `ConfigError` | `decktalk.toml`, `cues.json`, or `.env` is missing, malformed, or inconsistent. | | `MissingInputError` | A stage needs an artifact that an earlier stage has not produced. | | `ProviderError` | The speech provider refused or failed a request. | | `ToolError` | ffmpeg, ffprobe, or Chromium is unavailable or failed. | Progress goes to the `decktalk` logger at the INFO level, so attach a handler to see it. `__version__` is the installed version string. ## Speech providers DeckTalk needs one thing from a voice: audio plus a start and end time for every word. The boundary is `SpeechProvider`, a protocol with a `name`, a `speak(request)` method that returns the audio bytes and a list of `Word`, and a `cache_key(request)` method that returns everything that changes the audio apart from the text. A `SpeechRequest` carries the `text` with break tags, the `model`, the `voice_settings`, the `output_format`, and the neighbouring `previous_text` and `next_text` for prosody. `register(name, factory)` is public. The factory receives the loaded `Project` and returns a provider, and `[voice]` with `provider = "name"` then selects it. ElevenLabs is the built-in provider and the only one today. There is no plugin loading, so a new provider is a pull request that adds a module under `src/decktalk/providers/` and registers it. A local text-to-speech engine paired with a forced aligner is the obvious candidate, and an issue that proposes one is welcome. ## Stability The file formats are stable already. That covers `decktalk.toml`, `cues.json`, the build artifacts, and the page contract, and a change to any of them bumps the minor version with a migration note in the [changelog](/changelog). The Python names may still move, and a rename is a breaking change once the project leaves the 0.x series. Everything under `decktalk.media`, everything under `decktalk.providers` other than the three speech names above, and every name that starts with an underscore is internal. ## Every public name `AssembleResult`, `Beats`, `BeatsResult`, `BuildResult`, `ClipSection`, `ConfigError`, `DeckTalkError`, `LeadMeasurement`, `Manifest`, `MissingInputError`, `Mix`, `NarrateResult`, `PageSection`, `Project`, `ProviderError`, `Recording`, `RecordingCheck`, `Section`, `Settings`, `Sidecar`, `Soundscape`, `SoundscapeItem`, `SpeechProvider`, `SpeechRequest`, `Timeline`, `ToolError`, `Transition`, `VerifyResult`, `Voice`, `Word`, `__version__`, `assemble`, `build`, `check`, `load_settings`, `measure`, `narrate`, `record`, `register`, `resolve_beats`, `shoot`, `soundscape`, `verify`.