From the app link to narrated walkthrough.

🖱️ Cursor that hits the button

During capture, the skill takes the real bounding box of each target with getBoundingClientRect. The animated cursor lands in the center of the control—with a pulse and ripple on click. That’s what makes it look like a professional recording, not a screenshot with an arrow over it.

🔒 100% local, no API key

Capture via agent-browser (Playwright), HTML→MP4 rendering via HyperFrames, PT-BR narration via TTS Kokoro (voice pf_dora) running on the machine itself. No paid calls, no external services.

⏱️ Single source of timing

The generator reads the steps.json and measures the duration of each WAV with ffprobe. There is no hand-built timing table: audio and animation are created in sync, and the ambience loops prevent a silent tail at the end.

Script and text

5–8 steps + CTA (≈35–50s). Each sentence has two ways: screen (accented PT-BR, app buttons in the original spelling — Generate, Upload) e speech (expanded numbers and English rewritten phonetically — upload → “upload”). Review comes before capture and narration.

Capture and coordinates

O capture.mjs read a actions.json, directs the agent-browser through the app, take 1 screenshot per state and record each target's bounding box. Output: assets/shots/*.png + steps.json. You can do it manually when the app is unpredictable (login, dynamic states).

Composition and rendering

O build-demo.mjs read the steps.json, measures the WAVs, and assembles a browser frame + global cursor + highlight + zoom on the result + CTA. Then: lint, inspect, a draft to check the frames and final render at high / 30fps.

Node 22+ and FFmpeg

HyperFrames foundation (HTML→MP4 rendering) and ffprobe, which measures the narration durations.

node --version   # needs to be 22+
ffmpeg -version

HyperFrames Chrome

Headless browser used for rendering. Downloads once and stays cached.

npx hyperframes browser ensure

Kokoro TTS (PT-BR)

Local narration, voice pf_dora. The first run downloads ~340MB of model data.

pip install kokoro-onnx soundfile

agent-browser in PATH

Navigation skill (Playwright) that performs the actions and takes real screenshots.

agent-browser set viewport 1280 800

The target app running

The URL needs to be available during capture — localhost or public. An app with login requires test credentials.

# e.g.: your app serving at
http://localhost:8000/

The installed skill

Copy skills/video-demonstrativo/ from this repo to your Claude Code skills.

cp -r skills/video-demonstrativo \
  ~/.claude/skills/

Input · actions.json

You describe the action and the cursor target. The script handles the rest.

{
  "url": "http://localhost:8000/",
  "viewport": [1280, 800],
  "window": { "urlLabel": "localhost:8000" },
  "steps": [{
    "id": "size",
    "do": { "type": "clickText", "tag": "button", "text": "512²" },
    "target": { "tag": "button", "text": "512²" },
    "click": true,
    "caption": "2 · Escolha o tamanho — 512²",
    "narration": "Depois, escolha o tamanho. Vamos de quinhentos e doze."
  }]
}

Output · steps.json

The target is now a real coordinate in the screenshot's space. That's what the cursor follows.

{
  "viewport": [1280, 800],
  "steps": [
    { "shot": "00-home.png", "intro": true, "target": null },
    { "shot": "02-size.png", "click": true,
      "target": { "x": 179, "y": 501, "w": 44, "h": 26 } },
    { "shot": "04-result.png", "zoom": true,
      "target": { "x": 668, "y": 128, "w": 484, "h": 324 } }
  ]
}

Static screen

The app's dynamic state (animations, video, live data) becomes static screenshot. Real motion would require recording the screen video—a different approach, with harder narration sync.

Login

An app with authentication needs test credentials. Without them, capture only the public screens.

16:9 only

Natural format, since app screens are landscape. 9:16 would require cropping and reframing each shot.

Unacted voice

Kokoro is good, but it doesn't act. And you can't hear the result — the user always validates the narration.