playwright-gif-capture
Skill8 starsChanged 5 months agoMITView on GitHub
Specialization of playwright-harness for capturing an ANIMATED GIF of web content: drive a page/canvas/WebGL animation, grab a sequence of frames, and encode a looping GIF. Use when the task is "make a gif of this", "grab a gif of the demo/animation/shader", "record the canvas as a gif", or "capture a looping clip for a PR/README/issue"; any time a still screenshot is not enough. Read playwright-harness FIRST for script conventions and execution. For the quality/size dials (preventing deep-fried color, janky frame rate, or oversized files) read references/gif-optimization.md rather than guessing. Validated on Linux/WSL, headless Chromium + ANGLE, against WebGL canvas content.
- Reads credentials
- Installs packages
In this repository23 other files it gives its agents.
- skills/asset-optimization/AGENTS.mdAGENTS.md
- android-emulator-harnessSkill
- android-emulator-mask-testingSkill
- appraise-github-issuesSkill
- asset-optimizationSkill
- burn-down-github-issuesSkill
- carve-github-issueSkill
- code-github-issueSkill
- emoji-readoutSkill
- expo-developer-toolsSkill
- expo-ios-simulatorSkill
- fix-github-issueSkill
- how-to-planSkill
- ios-simulator-flow-evidenceSkill
- ios-simulatorSkill
- ios-simulator-triageSkill
- mobile-accessibilitySkill
- playwright-camera-mask-testingSkill
- playwright-harnessSkill
- playwright-storybook-flowsSkill
- prove-github-issueSkill
- prove-work-on-githubSkill
- zone-composerSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 117
Always print the output byte size and Read the GIF back (vision) before shipping.
- Distinctive: line 138
Never open a PR from the assets branch.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
GIF Capture: specialization of playwright-harness
Read playwright-harness first. The base owns prerequisites, the run pattern
(write to /tmp/pw-*.mjs, run with playwright resolvable), and the drive/assert
- WebGL-GPU patterns. This skill changes only how you turn a running animation
into frames. Encoding and the quality/size tradeoffs live in
references/gif-optimization.md; open it before tuning, since a deep-fried, janky, or oversized GIF is easy to make by accident.
Headless is required here (not just the default): the encode is offline and you want clean, chrome-free frames.
Prerequisites (in addition to the base)
ffmpegto encode frames/video into a GIF;npm i ffmpeg-staticin a /tmp dir gives a binary path, no system install.- For tuning,
gifski(best on gradients) andgifsicle(size reduction); seereferences/gif-optimization.md. ImageMagick is an optional alternative.
Capture the frames. Two ways.
A. Frame-by-frame screenshots (default)
The default for canvas, WebGL, or any clock-driven animation. Drive the clock yourself, one frame at a time, and screenshot each step: deterministic (same frames every run), evenly spaced (no wall-clock jitter, so no jank), croppable to an element, and it sidesteps the recordVideo GPU-death trap below.
// /tmp/pw-gif.mjs (run via the harness: node, with playwright resolvable)
import { chromium } from 'playwright';
import { mkdirSync } from 'node:fs';
const TARGET_URL = process.env.TARGET_URL || 'http://localhost:8080/';
const FRAMES = 48, FPS = 16, OUT = '/tmp/gif-frames';
mkdirSync(OUT, { recursive: true });
const browser = await chromium.launch({
headless: true,
args: ['--use-gl=angle', '--use-angle=gl', '--ignore-gpu-blocklist'], // real GPU under WSLg; see GPU note
});
const page = await browser.newPage({ viewport: { width: 960, height: 540 } });
await page.goto(TARGET_URL, { waitUntil: 'load' });
const target = page.locator('#canvas'); // element to crop to (omit -> full page)
for (let i = 0; i < FRAMES; i++) {
const t = i / FPS; // animation time for this frame (seconds)
// Step the animation deterministically. Best: the page exposes a render hook.
await page.evaluate((t) => window.__renderAtTime?.(t), t);
await page.waitForTimeout(30); // let the draw land (and the GPU flush)
await target.screenshot({ path: `${OUT}/f${String(i).padStart(4, '0')}.png` });
}
await browser.close();
console.log(`wrote ${FRAMES} frames to ${OUT}`);The clean version needs a render-at-time hook on the page
(window.__renderAtTime(t) sets the clock and draws one frame). If the app only
has a free-running requestAnimationFrame loop, either (a) add a tiny hook for
the capture, or (b) fall back to wall-clock sampling: waitForTimeout(1000/FPS)
between shots, accepting minor unevenness. Capture exactly one period of a
periodic animation so it loops seamlessly.
B. Playwright recordVideo (DOM/CSS animations you cannot time-step)
const context = await browser.newContext({
recordVideo: { dir: '/tmp/gif-vid', size: { width: 960, height: 540 } },
});
const page = await context.newPage();
await page.goto(TARGET_URL);
await page.waitForTimeout(3000); // record real-time playback
await context.close(); // <- video finalizes on CONTEXT close, not page close
// -> /tmp/gif-vid/<hash>.webm, then encode (below)Real-time, whole viewport, no hook needed. Two costs: it records wall-clock (so it inherits any jank), and under heavy GPU load it can kill the GPU process mid-record and the rest goes black (cranked WebGL + recordVideo is the known offender). For canvas/shader content prefer method A, or record at a light load.
Encode to a GIF
A sane default to get a watchable loop (ffmpeg-static via npm i in /tmp; npm,
not bun, since the postinstall downloads the binary):
cd /tmp && npm i ffmpeg-static >/dev/null 2>&1
FF=$(node -e "process.stdout.write(require('/tmp/node_modules/ffmpeg-static'))")
# from frame PNGs (method A):
"$FF" -y -framerate 16 -i /tmp/gif-frames/f%04d.png \
-vf "scale=720:-1:flags=lanczos,split[a][b];[a]palettegen=max_colors=256:stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5" \
-loop 0 /tmp/out.gif
# from a recorded webm (method B): swap "-framerate 16 -i .../f%04d.png" for "-i /tmp/gif-vid/*.webm" and add fps=16 to the -vf chainThen stop guessing and open references/gif-optimization.md for the
color/fps/size tradeoff model, the tool matrix (ffmpeg vs gifski vs gifsicle vs
ImageMagick), and the target-size loop. The short version: banding/deep-fried,
raise the dither or switch to gifski; too large, trade dims, then duration, fps,
colors, then a gifsicle lossy pass; janky, capture by method A at a fixed clock
and encode at the capture fps (12 to 20 is the sweet spot).
Always print the output byte size and Read the GIF back (vision) before shipping.
GPU note (delta)
The base's WebGL/GPU caveat applies verbatim; the launch args above already use it. For shader content the ANGLE relaunch is mandatory (heavy shaders no-op under SwiftShader headless), and you must let the animation settle a second or two (PSO compile) before the first captured frame. See playwright-harness, "WebGL / GPU caveat".
Embedding the GIF in a GitHub PR / issue / README
GitHub's inline drag-and-drop upload (user-attachments) has no API, so an
agent cannot post one that way. The working pattern: commit the GIF to a
never-merge assets branch (e.g. evidence/issue-verification) and embed it by
raw.githubusercontent URL
(),
which renders and animates inline. Push that branch from a detached worktree with
--no-verify (an assets worktree has no node_modules, so a pre-commit hook
manager such as lefthook or husky would fail).
Never open a PR from the assets branch. For a committed README asset, a normal
commit on the feature branch is fine; mind the repo's size budget.
Scope
- CAN: produce a reproducible, tight animated GIF of any web/canvas/WebGL
animation; crop to an element; control frame count, fps, size, and palette;
capture the real deployed site (point
TARGET_URLat it). - CANNOT: prove real-time FPS/perf (frame-by-frame is a controlled reconstruction at a chosen fps, not a measurement; use a GPU-time meter for cost); capture audio; or render a single frame so heavy it trips the OS GPU watchdog (split the work or lower the load first).
Does 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.

