create-hybrid-ad

name	create-hybrid-ad
description	Produce a Hybrid H-CARD ad (Common Thread Co taxonomy): a 22-second 9:16 video where a motion layer (NB2-generated avatars, Pexels stock b-roll, HTML phone mockups, NB2 product composites) runs underneath kinetic typography banner cards animated word-by-word via Playwright. Music-only, no VO, sound-off readable — banner copy IS the script. Autonomously scrapes brand kit from Shopify CDN, sources motion per beat, generates Indian-DTC-fit avatars where needed, renders banner overlays in Amulya 800, composites via ffmpeg overlay with mandatory de-AI grade. Two human gates only (brief approval + master review). Use when brand wants every-frame-is-a-complete-ad with always-on claim retention. NOT for UGC creator-led ads, VO-led storytelling, or product-only photoshoots.
status	PROD — validated on Clinikally V01 (2026-05-28), GOOSE-1785

create-hybrid-ad

Purpose

Produce a Hybrid H-CARD ad: a music-only 9:16 short with a motion layer (real footage / AI avatars / phone mockups / product composites) underneath kinetic typography banner cards that snap word-by-word. Banner copy IS the script.

The H-CARD sub-archetype (per references/format-dna.md) is the closest equivalent of Wild Earth's "YEAST" ad. The other Hybrid sub-archetypes (H-SPLIT product-heavy banner, H-PROMO discount strip) share most infrastructure but differ in banner composition — they're future variants of this skill.

Use when:

• Brand wants sound-off retention (every frame is a complete ad)
• Brand has a clear price/offer/promise (single number reveal beat)
• Brand has at least 3 real product photos (for end card brand-feel)
• Target length 15-25s

Do NOT use when:

• The ad needs a creator on-camera (use molecules/ugc-ad/)
• Audio narration drives the visual (use molecules/explainer-video/create-vo-anchored-beat-video)
• It's a single-product launch (Hybrid is brand-feel; use a product-spec format)
• Brand voice is sports/energy/party (different typography + music register; this skill defaults to clinical/wellness)

Inputs

Required:

• brand_url — Shopify URL of the brand (e.g. https://www.clinikally.com)
• service_or_offer — the headline product/service (e.g. "Video consult with dermatologist · ₹249 · 20-min")
• headline_sequence[] — 6 complete sentences (one per beat 1-6) + 1 social proof beat (beat 7). Per references/copy-rules.md, each must be a complete grammatical thought; no fragments stitched together.

Optional (autonomous defaults if omitted):

• aspect_ratio — 9:16 (default for Reels/Shorts), 1:1, or 4:5
• duration_s — default 22
• motion_source_per_beat — default decision tree: NB2 avatar for person beats if not Indian-presenting on Pexels; Pexels for generic context; HTML mockup for branded UI; NB2 composite for hand+product
• font_family — default amulya@800 (Indian Type Foundry, Fontshare) for Indian DTC clinical brands. For other registers see references/typography-rules.md
• music_brief — default: tropical-house wellness, 115 BPM, energetic from t=0, "Pacific Coast Dream" reference. Genre presets in references/music-presets.md
• end_card_pattern — logo_only (default, pattern B) or multi_product_grid (pattern A). Never single-product (per feedback_endcard_brand_not_product.md)
• kling_duration_per_beat — default 3s per Kling i2v call

Credentials:

• FAL_API_KEY / FAL_KEY in .env
• Pexels download requires curl_cffi (pip install --break-system-packages curl_cffi)

Composed Atoms

• skills/atoms/source/source-brand-assets — Phase 0 scrape: logo, palette, products from Shopify CDN
• skills/atoms/source/source-company-existing-ads — Phase 0: pull Meta Ad Library copy for inspiration
• skills/atoms/asset-preparation/remove-backgrounds — Phase 0: watermark-clean product photos via NB2 edit
• skills/atoms/clip-discovery/find-clips-pexels — Motion sourcing: stock b-roll for generic context beats
• skills/atoms/image-generation/create-image-nano-banana-fal — Avatar generation: NB2-gen Indian-presenting avatars at 9:16
• skills/atoms/product-images/edit-image-nano-banana — Product composite: compose hands+bottle, watermark cleans, etc.
• skills/atoms/video-generation/create-video-kling — Motion gen: Kling V3 Pro i2v with end_image_url lock for product beats
• skills/atoms/planning/create-storyboard-html — HTML mockups: phone bezel + booking card / derm list / etc.
• skills/atoms/motion-graphics/create-kinetic-typography — Banner overlays: per-frame Playwright renderAt(t) kinetic typography .mov
• skills/atoms/motion-graphics/create-motion-graphics-hyperframes — Static HTML hyperframes (for end card, beat 4 booking card)
• skills/atoms/end-cards/create-end-card-from-reference — End card: logo-only or multi-product brand-feel layout
• skills/atoms/music/create-music-elevenlabs — Music: instrumental bed via ElevenLabs Music API
• skills/atoms/assembly/stitch-videos-ffmpeg — Composite: per-beat segments → concat → mux
• skills/atoms/color/grade-consistency-pass — Color: uniform de-AI grade chain per feedback_deai_grade_chain.md
• skills/atoms/review/watch — Review: self-QC via /watch:watch skill end-to-end

Do NOT use: Klap captions (banner copy IS the captions), Whisper, Soul ID (no on-camera creator), VO atoms (music-only).

Workflow

Two human gates only. Phase 0-6 below.

Phase 0 — Autonomous brand kit + beat manifest

1. Scrape brand assets from Shopify CDN: logo PNG, brand color palette, 3-4 hero product photos, star rating + review count, "How it works" copy
2. Decide motion-source per beat via the decision tree (see references/motion-sourcing-tree.md):
   • Indian-DTC brand + person beat → NB2 avatar (Pexels has cultural-fit gap)
   • Generic context beat → Pexels stock
   • Branded UI beat → HTML phone mockup
   • Product + hands beat → NB2 single-hand composite
   • End card → logo-only HTML (pattern B) or multi-product grid (pattern A)
3. Generate beat manifest with: per-beat copy, emphasis word tags, motion source, expected output asset paths
4. PIL-upscale brand logo 6× LANCZOS+unsharp if source is <500px wide
5. Pre-render banner mockup contact sheet (for Gate 1 review)

🚦 HUMAN GATE 1 — Brief + banner copy + motion sourcing approval

Show user:

• brief.md with full beat manifest, copy per beat, emphasis words, motion source
• Banner mockup contact sheet (each banner card rendered with placeholder BG for layout review)
• Composite preview frame (banner overlaid on a representative motion layer frame)
• Estimated spend
• Compliance flags (for Personal Health category brands — see Decision Rule 11)

User approves OR edits copy OR swaps motion source OR rejects.

Phase 1 — Generate base stills + motion clips

1. NB2-generate avatars for person beats (Indian-presenting + warm honey-brown skin + casual modern clothing)
2. NB2 de-plasticize round 2 on each avatar (explicit "real iPhone photo, visible pores, asymmetry")
3. NB2 composite for product+hands beat (strict single-hand constraints, cap-on, anatomically correct prompt)
4. NB2 watermark-clean for product photos used in end card
5. Download Pexels clips via curl_cffi impersonation (Cloudflare bypass — see scripts/pexels_download.py)
6. Render HTML mockups (phone bezel + brand UI) for branded-screen beats

Phase 2 — Render production overlays (transparent BG)

1. Render kinetic banner .mov per beat via Playwright per-frame renderAt(t) pattern (NO CSS @keyframes — per repo rule)
   • Amulya 800, single weight, only size varies (base 74px / emph 128px / mega 248px for ₹249. style reveals)
   • Word-by-word scale-in animation (0.5→1.0 with easeOutBack), 0.09s stagger
   • Dim band radial gradient fades in 0-0.3s
   • Corner logo (hi-res white) fades in 0-0.4s
   • omit_background=True on Playwright screenshot
   • Encode PNG sequence to qtrle ARGB .mov
2. Render end card HTML at 1080×1920 with hi-res logo

Phase 3 — Run i2v on brand-critical beats

Per Decision Rule 6 (which beats get Kling i2v).

For each beat needing motion:

python3 scripts/kling_v3_pro.py \
  --start-image <still> \
  --end-image <still>  \   # LOCK for product beats
  --output <out.mp4> \
  --duration 3 \
  --prompt "<CHARACTER + VERB led, no subtle/slow language>"

Phase 4 — Music gen

fal_client.subscribe("fal-ai/elevenlabs/music", arguments={
    "prompt": "<vibe> instrumental in the style of '<ref track>'. Energetic from the very first beat — NO slow intro. <BPM>. <instruments>. No vocals.",
    "music_length_ms": 22000,
    "force_instrumental": True,
})

Phase 5 — Composite assembly

1. Per-beat segments: scale 1080×1920 → de-AI grade → banner overlay → output .mp4
2. Concat all 8 segments (demuxer, not filter_complex)
3. Mux music: -map 0:v -map 1:a -c:a aac -b:a 192k -shortest

Phase 6 — Self-QC + share

Mandatory /watch:watch end-to-end. Read every sampled frame. Verify per Quality Checks.

🚦 HUMAN GATE 2 — Final master review

Provide master via local file + gooseworks shareable URL together (per feedback_video_review_pattern.md).

User approves → done.

Decision Rules

1. Each banner card is a complete grammatical sentence. No fragments stitched together. Failure to follow = ungrammatical / unprofessional reads.
2. Frame 1 = complete composite at t=0. No animated reveal of banner or logo. Cards just hard-cut between beats.
3. Same font weight across all words in a card — only size varies. Mixed italic-base + bold-emph reads bad. Default amulya@800 single weight, base 74px / emph 128px / mega 248px.
4. CSS @keyframes are banned per repo rules. Animation is a pure function of beat-local time via JS renderAt(t).
5. Production banner overlays must be transparent-BG. Phase 0 mockups with colored placeholder gradients are review-only — never reuse them in final composite.
6. Kling i2v only on brand-critical beats, not generic context. Sourcing decision tree:

   Person/avatar beat? → NB2 still + Kling i2v
   Product+hands beat? → NB2 composite + Kling with end_image_url LOCK
   Booking card / branded UI? → HTML mockup + ffmpeg Ken Burns (NOT Kling — mangles small text)
   Phone scroll / generic? → Raw Pexels mp4 (no Kling)
   

7. Use end_image_url lock on every Kling product beat. Without lock, "rotate" prompts over-rotate past brand label. Pass same image as both start AND end.
8. Kling prompts: CHARACTER + VERB in first 8 words. No "subtle/slow/locked/static" — model interprets as "do less" and produces frozen output.
9. De-AI grade chain is mandatory final pass on every beat uniformly (curves + eq=saturation + noise per feedback_deai_grade_chain.md). ~50-60% plasticity reduction.
10. End card must be brand-feel — multi-product or logo-only, never single SKU. Per feedback_endcard_brand_not_product.md.
11. Personal Health category compliance: no before-after imagery, no prescriptive verbs ("treats X" / "cures X"), no efficacy %, no time-bound results, no body-shaming framing. Stick to declarative positioning, brand achievements, open-question hooks.
12. Music prompt MUST include "NO slow intro — energetic from t=0". Default ElevenLabs gen has 2-4s ambient build that wastes a quarter of a 22s spot.
13. Pre-upscale logo via PIL LANCZOS+unsharp 6× when source is <500px wide and no SVG exists. CSS browser scaling pixelates badly.
14. Per /watch:watch repo rule, self-QC every final mp4 before declaring done. Stills don't catch motion artifacts.

Output

<project>/
├── brief.md                          # Phase 0 plan
├── HOW_TO_MAKE_THIS_VIDEO.md         # per-project recipe
├── LEARNINGS.md                      # any new findings from this run
├── source/
│   ├── brand-pack.md
│   ├── logo.png + logo-hires.png + logo-white-hires.png
│   ├── pexels-clips/                 # raw Pexels mp4s
│   ├── clinikally-products/          # real product photos
│   ├── clinikally-screenshots/       # HTML mockups
│   └── locked-stills/                # final NB2-processed input stills
├── assets/
│   ├── nb2-generated-9x16/
│   ├── nb2-edits-9x16/               # de-plasticize + composites
│   ├── kinetic-banner-overlays-9x16/ # transparent .mov per beat
│   ├── kling-v3-pro-9x16/            # i2v outputs
│   └── music-bed.mp3
├── working/
│   ├── render_kinetic_banners.py
│   ├── render_endcard.py
│   ├── kling_v3_pro.py
│   ├── pexels_download.py
│   ├── build_master.py
│   └── ...
├── finals/
│   └── master-v<N>-9x16.mp4
└── archive/                          # prior versions

Quality Checks

• Length 15-25s (target 22s)
• Aspect matches requested (1080×1920 default)
• Frame 1 shows complete composite (banner + motion + logo all visible)
• Every banner card is a complete grammatical sentence
• Same font weight across all words in each card (only sizes vary)
• Banner overlays are transparent-BG (alpha verified via PIL getpixel((10,10)) → (0,0,0,0))
• Motion-layer hero doesn't enter banner zone (visual check)
• Logo readable at corner watermark + end card (no pixelation)
• Brand mark on all product beats stays readable (Kling didn't drift)
• No hand hallucinations on product+hands beats (anatomically correct, single hand if claimed)
• Banner card text NOT truncated at frame edges (check Amulya line widths)
• Music is instrumental, no lyrics, starts with energy (no slow intro)
• No VO, no Klap, no Whisper captions
• De-AI grade applied uniformly across all beats
• End card reads as brand (multi-product OR logo-only, never single SKU)
• Personal Health compliance: no before-after / prescriptive verbs / efficacy % / time-bound claims
• /watch:watch end-to-end self-QC completed before declaring done

Failure Modes

Failure	Cause	Recovery
Banner overlay covers motion entirely	Used Phase 0 mockup (colored placeholder BG) instead of production transparent overlay	Re-render with omit_background=True
Banner text truncated at right edge	Amulya letterforms wider than Boska; line has too many emph words	Split into 3 lines; max 3-4 words per line
Hand hallucinations (extra fingers, twisted joints) on product beat	NB2 composite drifted; or Kling i2v amplified anatomy issue	Re-roll NB2 with explicit "5 fingers, no extra digits, no merged fingers, anatomically correct" prompt; pass end_image_url lock to Kling
Bottle dissolves / brand mark drifts on product beat	Kling "rotate fully" over-rotates; long duration amplifies	Use end_image_url = start_image_url lock; reduce duration to 2-3s
Body text mangled (e.g. "Free doorstep delivery" → "Fere ctopoepetuer")	Kling i2v on HTML mockup with small body text	Replace Kling with ffmpeg Ken Burns subtle zoom on static still
Letterboxed/shrunk Pexels beat in 9:16 master	Source video aspect not native 9:16	Replace with NB2 avatar at 9:16 OR HTML mockup OR find a native 9:16 Pexels clip
Logo pixelated on end card	Brand only has small PNG, CSS scaled it up	PIL LANCZOS+unsharp 6× upscale; or get SVG from brand
Music has 2-4s slow intro before energy kicks in	ElevenLabs default behavior	Bake "Energetic from t=0 — NO slow intro" into prompt; re-roll
Music decays in 2nd half	Per feedback_elevenlabs_music_decay.md	Loop-and-flatten via ffmpeg acrossfade + acompressor + loudnorm
Single-product end card	Built from one hero photo instead of brand-feel	Per feedback_endcard_brand_not_product.md: switch to multi-product grid (pattern A) or logo-only (pattern B)
Avatar looks glossy AI-perfect	NB2 round 1 only	Always run round 2 de-plasticize edit with explicit "real iPhone photo, pores, asymmetry, fine lines"
Pexels download fails with 403	Cloudflare blocks plain curl	Use curl_cffi impersonation via scripts/pexels_download.py

Reference Files

• references/format-dna.md — Decoded Wild Earth H-CARD pattern + 3-sample DNA analysis
• references/copy-rules.md — Complete-sentence rule + emphasis word taxonomy
• references/typography-rules.md — Font selection by brand register; Amulya defaults; size hierarchy
• references/motion-sourcing-tree.md — Per-beat sourcing decision tree
• references/music-presets.md — Genre prompt presets + reference tracks
• references/banner-layout-templates/ — HTML templates per sub-archetype (H-CARD, H-SPLIT placeholder, H-PROMO placeholder)
• references/compliance-personal-health.md — Meta Personal Health category dos and don'ts

Validated Production Run

Originally validated in content-goose at clients/clinikally/video-01-derma-consult-hcard/. Adapt paths to your project.

Clinikally V01 (2026-05-28) — first production run of this molecule. Final master: clients/clinikally/video-01-derma-consult-hcard/finals/master-v10-9x16.mp4. Full recipe in clients/clinikally/video-01-derma-consult-hcard/HOW_TO_MAKE_THIS_VIDEO.md. Project learnings: clients/clinikally/video-01-derma-consult-hcard/LEARNINGS.md. Linear ticket: GOOSE-1785.

Spend: $11.92 across 10 iterations (clean recipe spend ~$4-5; the rest was UI/copy/font iteration).