lokeshrana9999/agent-demo-film

What does agent-demo-film do?

A demo video is worth sending only if what's on screen is real and matches what the person says at that moment. This skill gets the person to do one thing, which is read a script to camera in one sitting. Agents do the rest: the research, the footage, the script, and the cut and build afterwards.

1 prep ─> 2 capture ─> 3 script ─(approve)─> 4 record (the person) ─> 5 cut ─> 6 cue plan ─(approve)─> 7 build ─> 8 verify ─> MP4

Each project needs different footage and a different story; work those out from the project itself. examples/ shows two real runs: a narrated product walkthrough and a with/without film of an agent skill. Read the one closer to the request before planning.

principles

• Real footage only. Every app screen, agent reply, number and log on screen comes from a capture or a file, copied by a script, never retyped. If a line you want isn't in a capture, the film can't show it.
• The screen follows the voice. Each visual lands on the word that names it. Every time in the build comes from a word id in the cut, so re-cutting moves the visuals with the voice.
• Nothing claims more than the words and the sources. Keep a facts list (with the file each fact comes from) and a "not claiming" list. Check any research citation against the paper itself (Crossref: https://api.crossref.org/works/<doi>).
• Synthetic input. Invented users, chats and data. No real names or transcripts. Mask secrets and phone numbers in footage, and never print a key: sign-in steps read it from the env file in an unrecorded context.
• Keep every take. Scripts refuse to overwrite a capture or a cut source. Raw recordings stay where the person put them, and deleting them is the person's call.
• The person approves twice: the outline and script before recording, and the cue plan before the build. Expect several rounds of wording notes on the script; they're the point of that phase.

model routing

Run the bulk of the work in subagents, so the main session keeps the decisions. When the person names a model for a step, use that one.

work	model
bulk reading and research of text: the repo fact sheet, topic research, splitting the take into an edit list, reviewing a script for AI tells	Sonnet
anything that reads video or frames: crop framing, frame checks after a render, checking footage for secrets, and the per-section cue swarm (one agent per section)	Haiku
building a new tool the pipeline lacks, eg a custom recorder	Opus
the outline, the script, the cue plan and every call the person has to approve	the main session

Haiku and Sonnet can't hear audio. Word timings come only from transcription (step 5).

1. prep

Read references/prep.md. In parallel: a Sonnet agent writes a fact sheet from the repo (what it does, real numbers with their source files, known quirks to keep off screen), and Sonnet agents research whatever the story rests on. Then write the outline: sections with target seconds, what's on screen in each, the footage each needs, the facts list and the not-claiming list.

2. capture

Read references/capture.md. Pick the capture method from the project: Playwright for web apps, scripts/run_take.sh for agent behaviour through claude -p, a terminal recorder for CLIs, a scroll for a live page. Every take logs its marks (send, reply, scroll stops) with timestamps, so the build can cut the footage to the voice. Haiku agents check the frames of each take.

3. script

Read references/script.md. Write only the person's dialogue, in ## N. title sections that match the outline, for one sitting at about 150 words a minute. Plain spoken words in the person's voice: no marketing fluff and no AI tells. Show the script with the recording guide and wait for approval.

4. record

The person records one file with webcam and mic together (OBS, the Camera app or a phone). Mistakes and restarted lines are fine, since the cut takes the last complete version. Several files work too (one per section, or a pickup line recorded later).

5. cut

Read references/cut.md.

1. Transcribe each take locally: npx hyperframes transcribe <take> --engine parakeet.
2. Number the words and trim them to real silences: python scripts/words.py transcript.json <take> vo --media <take>.
3. Give the phrase listing and the script to a Sonnet agent (assets/SPLIT-BRIEF.md). It writes edl.json: which word ranges to keep per section, which fillers and false starts to drop, and which lines say something the facts don't support.
4. Ask the person about any repeated line or flagged claim before cutting.
5. Frame the webcam: a Haiku agent picks one crop that holds head and shoulders across all takes from sampled frames, or blur the background instead (scripts/blur_bg.py).
6. Cut: python scripts/cut.py edl.json writes vo.wav, cam.mp4, timeline.json and a words file per section. Lip sync holds because audio and video are trimmed on the same frame grid.

6. cue plan

One Haiku agent per section (assets/CUE-BRIEF.md) turns the section's timed words into subtitles, cues (which visual lands on which word, with its source) and flashes. Then:

1. python scripts/cues.py cut checks every section file against the cut and merges them into film.json. Send any error back to the agent that wrote that section.
2. Write the cue plan for the person (examples/samatva-support/CUE-plan.md shows the shape): section layout, line-by-line visuals, the audio edits, and the decisions only they can make. Wait for approval.

Subtitle rules: show the correct word. Fix the transcriber's mishearings silently. Mark a real slip with the correct word as *(word) in place of what was said. Flash names, numbers and terms that are hard to catch large above the subtitle.

7. build

Read references/hyperframes.md. Copy assets/build_film.py into the film folder. As it is, it builds an animatic from film.json: each cue's text on its word, the webcam inset per section, subtitles and flashes. Render that first if the timing is in doubt. Then replace each section's body with the real visuals: footage cut to the cue times, diagrams that build as each part is named, and cards for the sources.

8. verify

Read references/verify.md. In order:

1. npx hyperframes check --json until it shows 0 errors.
2. Snapshot at every cue time (the builder writes cues.json), and have Haiku agents check those frames against the cue plan and for leaked secrets.
3. Compare on-screen text with its sources by script.
4. Render the 1080p master and a 720p review copy.

Then send the review copy. When the person names a moment ("at 1:23 I say …"), fix it with a pickup recording or a cue change, and re-verify only the frames that changed.

files

• scripts/words.py: transcript to numbered words and a phrase listing, trimmed to real silences.
• scripts/cut.py: edit list to vo.wav, cam.mp4 and timeline.json, in sync on the frame grid.
• scripts/cues.py: checks the cue agents' section files and merges them into film.json.
• scripts/blur_bg.py: local background blur for the webcam (RobustVideoMatting, CPU).
• scripts/run_take.sh, scripts/grade.py: real claude -p takes of agent behaviour, and grading them.
• assets/build_film.py: the builder to start from (animatic, webcam, subtitles, flashes).
• assets/edl.example.json, assets/SPLIT-BRIEF.md, assets/CUE-BRIEF.md: the edit list format and the two agent briefs.
• references/: prep, capture, script, cut, hyperframes, verify.
• examples/samatva-support/: a 2:19 narrated product walkthrough, from three takes.
• examples/samatva-vent/: a short silent with/without film of an agent skill, built from real claude -p takes.