# Demo Video

> Produce a short demo video of a web UI change for a pull request: explore the flow unrecorded, script and replay it with 4K frame capture, plan the edit (zoom on each action, drawn cursor, click ripples, captions, optional narration), render an H.264 MP4, gate it with frame-measured quality control and an independent frame review, then attach it to the PR. Use when: 'demo video', 'record a demo of this change', 'make a PR video', 'produced walkthrough video', 'produced screen recording of a web flow', 'video proof a UI change works', 'video evidence for the PR'.

- Skill: `melodic-software/demo-video` (Agent Skill, multi-file: 25 files)
- Install (CLI): `npx get-skill add melodic-software/demo-video`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/demo-video/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: melodic-software (https://skillmd.com/u/melodic-software)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/melodic-software/demo-video

---


# Demo video for a pull request

A produced demo is a short MP4 (about 12-20 s) that shows the change working: the camera zooms in
on each action, a drawn cursor travels and clicks with a ripple, captions name each step and its
outcome, and page loads are cut out. The pipeline lives in `scripts/`; every editing decision is
data in an edit-decision list (EDL), so a defect is fixed in the plan, not by hand.

Run every Python script through the launcher, which supplies the hash-locked numpy and Pillow and
never installs. Below, `RUN` stands for this prefix, written out in full in each command:

```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/pydeps.py" run --data-dir "${CLAUDE_PLUGIN_DATA}" -- "${CLAUDE_SKILL_DIR}/scripts/<script>.py" ...
```

When the packages are missing the launcher exits 2 and prints one install line; show it to the
user and run it after their yes. It needs Python 3.12+, `ffmpeg` and `ffprobe` on PATH, and
`node` with `playwright-cli` (or `playwright-core`) for recording; `node "${CLAUDE_PLUGIN_ROOT}/lib/prerequisites.mjs" check "${CLAUDE_PLUGIN_ROOT}"` covers the
last two.

## Settings

The plugin's options set the defaults; a `--style` argument overrides the style for one run. When
the Saved value column shows a literal `${user_config...}` placeholder, nothing is saved for that
option: use its Default.

| Option | Saved value | Default | Effect |
|---|---|---|---|
| `demo_style` | `${user_config.demo_style}` | `produced` | `produced`, or `plain`: the same replay and cursor with no zoom, captions or title |
| `demo_title` | `${user_config.demo_title}` | `true` | title card |
| `demo_camera` | `${user_config.demo_camera}` | `true` | zoom and pan |
| `demo_cursor` | `${user_config.demo_cursor}` | `true` | drawn pointer |
| `demo_ripple` | `${user_config.demo_ripple}` | `true` | click ring |
| `demo_captions` | `${user_config.demo_captions}` | `true` | step and outcome captions |
| `demo_narration` | `${user_config.demo_narration}` | `false` | voice-over |

Pointer: [Reference a saved value](https://code.claude.com/docs/en/plugins/manifest-reference#reference-a-saved-value);
as of 2026-10-11; recheck when that section changes what an unset option renders as.

`plain` removes the title, camera and captions whatever their toggles say; a toggle set to `false`
removes its layer in either style. Pass them to `build_edl.py` as
`--style <style> --layers title=<bool>,camera=<bool>,cursor=<bool>,ripple=<bool>,captions=<bool>`.

## Workflow

1. **Explore, unrecorded.** Drive the flow with `/playwright:playwright` until every step works and
   you know a stable locator for each target. Nothing is recorded here: agent think-time is what
   makes a raw recording unwatchable. Keep what exploring leaves behind out of the repository:
   `/playwright:playwright` says where its artifacts land, so run it from `<work>` or move them
   into `<work>/explore/`. When the flow changes stored state (a save, a submit, a setting),
   explore on a throwaway copy of the app or its data and reset that state before every
   recording, so each replay starts from the state the demo shows.
2. **Write the replay script.** One ES module default-exporting `async (demo) => {}`, one
   `demo.click(...)` to `demo.settle(...)` per step, step ids that key the captions. The API and the
   example over the bundled fixture: [reference/replay-script.md](reference/replay-script.md),
   [scripts/fixture/replay.mjs](scripts/fixture/replay.mjs). Write `script.json` beside it: title,
   subtitle, and per step `caption`, `outcome` (the result the viewer reads once the step lands,
   on a new page or in place), and the narration lines. A hold that shows an outcome lasts its
   reading time (`captions.seconds_per_word`, never under `captions.min_seconds`, in
   `scripts/defaults.json`), and quality control lets it stay still that much longer than the
   stillness limit; a hold with no outcome keeps the limit.
3. **Replay with 4K capture.**
   `node ${CLAUDE_SKILL_DIR}/scripts/record.mjs [--playwright-core DIR] replay.mjs <work>/capture`.
   The viewport is 1920x1080 at device scale 2, so every frame is a 3840x2160 PNG; cursor travel and
   typing run three times slower than real time and are retimed in post, because device-pixel
   screenshots arrive at about 4 fps (`record.mjs` prints the rate of each recording). Capture
   uses device-pixel screenshots, not Chromium's screencast. Pointer: when weighing the screencast
   as a capture source, fetch
   [Page.startScreencast](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-startScreencast)
   live. As of: 2026-11-03. Recheck trigger: that method changes its frame size parameters.
4. **Narration (only when `demo_narration` is true).** When the speech plugin is installed, run
   `/speech:narrate` once per line into `<work>/audio/<step>/`, `<work>/audio/<step>.outcome/` and,
   for a typing step, `<work>/audio/<step>.results/`; each folder gets `narration.wav` and
   `words.json`. Without the speech plugin, skip narration and say so.
5. **Build the edit plan.**
   `RUN build_edl.py <work>/capture script.json <work>/edl.json --style ... --layers ... [--audio-dir <work>/audio]`.
   It refuses (exit 1, plan kept as `edl.rejected.json`) when a rule breaks: a zoom edge through
   text, a navigation cut not at 1.0x, a camera move over the limits, a caption with no empty
   anchor. A `shot search:` line after the rules names the steps no zoom shot fits; a caption
   with no empty anchor often follows from it. Fix the replay (a tighter `block`, a pause) or the
   script, never the rule.
6. **Render.** `RUN produce.py <work>/edl.json <work>/demo.mp4`
   (add `--preset veryfast` for drafts). It writes `demo.render.json` beside the video.
7. **Frame quality control.** `RUN quality_control.py <work>/edl.json <work>/demo.mp4 <work>/quality-control`
   measures every rule from the rendered frames and exits 1 on any FAIL. The checks and where each
   threshold comes from: [reference/quality-control.md](reference/quality-control.md). A FAIL goes back to step 2 or 5.
8. **Independent frame review.** Run
   `bash "${CLAUDE_PLUGIN_ROOT}/lib/read-verification.sh" --plugin playwright --skill demo-video`
   and copy its line into the report
   ([levels](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/verification-level/README.md)).
   At standard or strict, dispatch a fresh-context subagent that did not produce the video,
   with the brief in [reference/independent-review.md](reference/independent-review.md): the video,
   the quality-control sheets and the acceptance rules, and none of your reasoning about why it is fine. Fix what
   it finds and repeat 6-8. Nothing is posted on the producer's word.
   - Under `light`, and `off`, which acts as `light` here, the secrets check still runs: it is the
     only check for secrets and personal data in the frames before posting. Dispatch the
     fresh-context subagent with the brief's item 7 only, and post only when it finds nothing.
     Skip items 1-6, never judge them yourself in their place, and write
     `verification: skipped (<level>)` with the video reported as not independently judged for
     quality.
9. **Post.** [reference/posting.md](reference/posting.md): verification evidence goes through
   `/source-control:pull-request evidence` when it resolves. A demo a person asked for, or
   evidence when that step does not resolve, goes locally through `gh pr comment --attach`, and in
   CI as a non-zipped Actions artifact plus a comment linking it. Pointer: when checking what
   `--attach` takes, fetch [gh pr comment: Options](https://cli.github.com/manual/gh_pr_comment#options)
   live. As of: 2026-11-03. Recheck trigger: that list renames or drops `--attach`.

## Next

/playwright:playwright

Return to it to re-run the flow when the review asks for a change to the app or the replay.

## Gotchas

- **Backdrop blur stalls capture.** A `backdrop-filter` (a DocSearch-style search modal) dropped
  software-rendered capture to about 3 fps; `record.mjs` disables it, and the caret, on every page.
- **Looping animations never settle.** `demo.settle` waits for identical captures, so an endless
  CSS animation (a pulsing status dot, a spinner), often drawn on `::before` or `::after`, makes
  `record.mjs` stop with "page never went still". Find it with `document.getAnimations()` while
  exploring and stop it in the replay with `demo.style(...)`, naming the pseudo-element in the
  selector (`.pill::before { animation: none !important; }`): a rule on the element, or on `*`
  under it, does not reach its pseudo-elements.
- **Kokoro pads each clip.** The local voice adds about 0.35 s of silence before the first word;
  `build_edl.py` trims each clip to its first word using `words.json`, so keep that file beside
  each `narration.wav`.
- **Crossfades ghost.** Blending two page states shows both at once (double text, half-drawn
  panels). Page changes are hard cuts with the camera still; the only blend is the title dipping
  through ink, and `quality_control.py` fails any other.
- **Producer self-reports are not evidence.** A producer's own numbers (zoom share from the plan,
  "all checks pass") disagreed with frame measurement three times while this pipeline was built.
  Only `quality_control.py` output and the independent review count.
- **Block-level elements span the row.** A heading's box is as wide as its container, so a `block`
  made from it cannot be zoomed; build the block from elements that hug their content or pass an
  explicit `[x, y, w, h]`.
- **Hide partial states in the replay.** Results that re-render per keystroke flash "No results"
  states; hide them with `demo.style(css)` while typing and reveal them after, as the reference
  shows.
- **`ffmpeg -ss` in the quality-control sheets is approximate.** The sheets are for looking; the checks read
  every decoded frame.

