Metadata-Version: 2.4
Name: democast
Version: 0.3.0
Summary: Turn a slide deck (reveal.js or pptx) plus an optional scripted app demo into a single narrated MP4.
Project-URL: Homepage, https://github.com/xanhuang/democast
Project-URL: Source, https://github.com/xanhuang/democast
Project-URL: Issues, https://github.com/xanhuang/democast/issues
Author-email: Xan Huang <xan@example.com>
License: MIT
License-File: LICENSE
Keywords: demo,ffmpeg,narration,playwright,polly,pptx,reveal.js,video
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: boto3>=1.34
Requires-Dist: mutagen>=1.47
Requires-Dist: playwright>=1.49
Requires-Dist: python-pptx>=1.0
Provides-Extra: pymupdf
Requires-Dist: pymupdf>=1.24; extra == 'pymupdf'
Description-Content-Type: text/markdown

# 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

```bash
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:

```bash
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:

```bash
pipx install 'democast[pymupdf]'
```

## CLI

```bash
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](LICENSE).
