tourcast

Record a hands-free walkthrough of a web app as an MP4.

Write the tour as YAML. Playwright walks the app, a synthetic cursor moves to each target, and the camera zooms and dims to direct attention. When the product changes, run it again — the video is regenerated, not re-shot. Demo-as-Code.

python -m http.server 8765 --directory examples/demo-site &
tourcast record examples/scenarios/demo-tour.yaml -o demo.mp4

That example needs nothing but this repository: the demo site is checked in.

Commands

Four of them, and every one takes a single scenario file — tourcast <verb> <scenario>.

probe exists because scenarios should be written from measurement, not guesswork. It walks the sidebar, clicks the first row of every table and reports what actually happened — whether the row opens a detail page or a modal, how far each screen scrolls, which tabs exist.

How it works

scenario.yaml  ->  world (Playwright)  ->  frames (CDP screencast)  ->  camera  ->  MP4
                        |                                                 |
                        |  navigation, clicks, the real pointer           |  crop, dim,
                        |                                                 |  cursor, timing

Two decisions shape everything else.

The camera never touches the page. Zoom is a crop rectangle over captured frames, not a CSS transform. A transform would re-evaluate viewport units and media queries, so the video would no longer show the app as users see it — and it would break differently in every app, which makes a shared tool impossible.

The cursor is composited after capture. It is not injected into the DOM. Its path is recorded as data and drawn onto each output frame, so its motion is independent of browser paint timing. That also means it works unchanged inside iframes.

Profiles keep it app-agnostic

Everything the engine would otherwise need to know about an app lives in a profile.

profiles/<app>.yaml    base URL, login recipe, selector aliases, ready states
scenarios/*.yaml       order of movement, dwell times, emphasis
tourcast/              the engine — knows no app

Recording a new app means adding one profile and one scenario. The engine is not touched — the claim was checked by recording a second, deliberately different app (no login, direct page entry instead of an iframe): one profile and one scenario were added and no engine line changed.

Scenarios never contain raw selectors — only aliases the profile defines. When a selector breaks, exactly one file changes.

Install

pipx install tourcast          # or: pip install tourcast
playwright install chromium

ffmpeg must be on PATH:

brew install ffmpeg            # macOS
sudo apt install ffmpeg        # Debian/Ubuntu
winget install Gyan.FFmpeg     # Windows

Fonts are the machine's job, not the tool's. tourcast draws no text, and Chromium can only use fonts the OS knows about — so recording an app in a language whose font is missing produces a valid video full of empty boxes, with no error. On a bare container, install them and verify:

sudo apt install fonts-noto-core fonts-noto-cjk
python tools/check-glyphs.py    # exits 1 if a script renders as tofu

Non-goals

Kept out on purpose, so a request to add them has a clear answer.

Status

Working end to end. Measured on the pipeline itself:

Documentation

Split by kind, not by language — a translated journal would only diverge from the original.

Reference — what you read to use the tool. English, single source.

Decisions — why it is built this way. A working journal in Korean, with an English index.

The index is worth a minute before changing anything in tourcast/: several entries are invariants that fail silently when broken — the supersampling launch flag being the clearest one.

Development

python3 -m venv .venv
.venv/bin/pip install playwright pyyaml pillow pytest
.venv/bin/playwright install chromium

.venv/bin/python -m pytest tests/ -q                 # no browser needed, runs in under a second
python -m http.server 8765 --directory examples/demo-site &
.venv/bin/python -m tourcast.cli record examples/scenarios/demo-tour.yaml -o out/demo.mp4

Profiles and scenarios that carry credentials are named *.local.yaml and are gitignored.

CI (.github/workflows/ci.yml) runs the tests on 3.11–3.13, then records the example tour on Linux and checks the run report — a blurry zoom or a cursor that never moved fails the build, since neither shows up as a non-zero exit code.