App demo videos
A demo is a tutorial: one task, start to finish, in the real app.
- No captions and no on-screen text. The only words on screen are the app's own UI. A marker on the control being used directs attention: a pulsing ring, then a tap ripple on a phone or a cursor click on desktop. A camera zoom onto it does the same.
- The voice drives the timing. Claude writes the script. The user makes the speech with any TTS tool (or records it) and hands over the files. Each step lasts as long as its clip plus a silent gap. The screen changes in the gaps, never under speech. There's no music unless the user asks.
- Every video is 1920×1080. Phone demos show the app in a phone frame on a branded background. Desktop demos show it in a browser window.
- Optional second UI language. If the app has two UI languages, the
voice names each button in both. The screen crossfades from one language
to the other as the voice reaches the second name, so every viewer sees
the label they know.
references/script-format.mdcovers this. - Real screens only. Use captures of the real app, running locally, with sample data. Every spoken sentence must be true in the code today.
<skill> below means this skill's base directory. <demos> means the
project's demos folder, demo-videos/ by default. Run every command from the
project root.
The flow (always in this order, one gate per stage)
0. Set up (first time in a project)
Run node <skill>/scripts/doctor.mjs. It needs Node 22+, Chrome, Chromium,
Edge or Brave, and ffmpeg. Then run
node <skill>/scripts/init.mjs <demos> --product "<Name>", which copies the
tools into <demos>/_tools/, so the project can rebuild videos without this
skill. Fill in <demos>/demo.config.json from the code first. Then confirm
with the user the few things code can't tell you: the voice language and
tone, the TTS tool, and the public app URL to show. See
references/setup.md.
1. Find the features
Read the codebase and write <demos>/features.md: every user-facing feature,
who uses it, where it lives (route or screen) and the code that proves it.
Follow references/discovery.md. Show the user a short summary grouped by
area and audience, and ask what's missing or wrong.
2. Suggest demos, and let the user validate them
Turn the features into <demos>/catalog.md: videos grouped by audience,
each one task (or a few related tasks as consecutive parts), with form, a
priority and status proposed. Show it as a short list with your
recommended first video. Update it with the user's answers. Don't write
any script until the user picks a demo.
3. Write the script for the chosen demo
- Create the folder with
node <demos>/_tools/new-demo.mjs <slug> --form phone|desktop --title "…". A demo for both phone and desktop is two demos, each with its own script. - Verify the flow in the code first. Read the pages, components and copy (i18n files) the task touches, and walk it in the running app if you can. Note anything that differs between phone and desktop, or between roles.
- Write
<demos>/<slug>/script.mdin the format inreferences/script-format.md. Each numbered row is one voice clip. Then runnode <demos>/_tools/lines.mjs <demos>/<slug>. - Write
<demos>/<slug>/tts.md, paste-ready lines for the user's TTS tool. - Show the script in chat and wait for approval or edits. Once it's
approved, the numbering is frozen, because the voice files are named by
it. A step added later becomes
03a; tell the user which file is new.
4. Wait for the voice
The user generates the voice and gives you a folder path. While waiting you
may capture screens and pre-build the piece; lines.json carries estimated
lengths until then. When the folder arrives, run:
node <demos>/_tools/voice.mjs <demos>/<slug> "<folder>".
It accepts one file per row (1.mp3, 01.wav, 3a.m4a), or one file for
the whole script (full.mp3), which it splits. It reports missing or extra
files and any clip whose pace suggests the wrong line or a cut-off take.
Listen to, or ask about, every flagged clip before building on it.
5. Capture the real screens
Write <demos>/<slug>/capture.mjs against a fresh, seeded local copy of
the app, then run it. It takes every frame the voice needs, in every UI
language, and records each control's position. See references/capture.md.
6. Direct and build
Write <demos>/<slug>/direction.js: which frame each row shows, which
control is ringed at which word, where taps land and which frame follows.
Never edit index.html per demo; it's the shared engine. See
references/direction.md. Then run node <demos>/_tools/rows.mjs <demos>/<slug>
until it reports no problems.
7. Review, export, hand off
Render review stills, look at every one, fix and repeat. Then export the
MP4 and the thumbnail and hand off, as in references/review-export.md.
Update the demo's status in catalog.md.
Commands
node <skill>/scripts/doctor.mjs check the machine
node <skill>/scripts/init.mjs <demos> --product "Name" set up / update tools
node <demos>/_tools/new-demo.mjs <slug> --form phone|desktop --title "…"
node <demos>/_tools/lines.mjs <demos>/<slug> script.md → lines.json
node <demos>/<slug>/capture.mjs [--lang xx] [--only a,b] real screens + targets
node <demos>/_tools/voice.mjs <demos>/<slug> "<voice folder>" import the voice
node <demos>/_tools/rows.mjs <demos>/<slug> timings + problems
node <demos>/_tools/export.mjs <demos>/<slug> --review 2 stills per row
node <demos>/_tools/export.mjs <demos>/<slug> the MP4
node <demos>/_tools/thumbnail.mjs <demos>/<slug> thumbnail.png + -1280
node <demos>/_tools/serve.mjs <demos> preview with Play/scrub
node <demos>/_tools/new-demo.mjs <slug> --engine refresh a demo's engine
Exports take about 1.5–2× the video's length, so run long ones in the background.
Ground rules
- Truth. Every line matches a step the code really has, and every label is the app's exact copy. Don't make marketing claims. Anything that isn't an instruction must be true and verified in code.
- Data. Use sample data in a local or test environment only. Never use real customers, never production, and never the user's real accounts. Sign in with test accounts from the project's own seed or fixture files. If none exist, ask the user to create one. Don't type real passwords.
- Privacy. Never show secrets, API keys, payment destinations (IBANs,
wallet numbers, payment QR codes), personal chats, or other people's
accounts. Blur them from the rects the capture records (
references/capture.md). - Ask first before changing the app's code to make capture easier (adding test ids, seed data, flags), before installing anything, and before committing. MP4s aren't committed.
- Recreate, don't fake, what's outside the app. OS sheets, emails,
notifications or a third-party site the task passes through are rebuilt
in HTML/CSS, faithful to the current versions, with the app's real copy.
See
references/recreated-ui.md.
Where things live
<demos>/
demo.config.json product, app URLs, languages, voice, brand, capture settings
features.md step 1: what the app does, with evidence
catalog.md step 2: the videos to make and their status
brand/logo.svg the logo for end cards and thumbnails (copied from the app)
_tools/ the scripts (from init.mjs), dependency-free
<slug>/
script.md tts.md the approved script, and paste-ready TTS lines
lines.json each row's text, gap and real length (d)
capture.mjs this demo's capture run
shots-<lang>/ real captures, one PNG per frame
targets.json each control's rect per language and frame
direction.js the direction
index.html the engine (never edited per demo)
voice/ voice/norm/ the user's clips, then trimmed and normalised
thumbnail.png thumbnail-1280.png
out/ MP4s and review stills (git-ignored)
References
references/setup.md:demo.config.jsonfield by field, and asking the user.references/discovery.md: finding the features in any stack, and turning them into a catalog.references/script-format.md: the script table, voice style, bilingual naming, TTS files.references/capture.md: the capture API, data, sign-in, languages, blur, manual capture for native apps.references/direction.md:direction.js, timing, the language switch, and pitfalls.references/recreated-ui.md: OS, browser and third-party screens.references/review-export.md: review stills, export, thumbnail, hand off.