democast 0.3.0

Turn a slide deck (reveal.js or pptx) plus an optional scripted app demo into a single narrated MP4.

democast

Turn a slide deck (reveal.js HTML or PowerPoint .pptx) plus an optional scripted app demo into a single narrated MP4. Amazon Polly does the voice; Playwright drives the demo; ffmpeg stitches everything together.

narrate     →  Polly synthesises one MP3 per slide and per demo step
record_deck →  Playwright records the reveal.js deck headed,
               or LibreOffice → ffmpeg builds a video from pptx slides
record_demo →  Playwright drives the app per the demo bundle (skipped if absent)
stitch      →  ffmpeg splices  pre-deck → demo → post-deck → final.mp4

Quick start

pipx install democast
democast setup           # one-time: download Playwright Chromium, audit tooling

democast init            # in an empty project folder
# edit democast-config.json → point at your deck (.html or .pptx)
# (optional) edit democast-macro.json for the demo's actions/waits
democast run             # → final.mp4

pipx is the recommended way to install Python CLIs because each tool gets its own isolated venv. If you don't have pipx:

brew install pipx        # macOS
apt-get install pipx     # Linux
python -m pip install --user pipx

pip install democast also works — drop it into your venv of choice or use pip install --user democast.

If you don't have pdftoppm and want pptx support, install with the pymupdf extra:

pipx install 'democast[pymupdf]'

CLI

democast setup                                        # one-time tooling check
democast init  [--here <dir>] [--force] [--no-check]  # scaffold config files
democast run   [--config <path>] [--keep-intermediates]

System tooling

democast setup audits the toolchain. Full list:

What	Required for	Install (macOS)	Install (Linux)	Verify
Python ≥ 3.11	always	brew install python@3.12	distro package or pyenv	python3 --version
ffmpeg	always	brew install ffmpeg	apt-get install ffmpeg	ffmpeg -version
AWS creds with Polly access	always	aws configure	same	aws sts get-caller-identity
Playwright Chromium	reveal-format decks and any project with a demo segment	democast setup (or python -m playwright install chromium)	same	democast setup will tell you
LibreOffice	only format: "pptx" decks	brew install --cask libreoffice	apt-get install libreoffice	soffice --version
pdftoppm (poppler)	optional speedup for format: "pptx" (PyMuPDF fallback)	brew install poppler	apt-get install poppler-utils	pdftoppm -v

How it works

1. Narrate. Reads the deck (HTML <aside class="notes"> per slide, or .pptx notes pane). Sends each slide's narration text to Amazon Polly. Writes per-slide MP3s and a slides manifest.
2. Record deck. Either Playwright drives a reveal.js deck headed while the slide auto-advances, or LibreOffice + ffmpeg flatten the pptx into a video where each slide is held for its narration's duration.
3. Record demo (optional). For each demo.sequences[] entry, a fresh headless Chromium plays through the steps and writes one .webm per sequence.
4. Stitch. ffmpeg cuts the deck into slices around each after_slide, encodes each slice + each demo, then concats: slides → demo → slides → demo → … → final.mp4.

Configuration

democast init scaffolds two files plus a comprehensive democast-README.md reference:

File	Purpose
democast-config.json	Engine config: deck path/format, voice, video size, output, and the demo block (app URL, secrets, required vars, sequences).
democast-macro.json	Reusable Playwright recipes — named actions and waits referenced from sequences.

Omit the demo block in democast-config.json to skip the demo segment and get a deck-only video.

The scaffolded democast-README.md is a self-contained authoring guide covering the full schema, primitive reference, locator vocabulary, predicate cookbook, validation rules, multi-sequence splicing, and a worked end-to-end example. It's written so an LLM can read it once and populate the two config files for any project.

License

MIT. See LICENSE.