Metadata-Version: 2.4
Name: democast
Version: 0.2.1
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
```

## Install

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

```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`), 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:

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

## Quick start

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

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