> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decktalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install DeckTalk, build the starter video without an account, then add your voice.

This quickstart installs DeckTalk and builds the starter video, first with no account and then with your voice. Only part 3 needs an ElevenLabs API key.

If an agent does these steps for you, give it the [Reference card](/reference/card).

## Before you start

* You need Python 3.12 or later.
* You need uv, pipx, or pip.
* On Linux, step 2 needs sudo or root.
* Part 3 needs an ElevenLabs API key and a voice id.

## Part 1: Install DeckTalk

<Steps>
  <Step title="Install DeckTalk" stepNumber={1}>
    Install the `decktalk` command with your Python installer.

    <Tabs>
      <Tab title="uv">
        ```console theme={null}
        uv tool install decktalk
        ```

        uv is a Python package manager. If you do not have it, [install uv](https://docs.astral.sh/uv/getting-started/installation/) first.
      </Tab>

      <Tab title="pipx">
        ```console theme={null}
        pipx install decktalk
        ```
      </Tab>

      <Tab title="pip">
        ```console theme={null}
        python -m venv .venv && source .venv/bin/activate
        pip install decktalk
        ```

        On Windows, activate the environment with `.venv\Scripts\activate`.
      </Tab>
    </Tabs>

    ```text theme={null}
    Installed 1 executable: decktalk
    ```

    Check that the installer names the `decktalk` executable.
  </Step>

  <Step title="Download Chromium and ffmpeg" stepNumber={2}>
    `decktalk install` downloads the tools that DeckTalk runs. Run it one time per machine.

    ```console theme={null}
    decktalk install
    ```

    ```text theme={null}
    == Chromium (Playwright)
    == ffmpeg 8.1.2
       ffmpeg  ~/Library/Caches/decktalk/ffmpeg/8.1.2-darwin-arm64/ffmpeg
       ffprobe ~/Library/Caches/decktalk/ffmpeg/8.1.2-darwin-arm64/ffprobe
    install complete
    ```

    Check that the last line is `install complete`. On Linux, this step asks for sudo. [What install downloads](/requirements#what-install-downloads) says where each download goes.
  </Step>

  <Step title="Check the tools" stepNumber={3}>
    `decktalk doctor` reports each tool that DeckTalk needs.

    ```console theme={null}
    decktalk doctor
    ```

    ```text theme={null}
    components 6, missing 0
    python    ok      3.13.1 (~/.local/share/uv/tools/decktalk/bin/python)
    chromium  ok      151.0.7922.34
    ffmpeg    ok      ~/Library/Caches/decktalk/ffmpeg/8.1.2-darwin-arm64/ffmpeg
    ffprobe   ok      ~/Library/Caches/decktalk/ffmpeg/8.1.2-darwin-arm64/ffprobe
    config    ok      none (at ~/Library/Application Support/decktalk/decktalk.toml)
    katex     ok      0.18.7 in the wheel (~/.local/share/uv/tools/decktalk/lib/python3.13/site-packages/decktalk/katex)
    ```

    Check that the first line reads `missing 0` and that every row says `ok`. If a row does not, run `decktalk install` again. The `config` row is the per-machine settings file, which is optional, so `none` there is a passing row.
  </Step>
</Steps>

## Part 2: Build the starter without an account

<Steps>
  <Step title="Create the starter" stepNumber={4}>
    `decktalk init` writes the starter: three sections, one page, one equation, and a build that
    takes about a minute. Nothing in it is a demo you have to delete first.

    ```console theme={null}
    decktalk init my-lesson
    ```

    ```text theme={null}
    files 16
    created ~/my-lesson
      decktalk.toml  the project file: sections -> pages or clips, voice, mix, soundscape
      script.md      the narration (## N. sections)
      cues.json      which spoken phrase each visual lands on
      deck/          the pages, decktalk-runtime.js and katex/ (open a page for its scene index)
      AGENTS.md      the rules an agent working in this project follows
      .agents/skills the six DeckTalk skills, linked from .claude/skills
    next: `decktalk build --no-voice` renders with placeholder narration, no API key and no spend
          then cp .env.example .env  (ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID) and `decktalk build`
    ```

    If you skipped step 2, run `decktalk install` now. `init` copies the packaged KaTeX into `deck/katex/` either way.

    <Tip>`decktalk init --example lesson my-lesson` writes a finished lesson instead, to read rather than
    to start from. `--no-skills` leaves the six skills out.</Tip>
  </Step>

  <Step title="Go into the project" stepNumber={5}>
    ```console theme={null}
    cd my-lesson
    ```
  </Step>

  <Step title="Open the slides in a browser" stepNumber={6}>
    Serve the project and open the page it prints. This takes seconds, and you see the slides before
    you build. `decktalk serve` answers from your project directory on 127.0.0.1, which is the origin
    the recorder uses, so what you see is what the recorder will see. Press Ctrl-C to stop it.

    ```console theme={null}
    decktalk serve --open
    ```

    ```text theme={null}
    http://127.0.0.1:57962/deck/index.html
    serving /Users/you/my-lesson, and Ctrl-C stops it
    ```

    The port is any free one unless you set `--port`.

    <Frame caption="The scene index lists each scene of the page with its slides and cue ids.">
      <img src="https://mintcdn.com/decktalk/knAnjfR4WMnCHJIJ/images/quickstart-index.png?fit=max&auto=format&n=knAnjfR4WMnCHJIJ&q=85&s=52f4a472cb8db68e12e8042c159aa2f3" alt="The starter page in index mode, headed My Lesson. A line names the stage as 1920 by 1080 and gives the URL parameters: ?scene=N previews a scene, ?slide=ID freezes a slide, &speed=2, &hud=1, and &cues=id@s with &t0=. Under it are Scene 1 Open, Scene 2 How it works, and Scene 3 Close, each with a play link, and under each one a single slide with its hold seconds and its four cue ids." width="2008" height="930" data-path="images/quickstart-index.png" />
    </Frame>

    Check that the page shows an index of its three scenes, one slide each. Every cue id of a slide is listed beside it.
  </Step>

  <Step title="Build the video without an account" stepNumber={7}>
    A build without voice uses estimated word times and a click track, so it needs no key. Recording runs in real time. On a MacBook Pro with Apple M5 Pro and 64 GB memory, this build took about 64 seconds. Read [What the starter shows](#what-the-starter-shows) while it runs.

    ```console theme={null}
    decktalk build --no-voice
    ```

    ```text theme={null}
    [caps] 9 cue(s) -> my-lesson.srt, my-lesson.vtt
    [chap] 3 chapter(s) -> my-lesson.chapters.txt
    done: ~/my-lesson/build/out/my-lesson.mp4  (44.88s)
    [4/5 assemble] done in 2.5s
    ===== verify =====
    ...
    stages 5, seconds 44.88
    built build/out/my-lesson.mp4
    ```

    Check that the last line starts with `built`. Each of the five stages prints a table of its own above it.
  </Step>

  <Step title="Play the video" stepNumber={8}>
    <Tabs>
      <Tab title="macOS">
        ```console theme={null}
        open build/out/my-lesson.mp4
        ```
      </Tab>

      <Tab title="Linux">
        ```console theme={null}
        xdg-open build/out/my-lesson.mp4
        ```
      </Tab>

      <Tab title="Windows">
        ```console theme={null}
        start build\out\my-lesson.mp4
        ```
      </Tab>
    </Tabs>

    The video is 44.88 seconds long, in three sections, with a soft click on each word. [What the starter shows](#what-the-starter-shows) describes each one.
  </Step>
</Steps>

## Part 3: Add your voice and change a sentence

If you have no ElevenLabs account, stop here. The video without voice is a complete build.

<Steps>
  <Step title="Copy the example settings file" stepNumber={9}>
    <Tabs>
      <Tab title="macOS and Linux">
        ```console theme={null}
        cp .env.example .env
        ```
      </Tab>

      <Tab title="Windows">
        ```console theme={null}
        copy .env.example .env
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set your key and voice id" stepNumber={10}>
    In `.env`, replace the two placeholders with your API key and voice id.

    ```dotenv .env theme={null}
    ELEVENLABS_API_KEY=<your-elevenlabs-key>     # Profile, then API keys, on elevenlabs.io
    ELEVENLABS_VOICE_ID=<voice-id>               # the id on a voice's card under Voices
    ```

    A value that still starts with `<` counts as unset. DeckTalk never prints the key and never writes it under `build/`.
  </Step>

  <Step title="Build the video with your voice" stepNumber={11}>
    <Warning>`decktalk build` without `--no-voice` spends ElevenLabs credits. [What spends credits](/requirements#what-spends-credits) lists the cost.</Warning>

    ```console theme={null}
    decktalk build
    ```

    The `narrate` stage prints one line per section it sends, and the run ends with `built` as before. It
    voices all three sections, because a click track is never reused as a voice. `decktalk narrate --dry-run`
    prints what the run will send and what it will cost before you start it.

    ```console theme={null}
    decktalk narrate --dry-run
    ```

    ```text theme={null}
     #  section                take         sent spoken  reason
    -----------------------------------------------------------
     1  open                   synthesize    140    131  no take yet
     2  how-it-works           synthesize    150    141  no take yet
     3  close                  synthesize    126    120  no take yet
    -----------------------------------------------------------
    voice 3 section(s): 416 characters sent, 392 spoken, 949 with context. 0 cached. About $0.12 at $0.30 per 1,000.
    ```

    The rate comes from `[voice] price_per_1000_characters` in your own `decktalk.toml`, so the dollars are your plan's.
  </Step>

  <Step title="Change one word" stepNumber={12}>
    In section 3 of `script.md`, add a word to the last line.

    ```diff script.md theme={null}
    -[beat] Make your own at decktalk dot AI.
    +[beat] Make your own today at decktalk dot AI.
    ```

    The cue for that line matches the phrase "Make your own", which is still there, so `cues.json`
    and the page need no change.
  </Step>

  <Step title="Build again" stepNumber={13}>
    ```console theme={null}
    decktalk build
    ```

    DeckTalk voices only section 3 again. Sections 1 and 2 take their narration from the cache, because their text did not change. A take is named by the hash of its text and voice settings, so the two unchanged sections play the files they already have. [Rebuild one section](/guides/rebuild-one-section) says what each kind of edit runs again.

    <Tip>Run `decktalk narrate --dry-run` again after the edit. Sections 1 and 2 read `cached`, section 3 reads `synthesize`, and the totals count only what section 3 costs.</Tip>
  </Step>

  <Step title="Check that a reveal starts on its word" stepNumber={14}>
    ```console theme={null}
    decktalk verify 3:3.1make
    ```

    ```text theme={null}
    check                 cue       at   chg %   ctl %   offset     a/v  result
    3:3.1make            8.71    38.87   10.85    0.00    +10ms    -6ms  changed
    ```

    Check that the result is `changed`. The offset column is the time from the cue time to the onset of the reveal, in milliseconds. The `a/v` column is filled only after a build without voice, because only a click track has clicks. [Verify](/reference/verify#cues) defines every column.
  </Step>
</Steps>

## What the starter shows

The starter is three sections on one page. Every slide is markup: a `<template data-slide>` inside a
`[data-scene]` wrapper, with a `data-cue` on each thing that appears. There is no JavaScript to read.

| Section         | Plays                      | What it shows                                                                                                                 |
| --------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 1. Open         | `deck/index.html`, scene 1 | The title, then a card for each of the two files you write, then the promise.                                                 |
| 2. How it works | `deck/index.html`, scene 2 | The heading, then one displayed equation typeset by KaTeX, then the same average as two lines of Python, then a closing band. |
| 3. Close        | `deck/index.html`, scene 3 | The idea, the line about rebuilding one part, and the end card.                                                               |

The equation is the one place the starter shows a trap: `data-tex` holds the TeX and the element's
own text is the fallback that shows if KaTeX ever fails to load. The comment beside it names all
three traps. [Design a slide](/guides/design-a-slide) is the next thing to read.

### The examples

`decktalk init --example NAME` writes a finished project instead of the starter.

| Name       | What it is                                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lesson`   | A lesson on how a model learns, with a figure drawn in code and moved on every cue. It is the example of a page that needs more than attributes. |
| `product`  | Reserved. It is the film that shows DeckTalk itself, and it ships with that film.                                                                |
| `tutorial` | Reserved. It is a short technical tutorial with a code slide, a terminal block and a screenshot.                                                 |

`decktalk init --example NAME` refuses a reserved name, so `lesson` is the one example to read today.

## Next

* **Write your own section:** [Your first deck](/guides/first-deck)
* **Make the script time well:** [Writing for the ear](/guides/writing-for-the-ear)
* **Rebuild only what changed:** [Rebuild one section](/guides/rebuild-one-section)