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
- Narrate. Reads the deck (HTML
<aside class="notes">per slide, or.pptxnotes pane). Sends each slide's narration text to Amazon Polly. Writes per-slide MP3s and a slides manifest. - 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.
- Record demo (optional). For each
demo.sequences[]entry, a fresh headless Chromium plays through the steps and writes one.webmper sequence. - 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.
Metadata
Release files for democast 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| democast-0.3.0.tar.gz | 32.3 kB | Without provenance | Details for democast-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| democast-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for democast-0.3.0-py3-none-any.whl |
Total release size: 72.5 kB
Release files / democast-0.3.0.tar.gz
| Download URL | democast-0.3.0.tar.gz |
|---|---|
| Size | 32.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7421b8978987c86f385ade76b7f06e146093c83b0238d9fa1abded471ac81e31
|
|
BLAKE2b-256 checksum How to use checksums |
cfc03ea2b864eafa15156fbac996042c38c0161ac1bb60eb46a4cce244328995
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / democast-0.3.0-py3-none-any.whl
| Download URL | democast-0.3.0-py3-none-any.whl |
|---|---|
| Size | 40.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11decb31d8914122c9d415a37887e2801f4ede06232f0beb3ba48ba84a86b47b
|
|
BLAKE2b-256 checksum How to use checksums |
13473c37b394309e4eb675be98300d5f64e9fe227f92ff40058e5abc475b6445
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Security for democast 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.