Skip to main content
This page answers the questions a stranger asks before trying DeckTalk. If a command has already printed a code at you, Troubleshooting takes that code to a fix.

​
What does it cost?

A build without a voice costs nothing at all. Two stages spend money, and both of them tell you the price before they start.
  • narrate sends each turn’s text to ElevenLabs and is billed by the character. A turn whose text has not changed is served from the take on disk, so an edit to one sentence pays for the whole turn it is in, which is the whole section when one voice reads it.
  • score generates the music, the ambience bed and the effects the project describes, and is billed by the second of audio. It runs after record, so a run that stops at the recorder never reaches it.
  • decktalk check prices the narration of a voiced run before anything is bought, the way the voice declares it bills. ElevenLabs bills per character, so the price uses [elevenlabs] dollars_per_1000_characters from decktalk.toml as what your own plan charges.
  • No run spends without being told to. On the command line that is --spend, and --max-cost N refuses the run before the first call if the most it could cost is over N US dollars. In the library it is spend=True, and ApprovalRequired is raised rather than money being spent.
Requirements and costs lists every command that spends.

​
Do I need an account to try it?

No. decktalk init my-deck and then decktalk build --no-spend writes a complete film with placeholder narration whose words are timed by estimate, so every cue lands somewhere and the cues and the cuts are real. Nothing contacts a paid speech service, and no key is read. --no-spend gates money only, so a project whose voice is the free local dtsp is still voiced by it. A build voiced by ElevenLabs needs an ElevenLabs API key in .env and a voice id as [voices.narrator] id in decktalk.toml. The voice id is a published name rather than a credential: it says which voice reads the script, the way a model name says which model answers, and a cloned voice is usable only with its own account’s key, so the id is committed with the project.

​
Can I use a voice other than ElevenLabs?

Not yet. Today every voice is ElevenLabs. DeckTalk ships two voices: elevenlabs, the cloud voice, and dtsp, which speaks the DeckTalk speech protocol to decktalk-voice, a separate local server that is not part of this repository and is in development, not yet public. Once it is available, set provider = "dtsp" under the voice’s [voices.NAME] table. It needs no key and costs nothing, so it makes its takes with or without --spend, --no-spend included. The server’s address is [dtsp] base_url, http://127.0.0.1:9361 by default, and only this machine sets it, so a project someone else wrote cannot send its script anywhere else. When the server is not running, each missing take plays a placeholder with a TAKE_MISSING finding that says to start it, and the build still exits 0. The set is closed. There is no plugin path and nothing is read from entry points, so the voices a build can call are the ones a reader of the code can see. What that does not lock up is your project. script.md, cues.json, decktalk.toml and the deck pages name no service, and a build with --no-spend needs none, so the files outlive the choice. The one thing DeckTalk asks of any voice is a start and an end time for every word, because the cut is made on words, and that requirement is what a second provider would have to meet.

​
Can two voices read one film?

Yes. Declare each voice as its own [voices.NAME] table, and a line holding only [voice NAME] in script.md hands the turns after it to that voice until the next such line or the next section. The voices may be on different providers, and decktalk check prices each provider’s turns on a row of its own. Write a dialogue shows the whole task, and decktalk init --example interview writes a project that does it.

​
How does the voice sound?

It sounds like the ElevenLabs voice you pick. Any voice id works, including a clone of your own. [elevenlabs] in decktalk.toml sets stability, similarity_boost, style and speaker_boost, and [voices.NAME] speed sets the pace. DeckTalk also sends up to [narration] context_characters of the text before and after each section with the request, so the rhythm and the tone stay even across a cut that the listener never hears as one.

​
Why not just record the screen?

A screen recording needs a new take after every edit, and you time every reveal again by hand. DeckTalk takes each reveal’s second from the spoken words, so rewriting a sentence moves the pictures with it and nobody touches a timeline. Rebuild one section shows what a change runs again.

​
How is this different from the other tools?

DeckTalk takes its timing from the spoken words, and the slides are your own HTML. Choose DeckTalk when the timing must come from the words and the slides are yours. Other tools fit other jobs.
  • For frame-by-frame animation, use Remotion, Motion Canvas or Manim.
  • To edit a recording you already made, use Descript.
  • For an avatar on screen, use Synthesia or HeyGen.

​
Is generated music required?

No. Every part of the score is off until the project asks for it. [score.music], [score.ambience] and [score.effects.<name>] describe what decktalk score generates, and [mix] names the files that are mixed under the voice. You can point [mix] at audio files of your own and never run that stage at all. Sound explains both ways.

​
What comes out besides the video?

Every build writes the deliverables beside the film in build/final/. decktalk status reports where the film is and what is stale. Build artifacts gives every format.

​
Does another HTML framework work?

Yes. A page can be any HTML that follows the page contract.
  • Write a page by hand shows the smallest page that records.
  • The runtime is one file with no dependencies, and it adds only its own stage element to your markup.
  • KaTeX is optional. DeckTalk serves the packaged KaTeX at /__decktalk/katex/, and a page that needs no equations can drop its two tags.
A page that loads an asset from another origin still records, and PAGE_CDN_ASSET reports each origin it reached for, because a film that depends on somebody else’s server cannot be rebuilt the same way in a year.

​
Does it run on Windows?

Yes. DeckTalk runs on Linux, macOS and Windows.
  • The one-line installer covers Linux and macOS. On Windows, install with uv or pipx, which needs Python 3.12 or later.
  • Paths in decktalk.toml use forward slashes on every platform, and every path DeckTalk reports back is project-relative with forward slashes.
  • What DeckTalk fetches goes under %LOCALAPPDATA% on Windows, and [tools] cache_dir moves it. Chromium is fetched by the first command that needs it, or up front by decktalk install. If a proxy blocks the download, set PLAYWRIGHT_DOWNLOAD_HOST as Playwright documents, or point [tools] chromium at a browser the machine already has, with decktalk config set tools.chromium PATH --scope machine.
  • The groups that drive a real browser or a real ffmpeg run on macOS and Windows when a change merges and when a release is cut. Those legs report cue timing rather than fail on it, because a hosted runner presents frames late. The Linux e2e leg reports it too, until its own runs show the runner can be trusted. What CI runs says how each leg is judged, and uv run scripts/check.py --list names every one.

​
Can an agent drive it?

That is what it is built for. The command line is the instruction set and it documents itself, so four calls tell an agent everything: decktalk --help, decktalk schema, decktalk schema setting beside decktalk config explain KEY, and decktalk status --json beside decktalk doctor --json. Every command under --json prints one flat object with the same four reserved keys. decktalk init also writes six skills into the project, which hold the craft a help screen cannot say. The agent path is the whole story, and DeckTalk ships no MCP server.

​
What does the lesson example mean by error?

The “error” in decktalk init my-lesson --example lesson is what machine learning calls the loss. The lesson uses “error” because the everyday word already says that lower is better.
  • One guess. A loss function scores one guess. For a category guess, such as seal or otter, the usual loss is cross-entropy. It is large when the model gives the right answer a low probability.
  • The height of the bowl. Training lowers the average loss over many examples. Gradient descent moves the dials down the slope of that average.
  • Not the error rate. The error rate is the share of wrong guesses. It changes in jumps, so it has no useful slope to follow.

​
Where does the name come from?

A deck is the slides, and the talk is the narration. DeckTalk times the deck to the talk.