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:
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;
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
- 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.
- 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,
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.
- 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
live. As of: 2026-11-03. Recheck trigger: that method changes its frame size parameters.
- 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.
- 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.
- Render.
RUN produce.py <work>/edl.json <work>/demo.mp4
(add --preset veryfast for drafts). It writes demo.render.json beside the video.
- 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. A FAIL goes back to step 2 or 5.
- 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).
At standard or strict, dispatch a fresh-context subagent that did not produce the video,
with the brief in 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.
- Post. 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
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.
1---2name: demo-video3description: "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'."4argument-hint: "<url or flow to demo> [--style produced|plain]"5user-invocable: true6disable-model-invocation: false7metadata:8 source: https://skillmd.com/skills/melodic-software/demo-video9 workflow-stage: verify10 summary: Replay a web flow, render a produced demo video, quality-control it from frames, post it to the PR11---1213# Demo video for a pull request1415A produced demo is a short MP4 (about 12-20 s) that shows the change working: the camera zooms in16on each action, a drawn cursor travels and clicks with a ripple, captions name each step and its17outcome, and page loads are cut out. The pipeline lives in `scripts/`; every editing decision is18data in an edit-decision list (EDL), so a defect is fixed in the plan, not by hand.1920Run every Python script through the launcher, which supplies the hash-locked numpy and Pillow and21never installs. Below, `RUN` stands for this prefix, written out in full in each command:2223```bash24python3 "${CLAUDE_SKILL_DIR}/scripts/pydeps.py" run --data-dir "${CLAUDE_PLUGIN_DATA}" -- "${CLAUDE_SKILL_DIR}/scripts/<script>.py" ...25```2627When the packages are missing the launcher exits 2 and prints one install line; show it to the28user and run it after their yes. It needs Python 3.12+, `ffmpeg` and `ffprobe` on PATH, and29`node` with `playwright-cli` (or `playwright-core`) for recording; `node "${CLAUDE_PLUGIN_ROOT}/lib/prerequisites.mjs" check "${CLAUDE_PLUGIN_ROOT}"` covers the30last two.3132## Settings3334The plugin's options set the defaults; a `--style` argument overrides the style for one run. When35the Saved value column shows a literal `${user_config...}` placeholder, nothing is saved for that36option: use its Default.3738| Option | Saved value | Default | Effect |39|---|---|---|---|40| `demo_style` | `${user_config.demo_style}` | `produced` | `produced`, or `plain`: the same replay and cursor with no zoom, captions or title |41| `demo_title` | `${user_config.demo_title}` | `true` | title card |42| `demo_camera` | `${user_config.demo_camera}` | `true` | zoom and pan |43| `demo_cursor` | `${user_config.demo_cursor}` | `true` | drawn pointer |44| `demo_ripple` | `${user_config.demo_ripple}` | `true` | click ring |45| `demo_captions` | `${user_config.demo_captions}` | `true` | step and outcome captions |46| `demo_narration` | `${user_config.demo_narration}` | `false` | voice-over |4748Pointer: [Reference a saved value](https://code.claude.com/docs/en/plugins/manifest-reference#reference-a-saved-value);49as of 2026-10-11; recheck when that section changes what an unset option renders as.5051`plain` removes the title, camera and captions whatever their toggles say; a toggle set to `false`52removes its layer in either style. Pass them to `build_edl.py` as53`--style <style> --layers title=<bool>,camera=<bool>,cursor=<bool>,ripple=<bool>,captions=<bool>`.5455## Workflow56571. **Explore, unrecorded.** Drive the flow with `/playwright:playwright` until every step works and58 you know a stable locator for each target. Nothing is recorded here: agent think-time is what59 makes a raw recording unwatchable. Keep what exploring leaves behind out of the repository:60 `/playwright:playwright` says where its artifacts land, so run it from `<work>` or move them61 into `<work>/explore/`. When the flow changes stored state (a save, a submit, a setting),62 explore on a throwaway copy of the app or its data and reset that state before every63 recording, so each replay starts from the state the demo shows.642. **Write the replay script.** One ES module default-exporting `async (demo) => {}`, one65 `demo.click(...)` to `demo.settle(...)` per step, step ids that key the captions. The API and the66 example over the bundled fixture: [reference/replay-script.md](reference/replay-script.md),67 [scripts/fixture/replay.mjs](scripts/fixture/replay.mjs). Write `script.json` beside it: title,68 subtitle, and per step `caption`, `outcome` (the result the viewer reads once the step lands,69 on a new page or in place), and the narration lines. A hold that shows an outcome lasts its70 reading time (`captions.seconds_per_word`, never under `captions.min_seconds`, in71 `scripts/defaults.json`), and quality control lets it stay still that much longer than the72 stillness limit; a hold with no outcome keeps the limit.733. **Replay with 4K capture.**74 `node ${CLAUDE_SKILL_DIR}/scripts/record.mjs [--playwright-core DIR] replay.mjs <work>/capture`.75 The viewport is 1920x1080 at device scale 2, so every frame is a 3840x2160 PNG; cursor travel and76 typing run three times slower than real time and are retimed in post, because device-pixel77 screenshots arrive at about 4 fps (`record.mjs` prints the rate of each recording). Capture78 uses device-pixel screenshots, not Chromium's screencast. Pointer: when weighing the screencast79 as a capture source, fetch80 [Page.startScreencast](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-startScreencast)81 live. As of: 2026-11-03. Recheck trigger: that method changes its frame size parameters.824. **Narration (only when `demo_narration` is true).** When the speech plugin is installed, run83 `/speech:narrate` once per line into `<work>/audio/<step>/`, `<work>/audio/<step>.outcome/` and,84 for a typing step, `<work>/audio/<step>.results/`; each folder gets `narration.wav` and85 `words.json`. Without the speech plugin, skip narration and say so.865. **Build the edit plan.**87 `RUN build_edl.py <work>/capture script.json <work>/edl.json --style ... --layers ... [--audio-dir <work>/audio]`.88 It refuses (exit 1, plan kept as `edl.rejected.json`) when a rule breaks: a zoom edge through89 text, a navigation cut not at 1.0x, a camera move over the limits, a caption with no empty90 anchor. A `shot search:` line after the rules names the steps no zoom shot fits; a caption91 with no empty anchor often follows from it. Fix the replay (a tighter `block`, a pause) or the92 script, never the rule.936. **Render.** `RUN produce.py <work>/edl.json <work>/demo.mp4`94 (add `--preset veryfast` for drafts). It writes `demo.render.json` beside the video.957. **Frame quality control.** `RUN quality_control.py <work>/edl.json <work>/demo.mp4 <work>/quality-control`96 measures every rule from the rendered frames and exits 1 on any FAIL. The checks and where each97 threshold comes from: [reference/quality-control.md](reference/quality-control.md). A FAIL goes back to step 2 or 5.988. **Independent frame review.** Run99 `bash "${CLAUDE_PLUGIN_ROOT}/lib/read-verification.sh" --plugin playwright --skill demo-video`100 and copy its line into the report101 ([levels](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/verification-level/README.md)).102 At standard or strict, dispatch a fresh-context subagent that did not produce the video,103 with the brief in [reference/independent-review.md](reference/independent-review.md): the video,104 the quality-control sheets and the acceptance rules, and none of your reasoning about why it is fine. Fix what105 it finds and repeat 6-8. Nothing is posted on the producer's word.106 - Under `light`, and `off`, which acts as `light` here, the secrets check still runs: it is the107 only check for secrets and personal data in the frames before posting. Dispatch the108 fresh-context subagent with the brief's item 7 only, and post only when it finds nothing.109 Skip items 1-6, never judge them yourself in their place, and write110 `verification: skipped (<level>)` with the video reported as not independently judged for111 quality.1129. **Post.** [reference/posting.md](reference/posting.md): verification evidence goes through113 `/source-control:pull-request evidence` when it resolves. A demo a person asked for, or114 evidence when that step does not resolve, goes locally through `gh pr comment --attach`, and in115 CI as a non-zipped Actions artifact plus a comment linking it. Pointer: when checking what116 `--attach` takes, fetch [gh pr comment: Options](https://cli.github.com/manual/gh_pr_comment#options)117 live. As of: 2026-11-03. Recheck trigger: that list renames or drops `--attach`.118119## Next120121/playwright:playwright122123Return to it to re-run the flow when the review asks for a change to the app or the replay.124125## Gotchas126127- **Backdrop blur stalls capture.** A `backdrop-filter` (a DocSearch-style search modal) dropped128 software-rendered capture to about 3 fps; `record.mjs` disables it, and the caret, on every page.129- **Looping animations never settle.** `demo.settle` waits for identical captures, so an endless130 CSS animation (a pulsing status dot, a spinner), often drawn on `::before` or `::after`, makes131 `record.mjs` stop with "page never went still". Find it with `document.getAnimations()` while132 exploring and stop it in the replay with `demo.style(...)`, naming the pseudo-element in the133 selector (`.pill::before { animation: none !important; }`): a rule on the element, or on `*`134 under it, does not reach its pseudo-elements.135- **Kokoro pads each clip.** The local voice adds about 0.35 s of silence before the first word;136 `build_edl.py` trims each clip to its first word using `words.json`, so keep that file beside137 each `narration.wav`.138- **Crossfades ghost.** Blending two page states shows both at once (double text, half-drawn139 panels). Page changes are hard cuts with the camera still; the only blend is the title dipping140 through ink, and `quality_control.py` fails any other.141- **Producer self-reports are not evidence.** A producer's own numbers (zoom share from the plan,142 "all checks pass") disagreed with frame measurement three times while this pipeline was built.143 Only `quality_control.py` output and the independent review count.144- **Block-level elements span the row.** A heading's box is as wide as its container, so a `block`145 made from it cannot be zoomed; build the block from elements that hug their content or pass an146 explicit `[x, y, w, h]`.147- **Hide partial states in the replay.** Results that re-render per keystroke flash "No results"148 states; hide them with `demo.style(css)` while typing and reveal them after, as the reference149 shows.150- **`ffmpeg -ss` in the quality-control sheets is approximate.** The sheets are for looking; the checks read151 every decoded frame.