create-product-demo-video

name	create-product-demo-video
description	produce a 20-35s narrated product demo — a use-flow walkthrough (unbox → load → use → enjoy) where each spoken claim is matched by a proof visual within 1.5s, with one payoff hold on the hero moment. Karaoke-pop captions. Built on the EDL pipeline (generate-edit-decision-list → render-edl). Maps to the `vo-product-demo` archetype in CREATOR_GRAMMAR.md §8.

create-product-demo-video

Purpose

Produce a 20–35s narrated product demo — a use-flow walkthrough (unbox → load → use → enjoy) where every spoken claim is immediately matched by a proof visual, the pacing follows VO phrase boundaries, and the hero moment is given a deliberate payoff hold. The format maps to the vo-product-demo archetype: vo+music, karaoke-pop captions, VO-paced (not beat-synced) cuts.

Structural spine:

1. Hook (0–15%): One sharp claim-caption or visual pattern-interrupt that answers "who is this for and why."
2. Use-flow body (15–70%): Ordered steps through the product experience — unbox → load → use → enjoy. Every spoken claim has a proof visual within 1.5s of the word.
3. Payoff hold (60–85%): The single longest shot (2–4× the mean shot length) — the product working, the result, the hero moment.
4. Tail (last 15%): Decelerate. A held final frame or a light end card. No burned-in CTA.

Use for: DTC product launches, app or SaaS feature demos, unboxing-style shortform, tutorial/how-to VO ads.

Do not use for: silent feature-flash demos without VO (use create-silent-product-demo); lyrical lifestyle brand essays (use create-broll-narrative-essay); before/after formats (use before-after-video/).

---

Inputs

Input	Required	Notes
brief	yes	Brand, product, audience, platform, claim-to-prove
script	no	Pre-written use-flow VO script. If omitted, molecule drafts one in Phase 1.
voice_id	yes	ElevenLabs voice ID from VOICES.md approved list
product_clips	no	Paths to existing product footage (conform mode). If omitted, generative mode — clips sourced/generated per EDL spec.
product_images	no	Paths to product stills for use in AI video generation or still-to-motion clips.
music_path	no	Path to a pre-selected music track. If omitted, find-music is invoked.
target_duration_s	yes	20–35 (default: 28)
aspect	no	"9:16" (default), "1:1", "16:9"
caption_preset	no	Caption preset ID from caption-style-presets.json. Default: "platform-default" (karaoke-pop).
output_dir	yes	Canonical 5-folder project directory

---

Composed Atoms

• atoms/voiceover/create-voiceover-elevenlabs — Phase 2: render the approved use-flow VO
• atoms/source/transcribe-audio-fal — Phase 3: extract word-level timestamps from rendered VO
• atoms/source/split-audio-by-words — Phase 3: fallback word-boundary chunking if FAL unavailable
• atoms/music/find-music — Phase 2: select music bed if no track provided
• atoms/planning/generate-edit-decision-list — Phase 4: produce edl.json for vo-product-demo archetype — claim→proof intercut, payoff hold
• atoms/product-images/create-product-images-higgsfield-ms — Phase 5: generate product stills for AI video generation when no source footage exists
• atoms/video-generation/create-video-veo3 — Phase 5: produce scene clips from product images or text prompts (Tier 2 generative)
• atoms/editing/trim-video-clips — Phase 5: conform existing product footage to EDL scene durations
• atoms/editing/add-zoom-cuts — Phase 5: apply zoom-punch emphasis on claim payoff clips
• atoms/captions/style-captions — Phase 6: apply karaoke-pop preset to EDL caption cues
• atoms/assembly/render-edl — Phase 6: execute edl.json → master.mp4 with audio mix, ducking, and burned captions
• atoms/review/watch — Phase 7: self-QC — sample frames + transcribe + verify claim→proof pairing

---

Workflow

State machine: 7 phases. Produces a resumable artifact at each phase boundary.

P1 WRITE SCRIPT      P2 VO + MUSIC     P3 TRANSCRIBE
 brief → use-flow  →  vo.mp3,          → words.json
 script.md            music.mp3          [GATE 1]
                                           ↓
P7 SELF-QC    ←  P6 RENDER EDL  ←  P5 ACQUIRE CLIPS
 qc-report.md      master.mp4          clips/
                   [GATE 2]              ↑
                                   P4 GENERATE EDL
                                    edl.json (claim→proof
                                    intercut + payoff hold)

Phase 1 — Write the use-flow script

If script is provided, skip to Phase 2.

Otherwise, draft a use-flow VO from the brief:

• Hook sentence (the claim): Lead with the single strongest benefit or transformation. Answers "who is this for and why." Not a tagline — a direct claim ("This is the only foam that...").
• Use-flow body (steps): 3–5 narrated steps — unbox / load / use / enjoy. Each step is one short sentence. Write each sentence so it describes the visual a viewer would expect to see — the claim and the proof visual are written together, not separately.
• Payoff sentence: The hero moment in one sentence. This is the clip the EDL will mark role: "payoff-hold".
• Tail (optional): One closing line or a mid-sentence stop. No CTA copy.

VO word budget: ~3 words/second at 1.0× delivery speed. For 28s target, aim for ~80–90 words. Adjust per voice delivery speed.

Write to working/script.md. Present to user and wait for explicit approval before proceeding.

Phase 2 — Render VO and music

VO: Invoke atoms/voiceover/create-voiceover-elevenlabs with the approved voice_id and locked script. Use a clean, authoritative delivery style for product demos — stability: 0.45–0.55, similarity_boost: 0.72–0.80. Write to working/voice/vo.mp3.

Music: If music_path is provided, copy to working/music/music.mp3. Otherwise invoke atoms/music/find-music with a brief derived from the product's register — aim for a track with energy that builds into the payoff and doesn't fight the VO. Write to working/music/music.mp3.

Phase 3 — Transcribe and extract word timestamps (GATE 1)

Invoke atoms/source/transcribe-audio-fal on working/voice/vo.mp3. Save word-level timestamps to working/whisper/words-flat.json as [{text, start, end}, ...].

If FAL credentials are unavailable, use atoms/source/split-audio-by-words as fallback and document in manifest.json.

Identify the payoff sentence's word-timestamp range — this is the candidate payoff-hold window.

Present script.md, vo.mp3 duration, and word-count to the user. [GATE 1]: Confirm script and voice before proceeding.

Phase 4 — Generate the Edit Decision List

Invoke atoms/planning/generate-edit-decision-list with:

• archetype: "vo-product-demo"
• words_json: working/whisper/words-flat.json
• target_duration: <target_duration_s>
• source_mode: "generative" (default) or "conform" if product_clips are all provided
• output_path: working/edl.json

Claim→proof intercut rule (mandatory): in the scene table passed to generate-edit-decision-list, every clip covering a spoken use-flow step must carry a notes field of "proof-for: <claim>" identifying which spoken claim it proves. No claim should be separated from its proof by more than 1.5s on the timeline.

Payoff hold placement: the EDL's grammar.payoff_hold_id must point to the clip covering the payoff sentence. Confirm it is marked role: "payoff-hold" and its duration is 2–4× the mean shot length.

Zoom-punch plan: identify 2–3 feature clips in the body segment where a zoom-punch will add emphasis. Annotate those clips in the scene table as motion: { type: "zoom-punch", from: 1.0, to: 1.10 } — render-edl will execute this via add-zoom-cuts.

Validate edl.json with edl_validate.py. Do not proceed with an invalid EDL.

Phase 5 — Acquire and conform product clips

For each clip in edl.json's timeline[], source footage using the tiered strategy:

Decision: generative vs. conform (CREATOR_GRAMMAR §10):

• Conform mode (preferred when brand footage exists): invoke atoms/editing/trim-video-clips to cut the clip from the provided product_clips source files at the EDL-specified source.in/source.out windows. Update source.mode to "file" in the EDL.
• Tier 1 (free): HTML hyperframe for text-heavy overlays or callout claims. Use only when the clip is a stat reveal or on-screen text — never as a substitute for product footage.
• Tier 2 (product image → motion): If product_images are provided, generate short motion clips with atoms/video-generation/create-video-veo3 using the product images as keyframes and the EDL clip's source.spec.description as prompt. This covers unboxing, pour shots, and close-up texture footage.
• Tier 3 (full generation): Use atoms/video-generation/create-video-veo3 with a text prompt only when no images or real footage exist. Reserve for atmospheric or lifestyle-adjacent clips, not for clips with readable brand labels or hands manipulating the product precisely.

For any clip requiring add-zoom-cuts, apply it to the acquired clip before the final EDL render, and confirm the zoom-punched version is saved to working/clips/<scene_id>.mp4.

Phase 6 — Render the EDL (GATE 2)

Invoke atoms/assembly/render-edl with:

--edl working/edl.json
--output finals/master.mp4
--project-dir <output_dir>

render-edl will:

• Assemble clips as hard cuts in timeline order.
• Mix music bed + VO with sidechain-20:1 ducking.
• Burn karaoke-pop captions from the EDL's word-level timeline[].captions[] cues, using the caption_preset (default platform-default).

After render, confirm finals/master.mp4 exists, duration matches meta.target_duration ±0.5s, and manifest.json shows status: "pass".

[GATE 2]: Present finals/master.mp4 to the user for approval.

Phase 7 — Self-QC

Invoke atoms/review/watch on finals/master.mp4 with the QC prompt:

"Review this product demo for: (a) claim→proof pairing — does each spoken claim appear with a matching proof visual within 1.5s? (b) payoff hold — is there one clearly longer shot at the hero moment? (c) use-flow order — unbox → load → use → enjoy, or equivalent product-native flow? (d) zoom-punch emphasis — do the punches land on the right words? (e) karaoke captions — word-by-word sync, no leading-comma artifacts, no collision with product detail shots? (f) audio mix — VO clear above music?"

Write findings to working/qc-report.md. Surface any punch list items to the user with proposed fixes. Loop back to the relevant phase for critical issues.

---

Decision Rules

1. Generative vs. conform footage — the tier ladder

Tier	When to use	Atoms
Conform (0)	Brand or client has real product footage	trim-video-clips
1 — HTML hyperframe	Clip is a text callout or stat reveal	HTML authoring directly
2 — Still → motion	Product images exist; need unboxing/close-up motion	create-product-images-higgsfield-ms → create-video-veo3
3 — Full generative	No images, no footage; atmospheric b-roll only	create-video-veo3 (text prompt)

Never use Tier 3 for clips where hands manipulate the product, liquid pours, or readable labels are needed — AI fails reliably on these (CREATOR_GRAMMAR §10). If the use-flow step requires one of these and no real footage exists, flag it explicitly and request the brand to provide source footage before proceeding.

2. The claim→proof pairing rule

Every spoken use-flow claim must be accompanied by a visual proof of that claim within 1.5s of the spoken word. The mapping is:

• Claim: "dissolves in 30 seconds" → proof: ECU of the tablet dissolving in water.
• Claim: "no mess, no waste" → proof: MS of a clean pour, no spill.
• Claim: "works on all skin types" → proof: CU of diverse skin being treated.

If a claim has no visual proof available (neither sourced nor generatable), either cut the claim from the script or flag it in the EDL clip's notes as "no-proof-available". A claim without proof is a liability in the render — it makes the VO feel unsupported.

3. The payoff-hold choice

The payoff hold should be the single most visually convincing moment of the product working — not the most dramatic VO line, but the strongest visual proof. Typical candidates:

• The product in its final, beautiful in-use state.
• The outcome (skin glowing, app dashboard populating, coffee crema forming).
• An ECU of the hero detail that makes the product distinctive.

The payoff hold duration should be 2–4× the mean shot length. If the mean shot length is 1.2s, the payoff hold is 2.4–4.8s. The EDL's pacing_curve.payoff_hold_ratio must fall in this range.

4. Karaoke caption placement

Word-level caption cues are placed from word-timestamps. Rules:

• Suppress captions on the payoff-hold clip if it carries a text overlay or product callout (add-product-callouts).
• Suppress captions on any clip where on-screen text (sourced footage, hyperframe, or end card) would collide with the caption area.
• Caption preset defaults to "platform-default" (clean sans, lower-center). Use "bold-tiktok-hook" only on the hook clip if the hook requires loud emphasis.

---

Output

Under the project's canonical 5-folder layout:

<output_dir>/
├── HOW_TO_MAKE_THIS_VIDEO.md
├── working/
│   ├── script.md                   # Phase 1: locked use-flow VO script
│   ├── voice/
│   │   └── vo.mp3                  # Phase 2: rendered VO
│   ├── music/
│   │   └── music.mp3               # Phase 2: music bed
│   ├── whisper/
│   │   └── words-flat.json         # Phase 3: word-level timestamps
│   ├── edl.json                    # Phase 4: validated EDL (vo-product-demo archetype)
│   ├── clips/
│   │   └── <scene_id>.mp4          # Phase 5: individual scene clips
│   └── qc-report.md                # Phase 7: self-QC findings
├── finals/
│   └── master.mp4                  # Phase 6 deliverable
└── manifest.json                   # run metadata, phase statuses, gate approvals

manifest.json must include: skill, run_id, created_at, phase_statuses (P1–P7), gate_approvals (G1 brief, G2 master), source_mode, payoff_hold_scene_id, outputs.master, warnings, errors.

---

Quality Checks

• finals/master.mp4 exists; ffprobe reports both video and audio streams.
• Duration within ±0.5s of meta.target_duration.
• Resolution is 1080×1920 (9:16) or the appropriate canvas for meta.aspect.
• edl.json validates cleanly (all nine rules in edl-schema.md §"Validation rules").
• Exactly one clip has role: "payoff-hold" and pacing_curve.payoff_hold_ratio is 2.0–4.0.
• Every use-flow step clip has a notes field starting "proof-for:".
• Karaoke-pop captions appear on all non-suppressed clips; no leading-comma artifact.
• grammar.caption_preset is a recognized preset in caption-style-presets.json.
• Audio: VO clear above music; sidechain-20:1 ducking is active.
• Self-QC report (qc-report.md) exists with a PASS / NEEDS_REVISION verdict.
• Voice ID is from the approved list in VOICES.md.

---

Failure Modes

• No product footage and Tier 3 generation produces unusable clips — AI fails reliably on hands-on-product manipulation (CREATOR_GRAMMAR §10). If the use-flow requires unbox or pour shots without real footage, flag the clips as "needs-real-footage" in the EDL before running render-edl. Do not deliver a video with clearly AI-glitched product handling.
• Claim→proof gap exceeds 1.5s — usually caused by a VO sentence that spans too many words before the matching visual. Fix by splitting the sentence in the script or inserting an earlier b-roll-insert clip for the proof.
• Payoff hold too short — if the payoff-hold candidate is shorter than 2× mean shot length, trim a longer section from the source or generate a longer version. A too-short payoff hold deflates the pacing curve.
• Word-timestamps unavailable — karaoke-pop captions cannot be placed without word-level timing. If FAL is unavailable, use split-audio-by-words fallback; document in manifest.json. If no timestamps are available at all, fall back to static-title-card captions and note the deviation.
• EDL validation failure — fix every reported violation before running render-edl. Common causes: non-contiguous timeline, missing payoff-hold, target_out mismatch on the last clip.
• render-edl fails on missing generative clips — the renderer fails immediately listing every missing clips/<id>.mp4. Generate or source every clip before invoking render-edl.
• Karaoke caption collision with product callouts — two text layers at the same screen position are both unreadable (LEARNINGS.md). Suppress captions on any clip that carries a product callout or overlay. Set notes: "suppress-captions" on those clips in the EDL.
• Voice ID outside VOICES.md — reject in Phase 1; ask user to choose from the approved list. Do not render VO with an unapproved voice.
• Music track too energetic for VO clarity — if sidechain ducking cannot bring music below VO level, replace the track before rendering. Do not deliver a video where music competes with the VO.