Build in CI and offline

A silent build needs no API key, and after decktalk setup it needs no network. Use this guide to build and check the video on every push, or on a machine that is offline. decktalk build can pass when decktalk check or decktalk verify fails. To gate a job on the video, run all three commands.

decktalk build --silent && decktalk check && decktalk verify

Add a GitHub Actions job

This job builds the video with no API key, checks it, and uploads the video and the verify results.

.github/workflows/video.yml

jobs:
  video:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.1.0
      - run: uv tool install decktalk
      - name: Cache Chromium and KaTeX
        uses: actions/cache@v4
        with:
          path: |
            ~/.cache/ms-playwright
            ~/.cache/decktalk
          key: browsers-${{ runner.os }}
      - run: decktalk setup
      - run: decktalk doctor
      - run: decktalk build --silent
        env:
          DECKTALK_VIDEO_PRESET: veryfast
      - run: decktalk check
      - run: decktalk verify --json > verify.json
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: video
          path: build/out/*.mp4
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: verify
          path: verify.json

The cache paths are for Linux. Requirements lists the paths on macOS and Windows.
On Linux, setup installs Chromium’s system libraries, which needs sudo or root. Linux system libraries gives the full rule.
setup downloads ffmpeg into the static-ffmpeg package, inside the Python environment of DeckTalk. This job does not cache it, so each run downloads ffmpeg again.
DeckTalk’s own CI installs into .venv and caches .venv/lib/*/site-packages/static_ffmpeg/bin.
If a proxy blocks the Chromium download, set PLAYWRIGHT_DOWNLOAD_HOST to a mirror.

What each command catches

Each command exits 1 on a different set of problems.

Command	Exits 1 on	Does not catch
`decktalk build`	an error, `PAGE ERROR`, a cue phrase that is not found, an unknown cue id, `BLACK`, `SPEECH AT CUT`	`TRUNCATED`, `STALLED`, `NO COVER`, `BLACK?`, `KATEX?`, every cue result
`decktalk check`	`PAGE ERROR`, `STALLED`, `TRUNCATED`, `NO COVER`	`BLACK?` and `KATEX?`, unless you pass `--strict`
`decktalk verify`	`BLACK`, `SPEECH AT CUT`, `OFF CUE`, `NO CHANGE`, `UNRESOLVED`	a `skipped` row, such as a cue marked `"verify": false`
`decktalk doctor`	a missing required tool	a missing KaTeX cache, unless you pass `--strict`
`decktalk preflight`	an unfilled placeholder, `UNRESOLVED`, `UNKNOWN`, `NO CHANGE`, and `POP AT CUT` in frozen frames, before any recording	motion, timing, and every check on the final mp4

A silent build puts a click at every word start, so verify also reports an a/v value for each cue. The job fails when an a/v value is past max_av_frames, which is three frames at the defaults. A silent build therefore tests the recording, the cut, and the mix, not only the cues. build --strict fails on a missing clip, unless the clip section sets optional = true. With --silent, it cannot fail on loudness, because a silent build skips the loudness pass.

Fail the job on a bad video

status, beats, check, verify, and doctor share one exit rule. Use their exit codes as the assertions of a job.

A certain finding, such as OFF CUE or TRUNCATED, exits 1.
An uncertain finding ends in ?, such as BLACK? on a slide that is dark on purpose. It exits 1 only with --strict.
An error always exits 1.

decktalk check --strict      # also fail on BLACK? and KATEX?
decktalk verify              # fail on any certain finding

To keep the job running and decide later, add --no-fail and read the JSON.

decktalk verify --json --no-fail > verify.json
jq -e '.ok' verify.json
jq '.verify.cues[] | select(.verdict != "changed")' verify.json

--no-fail makes the command exit 0 on findings, but an error still exits 1. The JSON ok is false when the command would exit 1 without --no-fail. jq -e then exits 1, and the second jq line lists the rows to look at. Output and exit flags lists every key.

Allow for slower runners

A hosted runner has no GPU that Chromium can use, so Chromium draws every frame in software. The macOS and Windows runners are slower than Linux.

A page renders more slowly on a runner than on a laptop.
A canvas figure or a large SVG renders more slowly still.
A reveal can start two or three frames late, and verify reports OFF CUE.
A long draw after narration t=0 can read STALLED.

If that happens only on a slower runner, widen the limits for that runner. Keep the defaults on the machine that records the published video. DeckTalk’s own CI uses these values.

Environment variable	Linux	macOS and Windows
`DECKTALK_VERIFY_MAX_OFFSET_FRAMES`	2 (default)	4
`DECKTALK_VERIFY_MAX_AV_FRAMES`	3 (default)	5
`DECKTALK_ALIGN_STALL_MS`	150 (default)	400

A reveal can also start late while a large layer moves, such as a canvas figure that pans. To gate a job on cue timing, verify a light deck whose reveals land on still pages, and report the busy deck without failing. DeckTalk’s own CI builds tests/timing and fails on any finding there. It runs decktalk verify --no-fail on the scaffold.

.github/workflows/video.yml

      - name: Widen the sync tolerance on the slower runners
        if: runner.os != 'Linux'
        run: |
          echo "DECKTALK_VERIFY_MAX_OFFSET_FRAMES=4" >> "$GITHUB_ENV"
          echo "DECKTALK_VERIFY_MAX_AV_FRAMES=5" >> "$GITHUB_ENV"
          echo "DECKTALK_ALIGN_STALL_MS=400" >> "$GITHUB_ENV"

Build a voiced video in CI

Put ELEVENLABS_API_KEY and ELEVENLABS_VOICE_ID in the job’s secrets, and export them to the build step. DeckTalk never prints either value.

Never run decktalk build --silent in a build/ directory that you keep for voiced builds. It empties the narration cache, and the next voiced build spends credits on every section.

A silent build and a voiced build explains why.

Set the project directory

Every project command takes --project DIR. The DECKTALK_PROJECT variable sets the default, so a job can run from the repository root.

DECKTALK_PROJECT=lessons/derivatives decktalk build --silent

Build offline

A silent build runs with no network after these steps.

Download the tools

On a machine with network, run setup. It downloads Chromium, ffmpeg, and KaTeX.

decktalk setup

Create the project

Run init after setup. init copies the cached KaTeX into deck/katex/.

decktalk init my-lesson

Build the video

Run a silent build in the project directory.

decktalk build --silent

In the scaffold, only deck/index.html loads KaTeX. If init ran before KaTeX was cached, that page loads KaTeX from a CDN. Offline, its equations then stay plain text, and check reports KATEX?. To fix a project that loads KaTeX from a CDN:

Run decktalk setup.
Copy the files in the cached KaTeX folder into deck/katex/. Requirements lists the cache folder.
In deck/index.html, replace the two KaTeX CDN tags with these tags.

deck/index.html

<link rel="stylesheet" href="./katex/katex.min.css">
<script src="./katex/katex.min.js"></script>

If the project has no changes of its own yet, run decktalk init into a new directory instead.

See every exit code: CLI
Fix a failed check: Troubleshooting
Understand a cue result: Verify

Get started

Guides

Concepts

Reference

Help

Build in CI and offline

Add a GitHub Actions job

What each command catches

Fail the job on a bad video

Allow for slower runners

Build a voiced video in CI

Set the project directory

Build offline

Next

​Add a GitHub Actions job

​What each command catches

​Fail the job on a bad video

​Allow for slower runners

​Build a voiced video in CI

​Set the project directory

​Build offline

​Next

Add a GitHub Actions job

What each command catches

Fail the job on a bad video

Allow for slower runners

Build a voiced video in CI

Set the project directory

Build offline

Next