Demo recorder

Demo Recorder

Follow this state machine:

INTAKE -> BRIEF_APPROVED -> PREFLIGHT -> NARRATION_READY -> SHOT_READY -> CAPTURED -> ASSEMBLED -> VALIDATED

Do not skip states. After approval, continue through validation unless a permission, credential, or app state blocks execution. Keep updates to: current state, artifact, blocker.

Default product-video rule: tutorials, demos, walkthroughs, troubleshooting videos, and release recaps must show the real application being used. Capture the actual user flow—navigation, clicks, typed input, uploads, selections, and visible results—as live footage. A screenshot, generated slide, static image, or frozen frame is never a substitute for app-feature footage. It is permitted only for a user-approved non-product section such as a title card, transition, or closing card.

1. Intake

Reuse supplied facts. Ask once, in one compact message, only for missing decisions:

• type: tutorial, demo, walkthrough, pitch, troubleshooting, or release recap
• audience; outcome or call to action
• must-show and must-avoid content, especially private data
• runtime, video count, and output format
• narration: live, OpenAI, ElevenLabs, or macOS say
• style: practical, polished, sales-oriented, or exploratory

If the user delegates a choice, propose a default in the brief. Never re-ask answered questions.

Tailor the structure:

Type	Structure
Tutorial	orient -> numbered steps -> verify result
Demo	outcome -> key actions -> result
Walkthrough	navigation -> sections -> transitions -> summary
Pitch	problem -> value -> proof -> call to action
Troubleshooting	symptom -> reproduce -> fix -> verify
Release recap	change -> user impact -> examples -> next step

2. Brief and approval gate

Copy assets/demo-brief.md to the output directory. Fill every required field; use one live app-flow shot per visible action and align narration to that action.

Show the brief, full narration, shot order, and capture-isolation route. Recording and paid TTS require explicit approval such as approved or go ahead; record it. Reapprove material script or scope changes.

3. Tool route

Use the smallest sufficient stack:

• Default: UI control + FFmpeg silent capture + generated narration + FFmpeg assembly.
• OBS: scenes, overlays, webcam, or existing OBS setup.
• QuickTime: capture fallback only.
• Live microphone: only when requested.

Use bundled scripts, not one-off capture/muxing code. Read references/tooling.md only to install, choose, or troubleshoot tools. Read references/action-led-capture.md for live UI footage, native dialogs, timing, or visual-QA work. The bundled recorder is macOS-specific; on another operating system, use a verified native window/display recorder while retaining every take contract and validation gate.

4. Mandatory live-app-flow gate

For every app-feature narration beat, create a take contract before recording:

• start state; one visible action; target state or field; exact narration segment; on-screen proof
• capture route: window capture, or isolated display capture when a native picker must be visible
• a short live action take followed by an uninterrupted live target-state hold; never substitute generated slides, screenshots, static images, or frozen video

Prepare navigation before a take. Do not compress a route that loads asynchronously into the same short take. Confirm the start state is visible, then record the action.

A target-state hold may look still, but it must remain footage of the real app captured immediately after the named action. Do not reuse a prior frame or reconstruct it from an image. If the requested flow cannot be run, stop and report the blocker; do not replace it with static visuals without explicit user approval and a clear disclosure.

5. Execute

Use one directory per video containing the brief, narration, raw capture, audio, final video, and validation log.

From this skill directory:

scripts/preflight.sh
python3 scripts/generate_narration.py --provider openai --input narration.txt --output narration.mp3
scripts/record_macos.sh --video-device DEVICE --audio-device none --duration SECONDS --output capture.mov
scripts/assemble_video.sh --video capture.mov --narration narration.mp3 --output final.mp4
scripts/validate_media.sh --file final.mp4 --min-width 1200

Use --help for options. For live narration, capture the microphone; skip TTS/muxing when the raw file already has approved audio.

During capture:

• Set the requested viewport/window size before recording.
• Reset the app to known mock/test data.
• Hide notifications, secrets, personal data, and unrelated windows.
• Keep the target app foreground for the full take plus a safety buffer. Do not return to an agent, terminal, browser, or another app while a display capture is live.
• Follow one take contract at a time. Pause after navigation and before the action; restart a bad take rather than repairing it with a static frame.
• Record only the scoped flow. Use a safe, pre-approved folder when a real native picker is shown.
• Segment generated narration by take. Make the visual segment duration match its narration segment before final assembly; do not rely on padding as a sync strategy.

6. Assemble and validate

Run scripts/inspect_timeline.sh for every raw action take and the final cut. Reject any take with an unrelated desktop, wrong app state, missing target field, abrupt return to a prior view, static-image substitution, or a narration/action mismatch.

For action-led output, assemble action footage with its target-state hold, then mux the matching narration segment. Add captions from the same timing manifest. Run:

scripts/validate_media.sh --file final.mp4 --min-width 1200 --max-av-delta 0.25 --require-subtitles

Then play the final file end to end. Verify sync, intelligibility, framing, cursor, readable text, transitions, factual accuracy, privacy, and every approved shot. If player automation exposes unreliable timing, do not claim a player pass from that telemetry; record the limitation and supplement it with a full decode plus exact transition-frame inspection.

Before declaring success, reconcile the approved shot list against the final cut: every claimed product action, field, upload, and result must appear as captured app UI footage while the corresponding narration plays. Recapture any unproven beat.

Do not infer success from file existence. Report paths, duration/resolution, checks, and remaining issues. Approve one representative video before a large batch; get authorization before publishing.

Guardrails

• Never expose credentials or real personal data.
• Never send text to an unapproved paid/external TTS provider.
• Disclose AI-generated voice when the video is shared externally and the provider requires it.
• Do not publish, upload, or share without explicit authorization.
• Never describe a video as action-led when its narration is laid over static screenshots, unrelated footage, a padded final frame, or a non-live recreation of the app UI.