DeckTalk

Narrated presentations, cut to the word.
DeckTalk makes a narrated video from a markdown script and HTML slides. Each reveal starts on the word that introduces it. If you change a sentence, DeckTalk voices only that section again.

DeckTalk is for lecturers, course authors, developer advocates, and the agents that help them.

Quickstart · Docs · Requirements and costs · Reference card for agents · Changelog
Agents can read llms.txt.

Make your first video

You need Python 3.12 or later. These steps use uv, a Python package manager. If you use pipx, run pipx install decktalk in step 1 instead.

1. Install DeckTalk.

   uv tool install decktalk
   

   uv ends with Installed 1 executable: decktalk.

2. Download Chromium, ffmpeg, and KaTeX. You do this one time per machine.

   decktalk setup
   

   On Linux, this step asks for sudo. The last line is setup complete.

3. Create the scaffold, a complete example project.

   decktalk init my-lesson
   

4. Go into the project.

   cd my-lesson
   

5. Build the video without an account.

   decktalk build --silent
   

   The build ends with built and the path of build/out/my-lesson.mp4. The build took 224.4 seconds on a MacBook Pro with Apple M5 Pro and 64 GB memory, because recording runs in real time.

6. Copy the example settings file.

   cp .env.example .env
   

7. In .env, set your ElevenLabs API key and voice id. DeckTalk never prints the key.

8. Build the video with your voice.

   decktalk build
   

   This build spends ElevenLabs credits for every section. It writes the video, SRT and VTT captions, and one chapter per section. What spends credits lists the cost.

The scaffold is a lesson in nine sections, two of them optional clips. The quickstart shows the output of each step and what the example video shows.

What you write

You write four files. One cue id per reveal, such as 1.1bowl, ties the script, the cues, and the page together.

The narrate stage writes a words file with the start and end of every spoken word. If a cue phrase is not in the spoken words, the build stops and names the cue. Your first deck writes one section in all four files.

Why the cuts are exact

A browser does not start recording at a known time, so DeckTalk does not use a timer. The recorder covers the page in magenta until the narration starts. The first frame without magenta is narration t=0, on Linux, macOS, and Windows.

decktalk verify then measures every reveal in the finished video. This sample comes from a silent build of the scaffold.

check                 cue       at   chg %   ctl %   offset     a/v  result
1:1.1bowl            1.25     1.25    0.93    0.00    +30ms   +31ms  changed
3:3.4name           84.72   123.32    2.76    0.00     +0ms    -4ms  changed
8:7.1checked        10.03   238.31    0.83    0.00    +10ms    +3ms  changed

The offset column is the time from the cue time to the onset of the reveal, in milliseconds. Verify defines every column and limit.

Requirements and costs

• Software. DeckTalk needs Python 3.12 or later, on Linux, macOS, or Windows. decktalk setup downloads the rest.
• Accounts. A silent build needs no account. A voiced build needs an ElevenLabs API key and a voice id.
• Cost. Every ElevenLabs plan can call the API. The free plan has limits for a video you publish.

Requirements and costs lists every download and every command that spends credits.

How it compares

The FAQ has the full comparison. Every build also gives you these parts:

• A free silent build. Every stage runs with no key, and a click marks each word.
• Cached narration. DeckTalk voices a section again only when it changes.
• Captions and chapters. Every build writes SRT, VTT, and chapters.
• A soundscape. Add an underscore, an ambience bed, and sound effects.
• Loudness. DeckTalk normalizes the mix to -16 LUFS.
• Checked output. check and verify catch bad recordings and late reveals.

Status and support

DeckTalk is alpha, and a minor release can still break things. One person maintains it.

CI runs the unit tests and a full offline build on Linux for every push to main and every pull request. CONTRIBUTING lists the macOS and Windows runs.

• Report bugs and ask questions in Issues.
• Report a vulnerability privately. SECURITY.md explains how.
• The changelog lists every release.

Documentation

The docs are at docs.decktalk.app.

• Install and build a first video: Quickstart
• Write your own section: Your first deck
• Give an agent the whole contract: Reference card for agents

Contributing

To work on DeckTalk itself, start with CONTRIBUTING.md.

Apache-2.0. Made by Jacob Beaudin.