| name | create-how-we-made-this-hook |
| description | Produce a 9:16 "proof-then-recipe" social hook reel — open on the most jaw-dropping seconds of a finished brand film (the flex), hard-cut on a record-scratch, then a felt-Goose mascot reveals the exact AI tool-stack that made it (the recipe) with fast cuts, brand-colored tool cards, per-beat pop SFX, and word-level karaoke captions. Use when you have an impressive existing deliverable and want a behind-the-scenes / "how we made this" / "the stack behind this" video for Instagram/TikTok/Shorts. Composes a conform-cut proof montage + the talking-goose explainer engine. NOT for a plain talking-head explainer with no proof footage (use talking-goose-creator-video) or a straight recut of one video (use ugc-ad/recut-video-to-creator-grammar). |
create-how-we-made-this-hook
Purpose
The production line for the proof-then-recipe format: show an impressive result, then reveal the AI pipeline that produced it.
Structure (always two acts):
- The flex (proof hook, ~3–5s): a fast beat-cut montage of the most scroll-stopping moments from a finished brand film, riding the film's own music, with a small context caption ("we made this ad."). No VO.
- The recipe (explainer, ~22–30s): a hard record-scratch cut to the felt-Goose mascot (lip-synced), who names the stack one tool per beat — orchestration → video model → voice → editor → "one afternoon, one person" — over brand-colored tool cards, with a pop SFX on every beat and word-level karaoke captions. Closes on a follow CTA.
The reusable abstraction: point it at (a) a finished deliverable to use as proof and (b) a tool-stack to credit, and it returns the reel. First shipped as gooseworks-ads/how-we-made-this-touchland/.
NOT the right molecule for:
- A plain mascot explainer with no "proof" footage — use
talking-goose-creator-video.
- A straight creator-grammar recut of a single source video — use
ugc-ad/recut-video-to-creator-grammar.
- A long-form (>45s) walkthrough — this format lives or dies on pace; keep it under ~35s.
Inputs
| Input | Required | Notes |
|---|
proof_film | yes | Path to the finished brand film used as the proof hook. Must be visually strong — the "wow" has to land in under 5s. Any aspect; it is scaled/cropped to 1080×1920. |
tool_stack | yes | Ordered list of {role, name, brand_color, badge} (e.g. orchestration=Claude Code, video=Seedance, voice=ElevenLabs, editor=FFmpeg). Drives the tool cards + the VO rundown. |
voice | yes | ElevenLabs voice id + model. Default Goose character voice QzTKubutNn9TjrB7Xb2Q (eleven_v3). Must be listed in VOICES.md or explicitly approved. |
character | no | Lip-sync anchor still (neutral closed-mouth, head-and-shoulders). Default felt Goose; reuse a materialized anchor PNG (LFS pointers will not lip-sync). |
script | no | Override the auto-generated VO. If omitted, the molecule writes the pivot → tool-rundown → CTA script from tool_stack. |
hook_caption | no | Lower-third context caption over the proof montage. Default "we made this ad." Keep it from spoiling the explainer's reveal. |
output_dir | yes | Project folder (canonical 5-folder layout). |
auto | no | bool, default false. Pass through the script + composite gates with prior preferences. |
Composed Atoms
atoms/voiceover/create-voiceover-elevenlabs — eleven_v3 VO with-timestamps for the recipe narration (approved voice only).atoms/source/transcribe-audio-fal — word-level timestamps on the final (speed-tuned) VO; drives beat boundaries + caption cues.atoms/lipsync/create-lipsync-veed-fal — one Veed Fabric 1.0 call on the full VO to lip-sync the mascot (the PIP source).atoms/captions/burn-in-captions — word-level karaoke reference (ASS + libass); here captions are dark-ink + brand-color karaoke placed in the band above the circular cam.atoms/overlays/render-video-overlay-track — Playwright/Chromium HTML→PNG renderer used for the premium overlay cards (real brand logos, glass cards, step bars).atoms/assembly/stitch-videos-ffmpeg — concat the proof hook + the explainer into the master.atoms/review/watch — mandatory frame + transcript self-QC on the final master (VIDEO_GEN_RULES.md rule 3).molecules/talking-goose-creator-video — the mascot-explainer lineage (VO + lip-sync + pop-SFX + brand-name caption patching). This molecule supersedes its flat overlay/rectangle-PIP look with premium HTML cards + a circular Loom-style cam.
Workflow
Step 1 — Intake + project setup
Validate proof_film exists and voice is in VOICES.md. Create the 5-folder layout under output_dir; copy proof_film to source/. Write script/script-locked.md.
Step 2 — Cut the proof hook (conform, local)
Sample frames across proof_film; pick the 4–6 most arresting ~0.7–0.9s moments. Trim each (scale to 1080:1920:force_original_aspect_ratio=increase,crop=1080:1920, fps=30), hard-concat, and lay a single continuous music slice from the film (its climax) as the bed with a short fade. Overlay the hook_caption (looped image + alpha fade) only over a clean cut and remove it before any text-bearing end card.
Step 3 — Write + lock the VO script (GATE)
Author the recipe VO: pivot line ("Want to make ads like these? Here's how.") → one line per tool in tool_stack → "one afternoon, one person" → CTA. Save clean + eleven_v3-tagged versions. Human-approve before spending on VO/lip-sync.
Step 4 — Generate + pace the VO
Generate eleven_v3 with-timestamps. eleven_v3 reads slow/dramatic — measure the result and apply atempo (~1.4–1.5) to hit a snappy ~30s and to cut lip-sync cost. Re-run transcribe-audio-fal on the paced VO for accurate word timings. Verify the transcript matches the script with no audio-tag leakage.
Step 5 — SFX
Generate a pop (card snap), a record-scratch (the turn), and an optional whoosh via ElevenLabs sound-generation.
Step 6 — Overlays (premium HTML/CSS via Playwright)
Render each beat as two layers at 1080×1920 so content can animate over a stable bg:
- bg layer (opaque): light/studio cream gradient + a faint brand-tint glow + step bars (01→04) +
@handle watermark.
- content layer (transparent,
omitBackground): the card/hero only.
Tool cards use real brand logos — fetch official SVG marks from cdn.simpleicons.org/<slug> (claude, elevenlabs, ffmpeg, anthropic, bytedance) and CSS-filter them white on a brand-color app-tile. For a tool with no simpleicons entry (e.g. Seedance), use a clean inline glyph (play triangle). Beats: kinetic title, "no camera/studio/crew" strikes, one tool card per tool_stack entry (logo tile + role eyebrow + name + descriptor), "one afternoon / one person", and a centered-Follow CTA. Type: Space Grotesk + Inter (Google Fonts). Render via a small Playwright script (render.js) at 2× then downscale for crispness.
Step 7 — Lip-sync the mascot
One create-lipsync-veed-fal call (image=character, audio=paced VO, 720p). Reuse a materialized anchor; never feed a 130-byte LFS pointer.
Step 8 — Composite the explainer (with motion)
Per beat (timings from the word timestamps): show the static bg for its duration and overlay the content layer with a subtle entrance — fade-in ~0.24s + slide-up ~18px. Concat beats → bg-track. Then composite the circular Loom cam: crop the mascot's face from the lip-sync clip, mask to a circle, and overlay it as a unit with a gentle float (y = base + 8*sin(2πt/3.6)). Layer order is critical: shadow UNDER the cam, white ring OVER it — never a fill or glow over the face, or the mascot reads as a brown tint / dull. Lift the masked face with a small eq (brightness +0.05, saturation ~1.15) so it pops on the light bg. Mix audio = VO + pop at each beat + record-scratch at t=0 — or, when only visuals change, re-mux a previously approved audio track of the same timeline.
Step 9 — Stitch
Concat proof hook + explainer (normalize fps/SAR/sample-rate via the concat filter) → edits/master-nocaption.mp4.
Step 10 — Captions
Generate word-level karaoke ASS from the paced-VO timestamps: short 1–3 word cues, dark-ink base + brand-color (coral) active word + soft white halo for the light bg, placed in the band between the card and the circular cam (MarginV ≈ 930 at 1080×1920) so they never cover the mascot or the cards. Offset by the proof-hook duration; leave the CTA sentence uncaptioned. Pre-merge split brand names in the word stream (e.g. "Eleven"+"Labs" → "ElevenLabs"). Burn with ffmpeg-full (libass) → edits/master-final.mp4.
Step 11 — QC + deliver
Run atoms/review/watch on the final. Copy to finals/, build storyboard.html, print the absolute master path.
Decision Rules
- Captions: ASS karaoke, not Klap. Compound tool names (Claude Code, Seedance, FFmpeg, ElevenLabs) reliably break Klap's homophone handling, AND captions must be precisely placed in the narrow band above the PIP — Klap's auto-placement would land on the mascot's mouth. Both conditions trigger the
VIDEO_GEN_RULES.md ASS fallback, and the talking-goose-creator-video lineage uses ASS anyway.
- Suppress captions on the proof hook and the CTA end card (LEARNINGS #7 — never stack two text layers in the same spot). The hook caption and the CTA card already carry their own text.
- Pace the VO with
atempo. eleven_v3 with expressive tags runs ~1.8 words/sec; the proven Goose pace is ~2.7. Speed-tuning 1.4–1.5× hits the snappy target and lowers Veed cost proportionally. Lip-sync the paced audio.
- Premium HTML/CSS overlays, not flat Pillow. Render cards via Playwright (gradients, glass, real type, layered shadows). Split each beat into a static bg layer + an animated content layer.
- Use real brand logos via
cdn.simpleicons.org. The repo's logo PNGs are Git-LFS pointers (~130 bytes) and won't composite. Fetch official SVG marks and CSS-filter them white on a brand-color tile. For a tool with no simpleicons entry (Seedance), use a clean inline glyph — intentional, not hand-drawn.
- Circular Loom-style cam, not a rectangle PIP. Mask the mascot face into a circle with a white ring + soft shadow. Shadow UNDER, ring OVER; never a fill/glow over the face (it reads as a brown tint / dull mascot). A small
eq lift makes the face pop on the light bg.
- Subtle motion sells "premium." Content slides up + fades in per beat; the cam floats gently; step-bars advance; captions karaoke. Keep it subtle, never busy.
- Light/studio premium background. Cream gradient + a faint brand-tint glow; the brand color lives in the tile, bars, and accent — not a heavy wash.
- Reuse the proof film on the video-model beat. Showing a clip from the result while crediting the video model ties the recipe back to the flex and adds motion mid-explainer.
- Voice gate. If
voice is not in VOICES.md and not explicitly approved, stop at Step 1.
- Proof film must be strong. If the film is music-only, use its music as the hook bed; if it carries VO, duck or drop it under the montage. If nothing in the first scenes is scroll-stopping, the format will not land — flag it.
Output
<output_dir>/
├── script/script-locked.md # clean + eleven_v3-tagged VO, per-scene map
├── source/ # the proof film (read-only)
├── audio/
│ ├── voiceover.mp3 # paced (atempo) — canonical
│ ├── voiceover_raw.mp3 # pre-atempo
│ ├── words.json # fal word timestamps on the paced VO
│ └── sfx-{pop,scratch,whoosh}.mp3
├── generated/overlays/*.png # title, word flashes, tool cards, afternoon, CTA, hook caption
├── clips/goose-talking.mp4 # one Veed Fabric lip-sync of the full VO
├── edits/
│ ├── explainer.mp4
│ ├── master-nocaption.mp4
│ ├── captions.ass
│ └── master-final.mp4 # burned captions
├── working/ # build_*.py scripts + QC frames (regeneratable)
├── finals/<slug>.mp4 # shippable 9:16 master
└── storyboard.html
Quality Checks
finals/*.mp4 exists, is 1080×1920, h264 + AAC, total runtime ~30–36s.- Proof hook is ≤5s and the strongest moment lands in the first ~2s.
- Captions: word-level, gold karaoke sweep, no phantom leading comma (correct ASS Dialogue field count), no two cues stacked at once, every tool name spelled correctly, none covering the mascot's mouth.
- Captions suppressed during the proof hook and the CTA end card.
- Audio: continuous,
max_volume < 0 dB (no clipping); the music→VO transition is marked by the record-scratch.
- One tool card per
tool_stack entry, each with the correct brand color + a one-line descriptor.
atoms/review/watch pass finds no subtitle/overlay collisions on any frame.storyboard.html embeds the final and lists the stack.
Failure Modes
| Symptom | Likely cause | Fix |
|---|
| VO is 40s+ and feels slow | eleven_v3 expressive pacing | atempo 1.4–1.5 on the VO before lip-sync; rescale/re-transcribe timestamps |
| Phantom leading comma on every caption | extra comma in the ASS Dialogue: line → empty field pushes a comma into Text | Use exactly Dialogue: 0,{start},{end},Style,0,0,0,,{text} (MarginL,MarginR,MarginV,Effect,Text) |
| Two caption lines stacked on screen | adjacent cues overlap (hold time runs past the next cue's start) | Clamp each cue's end to next_cue_start − 0.02s |
| Captions cover the mascot's mouth | MarginV too low | Place in the band above the PIP head (MarginV ≈ 848 at 1080×1920) |
| Tool card shows a blank/garbled logo | logo PNG is a Git-LFS pointer (~130 bytes) | Use a drawn Pillow wordmark + brand-colored badge instead |
| Lip-sync clip is silent/static or 403s | LFS-pointer anchor, or Veed storage auth under parallel load | Use a materialized anchor PNG; keep Veed calls sequential |
fal_client cannot authenticate | .env has FAL_API_KEY but fal reads FAL_KEY | export FAL_KEY="$FAL_API_KEY" before fal scripts (LEARNINGS #10) |
| ASS burn does nothing | default brew ffmpeg lacks libass | Use /opt/homebrew/opt/ffmpeg-full/bin/ffmpeg for the ass= filter |
| Hook caption invisible / fades wrong | image overlaid without -loop 1 is a single frame at t=0 so fades never animate | Add -loop 1 to the caption image input |
| Proof hook feels random/choppy | cuts picked without checking content, or music jumps between cuts | Confirm each cut frame; use one continuous music slice as the bed |
| Mascot in the cam looks brown / dull | a glow disc or the drop shadow is composited OVER the face | Compose shadow UNDER the cam and the white ring OVER it — nothing tinted over the face; add a small eq lift |
| Tool card shows a blank/garbled logo |
