demo-recording
Skill37 starsChanged 20 days agoApache-2.0View on GitHub
Record a video of SLICC UI changes for a pull request. Two modes: a fast CDP screencast of the *running* dev/e2e harness (to review what changed frame-by-frame, issue #1264), and a polished cursor-animated MP4 (playwright-cli + ffmpeg) for showcase demos. Upload the result to the PR with `gh --attach`. Use when asked to record a UI demo, capture a before/after, showcase a feature, or attach a screencast to a pull request.
- Commits and pushes
5 other projects use a version of this.
Adopted by
Most recently taken up by
- SamRome1/devrel-skillstheir own version, first seen Nov 8, 2026
- product-llc/claude-skillstheir own version, first seen Oct 8, 2026
- weill-labs/amuxtheir own version, first seen Jun 2, 2026
- masonhuemmer/dopstheir own version, first seen Mar 24, 2026
- rundops/dopstheir own version, first seen Mar 24, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- weill-labs/amux★ 34same name
- masonhuemmer/dops★ 3same name
- rundops/dops★ 3same name
- SamRome1/devrel-skills★ 1same name
- product-llc/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- adding-slicc-featuresSkill
- cdp-smoke-testSkill
- deploying-tray-workerSkill
- slicc-handoffSkill
- verifying-before-pushSkill
- writing-slicc-testsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. 0 are common, 8 are distinctive, and 10 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 111
Verify the dev URL first: Don't assume the obvious port serves the UI — in thin-bridge/single-page-app architectures the "app port" may …
- Very specific: line 255
Always inject the cursor inside the run-code script, not in a prior playwright-cli eval.
- Distinctive: line 302
Always verify state with a measurement eval before starting the recording, especially when re-taking a failed demo.
- Very specific: line 309
NOT fire pointerover/pointermove events on page elements.
- Distinctive: line 367
If you see "Cannot accept dialog which is already handled" that's fine — it means an in-script handler beat you to it.
- Very specific: line 425
If your actual viewport is larger (e.g.
- Very specific: line 435
Workaround: use page.evaluate() to dispatch PointerEvent directly on the element for the functional behavior, and use page.evaluate() with …
- Distinctive: line 475
Read each frame image — adjust timestamps based on what's actually visible
- Distinctive: line 476
Only then add overlays/toasts
- Distinctive: line 482
Keep pauses short (200–400ms between actions) for a snappy demo
- Distinctive: line 483
Add 1–1.5s holds after each major state change so viewers can see it
- Very specific: line 490
Use -movflags +faststart for instant playback in browsers
- Distinctive: line 495
Add chapter markers for longer recordings (visible in the Playwright dashboard, useful for debugging timing):
- Distinctive: line 542
If missing, use Python + OpenCV + Pillow instead.
- Very specific: line 626
Important: Use ASCII-only text — Unicode arrows (→), dots (·), and em-dashes (—) render as empty squares with Helvetica.ttc in PIL.
- Very specific: line 628
Use - and -> instead.
- Very specific: line 668
If you need the URLs somewhere the rewrite cannot reach (a second comment, the PR body, a checklist you build later), post once with a …
- Very specific: line 686
Use --repo owner/repo outside a repo dir.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Demo Recording
Record a video of a SLICC UI change for a pull request, then upload it with
gh --attach (see § Embedding in GitHub PRs; needs gh >= 2.99). Pick the mode
that fits.
Two capture modes
- CDP screencast (§ CDP screencast) — attaches over Chrome DevTools
Protocol to the leader tab the dev/e2e harness already drives, streams
Page.startScreencastframes to disk, and optionally stitches a webm. Fast, no separate browser, source-of-truth frames for "what changed". Use to review UI changes frame-by-frame or capture a before/after for a PR. - Polished cursor-animated MP4 (§ Polished MP4 with playwright-cli) —
playwright-cli video-start/stopwith an injected visible cursor and chapter markers, post-processed into a GitHub-embeddable MP4. Use for showcase demos.
CDP screencast (frame capture of the running harness)
packages/dev-tools/tools/slicc-screencast.mjs attaches to Chrome's remote
debugging port, locks onto the SLICC leader page target, and streams
Page.startScreencast frames to disk as frame-000001.jpeg … plus a
manifest.json (real capture timestamps). It records the same Chrome the
harness already uses — so you review exactly what the harness rendered. It is a
host-side node tool (like slicc-debug.mjs), not a SLICC shell command.
Quick start (against the deterministic fake-LLM e2e harness)
The e2e harness (packages/webapp/tests/e2e/playwright.config.ts) boots wrangler
(UI on :8787), the node-server thin-bridge, and the fake LLM, and launches
Chrome with --remote-debugging-port=9222. Reuse it to get a reproducible run:
# 0. one-time in a fresh VM: system libs for Chrome + ffmpeg
npx playwright install chromium && npx playwright install-deps chromium
# 1. start the recorder against the harness Chrome, locked to the leader tab
node packages/dev-tools/tools/slicc-screencast.mjs \
--port 9222 --url localhost:8787 --out /tmp/shot --video &
# 2. drive the UI (see below), then stop the recorder
kill -INT %1 # flushes manifest.json (+ screencast.webm if --video)Frames + manifest.json land in --out. Review them directly (open a few
frame-*.jpeg), or watch screencast.webm.
Driving the UI while recording
Pick whichever fits — the recorder just captures whatever the tab shows:
slicc-cdp+slicc-debug.mjs(host, over the same CDP port) — drive the agent with.agents/skills/cdp-smoke-test/scripts/slicc-cdp prompt "open the reference page"or the shell withnode packages/dev-tools/tools/slicc-debug.mjs shell "playwright-cli ...".- A Playwright e2e test — the deterministic path. Boot the leader with the
harness helpers (
seedLocalLlmProvider→gotoLeader→waitForSW), thensubmitUserMessage(page, …)+waitForTurnComplete(page)per phase. Spawn the recorder as a child against:9222for a fully reproducible capture. - By hand — just interact in the visible Chrome window.
Live dev harness (non-e2e)
The recorder works against any SLICC Chrome with remote debugging — e.g.
npm run dev or npm run dev:standalone:fresh (wrangler :8787 + thin-bridge
:5710, Chrome CDP :9222). Same command; --port/SLICC_CDP_PORT and
--url/SLICC_TARGET_URL select the port and page target.
Options
| Flag | Default | Purpose |
--out <dir> | /tmp/slicc-screencast/<stamp> | Frame output directory |
--port <n> | SLICC_CDP_PORT else 9222/9223 | Chrome CDP port |
--url <substr> / --url-pattern <re> | SLICC_TARGET_URL | Pick the page target (errors if it matches nothing; with no filter, prefers the leader origin :8787/:57xx) |
--duration <sec> | until SIGINT | Auto-stop after N seconds |
--format jpeg|png | jpeg | Frame image format |
--quality <0-100> | 80 | JPEG quality |
--max-width/--max-height <px> | 1280 / 800 | Frame bounds |
--every-nth <n> | 1 | Capture every Nth frame |
--video / --fps <n> | off / 10 | Assemble screencast.webm |
Video assembly (best-effort)
The frames + manifest.json are the source of truth; --video is a
convenience. slicc-screencast-video.mjs resolves ffmpeg from PATH, falling
back to Playwright's bundled ffmpeg. That bundled build is stripped — it has no
image2 demuxer and only the VP8 encoder — so assembly feeds frames via
image2pipe on stdin (-c:v mjpeg -i pipe:0) and writes VP8 webm. On a full
ffmpeg build it also produces mp4/gif. If assembly fails, the frames remain.
Polished MP4 with playwright-cli
Record short (15–30s) demo videos of SLICC UI features using
playwright-cli video-start/stop, an injected visible cursor, and
ffmpeg for post-processing. Produces GitHub-embeddable MP4s.
Quick Start (playwright-cli)
Verify the dev URL first. Don't assume the obvious port serves the UI —
in thin-bridge/single-page-app architectures the "app port" may serve no UI
at all (SLICC's node-server serves none; the webapp loads from a separate
UI-serving port and dials back over a bridge token in the query string, e.g.
http://localhost:8787/?bridge=ws://localhost:5710/cdp&bridgeToken=<uuid>).
curl the candidate port or check the dev script before wiring a recording
around it. See "Attaching to a Single-Leader-Tab App" below if the app only
accepts one connected browser session.
# 1. Open a browser and navigate — replace with your app's real dev URL
playwright-cli open http://localhost:PORT
playwright-cli resize 1280 720
# 2. Inject the visible cursor (headless Chrome has no native cursor)
playwright-cli eval '<CURSOR_SNIPPET>' # see § Visible Cursor below
# 3. Start recording
playwright-cli video-start /tmp/demo.webm
# 4. Perform interactions (clicks, drags, etc.)
playwright-cli click e119 # click by snapshot ref
playwright-cli run-code --filename /tmp/demo-script.js
# 5. Stop recording
playwright-cli video-stop
# 6. Convert + trim with ffmpeg
ffmpeg -y -ss 2 -t 18 -i /tmp/demo.webm \
-c:v libx264 -preset fast -crf 20 \
-pix_fmt yuv420p -movflags +faststart \
/tmp/demo.mp4Visible Cursor
Headless Chrome renders no mouse pointer. Inject a fake SVG cursor
that you position via window.__mc(x, y) during the demo:
playwright-cli eval '(() => { var c = document.createElement("div"); c.id = "fake-cursor"; c.style.cssText = "position:fixed;width:24px;height:24px;z-index:999999;pointer-events:none;display:none;"; c.innerHTML = "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\"><path d=\"M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a.5.5 0 01.35-.15h6.87a.5.5 0 00.35-.85L6.35 2.86a.5.5 0 00-.85.35z\" fill=\"#111\" stroke=\"#fff\" stroke-width=\"1.5\"/></svg>"; document.body.appendChild(c); window.__mc = function(x, y) { c.style.left = x + "px"; c.style.top = y + "px"; c.style.display = "block"; }; window.__hc = function() { c.style.display = "none"; }; return "cursor ready"; })()'window.__mc(x, y)— move cursor to position (display it)window.__hc()— hide cursor
Attaching to a Single-Leader-Tab App
Some apps only support one connected browser session per backend instance
(e.g. SLICC's standalone thin-bridge: one Chrome tab is "the leader" for a
given bridge token). playwright-cli open <url> launches an independent
browser — pointing it at a URL someone else's session already owns creates
two competing clients on the same channel, not a second view.
Recording without disturbing a live session: spin up an isolated
instance of the app's own dev stack on different ports, then attach
playwright-cli to that instance's browser instead of opening a new one:
# 1. Launch Chrome yourself with a FIXED (non-zero) CDP port
"$CHROME_BIN" --remote-debugging-port=9522 --no-first-run \
--user-data-dir="$(mktemp -d)" about:blank &
# 2. Start the app's own dev server(s) on unused ports, pointed at that
# fixed CDP port if the framework supports reusing an external browser
# (check for a "--serve-only" / "--attach" / "--external-cdp" style flag
# before assuming you must launch its browser too)
# 3. Grab the real websocket endpoint from the profile dir Chrome just
# wrote (needed because `--remote-debugging-port=0` is otherwise auto-picked)
cat "$USER_DATA_DIR/DevToolsActivePort" # port on line 1, ws path on line 2
# 4. Attach playwright-cli's tooling (video, run-code, etc.) to that SAME
# browser instead of launching a new one
playwright-cli attach --cdp "ws://127.0.0.1:9522/devtools/browser/<uuid>"
playwright-cli goto "http://localhost:<app-ui-port>/?<app-specific-auth-params>"This keeps the recording fully isolated — the original session's ports,
tabs, and state are never touched. Tear down the isolated Chrome/dev-server
processes when done (kill by the PIDs you started, or by the ports you
picked) — they're throwaway infrastructure, not the user's environment.
Clipboard Interactions
Reading a value with navigator.clipboard.readText() proves what's in the
clipboard, but inserting it with page.keyboard.type(value) is simulated
typing, not a paste — visually similar, technically a different action. If
the demo is specifically about a copy/paste feature, do a real paste:
// Once, before interacting with the composer:
await page.context().grantPermissions(['clipboard-read', 'clipboard-write'], {
origin: 'http://localhost:PORT', // must match the page's actual origin
});
// Later, in the recording script:
await composer.click();
await page.keyboard.press('Meta+V'); // 'Control+V' on non-Mac targetsWithout grantPermissions, both readText() and a real Meta+V paste can
hang waiting on a permission prompt that never resolves headlessly.
Recording Script Pattern
For complex demos with animated drags or multi-step flows, write a
run-code script file. The function receives page (Playwright Page):
// /tmp/demo-script.js
async (page) => {
const wait = (ms) => page.waitForTimeout(ms);
// Click a button by accessible name
await page.getByRole('button', { name: 'Terminal' }).click();
await wait(1500);
// Move the visible cursor
await page.evaluate(([x, y]) => window.__mc(x, y), [400, 300]);
await wait(300);
// Animate a smooth cursor move
for (let i = 0; i <= 20; i++) {
const x = 400 + (700 - 400) * (i / 20);
await page.evaluate(([px, py]) => window.__mc(px, py), [x, 300]);
await wait(25);
}
// Hide cursor at end
await page.evaluate(() => window.__hc());
};Run it:
playwright-cli run-code --filename /tmp/demo-script.jsKey Gotchas
Scripts must be self-contained
Always inject the cursor inside the run-code script, not in a
prior playwright-cli eval. If the page URL changes (e.g., switching
workbench surfaces updates ?ws= via replaceState), window.__mc
survives. But a full reload wipes it. Putting injection at the top of
every script makes it idempotent:
async (page) => {
// Always re-inject — idempotent, safe to call multiple times
await page.evaluate(() => {
const old = document.getElementById('fake-cursor');
if (old) old.remove();
const c = document.createElement('div');
c.id = 'fake-cursor';
c.style.cssText =
'position:fixed;width:24px;height:24px;z-index:999999;pointer-events:none;display:none;';
c.innerHTML =
'<svg width="24" height="24" viewBox="0 0 24 24"><path d="M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a.5.5 0 01.35-.15h6.87a.5.5 0 00.35-.85L6.35 2.86a.5.5 0 00-.85.35z" fill="#111" stroke="#fff" stroke-width="1.5"/></svg>';
document.body.appendChild(c);
window.__mc = (x, y) => {
c.style.left = x + 'px';
c.style.top = y + 'px';
c.style.display = 'block';
};
window.__hc = () => {
c.style.display = 'none';
};
});
// ... rest of script
};Reset page/component state before recording
Component state persists between recording takes. If a previous run expanded a tree node or left a file selected, the next run will start in that state — shifting all coordinates and breaking the script. Reset before recording:
// Example: ensure a file tree starts clean
await page.evaluate(() => {
const ft = document.querySelector('slicc-file-tree');
if (ft && ft.isDirOpen('/workspace/skills')) ft.toggleDir('/workspace/skills');
});Always verify state with a measurement eval before starting the recording, especially when re-taking a failed demo.
Combine page.mouse.move with window.__mc for hover events
The visible cursor and the real browser pointer are independent.
page.evaluate(() => window.__mc(x, y)) only moves the SVG — it does
NOT fire pointerover/pointermove events on page elements. Always
drive both together in the moveTo loop:
async function moveTo(tx, ty, steps = 14, delay = 18) {
const p = await page.evaluate(() => {
const c = document.getElementById('fake-cursor');
return { x: parseInt(c.style.left || '640'), y: parseInt(c.style.top || '360') };
});
for (let i = 1; i <= steps; i++) {
const nx = p.x + (tx - p.x) * (i / steps);
const ny = p.y + (ty - p.y) * (i / steps);
await page.evaluate((v) => window.__mc(v[0], v[1]), [nx, ny]);
await page.mouse.move(nx, ny); // ← fires real pointerover/hover
await wait(delay);
}
}Without page.mouse.move, hover-triggered UI (dropdown buttons,
tooltips, action overlays) will not appear on screen.
Don't also call .locator().hover() or .locator().click() alongside a
manual moveTo loop. Playwright's own actionability pre-checks (visible,
stable, "receives events") run independently of your animation and can fail
intermittently — "element is not visible" / "X intercepts pointer events" —
even though the element is plainly on screen. Once you're driving the cursor
yourself, commit to it: use page.mouse.click(x, y) at the coordinates you
already animated to, not the locator-based click/hover helpers.
Prefer CSS selectors over snapshot refs for apps with periodic re-renders
playwright-cli snapshot-derived ref=... IDs go stale the moment the
underlying DOM node is replaced. If the app rebuilds parts of its UI on a
timer (polling, live-refresh panels), a ref captured even a few seconds
earlier can point at a detached node, failing with "Ref not found in the
current page snapshot." A CSS/attribute selector (page.locator('[data-id="..."]'))
re-resolves against the live DOM on every call and doesn't have this problem
— use selectors for anything you'll interact with more than once per script.
Native dialogs (confirm/prompt) in attached CDP sessions
page.once('dialog', async (d) => await d.accept(...)) registered inside a
run-code script is NOT reliably intercepted when attached via
playwright-cli attach --cdp — the CLI's own dialog tracking can surface it
as a pending "Modal state" instead, and the triggering run-code call
returns without finishing. Don't chase this inside the script. Instead:
# 1. Trigger the action that opens the dialog
playwright-cli run-code --filename open-dialog-step.js
# 2. Resolve it as a separate command
playwright-cli dialog-accept "typed value" # or: playwright-cli dialog-dismiss
# 3. Verify the app's actual state changed — don't trust the CLI's own
# "already handled" / "Modal state" messages as proof of success
playwright-cli eval '...check the DOM reflects the action...'If you see "Cannot accept dialog which is already handled" that's fine — it
means an in-script handler beat you to it. If a later command reports a
NEW pending "Modal state" you didn't expect, dialogs can queue; drain them
with repeated dialog-dismiss/dialog-accept calls before continuing.
video-start's live screencast can silently render panels as solid grey
The CDP screencast behind video-start is a different rendering path than
page.screenshot(), and can fail to composite certain panels — rendering
them as a flat color for the entire recording while the rest of the page
looks fine. This is easy to miss at a glance and will ruin a recording whose
whole point is that panel. Verify before trusting a video-start take:
extract one frame and compare it to a page.screenshot() taken at the same
moment; if the panel is blank/flat in the video frame but populated in the
screenshot, video-start isn't usable for this recording.
Fallback: screenshot-sequence recording. page.screenshot() always
renders correctly, so build the video from a sequence of screenshots
instead of a live capture:
// Inside the run-code script: snap(N) takes ONE screenshot but reserves N
// index slots, so the gap to the next frame encodes how long to hold it.
let fc = 0;
async function snap(page, holdFrames = 1) {
const n = ++fc;
await page.screenshot({ path: `/tmp/frames/frame_${String(n).padStart(5, '0')}.png` });
fc += holdFrames - 1;
}
// snap(page, 1) during cursor movement, snap(page, 10-30) to hold a result# Build an ffmpeg concat playlist from the actual files present (gaps = hold
# duration in units of BASE seconds), then encode — handles the numbering
# gaps `snap()` leaves behind:
import os, re
d = '/tmp/frames'
entries = sorted((int(re.match(r'frame_(\d+)\.png', f).group(1)), f) for f in os.listdir(d))
BASE = 0.09
lines = []
for i, (n, f) in enumerate(entries):
gap = (entries[i + 1][0] - n) if i + 1 < len(entries) else 20
lines += [f"file '{d}/{f}'", f'duration {max(gap, 1) * BASE:.3f}']
lines.append(f"file '{d}/{entries[-1][1]}'") # concat demuxer quirk: repeat last file, no duration
open('/tmp/concat.txt', 'w').write('\n'.join(lines) + '\n')ffmpeg -y -f concat -safe 0 -i /tmp/concat.txt \
-vsync vfr -pix_fmt yuv420p -vf "fps=30,scale=1280:800" \
-c:v libx264 -preset fast -crf 19 -movflags +faststart \
/tmp/demo.mp4--size for video-start
playwright-cli video-start defaults to fitting the video within 800×800.
If your actual viewport is larger (e.g. 1280×800), the output is scaled down
and padded with a dead margin. Always pass --size matching the real
viewport: playwright-cli video-start out.webm --size "1280x800".
CDP mouse events vs Pointer Events
page.mouse.down() dispatches CDP-level mouse events. These do NOT
reliably engage setPointerCapture() — if the target uses Pointer
Events with capture (like a drag handle), the drag won't work.
Workaround: use page.evaluate() to dispatch PointerEvent
directly on the element for the functional behavior, and use
page.evaluate() with window.__mc() for the visual cursor:
// Dispatch a real PointerEvent for the handler
await page.evaluate(
([cx, cy]) => {
const el = document.querySelector('.my-drag-handle');
el.dispatchEvent(
new PointerEvent('pointerdown', {
clientX: cx,
clientY: cy,
pointerId: 1,
button: 0,
bubbles: true,
})
);
},
[x, y]
);
// Move the visible cursor in sync
await page.evaluate((v) => window.__mc(v[0], v[1]), [x, y]);Timing estimates drift — verify with frame screenshots
Script timing is cumulative and unpredictable: page.evaluate
overhead, animation frames, and async VFS calls all add invisible
latency. Never trust timing math alone. The correct workflow:
- Record the raw webm
- Convert to mp4
- Extract frames at estimated timestamps:
for ts in 1.5 3.0 5.5 9.0; do frame=$(echo "$ts * 25" | bc | cut -d. -f1) ffmpeg -y -i demo.mp4 -vf "select=eq(n\,${frame})" -vframes 1 /tmp/check_${ts}.png -loglevel quiet done - Read each frame image — adjust timestamps based on what's actually visible
- Only then add overlays/toasts
Timing
page.waitForTimeout(ms)— use this inrun-codescripts (setTimeoutis not available in Playwright's Node context)- Keep pauses short (200–400ms between actions) for a snappy demo
- Add 1–1.5s holds after each major state change so viewers can see it
- Total target: 15–30s — shorter is better for PR embeds
Video format
playwright-cli video-startproduces.webm(VP8)- GitHub PR embeds require
.mp4(H.264) — always convert with ffmpeg - Use
-movflags +faststartfor instant playback in browsers - Crop banners/chrome:
-vf "crop=iw:ih-18:0:18"
Chapter Markers
Add chapter markers for longer recordings (visible in the Playwright dashboard, useful for debugging timing):
playwright-cli video-chapter "Panel opened"
# ... interactions ...
playwright-cli video-chapter "Resize complete"Action Annotations
video-show-actions overlays a callout on each subsequent CLI action
with the action name and a pointer animation between targets:
playwright-cli video-show-actions --cursor pointer --duration 500This is useful for simple click/type flows but does NOT show custom
page.evaluate() interactions. For complex demos (drags, animated
sequences), use the manual cursor approach above.
Post-Processing with ffmpeg
# Convert webm → mp4
ffmpeg -y -i demo.webm -c:v libx264 -preset fast -crf 20 \
-pix_fmt yuv420p -movflags +faststart demo.mp4
# Trim to 15s starting at 5s mark
ffmpeg -y -ss 5 -t 15 -i demo.webm ... demo.mp4
# Crop top 18px (remove a banner)
ffmpeg -y -i demo.webm -vf "crop=iw:ih-18:0:18" ... demo.mp4
# All together
ffmpeg -y -ss 5 -t 15 -i demo.webm \
-vf "crop=iw:ih-18:0:18" \
-c:v libx264 -preset fast -crf 20 \
-pix_fmt yuv420p -movflags +faststart \
demo.mp4Text Overlays / Chapter Toasts
ffmpeg's drawtext filter requires freetype, which may not be
compiled in. Check first: ffmpeg -filters 2>/dev/null | grep drawtext.
If missing, use Python + OpenCV + Pillow instead.
Freeze-frame toast pattern (Python)
Insert a static freeze at key moments with a text overlay — much more reliable than trying to match exact timestamps to fast-moving content. The workflow:
- Extract verification frames at estimated timestamps (see timing section above)
- Identify the right freeze frame for each section by reading the PNGs
- Run the script to insert freezes and overlay text
# /tmp/add_toasts.py
import cv2, subprocess
import numpy as np
from PIL import Image, ImageDraw, ImageFont
INPUT = "/tmp/demo.mp4"
OUTPUT = "/tmp/demo-toasts.mp4"
# (original_video_time_s, freeze_duration_s, text) — ASCII only, no Unicode arrows/dots
FREEZE = [
(1.2, 1.5, "Files panel - folder icons, file sizes, navigation"),
(3.0, 1.5, "Hover a file - action buttons appear"),
(6.0, 2.0, "Click CAT - file opens in terminal"),
]
FONT_SIZE = 15; PAD_X = 16; PAD_Y = 9; MARGIN_BOT = 38; FADE = 0.20
cap = cv2.VideoCapture(INPUT)
FPS = cap.get(cv2.CAP_PROP_FPS)
W = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
H = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
try:
font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", FONT_SIZE)
except Exception:
font = ImageFont.load_default()
frames = []
while True:
ok, f = cap.read()
if not ok: break
frames.append(f)
cap.release()
def draw_toast(frame_bgr, text, alpha):
img = Image.fromarray(cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)).convert("RGBA")
ov = Image.new("RGBA", img.size, (0, 0, 0, 0))
d = ImageDraw.Draw(ov)
bb = d.textbbox((0, 0), text, font=font)
tw, th = bb[2]-bb[0], bb[3]-bb[1]
bx = (W - tw)//2 - PAD_X; by = H - MARGIN_BOT - th - PAD_Y*2
d.rounded_rectangle([bx, by, bx+tw+PAD_X*2, by+th+PAD_Y*2], radius=6,
fill=(20, 20, 20, int(180*alpha)))
d.text((bx+PAD_X, by+PAD_Y), text, font=font, fill=(255, 255, 255, int(240*alpha)))
return cv2.cvtColor(np.array(Image.alpha_composite(img, ov).convert("RGB")), cv2.COLOR_RGB2BGR)
output_frames = []
freeze_specs = [(int(t * FPS), int(dur * FPS), txt) for t, dur, txt in FREEZE]
prev_src = 0
for (orig_idx, n_freeze, txt) in freeze_specs:
for i in range(prev_src, min(orig_idx, len(frames))):
output_frames.append((frames[i], None, None))
ff = frames[min(orig_idx, len(frames)-1)]
fade_f = int(FADE * FPS)
for j in range(n_freeze):
a = j/fade_f if j < fade_f else (n_freeze-j)/fade_f if j > n_freeze-fade_f else 1.0
output_frames.append((ff, txt, max(0.0, min(1.0, a))))
prev_src = orig_idx
for i in range(prev_src, len(frames)):
output_frames.append((frames[i], None, None))
cmd = ["ffmpeg", "-y", "-f", "rawvideo", "-vcodec", "rawvideo",
"-s", f"{W}x{H}", "-pix_fmt", "rgb24", "-r", str(FPS), "-i", "pipe:0",
"-c:v", "libx264", "-preset", "fast", "-crf", "20",
"-pix_fmt", "yuv420p", "-movflags", "+faststart", OUTPUT]
proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.DEVNULL)
for frame_bgr, txt, alpha in output_frames:
out = draw_toast(frame_bgr, txt, alpha) if txt and alpha and alpha > 0.01 else frame_bgr
proc.stdin.write(cv2.cvtColor(out, cv2.COLOR_BGR2RGB).tobytes())
proc.stdin.close(); proc.wait()Important: Use ASCII-only text — Unicode arrows (→), dots (·),
and em-dashes (—) render as empty squares with Helvetica.ttc in PIL.
Use - and -> instead.
Embedding in GitHub PRs
Upload the recording with gh's repeatable --attach flag. It needs
gh >= 2.99 — check with gh --version before recording, because a failed
upload after a long capture wastes the whole run. The file is uploaded to
https://github.com/user-attachments/assets/<uuid> and the embed markdown
lands in the body — appended to the end, or in place if the body references
the local path (see § Controlling where the media lands) — so agents get a
programmatic upload path (no browser drag-and-drop). Supported: mp4 mov webm
(plus image types), up to 50 files per command.
--attach works on gh pr comment, gh pr create, gh pr edit,
gh issue comment and gh issue create:
# Attach the recording to a PR comment; repeat --attach for several files.
gh pr comment <pr> --body "UI change: before / after" \
--attach ./before.png --attach /tmp/shot/screencast.webm
# Alt text follows the path after '#' (images only — video renders as a
# player and takes no alt text).
gh pr comment <pr> --body "…" --attach './before.png#Terminal panel at 75%'Controlling where the media lands
An attachment the body does not mention is appended to the end. To place it,
reference the local path in the body and gh rewrites that reference to
the uploaded URL — this is the easy way to get a laid-out comment:
gh pr comment <pr> --body-file - --attach ./before.png --attach ./after.png <<'EOF'
| Before | After |
| --- | --- |
|  |  |
EOFIf you need the URLs somewhere the rewrite cannot reach (a second comment, the
PR body, a checklist you build later), post once with a placeholder body and
every --attach, read the assigned URLs back out of the stored body, then
PATCH the comment with the real markdown:
# 1. Post with a placeholder; gh prints the comment URL (…#issuecomment-<id>).
gh pr comment <pr> --body "uploading…" --attach ./before.png --attach ./after.png
# 2. Read the body back — it now carries the user-attachments URLs.
gh api repos/<owner>/<repo>/issues/comments/<id> --jq .body
# 3. PATCH the comment with laid-out markdown substituting those URLs.
# Write the body to a file first — backticks in a shell-passed body get
# interpolated.
gh api repos/<owner>/<repo>/issues/comments/<id> -X PATCH -F body=@/tmp/comment.mdUse --repo owner/repo outside a repo dir.
When there is no upload path
--attach is a write operation, so under the sibling
ai-ecoverse/ai-aligned-gh
wrapper it goes through the gated write path and can prompt the as-a-bot
device flow. An agent that cannot complete an interactive authorization has
no upload path for the recording. Say so in the PR comment — name the
local file path and the command that regenerates it — rather than blocking on
the prompt or silently dropping the recording:
Recorded
/tmp/shot/screencast.webm(14 s, 30 fps) but could not attach it:ghneeds an interactive as-a-bot authorization I cannot complete. Re-attach withgh pr comment <pr> --body "…" --attach /tmp/shot/screencast.webm.
Full Example: Resize Demo
// /tmp/resize-demo.js — records the side panel resize feature
async (page) => {
const wait = (ms) => page.waitForTimeout(ms);
// Get layout dimensions
const dims = await page.evaluate(() => {
const s = document.querySelector('slicc-shell');
const b = s.getBoundingClientRect();
return { left: b.left, width: b.width, top: b.top, height: b.height };
});
const avail = dims.width - 48;
const midY = dims.top + dims.height / 2;
// Helper: animate cursor + dispatch resize events
async function drag(fromFrac, toFrac) {
const sx = dims.left + avail * fromFrac;
const tx = dims.left + avail * toFrac;
// Approach cursor
for (let i = 0; i <= 6; i++) {
const x = sx - 30 + 30 * (i / 6);
await page.evaluate(([px, py]) => window.__mc(px - 4, py - 2), [x, midY]);
await wait(20);
}
await wait(150);
// Start drag
await page.evaluate(
([cx, cy]) => {
const d = document.querySelector('.slicc-shell__divider');
d.dispatchEvent(
new PointerEvent('pointerdown', {
clientX: cx,
clientY: cy,
pointerId: 1,
button: 0,
bubbles: true,
})
);
},
[sx, midY]
);
// Animate drag
for (let i = 0; i <= 30; i++) {
const x = sx + (tx - sx) * (i / 30);
await page.evaluate(([px, py]) => window.__mc(px - 4, py - 2), [x, midY]);
await page.evaluate(
([cx, cy]) => {
const d = document.querySelector('.slicc-shell__divider');
d.dispatchEvent(
new PointerEvent('pointermove', {
clientX: cx,
clientY: cy,
pointerId: 1,
bubbles: true,
})
);
},
[x, midY]
);
await wait(25);
}
// End drag
await page.evaluate(
([cx, cy]) => {
const d = document.querySelector('.slicc-shell__divider');
d.dispatchEvent(
new PointerEvent('pointerup', {
clientX: cx,
clientY: cy,
pointerId: 1,
bubbles: true,
})
);
},
[tx, midY]
);
}
// Open terminal panel
await page.getByRole('button', { name: 'Terminal' }).click();
await wait(1500);
// Drag wider → narrower → reset
await drag(0.75, 0.55);
await wait(1000);
await drag(0.55, 0.22);
await wait(1000);
await drag(0.22, 0.48);
await wait(500);
// Double-click to reset
await page.evaluate(() => {
document
.querySelector('.slicc-shell__divider')
.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
});
await wait(1000);
await page.evaluate(() => window.__hc());
};Orchestration:
playwright-cli open http://localhost:PORT
playwright-cli resize 1280 720
playwright-cli eval '<CURSOR_SNIPPET>'
playwright-cli video-start /tmp/resize-demo.webm --size "1280x720"
playwright-cli run-code --filename /tmp/resize-demo.js
playwright-cli video-stop
ffmpeg -y -i /tmp/resize-demo.webm \
-c:v libx264 -preset fast -crf 20 \
-pix_fmt yuv420p -movflags +faststart \
/tmp/resize-demo.mp4Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

