flow-video-recorder

An agent skill that records a narrated demo video of your app. Tell Claude Code (or Codex, Cursor, any agent that reads SKILL.md) which flow to show, and it writes a script, drives the app, and hands back an MP4 with a moving cursor, a ripple on every click, a caption per step, and a voice that explains what is happening while it happens.

It works on two surfaces:

Narration can come from ElevenLabs, OpenAI, the macOS say command, or any local model you can call from a shell line (Piper, Kokoro, a TTS server). With no engine configured the same flow records silently with captions.

See it working

Every video on edumind.school/course was made with this skill: 20 walkthroughs of a school management platform, about 41 minutes in total, in English and Arabic, covering both the web app and the native parent and teacher apps. A few direct links:

• Meet EduMind (web, with motion-graphics scenes)
• The parent app (native iOS)
• Exams: from question bank to paper (web)

Install

Claude Code, as a plugin (updates itself). Two commands, run one after the other:

1. Add the marketplace:

   /plugin marketplace add muayadjamal/flow-video-recorder
   

2. Install the plugin:

   /plugin install flow-video-recorder@flow-video-recorder
   

Claude Code, Codex, Cursor and other agents, through skills.sh (copies the files so you can edit them):

npx skills add muayadjamal/flow-video-recorder                       # into this project
npx skills add muayadjamal/flow-video-recorder -g                    # for every project
npx skills add muayadjamal/flow-video-recorder -g -a claude-code     # one agent only

Codex, from inside a session:

$skill-installer install https://github.com/muayadjamal/flow-video-recorder

By hand:

git clone https://github.com/muayadjamal/flow-video-recorder ~/.claude/skills/flow-video-recorder

Requirements

• node 20 or newer and ffmpeg on the PATH.
• Browser flows: playwright in the target project (npm i -D playwright && npx playwright install chromium).
• iOS flows: macOS with Xcode, a booted simulator with your app installed, and Maestro at ~/.maestro/bin/maestro.
• Narration, optional: ELEVENLABS_API_KEY or OPENAI_API_KEY in the environment or the project's .env, or TTS_COMMAND for your own engine. On macOS say works with nothing set.

Usage

Ask for a video in plain language:

Record a demo video of the checkout flow, with narration.

The skill first asks what goes in the video (voice-over, subtitles, pointer, motion graphics), checks the tools above, copies its helper scripts into the project, writes a flow file for your app, and runs one of:

ELEVENLABS_API_KEY=… BASE=http://localhost:8000 bash <skill>/assets/record.sh flow.mjs demo.mp4
ELEVENLABS_API_KEY=… UDID=<simulator> bash <skill>/assets/record-ios.sh flow.mjs demo.mp4

A flow file is a short JavaScript module. Each step says its line, does its clicking, and holds until the line is finished:

export const narration = [
  { id: 'open', caption: 'Open the order', text: 'Start from the orders list and open the one that just arrived.' },
];

export default async ({ page, say, hold, click, goto }) => {
  await goto('http://localhost:8000/orders');
  say('open');
  await click(page.getByRole('link', { name: 'ORD-1042' }));
  await hold();
};

Narration engine, picked automatically from the environment or forced with TTS_PROVIDER:

Any local model (Piper, Kokoro, a TTS server you run) plugs in through command:

TTS_COMMAND='piper --model en_US-lessac-medium.onnx --output_file "$TTS_OUT" <<< "$TTS_TEXT"' \
  bash <skill>/assets/record.sh flow.mjs demo.mp4

After every run the recorder prints a table of spoken length against on-screen length per step, and flags silence and lines that kept talking after the screen changed.

How it works

The picture is paced to the audio rather than the other way round. Every narration clip is synthesized and measured before the app opens, so a step lasts exactly as long as its sentence, and the voice never gets cut off by the next screen. Fitting audio to an already recorded video fails because step durations vary from run to run.

On iOS there is no DOM to inject into and Maestro runs a static YAML, so the flow is executed twice: once to plan, once for real, with Maestro calling back into the recorder over HTTP before every tap. The cursor, ripples and captions are painted on afterwards from the tap log. A frame-difference check then confirms each line stayed on the screen it describes.

Motion graphics are optional HTML scenes animated with GSAP, rendered frame by frame and cut in between recorded steps with a transition on each side. The assembler measures loudness around every join and refuses to ship a video where speech falls under a cut.

The full method, every environment knob, and the gotchas are in SKILL.md.

Files

Support

• A recording failed or came out wrong: open a bug report with the command you ran and the recorder's output.
• Something it should do and does not: request a feature.
• A question, or a video you made with it: Discussions.
• A security problem: see SECURITY.md.

Pull requests are welcome. CONTRIBUTING.md has the layout, the checks to run, and the versioning rule.

License

MIT. See LICENSE.