democast 0.2.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

Install

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

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), but pipx is the cleanest path.

System tooling democast needs

democast setup audits the rest of the toolchain. The 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

If pdftoppm isn't available, install democast with the pymupdf extra:

pipx install 'democast[pymupdf]'

Quick start

# In an empty project folder, anywhere on disk:
democast init

# Edit the scaffolded files (see democast-README.md for the full reference).
# At minimum, point deck.path in democast.config.json at your deck.

# Demo credentials (only if you keep the demo segment).
export DEMO_EMAIL=...
export DEMO_PASSWORD=...

# Build.
democast run

Output lands at ./final.mp4 by default. Change with output.dir and output.final_name in democast.config.json. All intermediates land in output.dir/democast-working-dir/, which is removed automatically on success. Pass --keep-intermediates to keep it for debugging.

CLI

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

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). Playwright drives a live web app headless, following a JSON-defined sequence of clicks/types/waits.
4. Stitch. ffmpeg cuts the deck around insert_after_slide, re-encodes each segment with its narration, and concats: pre-deck → demo → post-deck → final.mp4.

Configuration

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

File	Purpose
democast.config.json	Engine config (deck path, voice, viewport, output).
democast-macro.json	Optional. Reusable engine for the demo: app URL, credentials, named actions (Playwright recipes), waits (JS predicates).
democast-sequence.json	Optional. Storyboard for one video: where to splice the demo into the deck, ordered list of steps with narration.

Set "demo": false (or omit) 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, and a worked end-to-end example. It's written so an LLM can read it once and populate the three config files for any project.

License

MIT. See LICENSE.