First, keep this skill fresh — confirm with the user before running: npx hyperframes skills update talking-head-recut. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
Talking Head Recut
Talking Head Recut takes a local video that plays in full and layers a sequence of
timed, designed graphic cards onto it — titles, lower-thirds, data callouts,
quotes, side panels, picture-in-picture — synced to what's being said. The agent
designs the cards (timing + content) and writes each card's HTML directly in the
conversation, then assembles a single composition HTML and renders it to MP4 via
hyperframes. There is no fixed archetype list and no prescribed card structure —
the overlays emerge from what the transcript actually says.
The front door is /hyperframes. This skill packages an existing talking-head clip with designed graphic cards (titles, lower-thirds, data callouts, quotes, side panels, PiP) — not plain captions (the spoken words as text). The clip plays untouched. Any other intent — plain subtitles, a standalone graphic, a from-scratch video — or any uncertainty → read /hyperframes first: the intent layer owns every route decision.
Graphic-packaging sibling of embedded-captions. Captions add the spoken words
as a readable subtitle; this adds designed graphics on top of the playing video.
Plain subtitles → embedded-captions. Build a video from scratch → the creation
workflows (product-launch-video / faceless-explainer / …).
Routed through /hyperframes, the intent layer confirms only the input (which clip) and announces the render-strategy questions as deferred asks — aspect, layout, style group, and card count stay at Step 7, where the probed footage and transcript ground the recommendations; the layer's run-shape questions don't apply. A BRIEF.md, when present, carries the confirmed input and any user notes — read it first.
Inspectable intermediate files in the work directory:
metadata.json — duration / width / height / fps
audio.mp3 — extracted audio
transcript.json — a flat word array [{ text, start, end }, …] (Whisper; no segments, no words wrapper)
storyboard.json — lightweight card outline (the agent's plan)
public/cards/card-XX.html — one HTML fragment per card
public/index.html — final assembled composition
output.mp4 — rendered video
CLI Resolution
# hyperframes — transcription (local Whisper) + rendering the assembled HTML to MP4
npx hyperframes --help
This skill runs entirely on the hyperframes CLI plus system ffmpeg / ffprobe.
Transcription is local Whisper via hyperframes transcribe — no third-party
service, API key, or rate-limited proxy.
Workflow
1. Check Environment
npx hyperframes doctor # ffmpeg, headless browser, render deps
# confirm bundled assets:
ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"
Required:
ffmpeg / ffprobe (system)
<SKILL_DIR>/assets/fonts/*.woff2, <SKILL_DIR>/assets/vendor/gsap.min.js (bundled inside this skill, staged to work dir in Step 9)
Transcription needs no key — hyperframes transcribe runs Whisper locally (Step 4).
Strongly recommended on macOS for hyperframes render:
export PRODUCER_BROWSER_GPU_MODE=hardware
2. Create a Work Directory
All artifacts live under videos/<project-name>/ — the same convention as the other
video workflows (product-launch-video / faceless-explainer / pr-to-video). Keep
the cwd at the workspace root; everything below writes under this one subdirectory.
VIDEO_PATH="/absolute/path/input.mp4"
WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"
3. Extract Audio and Metadata
# metadata — duration / width / height / fps
ffprobe -v error -select_streams v:0 \
-show_entries stream=width,height,r_frame_rate \
-show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
# audio
ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"
Outputs: metadata.json (read width/height/duration; fps = the r_frame_rate
fraction evaluated, e.g. 30000/1001 → 29.97) + audio.mp3.
4. Transcribe
npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en
Local Whisper — no API key, no proxy, no rate limit. Writes a word-level
transcript.json into the work dir (word text + start / end timestamps).
Read it for the word / sentence timings that drive card timing in Step 6; group
words into sentences yourself at punctuation / pauses if you need segment-level
chunks.
Clamp to media duration. Whisper can return the final word's end a hair past the
actual clip length — clamp every card endSec and composition.durationSeconds to the
metadata.json duration, or the render will show a black tail past the video.
5. Correct Transcript
transcript.json is a flat array of word objects — [{ "text": "...", "start": s, "end": s }, …] (no segments array, no words wrapper; the per-word key is text). Read it and fix obvious ASR errors:
- Homophones, product names, technical terms, punctuation
- Edit a word's
text in place; preserve its start / end timestamps
- There is no pre-grouped
segments array — group words into sentences yourself (split at terminal punctuation / pauses) when you need segment-level chunks for card timing
6. Draft a Lightweight Storyboard (in chat)
No CLI involved. Read transcript.json + metadata.json and design
cards directly. storyboard.json is an agent-internal planning artifact
— no CLI command consumes it; it exists so you can think clearly
about timing and content before writing each card's HTML. Keep the
shape consistent with the example below so the same outline can drive
the composition you author in Step 9:
{
"schemaVersion": 3,
"composition": {
"fps": 30,
"width": 1080,
"height": 1920,
"durationSeconds": 121.2,
"layout": "portrait",
"themeId": "noir",
"seed": 42
},
"videoTrack": {
"sourcePath": "input-video.mp4",
"startSec": 0,
"endSec": 121.2,
"bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
},
"subtitles": { "enabled": false },
"cards": [
{
"id": "card-01",
"intent": "Hook with the speaker's anxious midnight question",
"startSec": 0.5,
"endSec": 13.0,
"accentIndex": 0,
"zone": "fullscreen",
"contentHints": {
"kicker": "AN HONEST QUESTION",
"title": "The soul-searching question at 11 PM",
"detail": "Client's 60-second voice message: 'If the RMB appreciates, does that mean my USD policy is a terrible loss?'"
}
}
]
}
Required Card fields:
| field |
type |
purpose |
id |
string |
stable id used in card HTML & GSAP selectors |
intent |
string |
natural-language description; fed to card synthesis |
startSec / endSec |
number |
times in seconds (endSec > startSec) |
accentIndex |
0 | 1 | 2 | 3 | 4 |
which of the 5 theme accent colors this card pulls |
zone |
enum (see below) |
where on the canvas the card lives |
contentHints |
object |
free-form bag; agent puts kicker/title/detail/data/quote here |
archetype (optional) |
string |
free-form label you may attach to remember a card's pattern; absent = free-form, which is the default |
transition (optional) |
enum: cut | fade | slide | wipe |
declarative card-to-card transition |
Five zone values:
| zone |
resolved bounds |
when to use |
fullscreen |
covers whole canvas |
hero moments, big numbers, mantras |
whiteboard-area |
inset 40px margin (or 45% of portrait height) |
dense data / annotated content |
lower-third |
bottom 30% band |
annotation over visible video |
side-panel |
right 42% (landscape) or bottom 40% (portrait) |
data side, video other side |
video-overlay |
full canvas, expects mostly-transparent card |
annotation overlays on full-bleed video |
When you assemble the composition in Step 9, resolve each card's zone
into pixel bounds on the card-host wrapper following the table above.
Video bounds are set once at composition level (videoTrack.bounds);
to make video appear to "move between cards", author GSAP tweens against
#video-wrap in the composition's <script> (see Step 9).
No prescribed card roles, no prescribed narrative arc. Cards emerge
from what the video actually says — could be all quotes or all data,
could open with a number or with a story. Let the transcript drive the
rhythm.
How many takeaways? — auto-infer from duration + density. No fixed
upper limit. Pick a base pace from the video duration, then adjust
by information density. Only floor is fixed: minimum 5 cards so
even short videos have rhythm.
Step 1 — base pace by duration (the natural sec/card for medium density):
| video duration |
base pace (sec per card) |
rationale |
| < 60s (short reel) |
6–8s |
viewers expect fast cuts in short-form |
| 60s – 3 min |
8–12s |
normal social pace |
| 3 – 10 min |
12–20s |
give breathing room; each card carries more |
| 10 – 30 min |
20–35s |
long-form lecture / interview rhythm |
| > 30 min |
30–60s |
episodic, near-chapter feel |
Step 2 — density multiplier (multiplies the base pace):
| signal in the transcript |
multiplier |
effect |
| High density — many numbers, distinct claims, staccato pacing, list-like enumeration, every 1–2 sentences is a new idea |
× 0.7 |
cuts faster, more cards |
| Medium density — mixed flow with both data and narrative |
× 1.0 |
base pace |
| Low density — one extended story, repeated reframing, slow reflective pacing, single argument unfolding |
× 1.5 |
cuts slower, fewer cards |
Step 3 — compute:
secPerCard = basePace × densityMultiplier
cardCount = max(5, round(videoDurationSec / secPerCard))
Examples (notice — no upper clamp; long videos naturally produce more cards):
- 30s reel, single punchline (low density) → 7 × 1.5 = 10.5s/card → round(30/10.5)=3 → floor to 5 cards
- 60s reflective monologue (low density) → 10 × 1.5 = 15s/card → 4 → floor to 5 cards
- 121s talking-head with rich data (high density) → 10 × 0.7 = 7s/card → 17 cards
- 5 min interview, mixed density → 16 × 1.0 = 16s/card → 19 cards
- 10 min deep-dive, high density → 16 × 0.7 = 11s/card → 55 cards
- 30 min lecture, medium density → 28 × 1.0 = 28s/card → 64 cards
- 1 hr podcast, low density → 45 × 1.5 = 67.5s/card → 53 cards
When a card holds longer than ~15s, plan for a richer card (data block,
multi-step reveal, several sub-points unfolding with staggered
animations) — a static one-liner gets boring past 8s. For long pieces
where many cards exceed 30s, consider chunking the timeline into
sub-compositions (one .html per chapter, mounted with
data-composition-src) so the GSAP timeline per file stays manageable
— see the timeline_track_too_dense HyperFrames lint warning.
content can be a plain string ("Title: annualized 5.69%\nNotes: ...") or any JSON
shape that captures the data. The agent decides the shape per card.
Optional outro. This skill ships no fixed brand outro. If the user wants a closing card, design a neutral one yourself (wordmark + one-line tagline, ~1.5-2s, fade in -> short hold -> fade out), append it to cards[], and extend composition.durationSeconds to its endSec. Otherwise end on the last content card.
7. Decide Render Strategy
Confirm Visual Direction with User (DO THIS FIRST)
Before you start designing cards or deciding bounds, ask the user to
pick the output ratio, the layout, the style, and the card-density
preset. Frames are auto-selected from the chosen layout × style
combination (see "Auto-pick frame" table below). Before sending the
question, precompute two things:
recommendedRatio from the source video's aspect ratio
(metadata.json width / height):
sourceAspect = width / height
sourceAspect ≥ 1.5 (≥ ~3:2 wide) → recommend 16:9
sourceAspect ≤ 0.7 (≤ ~9:13 tall) → recommend 9:16
0.7 < sourceAspect < 1.5 (near-square) → recommend 4:5
Mark the recommended option's label with " (recommended · matches source video X:Y)"
so the user sees why it's recommended.
autoCount from Step 6 (max(5, round(videoSec / (basePace × densityMultiplier)))) so the "auto" option's label can show the
concrete number.
Environment compatibility — pick the best available question channel.
Not every runtime exposes the same structured-question tool. Apply this
order:
- Native clarification tool — use the structured 4-question call below.
- Other native clarification tool (e.g.
ask_question,
request_user_input, IDE-specific prompt) — use that tool with the
same 4 question texts and option lists. Preserve the recommendation
markers and the precomputed values.
- No native tool (Codex CLI, plain text-only runtimes) — ask
directly in normal conversation. Use the plain-text template at the
end of this section. Keep it to one message, 4 numbered questions
(the global cap is 2–5 questions per round; we stay inside it).
Rules that apply to every channel:
- Ask at most 2–5 questions per round. Our 4 here fits.
- Even if missing info doesn't block rendering, ask once to confirm
the parameters that materially affect the final output (ratio,
layout, style, cardCount).
- If the user has already pre-approved defaults ("just use defaults",
"no need to ask", "auto-pick everything"), asked you not to ask, or the
run carries an ongoing autonomous signal ("surprise me" / "decide for me" —
../hyperframes-core/references/brief-contract.md § 1) — skip
the question entirely and use: recommendedRatio, layout="stack"
(safest cross-ratio default), style chosen from transcript tone in
the most neutral group (editorial/data), autoCount. Tell the user
what you picked in one sentence and continue.
Channel A — native AskUserQuestion:
// Precompute before the call:
// recommendedRatio = "16:9" | "9:16" | "4:5"
// autoCount = integer (from Step 6)
AskUserQuestion({
questions: [
{
question: "Output video aspect ratio (canvas):",
header: "Aspect ratio",
multiSelect: false,
// Reorder so the recommended option appears FIRST (per AskUserQuestion convention).
// Append " (recommended · matches source video W×H)" to the recommended option's label.
options: [
{ label: "16:9 (1920×1080) landscape", description: "TV / YouTube / desktop playback. Most natural when the source video is already landscape; widest canvas." },
{ label: "9:16 (1080×1920) portrait", description: "TikTok / Reels / short-form mobile. Most natural for portrait source; native mobile experience." },
{ label: "4:5 (1080×1350) near-portrait", description: "Instagram feed / WeChat Moments. Best when source is near-square or you want to cover both platforms." }
]
},
{
question: "Choose the overall layout: how should the video and cards coexist on the canvas?",
header: "Layout",
multiSelect: false,
options: [
{ label: "side-by-side (split)", description: "Video and card each take half the canvas. Most stable for interview / data side-by-side; clear visual separation." },
{ label: "top-bottom (stack)", description: "Video on top (~52%), card below. Classic combo of speaker face + summary card; works well in portrait too." },
{ label: "picture-in-picture (pip)", description: "Card fills the canvas, video shrinks to a rounded corner window. Use when content is primary and speaker is secondary." },
{ label: "full-screen overlay (overlay)", description: "Video plays full-bleed, card floats as a glass layer on top. Strong cinematic / emotional feel." }
]
},
{
question: "Choose the card visual style (style):",
header: "Style group",
multiSelect: false,
// NOTE: these 3 groups intentionally match the frame auto-pick matrix
// rows below, so picking a group resolves both `style` group AND the
// frame matrix column in one step. Memberships are mutually exclusive.
options: [
{ label: "warm paper (warm-paper)", description: "academic notebook · editorial big-type · whiteboard hand-drawn · xhs social. Best for interview reflections, product launches, lifestyle, emotional stories." },
{ label: "clinical / cold (clinical)", description: "audit magazine · swiss grid · terminal CLI · minimal modern. Best for financial analysis, investigative reports, technical tutorials, serious presentations." },
{ label: "experimental / avant-garde (experimental)", description: "geom color-clash geometry · spotlight dark-background. Best for short-form highlights, product launches, strong emotion, cinematic feel." }
]
},
{
question: "Card count (takeaway pacing): how many cards to cut?",
header: "Card count",
multiSelect: false,
options: [
{ label: "Auto (recommended) · approx N cards", description: "Inferred automatically from video duration and information density (see Step 6 rules). This run estimates approx N cards. Substitute the real N (your autoCount) into the label." },
{ label: "Fewer · approx round(N × 0.6) cards", description: "Sparser cuts, each card holds longer — suits reflective / slow-paced content." },
{ label: "More · approx round(N × 1.5) cards", description: "Tighter cuts, faster rhythm — suits staccato / data-dense / short-form highlight content." }
]
}
]
})
About "Other" — AskUserQuestion automatically adds an "Other" option to the card count question. The user can type a number directly (e.g. "8", "20") as the cardCount target. Parse the input as an integer: if parsing succeeds → use that value (minimum 5 as a floor); if parsing fails → fall back to "auto".
Channel B — plain-text fallback (Codex CLI, runtimes without a
native question tool). Post this as one normal message, then wait for
the reply. Bullet-style 1/2/3/4 keeps the reply parseable:
I need to confirm four visual decisions with you before I start cutting cards:
1) Output aspect ratio (canvas):
A. 16:9 landscape (1920×1080) — TV / YouTube / desktop playback
B. 9:16 portrait (1080×1920) — TikTok / Reels / short-form mobile
C. 4:5 near-portrait (1080×1350) — Instagram feed / works for both platforms
▸ My recommendation: <recommendedRatio> (matches source video W×H = <sourceW>×<sourceH>)
2) Overall layout (how video & card coexist):
A. split side-by-side (50/50)
B. stack top-bottom (video top, card bottom)
C. pip picture-in-picture (card full canvas, video rounded corner window)
D. overlay full-screen glass overlay (video full-bleed, card glass layer)
3) Card style group (maps to frame auto-pick matrix, pick 1 of 3):
A. warm paper (warm-paper) (academic / editorial / whiteboard / xhs)
B. clinical / cold (clinical) (audit / swiss / terminal / minimal)
C. experimental (experimental) (geom / spotlight)
4) Card count (takeaway pacing):
A. Auto (recommended) — approx <autoCount> cards
B. Fewer — approx round(<autoCount> × 0.6) cards
C. More — approx round(<autoCount> × 1.5) cards
D. Give me a specific number (e.g. "8", "20")
Reply format: "1A 2C 3B 4A" or natural language is fine.
If you want all recommended defaults, reply "default" / "auto" / "use all recommendations".
Parsing the plain-text reply:
- Accept loose formats:
"1A 2C 3B 4A", "A C B A", "16:9 / pip / data / auto", full sentences, or default.
- If any answer is ambiguous → re-ask only the ambiguous ones (still
inside the 2–5 cap).
- If the user says "default / auto / use all recommendations" → skip without re-asking.
After the user answers (any channel):
Resolve the output canvas from the ratio answer — these are the
exact storyboard.composition.width / height values to write:
| user choice |
composition.width × height |
storyboard.layout field |
16:9 |
1920 × 1080 |
"landscape" |
9:16 |
1080 × 1920 |
"portrait" |
4:5 |
1080 × 1350 |
"portrait" (schema treats 4:5 as portrait — height > width) |
For 4:5 bounds inside references/layouts/*.html — those files
only document landscape (1920×1080) and portrait (1080×1920). For
4:5 (1080×1350) derive bounds by proportional scaling from
portrait: keep horizontal values, scale vertical values by
1350/1920 ≈ 0.703. Example: overlay portrait card =
{ x: 24, y: 1280, w: 1032, h: 564 } → 4:5 card =
{ x: 24, y: round(1280 × 0.703), w: 1032, h: round(564 × 0.703) }
= { x: 24, y: 900, w: 1032, h: 397 }.
Map the style group to a specific style by looking at the
transcript tone — pick the one that best fits, but stay inside the
user's chosen group. If you're unsure between two specific styles
inside the group, send a second AskUserQuestion with those 2–4
specific style options.
Resolve final cardCount from the density answer:
| user choice |
final cardCount |
| Auto (recommended) |
the autoCount you already computed |
| Fewer |
max(5, round(autoCount × 0.6)) |
| More |
round(autoCount × 1.5) (no upper clamp) |
| Other = "" (integer) |
max(5, parseInt(n)) |
| Other = anything else |
fall back to autoCount |
Auto-pick the video frame from this table (frames don't ask the
user — they follow from layout × style):
| layout |
warm-paper styles (academic / whiteboard / editorial / xhs) |
clinical styles (audit / swiss / terminal / minimal) |
experimental styles (geom / spotlight) |
split |
polaroid |
hairline |
clean |
stack |
polaroid |
hairline |
clean |
pip |
clean (pip pill already has chrome) |
clean |
clean |
overlay |
clean (full-bleed forbids deco frames) |
clean |
clean |
Tell the user what you chose in one sentence — ratio (+ canvas
size), layout, specific style, frame, and final cardCount — then
proceed with the rest of Step 7 (per-card layouts, motion patterns).
Record the five values (ratio / layout / style / frame / cardCount)
in working memory (no schema field needed); you'll reference them
while writing each card's HTML in Step 8 and while reading the
matching references/<dim>/<key>.html for tokens and structure.
If the user picks an answer via "Other" with a free-text style name not
in the 10-style library, treat it as a hint to design a fresh card
visual yourself, but still anchor on the chosen layout's bounds.
Render Strategy Inputs
With ratio / layout / style / cardCount / frame locked from Step 7.0,
the remaining per-card decisions are:
- Source-video fit inside the GSAP target: video element has
object-fit: cover and is clipped to #video-wrap's tween bounds.
If you want NO cropping (e.g. portrait source on landscape canvas
shouldn't get its top/bottom chopped), aim the tween at a rect that
matches the source's aspect ratio and let surrounding canvas show
through (or fill with the card / a backdrop).
card.zone per card: derive from your chosen composition layout
(split → side-panel, stack → lower-third, pip → fullscreen, overlay
→ video-overlay), OR pick a different zone for one-off variants
(fullscreen for hero / quote, whiteboard-area for dense data).
accentIndex per card: each card pulls one of the 5 theme accent
colors. Vary across cards for rhythm; reuse the same index when two
cards belong to the same narrative beat.
- Motion vocabulary: pick 2–3 repeatable patterns from
data-anim kinds (see the table later) and stick to them so the
composition feels coherent.
Pick from these themeId palettes (use them as --accent-N /
--bg / --text CSS variables in your composition <style> block):
| themeId |
accent palette (5 colors) |
board bg |
text |
| classic |
#1971c2 #e03131 #2f9e44 #e8590c #9c36b5 |
#FFF9E3 (paper) |
#1e1e1e |
| noir |
#4cc9f0 #f72585 #4ade80 #fb923c #a78bfa |
#1a1a1a |
#f1f1f1 |
| mint |
#0077b6 #d62828 #2d6a4f #e76f51 #7209b7 |
#e8faf0 |
#1b4332 |
| craft |
#bf5700 #d62728 #6c757d #e9b54a #3d5a80 |
#f6efe1 |
#2d2d2d |
| slate |
#0ea5e9 #ef4444 #22c55e #f97316 #a855f7 |
#1e293b |
#f1f5f9 |
| mono |
#000 #555 #888 #aaa #ccc |
#fff |
#000 |
Available fonts (woff2 in <SKILL_DIR>/assets/fonts/, staged to work dir in Step 9): Caveat (handwriting),
LXGW WenKai TC (Chinese hand-script), Inter (modern sans), Virgil
(geometric hand). Reference via @font-face or font-family directly.
For inspiration on visual patterns, <SKILL_DIR>/references/styles/
ships 10 self-contained reference cards (academic / editorial / minimal
/ spotlight / geom / whiteboard / audit / terminal / swiss / xhs) that
you can copy as starting points — but do not feel constrained to
match any of these. Each card is your own design.
Visual Design Library (/references/)
Beyond the composition-level themeId, the skill ships a richer reference
library at <SKILL_DIR>/references/ covering three orthogonal
visual dimensions you can freely mix:
Style × Layout × VideoFrame
(10) (4) (3)
| dimension |
keys |
what it decides |
| style |
academic editorial minimal spotlight geom whiteboard audit terminal swiss xhs |
the card's visual language — fonts, colors, ornament, layout-within-card |
| layout |
split stack pip overlay |
how the source video and the card share the canvas |
| frame |
clean hairline polaroid |
the decorative chrome around the video element |
Read <SKILL_DIR>/references/DESIGN_INDEX.md
for the full matrix and a loose decision guide (interview / product launch / data analysis /
social clip / technical tutorial / emotional story …). When you decide to use a specific
style / layout / frame, Read the corresponding file:
references/styles/<key>.html — self-contained card fragment with that
style's CSS tokens (colors, fonts, padding, ornament) and a placeholder
takeaway. Copy the .card[data-card-id="ref-<key>"] style block, rename
the data-card-id to your card's id, swap the placeholder content for the
real takeaway, and you're done.
references/layouts/<key>.html — exact videoBounds + cardBounds for
both landscape and portrait, with a copy-paste JSON snippet for
storyboard.json's per-card layout field.
references/frames/<key>.html — decorative HTML to add as a sibling of
#video-wrap, plus placement instructions for the composition CSS.
Pick style × layout × frame per card — you can change all three
between cards as long as the transitions read smoothly. A common rhythm:
open editorial × overlay × clean, switch to audit × split × hairline
for the data card, close on whiteboard × pip × polaroid.
The 10 styles are skill-side design tokens, not composition-level themes —
they don't need to be declared in storyboard.composition; they live
inside each card's HTML. The themeId field can still pick a
composition-level palette (table above) that controls page-body background
and video border chrome.
Layout Compositions (Card + Video)
Two coordinated decisions per card define how it shares the canvas with
the source video:
card.zone (declared in storyboard.json) — one of the 5 schema
values; resolve it into pixel bounds (per the table in Step 6) when
you write the card-host wrapper's inline style in Step 9.
#video-wrap bounds at this card's time window (declared
imperatively in the composition's GSAP timeline) — the agent tweens
#video-wrap to a target rect for each layout transition.
Schema does NOT store per-card video bounds. videoTrack.bounds is
one-time at composition level (defaults to full canvas). Video
"moving" between cards is purely a GSAP animation authored in
index.html. There is no card.layout field — earlier versions of this
doc invented one; the real schema only has card.zone.
4 composition layouts (from references/layouts/) — each is a
recipe pairing a zone with a #video-wrap tween target:
| composition layout |
recommended card.zone |
GSAP target for #video-wrap (landscape 1920×1080) |
GSAP target for #video-wrap (portrait 1080×1920) |
when to use |
split |
side-panel |
{ left: 960, top: 0, width: 960, height: 1080 } |
{ left: 0, top: 960, width: 1080, height: 960 } (bottom half) |
speaker + data side-by-side / 50:50 weight |
stack |
lower-third |
{ left: 14, top: 14, width: 1892, height: 548 } (top 52%) |
{ left: 0, top: 0, width: 1080, height: 844 } (top 44%) |
speaker on top + summary card below |
pip |
fullscreen |
{ left: 1480, top: 760, width: 400, height: 300 } + add .framed class |
{ left: 690, top: 28, width: 360, height: 203 } + add .framed |
content-heavy card + corner pip |
overlay |
video-overlay |
{ left: 0, top: 0, width: 1920, height: 1080 } (full-bleed) |
{ left: 0, top: 0, width: 1080, height: 1920 } |
cinematic / dramatic / glass card on full video |
For 4:5 (1080×1350), scale portrait y/h values by 1350/1920 ≈ 0.703
(see Step 7.0 Channel A / Channel B recommendedRatio resolution
table).
Other zone values for one-off variants (still uses card.zone; no
fake "layout" field):
zone |
resolved bounds |
common use |
fullscreen |
covers whole canvas |
hero card, video tweens to hidden/pip |
whiteboard-area |
inset 40px margin (landscape) or bottom 45% (portrait) |
dense data card, free margins |
lower-third |
bottom 30% band |
talking-head annotation |
side-panel |
right 42% (landscape) or bottom 40% (portrait) |
sidebar / "split" recipe |
video-overlay |
full canvas; expect transparent card root |
glass overlay on full-bleed video |
You can mix recipes per card — choose card.zone based on what suits
the moment, then write the GSAP tween for #video-wrap between cards.
Storyboard Render Contract
storyboard.json is an agent-internal planning artifact — no CLI
command parses it. It exists to keep your timing and content decisions
explicit before you write each card's HTML. Stick to the v3-style
shape below so the same outline drives the composition you assemble in
Step 9.
Required structure (see Step 6 for the full example):
schemaVersion: 3
composition: { fps, width, height, durationSeconds, layout, themeId, seed } — note durationSeconds/fps/themeId/layout live inside composition, NOT at top level
videoTrack: { sourcePath, startSec, endSec, bounds? } — video bounds default to full canvas
subtitles: { enabled, ... }
cards[] — each card has the 6 required fields: id, intent, startSec, endSec, accentIndex, zone, contentHints
Rules:
- Card times stay inside
composition.durationSeconds and should not overlap unless intentional (use data-track-index to control z-order when they do).
- Visual details live in card HTML fragments (Step 8), NOT in
contentHints. contentHints is your own structured prompt for designing the card; the rendered look is the HTML.
- Keep the storyboard shape stable — even though nothing parses it, you read it back while authoring Step 8/9, and consistency keeps card IDs and timing in sync.
- Agent-side decisions like "I picked overlay × geom × clean" do NOT belong in
storyboard.json — keep them in working memory and use them when authoring card HTML + GSAP tweens.
Transparent card backgrounds for cards that share canvas with video.
When the GSAP tween leaves video visible behind/beside the card (overlay
recipe, pip recipe, or any card.zone = 'lower-third' | 'video-overlay'
moment), the card's .root MUST NOT paint a full opaque background —
otherwise it occludes the video. Two patterns:
/* Pattern A: transparent root, page body provides the cream backdrop */
html,
body {
background: var(--bg);
}
.card[data-card-id="card-X"] .root {
background: transparent;
}
/* Pattern B: explicit per-card background ONLY for fullscreen cards */
.card[data-card-id="card-hero"] .root {
background: var(--bg);
}
.card[data-card-id="card-overlay"] .root {
background: transparent;
}
For side-panel-zone cards (split recipe), the card-host is already
only half the canvas, so an opaque card bg is fine — it only covers its
half.
8. Write Each Card's HTML
Create $WORK_DIR/public/cards/{card-id}.html for each card. Each file
contains a single rooted HTML fragment that follows this contract:
Card HTML Contract
<div class="card" data-card-id="{cardId}">
<style>
/* MUST: every rule starts with .card[data-card-id="{cardId}"] */
.card[data-card-id="card-01"] .root {
width: 100%; height: 100%;
display: flex; ...;
font-family: 'Caveat', 'LXGW WenKai TC', serif;
color: var(--text);
background: var(--bg);
}
.card[data-card-id="card-01"] .title { font-size: 84px; ... }
</style>
<div class="root">
<h1
id="card-01-title"
data-anim="kinetic-chars"
data-anim-at="0.3"
data-anim-duration="0.5"
data-anim-stagger="0.04"
data-anim-pattern="pop"
>
<span class="char">S</span>
<span class="char">u</span>
</h1>
<div
id="card-01-line"
data-anim="grow-x"
data-anim-at="0.65"
data-anim-duration="0.5"
data-anim-target-w="420"
style="width:0;height:8px;background:var(--accent-0);border-radius:4px;"
></div>
</div>
</div>
Hard rules (hyperframes lint will reject violations):
- Single root
<div class="card" data-card-id="{cardId}">
- Inline
<style> rules MUST be prefixed with the scope selector above
- No
<script> tags
- No external URLs in
src= / href= (no CDN, no remote fonts)
- No inline event handlers (
onclick= etc.)
- All assets via relative paths into the same
public/ directory
- Colors via
var(--accent-N) etc. for portability across themes
Animations are declared, not coded. Use data-anim-* attributes
only; never write <script> to animate. You compile every data-anim-*
declaration into the single master GSAP timeline in Step 9.
Card Sizing — Mobile-First in Portrait
The 10 references/styles/*.html are sized for a 1920×1080 landscape
preview. When storyboard.layout = "portrait" (1080×1920, the dominant
case for social / mobile), scale every visual size up — phones hold
the screen close, and the same pixel count reads smaller than on a
landscape TV-style canvas.
| token | landscape baseline | portrait target | scale |
| ------------------------- | --------
…(truncated)
1---
2name: talking-head-recut
3description: Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.
4metadata:
5 source: https://skillmd.com/skills/heygen-com/talking-head-recut
6---
7
8> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update talking-head-recut`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
9
10# Talking Head Recut
11
12Talking Head Recut takes a local video that **plays in full** and layers a sequence of
13timed, designed **graphic cards** onto it — titles, lower-thirds, data callouts,
14quotes, side panels, picture-in-picture — synced to what's being said. The agent
15designs the cards (timing + content) and **writes each card's HTML directly in the
16conversation**, then assembles a single composition HTML and renders it to MP4 via
17`hyperframes`. There is no fixed archetype list and no prescribed card structure —
18the overlays emerge from what the transcript actually says.
19
20> **The front door is `/hyperframes`.** This skill packages an **existing talking-head clip** with **designed graphic cards** (titles, lower-thirds, data callouts, quotes, side panels, PiP) — not plain captions (the spoken words as text). **The clip plays untouched.** Any other intent — plain subtitles, a standalone graphic, a from-scratch video — or any uncertainty → read `/hyperframes` first: the intent layer owns every route decision.
21
22> **Graphic-packaging sibling of `embedded-captions`.** Captions add the _spoken words_
23> as a readable subtitle; this adds _designed graphics_ on top of the playing video.
24> Plain subtitles → `embedded-captions`. Build a video from scratch → the creation
25> workflows (`product-launch-video` / `faceless-explainer` / …).
26
27Routed through `/hyperframes`, the intent layer confirms only the input (which clip) and **announces** the render-strategy questions as deferred asks — aspect, layout, style group, and card count stay at Step 7, where the probed footage and transcript ground the recommendations; the layer's run-shape questions don't apply. A `BRIEF.md`, when present, carries the confirmed input and any user notes — read it first.
28
29Inspectable intermediate files in the work directory:
30
31- `metadata.json` — duration / width / height / fps
32- `audio.mp3` — extracted audio
33- `transcript.json` — a flat **word array** `[{ text, start, end }, …]` (Whisper; no `segments`, no `words` wrapper)
34- `storyboard.json` — lightweight card outline (the agent's plan)
35- `public/cards/card-XX.html` — one HTML fragment per card
36- `public/index.html` — final assembled composition
37- `output.mp4` — rendered video
38
39## CLI Resolution
40
41```bash
42# hyperframes — transcription (local Whisper) + rendering the assembled HTML to MP4
43npx hyperframes --help
44```
45
46This skill runs entirely on the **hyperframes** CLI plus system `ffmpeg` / `ffprobe`.
47Transcription is local **Whisper** via `hyperframes transcribe` — no third-party
48service, API key, or rate-limited proxy.
49
50## Workflow
51
52### 1. Check Environment
53
54```bash
55npx hyperframes doctor # ffmpeg, headless browser, render deps
56# confirm bundled assets:
57ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"
58```
59
60Required:
61
62- `ffmpeg` / `ffprobe` (system)
63- `<SKILL_DIR>/assets/fonts/*.woff2`, `<SKILL_DIR>/assets/vendor/gsap.min.js` (bundled inside this skill, staged to work dir in Step 9)
64
65Transcription needs no key — `hyperframes transcribe` runs Whisper locally (Step 4).
66
67Strongly recommended on macOS for `hyperframes render`:
68
69```bash
70export PRODUCER_BROWSER_GPU_MODE=hardware
71```
72
73### 2. Create a Work Directory
74
75All artifacts live under `videos/<project-name>/` — the same convention as the other
76video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video`). Keep
77the cwd at the workspace root; everything below writes under this one subdirectory.
78
79```bash
80VIDEO_PATH="/absolute/path/input.mp4"
81WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
82mkdir -p "$WORK_DIR"
83```
84
85### 3. Extract Audio and Metadata
86
87```bash
88# metadata — duration / width / height / fps
89ffprobe -v error -select_streams v:0 \
90 -show_entries stream=width,height,r_frame_rate \
91 -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
92# audio
93ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"
94```
95
96Outputs: `metadata.json` (read `width`/`height`/`duration`; fps = the `r_frame_rate`
97fraction evaluated, e.g. `30000/1001 → 29.97`) + `audio.mp3`.
98
99### 4. Transcribe
100
101```bash
102npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en
103```
104
105Local **Whisper** — no API key, no proxy, no rate limit. Writes a word-level
106`transcript.json` into the work dir (word `text` + `start` / `end` timestamps).
107Read it for the word / sentence timings that drive card timing in Step 6; group
108words into sentences yourself at punctuation / pauses if you need segment-level
109chunks.
110
111**Clamp to media duration.** Whisper can return the final word's `end` a hair past the
112actual clip length — clamp every card `endSec` and `composition.durationSeconds` to the
113`metadata.json` duration, or the render will show a black tail past the video.
114
115### 5. Correct Transcript
116
117`transcript.json` is a **flat array of word objects** — `[{ "text": "...", "start": s, "end": s }, …]` (no `segments` array, no `words` wrapper; the per-word key is **`text`**). Read it and fix obvious ASR errors:
118
119- Homophones, product names, technical terms, punctuation
120- Edit a word's `text` in place; **preserve its `start` / `end`** timestamps
121- There is no pre-grouped `segments` array — **group words into sentences yourself** (split at terminal punctuation / pauses) when you need segment-level chunks for card timing
122
123### 6. Draft a Lightweight Storyboard (in chat)
124
125**No CLI involved.** Read `transcript.json` + `metadata.json` and design
126cards directly. `storyboard.json` is an agent-internal planning artifact
127— no CLI command consumes it; it exists so you can think clearly
128about timing and content before writing each card's HTML. Keep the
129shape consistent with the example below so the same outline can drive
130the composition you author in Step 9:
131
132```json
133{
134 "schemaVersion": 3,
135 "composition": {
136 "fps": 30,
137 "width": 1080,
138 "height": 1920,
139 "durationSeconds": 121.2,
140 "layout": "portrait",
141 "themeId": "noir",
142 "seed": 42
143 },
144 "videoTrack": {
145 "sourcePath": "input-video.mp4",
146 "startSec": 0,
147 "endSec": 121.2,
148 "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
149 },
150 "subtitles": { "enabled": false },
151 "cards": [
152 {
153 "id": "card-01",
154 "intent": "Hook with the speaker's anxious midnight question",
155 "startSec": 0.5,
156 "endSec": 13.0,
157 "accentIndex": 0,
158 "zone": "fullscreen",
159 "contentHints": {
160 "kicker": "AN HONEST QUESTION",
161 "title": "The soul-searching question at 11 PM",
162 "detail": "Client's 60-second voice message: 'If the RMB appreciates, does that mean my USD policy is a terrible loss?'"
163 }
164 }
165 ]
166}
167```
168
169**Required Card fields:**
170
171| field | type | purpose |
172| ----------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
173| `id` | string | stable id used in card HTML & GSAP selectors |
174| `intent` | string | natural-language description; fed to card synthesis |
175| `startSec` / `endSec` | number | times in seconds (endSec > startSec) |
176| `accentIndex` | 0 \| 1 \| 2 \| 3 \| 4 | which of the 5 theme accent colors this card pulls |
177| `zone` | enum (see below) | where on the canvas the card lives |
178| `contentHints` | object | free-form bag; agent puts kicker/title/detail/data/quote here |
179| `archetype` (optional) | string | free-form label you may attach to remember a card's pattern; absent = free-form, which is the default |
180| `transition` (optional) | enum: `cut` \| `fade` \| `slide` \| `wipe` | declarative card-to-card transition |
181
182**Five `zone` values:**
183
184| zone | resolved bounds | when to use |
185| ----------------- | ---------------------------------------------- | --------------------------------------- |
186| `fullscreen` | covers whole canvas | hero moments, big numbers, mantras |
187| `whiteboard-area` | inset 40px margin (or 45% of portrait height) | dense data / annotated content |
188| `lower-third` | bottom 30% band | annotation over visible video |
189| `side-panel` | right 42% (landscape) or bottom 40% (portrait) | data side, video other side |
190| `video-overlay` | full canvas, expects mostly-transparent card | annotation overlays on full-bleed video |
191
192When you assemble the composition in Step 9, resolve each card's `zone`
193into pixel bounds on the card-host wrapper following the table above.
194Video bounds are set **once** at composition level (`videoTrack.bounds`);
195to make video appear to "move between cards", author GSAP tweens against
196`#video-wrap` in the composition's `<script>` (see Step 9).
197
198**No prescribed card roles, no prescribed narrative arc.** Cards emerge
199from what the video actually says — could be all quotes or all data,
200could open with a number or with a story. Let the transcript drive the
201rhythm.
202
203**How many takeaways? — auto-infer from duration + density.** No fixed
204upper limit. Pick a **base pace** from the video duration, then adjust
205by **information density**. Only **floor is fixed: minimum 5 cards** so
206even short videos have rhythm.
207
208**Step 1 — base pace by duration** (the natural sec/card for medium density):
209
210| video duration | base pace (sec per card) | rationale |
211| ------------------ | ------------------------ | ------------------------------------------- |
212| < 60s (short reel) | **6–8s** | viewers expect fast cuts in short-form |
213| 60s – 3 min | **8–12s** | normal social pace |
214| 3 – 10 min | **12–20s** | give breathing room; each card carries more |
215| 10 – 30 min | **20–35s** | long-form lecture / interview rhythm |
216| > 30 min | **30–60s** | episodic, near-chapter feel |
217
218**Step 2 — density multiplier** (multiplies the base pace):
219
220| signal in the transcript | multiplier | effect |
221| --------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------ |
222| **High density** — many numbers, distinct claims, staccato pacing, list-like enumeration, every 1–2 sentences is a new idea | **× 0.7** | cuts faster, more cards |
223| **Medium density** — mixed flow with both data and narrative | **× 1.0** | base pace |
224| **Low density** — one extended story, repeated reframing, slow reflective pacing, single argument unfolding | **× 1.5** | cuts slower, fewer cards |
225
226**Step 3 — compute:**
227
228```
229secPerCard = basePace × densityMultiplier
230cardCount = max(5, round(videoDurationSec / secPerCard))
231```
232
233Examples (notice — **no upper clamp**; long videos naturally produce more cards):
234
235- **30s reel, single punchline (low density)** → 7 × 1.5 = 10.5s/card → round(30/10.5)=3 → floor to **5** cards
236- **60s reflective monologue (low density)** → 10 × 1.5 = 15s/card → **4** → floor to **5** cards
237- **121s talking-head with rich data (high density)** → 10 × 0.7 = 7s/card → **17** cards
238- **5 min interview, mixed density** → 16 × 1.0 = 16s/card → **19** cards
239- **10 min deep-dive, high density** → 16 × 0.7 = 11s/card → **55** cards
240- **30 min lecture, medium density** → 28 × 1.0 = 28s/card → **64** cards
241- **1 hr podcast, low density** → 45 × 1.5 = 67.5s/card → **53** cards
242
243When a card holds longer than ~15s, plan for a richer card (data block,
244multi-step reveal, several sub-points unfolding with staggered
245animations) — a static one-liner gets boring past 8s. For long pieces
246where many cards exceed 30s, consider **chunking the timeline into
247sub-compositions** (one .html per chapter, mounted with
248`data-composition-src`) so the GSAP timeline per file stays manageable
249— see the `timeline_track_too_dense` HyperFrames lint warning.
250
251`content` can be a plain string ("Title: annualized 5.69%\nNotes: ...") or any JSON
252shape that captures the data. The agent decides the shape per card.
253
254**Optional outro.** This skill ships **no fixed brand outro**. If the user wants a closing card, design a neutral one yourself (wordmark + one-line tagline, ~1.5-2s, fade in -> short hold -> fade out), append it to `cards[]`, and extend `composition.durationSeconds` to its `endSec`. Otherwise end on the last content card.
255
256### 7. Decide Render Strategy
257
258#### Confirm Visual Direction with User (DO THIS FIRST)
259
260Before you start designing cards or deciding bounds, **ask the user to
261pick the output ratio, the layout, the style, and the card-density
262preset**. Frames are auto-selected from the chosen layout × style
263combination (see "Auto-pick frame" table below). Before sending the
264question, **precompute two things**:
265
2661. **`recommendedRatio`** from the source video's aspect ratio
267 (`metadata.json` width / height):
268 - `sourceAspect = width / height`
269 - `sourceAspect ≥ 1.5` (≥ ~3:2 wide) → recommend **`16:9`**
270 - `sourceAspect ≤ 0.7` (≤ ~9:13 tall) → recommend **`9:16`**
271 - `0.7 < sourceAspect < 1.5` (near-square) → recommend **`4:5`**
272
273 Mark the recommended option's label with " (recommended · matches source video X:Y)"
274 so the user sees why it's recommended.
275
2762. **`autoCount`** from Step 6 (`max(5, round(videoSec / (basePace ×
277densityMultiplier)))`) so the "auto" option's label can show the
278 concrete number.
279
280**Environment compatibility — pick the best available question channel.**
281Not every runtime exposes the same structured-question tool. Apply this
282order:
283
2841. **Native clarification tool** — use the structured 4-question call below.
2852. **Other native clarification tool** (e.g. `ask_question`,
286 `request_user_input`, IDE-specific prompt) — use that tool with the
287 same 4 question texts and option lists. Preserve the recommendation
288 markers and the precomputed values.
2893. **No native tool** (Codex CLI, plain text-only runtimes) — **ask
290 directly in normal conversation**. Use the plain-text template at the
291 end of this section. Keep it to **one message, 4 numbered questions**
292 (the global cap is 2–5 questions per round; we stay inside it).
293
294Rules that apply to every channel:
295
296- Ask **at most 2–5 questions per round**. Our 4 here fits.
297- Even if missing info doesn't block rendering, **ask once to confirm
298 the parameters that materially affect the final output** (ratio,
299 layout, style, cardCount).
300- If the user has already pre-approved defaults ("just use defaults",
301 "no need to ask", "auto-pick everything"), asked you not to ask, or the
302 run carries an ongoing autonomous signal ("surprise me" / "decide for me" —
303 `../hyperframes-core/references/brief-contract.md` § 1) — **skip
304 the question entirely** and use: `recommendedRatio`, `layout="stack"`
305 (safest cross-ratio default), `style` chosen from transcript tone in
306 the most neutral group (editorial/data), `autoCount`. Tell the user
307 what you picked in one sentence and continue.
308
309**Channel A — native `AskUserQuestion`:**
310
311```
312// Precompute before the call:
313// recommendedRatio = "16:9" | "9:16" | "4:5"
314// autoCount = integer (from Step 6)
315
316AskUserQuestion({
317 questions: [
318 {
319 question: "Output video aspect ratio (canvas):",
320 header: "Aspect ratio",
321 multiSelect: false,
322 // Reorder so the recommended option appears FIRST (per AskUserQuestion convention).
323 // Append " (recommended · matches source video W×H)" to the recommended option's label.
324 options: [
325 { label: "16:9 (1920×1080) landscape", description: "TV / YouTube / desktop playback. Most natural when the source video is already landscape; widest canvas." },
326 { label: "9:16 (1080×1920) portrait", description: "TikTok / Reels / short-form mobile. Most natural for portrait source; native mobile experience." },
327 { label: "4:5 (1080×1350) near-portrait", description: "Instagram feed / WeChat Moments. Best when source is near-square or you want to cover both platforms." }
328 ]
329 },
330 {
331 question: "Choose the overall layout: how should the video and cards coexist on the canvas?",
332 header: "Layout",
333 multiSelect: false,
334 options: [
335 { label: "side-by-side (split)", description: "Video and card each take half the canvas. Most stable for interview / data side-by-side; clear visual separation." },
336 { label: "top-bottom (stack)", description: "Video on top (~52%), card below. Classic combo of speaker face + summary card; works well in portrait too." },
337 { label: "picture-in-picture (pip)", description: "Card fills the canvas, video shrinks to a rounded corner window. Use when content is primary and speaker is secondary." },
338 { label: "full-screen overlay (overlay)", description: "Video plays full-bleed, card floats as a glass layer on top. Strong cinematic / emotional feel." }
339 ]
340 },
341 {
342 question: "Choose the card visual style (style):",
343 header: "Style group",
344 multiSelect: false,
345 // NOTE: these 3 groups intentionally match the frame auto-pick matrix
346 // rows below, so picking a group resolves both `style` group AND the
347 // frame matrix column in one step. Memberships are mutually exclusive.
348 options: [
349 { label: "warm paper (warm-paper)", description: "academic notebook · editorial big-type · whiteboard hand-drawn · xhs social. Best for interview reflections, product launches, lifestyle, emotional stories." },
350 { label: "clinical / cold (clinical)", description: "audit magazine · swiss grid · terminal CLI · minimal modern. Best for financial analysis, investigative reports, technical tutorials, serious presentations." },
351 { label: "experimental / avant-garde (experimental)", description: "geom color-clash geometry · spotlight dark-background. Best for short-form highlights, product launches, strong emotion, cinematic feel." }
352 ]
353 },
354 {
355 question: "Card count (takeaway pacing): how many cards to cut?",
356 header: "Card count",
357 multiSelect: false,
358 options: [
359 { label: "Auto (recommended) · approx N cards", description: "Inferred automatically from video duration and information density (see Step 6 rules). This run estimates approx N cards. Substitute the real N (your autoCount) into the label." },
360 { label: "Fewer · approx round(N × 0.6) cards", description: "Sparser cuts, each card holds longer — suits reflective / slow-paced content." },
361 { label: "More · approx round(N × 1.5) cards", description: "Tighter cuts, faster rhythm — suits staccato / data-dense / short-form highlight content." }
362 ]
363 }
364 ]
365})
366```
367
368**About "Other"** — `AskUserQuestion` automatically adds an "Other" option to the card count question. The user can type a number directly (e.g. "8", "20") as the cardCount target. Parse the input as an integer: if parsing succeeds → use that value (minimum 5 as a floor); if parsing fails → fall back to "auto".
369
370**Channel B — plain-text fallback** (Codex CLI, runtimes without a
371native question tool). Post this as one normal message, then wait for
372the reply. Bullet-style 1/2/3/4 keeps the reply parseable:
373
374```
375I need to confirm four visual decisions with you before I start cutting cards:
376
3771) Output aspect ratio (canvas):
378 A. 16:9 landscape (1920×1080) — TV / YouTube / desktop playback
379 B. 9:16 portrait (1080×1920) — TikTok / Reels / short-form mobile
380 C. 4:5 near-portrait (1080×1350) — Instagram feed / works for both platforms
381 ▸ My recommendation: <recommendedRatio> (matches source video W×H = <sourceW>×<sourceH>)
382
3832) Overall layout (how video & card coexist):
384 A. split side-by-side (50/50)
385 B. stack top-bottom (video top, card bottom)
386 C. pip picture-in-picture (card full canvas, video rounded corner window)
387 D. overlay full-screen glass overlay (video full-bleed, card glass layer)
388
3893) Card style group (maps to frame auto-pick matrix, pick 1 of 3):
390 A. warm paper (warm-paper) (academic / editorial / whiteboard / xhs)
391 B. clinical / cold (clinical) (audit / swiss / terminal / minimal)
392 C. experimental (experimental) (geom / spotlight)
393
3944) Card count (takeaway pacing):
395 A. Auto (recommended) — approx <autoCount> cards
396 B. Fewer — approx round(<autoCount> × 0.6) cards
397 C. More — approx round(<autoCount> × 1.5) cards
398 D. Give me a specific number (e.g. "8", "20")
399
400Reply format: "1A 2C 3B 4A" or natural language is fine.
401If you want all recommended defaults, reply "default" / "auto" / "use all recommendations".
402```
403
404Parsing the plain-text reply:
405
406- Accept loose formats: `"1A 2C 3B 4A"`, `"A C B A"`, `"16:9 / pip /
407data / auto"`, full sentences, or `default`.
408- If any answer is ambiguous → re-ask only the ambiguous ones (still
409 inside the 2–5 cap).
410- If the user says "default / auto / use all recommendations" → skip without re-asking.
411
412After the user answers (any channel):
413
4141. **Resolve the output canvas** from the ratio answer — these are the
415 exact `storyboard.composition.width / height` values to write:
416
417 | user choice | composition.width × height | storyboard.layout field |
418 | ----------- | -------------------------- | ------------------------------------------------------------- |
419 | `16:9` | **1920 × 1080** | `"landscape"` |
420 | `9:16` | **1080 × 1920** | `"portrait"` |
421 | `4:5` | **1080 × 1350** | `"portrait"` (schema treats 4:5 as portrait — height > width) |
422
423 For **4:5 bounds inside `references/layouts/*.html`** — those files
424 only document landscape (1920×1080) and portrait (1080×1920). For
425 4:5 (1080×1350) derive bounds by **proportional scaling from
426 portrait**: keep horizontal values, scale vertical values by
427 `1350/1920 ≈ 0.703`. Example: `overlay` portrait card =
428 `{ x: 24, y: 1280, w: 1032, h: 564 }` → 4:5 card =
429 `{ x: 24, y: round(1280 × 0.703), w: 1032, h: round(564 × 0.703) }`
430 = `{ x: 24, y: 900, w: 1032, h: 397 }`.
431
4322. **Map the style group to a specific style** by looking at the
433 transcript tone — pick the one that best fits, but stay inside the
434 user's chosen group. If you're unsure between two specific styles
435 inside the group, send a second `AskUserQuestion` with those 2–4
436 specific style options.
437
4383. **Resolve final cardCount** from the density answer:
439
440 | user choice | final cardCount |
441 | ----------------------- | ----------------------------------------- |
442 | Auto (recommended) | the `autoCount` you already computed |
443 | Fewer | `max(5, round(autoCount × 0.6))` |
444 | More | `round(autoCount × 1.5)` (no upper clamp) |
445 | Other = "<n>" (integer) | `max(5, parseInt(n))` |
446 | Other = anything else | fall back to `autoCount` |
447
4484. **Auto-pick the video frame** from this table (frames don't ask the
449 user — they follow from layout × style):
450
451 | layout | warm-paper styles (academic / whiteboard / editorial / xhs) | clinical styles (audit / swiss / terminal / minimal) | experimental styles (geom / spotlight) |
452 | --------- | ----------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------- |
453 | `split` | `polaroid` | `hairline` | `clean` |
454 | `stack` | `polaroid` | `hairline` | `clean` |
455 | `pip` | `clean` (pip pill already has chrome) | `clean` | `clean` |
456 | `overlay` | `clean` (full-bleed forbids deco frames) | `clean` | `clean` |
457
4585. **Tell the user what you chose** in one sentence — ratio (+ canvas
459 size), layout, specific style, frame, and final cardCount — then
460 proceed with the rest of Step 7 (per-card layouts, motion patterns).
4616. Record the five values (ratio / layout / style / frame / cardCount)
462 in working memory (no schema field needed); you'll reference them
463 while writing each card's HTML in Step 8 and while reading the
464 matching `references/<dim>/<key>.html` for tokens and structure.
465
466If the user picks an answer via "Other" with a free-text style name not
467in the 10-style library, treat it as a hint to design a fresh card
468visual yourself, but still anchor on the chosen layout's bounds.
469
470#### Render Strategy Inputs
471
472With ratio / layout / style / cardCount / frame locked from Step 7.0,
473the remaining per-card decisions are:
474
475- **Source-video fit inside the GSAP target**: video element has
476 `object-fit: cover` and is clipped to `#video-wrap`'s tween bounds.
477 If you want NO cropping (e.g. portrait source on landscape canvas
478 shouldn't get its top/bottom chopped), aim the tween at a rect that
479 matches the source's aspect ratio and let surrounding canvas show
480 through (or fill with the card / a backdrop).
481- **`card.zone` per card**: derive from your chosen composition layout
482 (split → side-panel, stack → lower-third, pip → fullscreen, overlay
483 → video-overlay), OR pick a different zone for one-off variants
484 (fullscreen for hero / quote, whiteboard-area for dense data).
485- **`accentIndex` per card**: each card pulls one of the 5 theme accent
486 colors. Vary across cards for rhythm; reuse the same index when two
487 cards belong to the same narrative beat.
488- **Motion vocabulary**: pick 2–3 repeatable patterns from
489 `data-anim` kinds (see the table later) and stick to them so the
490 composition feels coherent.
491
492Pick from these `themeId` palettes (use them as `--accent-N` /
493`--bg` / `--text` CSS variables in your composition `<style>` block):
494
495| themeId | accent palette (5 colors) | board bg | text |
496| ------- | ----------------------------------------- | ----------------- | --------- |
497| classic | `#1971c2 #e03131 #2f9e44 #e8590c #9c36b5` | `#FFF9E3` (paper) | `#1e1e1e` |
498| noir | `#4cc9f0 #f72585 #4ade80 #fb923c #a78bfa` | `#1a1a1a` | `#f1f1f1` |
499| mint | `#0077b6 #d62828 #2d6a4f #e76f51 #7209b7` | `#e8faf0` | `#1b4332` |
500| craft | `#bf5700 #d62728 #6c757d #e9b54a #3d5a80` | `#f6efe1` | `#2d2d2d` |
501| slate | `#0ea5e9 #ef4444 #22c55e #f97316 #a855f7` | `#1e293b` | `#f1f5f9` |
502| mono | `#000 #555 #888 #aaa #ccc` | `#fff` | `#000` |
503
504Available fonts (woff2 in `<SKILL_DIR>/assets/fonts/`, staged to work dir in Step 9): `Caveat` (handwriting),
505`LXGW WenKai TC` (Chinese hand-script), `Inter` (modern sans), `Virgil`
506(geometric hand). Reference via `@font-face` or `font-family` directly.
507
508For inspiration on visual patterns, `<SKILL_DIR>/references/styles/`
509ships 10 self-contained reference cards (academic / editorial / minimal
510/ spotlight / geom / whiteboard / audit / terminal / swiss / xhs) that
511you can copy as starting points — but **do not feel constrained to
512match any of these**. Each card is your own design.
513
514#### Visual Design Library (<SKILL_DIR>/references/)
515
516Beyond the composition-level `themeId`, the skill ships a richer **reference
517library** at `<SKILL_DIR>/references/` covering three **orthogonal**
518visual dimensions you can freely mix:
519
520```
521Style × Layout × VideoFrame
522 (10) (4) (3)
523```
524
525| dimension | keys | what it decides |
526| ---------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
527| **style** | `academic` `editorial` `minimal` `spotlight` `geom` `whiteboard` `audit` `terminal` `swiss` `xhs` | the card's visual language — fonts, colors, ornament, layout-within-card |
528| **layout** | `split` `stack` `pip` `overlay` | how the source video and the card share the canvas |
529| **frame** | `clean` `hairline` `polaroid` | the decorative chrome around the video element |
530
531Read `<SKILL_DIR>/references/DESIGN_INDEX.md`
532for the full matrix and a loose decision guide (interview / product launch / data analysis /
533social clip / technical tutorial / emotional story …). When you decide to use a specific
534style / layout / frame, Read the corresponding file:
535
536- `references/styles/<key>.html` — self-contained card fragment with that
537 style's CSS tokens (colors, fonts, padding, ornament) and a placeholder
538 takeaway. Copy the `.card[data-card-id="ref-<key>"]` style block, rename
539 the data-card-id to your card's id, swap the placeholder content for the
540 real takeaway, and you're done.
541- `references/layouts/<key>.html` — exact `videoBounds` + `cardBounds` for
542 both landscape and portrait, with a copy-paste JSON snippet for
543 `storyboard.json`'s per-card `layout` field.
544- `references/frames/<key>.html` — decorative HTML to add as a sibling of
545 `#video-wrap`, plus placement instructions for the composition CSS.
546
547Pick `style × layout × frame` **per card** — you can change all three
548between cards as long as the transitions read smoothly. A common rhythm:
549open `editorial × overlay × clean`, switch to `audit × split × hairline`
550for the data card, close on `whiteboard × pip × polaroid`.
551
552The 10 styles are skill-side design tokens, **not composition-level themes** —
553they don't need to be declared in `storyboard.composition`; they live
554inside each card's HTML. The `themeId` field can still pick a
555composition-level palette (table above) that controls page-body background
556and video border chrome.
557
558#### Layout Compositions (Card + Video)
559
560Two coordinated decisions per card define how it shares the canvas with
561the source video:
562
563- **`card.zone`** (declared in `storyboard.json`) — one of the 5 schema
564 values; resolve it into pixel bounds (per the table in Step 6) when
565 you write the card-host wrapper's inline `style` in Step 9.
566- **`#video-wrap` bounds at this card's time window** (declared
567 imperatively in the composition's GSAP timeline) — the agent tweens
568 `#video-wrap` to a target rect for each layout transition.
569
570Schema does NOT store per-card video bounds. `videoTrack.bounds` is
571**one-time** at composition level (defaults to full canvas). Video
572"moving" between cards is purely a GSAP animation authored in
573`index.html`. There is no `card.layout` field — earlier versions of this
574doc invented one; the real schema only has `card.zone`.
575
576**4 composition layouts** (from `references/layouts/`) — each is a
577recipe pairing a `zone` with a `#video-wrap` tween target:
578
579| composition layout | recommended `card.zone` | GSAP target for `#video-wrap` (landscape 1920×1080) | GSAP target for `#video-wrap` (portrait 1080×1920) | when to use |
580| ------------------ | ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
581| `split` | `side-panel` | `{ left: 960, top: 0, width: 960, height: 1080 }` | `{ left: 0, top: 960, width: 1080, height: 960 }` (bottom half) | speaker + data side-by-side / 50:50 weight |
582| `stack` | `lower-third` | `{ left: 14, top: 14, width: 1892, height: 548 }` (top 52%) | `{ left: 0, top: 0, width: 1080, height: 844 }` (top 44%) | speaker on top + summary card below |
583| `pip` | `fullscreen` | `{ left: 1480, top: 760, width: 400, height: 300 }` + add `.framed` class | `{ left: 690, top: 28, width: 360, height: 203 }` + add `.framed` | content-heavy card + corner pip |
584| `overlay` | `video-overlay` | `{ left: 0, top: 0, width: 1920, height: 1080 }` (full-bleed) | `{ left: 0, top: 0, width: 1080, height: 1920 }` | cinematic / dramatic / glass card on full video |
585
586For 4:5 (1080×1350), scale portrait y/h values by `1350/1920 ≈ 0.703`
587(see Step 7.0 Channel A / Channel B `recommendedRatio` resolution
588table).
589
590**Other zone values for one-off variants** (still uses `card.zone`; no
591fake "layout" field):
592
593| `zone` | resolved bounds | common use |
594| ----------------- | ------------------------------------------------------ | ------------------------------------- |
595| `fullscreen` | covers whole canvas | hero card, video tweens to hidden/pip |
596| `whiteboard-area` | inset 40px margin (landscape) or bottom 45% (portrait) | dense data card, free margins |
597| `lower-third` | bottom 30% band | talking-head annotation |
598| `side-panel` | right 42% (landscape) or bottom 40% (portrait) | sidebar / "split" recipe |
599| `video-overlay` | full canvas; expect transparent card root | glass overlay on full-bleed video |
600
601You can mix recipes per card — choose `card.zone` based on what suits
602the moment, then write the GSAP tween for `#video-wrap` between cards.
603
604#### Storyboard Render Contract
605
606`storyboard.json` is an agent-internal planning artifact — no CLI
607command parses it. It exists to keep your timing and content decisions
608explicit before you write each card's HTML. Stick to the v3-style
609shape below so the same outline drives the composition you assemble in
610Step 9.
611
612Required structure (see Step 6 for the full example):
613
614- `schemaVersion: 3`
615- `composition: { fps, width, height, durationSeconds, layout, themeId, seed }` — note `durationSeconds`/`fps`/`themeId`/`layout` live **inside** `composition`, NOT at top level
616- `videoTrack: { sourcePath, startSec, endSec, bounds? }` — video bounds default to full canvas
617- `subtitles: { enabled, ... }`
618- `cards[]` — each card has the 6 required fields: `id`, `intent`, `startSec`, `endSec`, `accentIndex`, `zone`, `contentHints`
619
620Rules:
621
622- Card times stay inside `composition.durationSeconds` and should not overlap unless intentional (use `data-track-index` to control z-order when they do).
623- Visual details live in card HTML fragments (Step 8), NOT in `contentHints`. `contentHints` is your own structured prompt for designing the card; the rendered look is the HTML.
624- Keep the storyboard shape stable — even though nothing parses it, you read it back while authoring Step 8/9, and consistency keeps card IDs and timing in sync.
625- Agent-side decisions like "I picked overlay × geom × clean" do NOT belong in `storyboard.json` — keep them in working memory and use them when authoring card HTML + GSAP tweens.
626
627**Transparent card backgrounds for cards that share canvas with video.**
628When the GSAP tween leaves video visible behind/beside the card (overlay
629recipe, pip recipe, or any `card.zone = 'lower-third' | 'video-overlay'`
630moment), the card's `.root` MUST NOT paint a full opaque background —
631otherwise it occludes the video. Two patterns:
632
633```css
634/* Pattern A: transparent root, page body provides the cream backdrop */
635html,
636body {
637 background: var(--bg);
638}
639.card[data-card-id="card-X"] .root {
640 background: transparent;
641}
642
643/* Pattern B: explicit per-card background ONLY for fullscreen cards */
644.card[data-card-id="card-hero"] .root {
645 background: var(--bg);
646}
647.card[data-card-id="card-overlay"] .root {
648 background: transparent;
649}
650```
651
652For `side-panel`-zone cards (split recipe), the card-host is already
653only half the canvas, so an opaque card bg is fine — it only covers its
654half.
655
656### 8. Write Each Card's HTML
657
658Create `$WORK_DIR/public/cards/{card-id}.html` for each card. Each file
659contains a single rooted HTML fragment that follows this contract:
660
661#### Card HTML Contract
662
663```html
664<div class="card" data-card-id="{cardId}">
665 <style>
666 /* MUST: every rule starts with .card[data-card-id="{cardId}"] */
667 .card[data-card-id="card-01"] .root {
668 width: 100%; height: 100%;
669 display: flex; ...;
670 font-family: 'Caveat', 'LXGW WenKai TC', serif;
671 color: var(--text);
672 background: var(--bg);
673 }
674 .card[data-card-id="card-01"] .title { font-size: 84px; ... }
675 </style>
676
677 <div class="root">
678 <h1
679 id="card-01-title"
680 data-anim="kinetic-chars"
681 data-anim-at="0.3"
682 data-anim-duration="0.5"
683 data-anim-stagger="0.04"
684 data-anim-pattern="pop"
685 >
686 <span class="char">S</span>
687 <span class="char">u</span>
688 </h1>
689 <div
690 id="card-01-line"
691 data-anim="grow-x"
692 data-anim-at="0.65"
693 data-anim-duration="0.5"
694 data-anim-target-w="420"
695 style="width:0;height:8px;background:var(--accent-0);border-radius:4px;"
696 ></div>
697 </div>
698</div>
699```
700
701**Hard rules** (`hyperframes` lint will reject violations):
702
703- Single root `<div class="card" data-card-id="{cardId}">`
704- Inline `<style>` rules MUST be prefixed with the scope selector above
705- **No `<script>` tags**
706- **No external URLs** in `src=` / `href=` (no CDN, no remote fonts)
707- **No inline event handlers** (`onclick=` etc.)
708- All assets via relative paths into the same `public/` directory
709- Colors via `var(--accent-N)` etc. for portability across themes
710
711**Animations are declared, not coded.** Use `data-anim-*` attributes
712only; never write `<script>` to animate. You compile every `data-anim-*`
713declaration into the single master GSAP timeline in Step 9.
714
715#### Card Sizing — Mobile-First in Portrait
716
717The 10 `references/styles/*.html` are sized for a **1920×1080 landscape**
718preview. When `storyboard.layout = "portrait"` (1080×1920, the dominant
719case for social / mobile), **scale every visual size up** — phones hold
720the screen close, and the same pixel count reads smaller than on a
721landscape TV-style canvas.
722
723| token | landscape baseline | **portrait target** | scale |
724| ------------------------- | ------------------ | ------------------- | ------------- |
725| title (h1/h2 hero) | 64–96px | **88–132px** | ×1.35 |
726| detail / body | 24–30px | **30–40px** | ×1.30 |
727| kicker / chip label | 14–16px | **18–22px** | ×1.30 |
728| timecode / meta | 12–14px | **16–18px** | ×1.30 |
729| data block primary number | 48–60px | **64–88px** | ×1.40 |
730| line-height multiplier | 1.05–1.5 | same | (don't scale) |
731
732**Rule of thumb:** `portraitPx = round(landscapePx × 1.3)`, then floor
733to a nearby 4px multiple for visual rhythm. Hero headlines may go up to
734×1.4; small meta text stays at ×1.2 to avoid crowding.
735
736Padding **shrinks slightly** in portrait — the card is narrower so big
737landscape padding (40–64px) eats too much width. Use 24–36px horizontal
738padding in portrait.
739
740If you're producing a single card that must work in **both** layouts,
741prefer a `@container` query on the card root over hard-coding sizes:
742
743```css
744.card[data-card-id="X"] .root {
745 container-type: inline-size;
746}
747.card[data-card-id="X"] .title {
748 font-size: clamp(64px, 8.5cqi, 132px);
749}
750.card[data-card-id="X"] .detail {
751 font-size: clamp(24px, 3.2cqi, 40px);
752}
753```
754
755But for most cards, a single layout choice is fine — just pick the size
756table column that matches the storyboard's `layout` field.
757
758#### Available `data-anim` Kinds
759
760| kind | use for | key params |
761| --------------- | ------------------- | ----------------------------------------------------------------------------------------------- |
762| `fade-in` | enter | `at`, `duration`, `ease?` |
763| `fade-out` | exit | `at`, `duration`, `ease?` |
764| `slide-in` | slide enter | `at`, `duration`, `from=left\|right\|top\|bottom`, `distance` |
765| `kinetic-chars` | per-char pop | `at`, `duration`, `stagger`, `pattern=pop\|fade` — element needs `<span class="char">` children |
766| `typewriter` | per-char fade | same as kinetic-chars but slower default stagger |
767| `count-up` | animate number | `at`, `duration`, `from`, `to`, `format=.0f\|.1f\|.2f\|,d` |
768| `draw-path` | SVG path reveal | `at`, `duration` — element should be a `<path>` |
769| `grow-y` | bar height | `at`, `duration`, `target-h` (px) — element starts `height:0` |
770| `grow-x` | bar width | `at`, `duration`, `target-w` (px) — element starts `width:0` |
771| `scale-pop` | pop entrance | `at`, `duration` |
772| `blur-in` | unfocused → focused | `at`, `duration` |
773| `mask-reveal` | clip reveal | `at`, `duration`, `direction=left\|right\|top\|bottom` |
774| `morph-to` | tween any CSS | `at`, `duration`, `props='{...JSON...}'` |
775
776`data-anim-at` is **seconds relative to the card's startSec** — when you
777compile each declaration into the GSAP timeline in Step 9, add the
778card's `startSec` to get the absolute time and quantize to 1/fps.
779
780### 9. Assemble the Composition HTML
781
782Stage the assets and write `$WORK_DIR/public/index.html`:
783
784```bash
785# SKILL_DIR is injected by the host ("Base directory for this skill: …")
786SKILL_DIR="<SKILL_DIR>"
787
788mkdir -p "$WORK_DIR/public/fonts" "$WORK_DIR/public/vendor" "$WORK_DIR/public/cards"
789cp -n "$SKILL_DIR/assets/fonts/"* "$WORK_DIR/public/fonts/"
790cp -n "$SKILL_DIR/assets/vendor/gsap.min.js" "$WORK_DIR/public/vendor/"
791# stage the input video — RE-ENCODE with dense keyframes. Sources with a sparse GOP
792# (keyframe interval > ~1s) freeze on seek in the renderer (a frozen frame under the
793# overlays); -g / -keyint_min set to your composition fps make every frame seekable.
794# (Set both to your fps — 30 shown; use 24/25/60 to match.)
795ffmpeg -y -i "$VIDEO_PATH" -c:v libx264 -crf 18 -g 30 -keyint_min 30 \
796 -pix_fmt yuv420p -movflags +faststart -c:a aac "$WORK_DIR/public/input-video.mp4"
797```
798
799#### Composition Template
800
801```html
802<!doctype html>
803<html lang="en">
804 <head>
805 <meta charset="utf-8" />
806 <style>
807 @font-face {
808 font-family: "Caveat";
809 src: url("fonts/Caveat-400-latin.woff2") format("woff2");
810 font-weight: 400;
811 font-display: block;
812 }
813 @font-face {
814 font-family: "Caveat";
815 src: url("fonts/Caveat-700-latin.woff2") format("woff2");
816 font-weight: 700;
817 font-display: block;
818 }
819 @font-face {
820 font-family: "LXGW WenKai TC";
821 src: url("fonts/LXGWWenKaiTC-400-latin.woff2") format("woff2");
822 font-weight: 400;
823 font-display: block;
824 }
825 @font-face {
826 font-family: "Inter";
827 src: url("fonts/Inter-400-latin.woff2") format("woff2");
828 font-weight: 400;
829 font-display: block;
830 }
831 @font-face {
832 font-family: "Inter";
833 src: url("fonts/Inter-700-latin.woff2") format("woff2");
834 font-weight: 700;
835 font-display: block;
836 }
837 @font-face {
838 font-family: "Virgil";
839 src: url("fonts/Virgil.woff2") format("woff2");
840 font-display: block;
841 }
842
843 :root {
844 /* Pick from the themeId palette table in Step 7 — example: classic */
845 --bg: #fff9e3;
846 --text: #1e1e1e;
847 --accent-0: #1971c2;
848 --accent-1: #e03131;
849 --accent-2: #2f9e44;
850 --accent-3: #e8590c;
851 --accent-4: #9c36b5;
852 --font-family: "Caveat", "LXGW WenKai TC", serif;
853 }
854 * {
855 box-sizing: border-box;
856 }
857 /* Body font-family MUST list concrete font names (not just var(--font-family)) —
858 the HyperFrames renderer's static analyzer doesn't expand CSS variables when
859 resolving fonts, so a var-only chain triggers `font_family_without_font_face`
860 lint and falls back to a generic. Use the concrete chain here; cards that
861 want the theme font can still reference var(--font-family) internally. */
862 html,
863 body {
864 margin: 0;
865 padding: 0;
866 width: 100%;
867 height: 100%;
868 overflow: hidden;
869 background: #000;
870 font-family: "Inter", "Caveat", "LXGW WenKai TC", ui-sans-serif, system-ui, sans-serif;
871 }
872 #stage {
873 position: relative;
874 width: 100%;
875 height: 100%;
876 overflow: hidden;
877 }
878
879 /* video-wrapper holds the source video. Its position / size are animated
880 over time by the master timeline (one tween per layout transition). */
881 .video-wrapper {
882 position: absolute;
883 left: 0;
884 top: 0;
885 width: 1920px;
886 height: 1080px;
887 overflow: hidden;
888 border-radius: 0;
889 box-shadow: none;
890 }
891 .video-wrapper video {
892 width: 100%;
893 height: 100%;
894 object-fit: cover;
895 }
896
897 .card-host {
898 position: absolute;
899 pointer-events: none;
900 overflow: hidden;
901 }
902 .card-host .card {
903 position: relative;
904 width: 100%;
905 height: 100%;
906 overflow: hidden;
907 }
908 .card-host .char {
909 display: inline-block;
910 visibility: visible;
911 }
912
913 /* Subtle drop shadow + rounded corners for non-fullscreen video framings */
914 .video-wrapper.framed {
915 border-radius: 16px;
916 box-shadow: 0 12px 40px rgba(0, 0, 0, 0.35);
917 }
918 </style>
919 </head>
920 <body>
921 <div
922 id="stage"
923 data-composition-id="talking-head-recut"
924 data-start="0"
925 data-duration="121.2"
926 data-fps="30"
927 data-width="1920"
928 data-height="1080"
929 >
930 <!-- Layer 1: source video — initial position matches card-01's layout -->
931 <div class="video-wrapper" id="video-wrap">
932 <video
933 id="bg-video"
934 src="input-video.mp4"
935 muted
936 playsinline
937 data-start="0"
938 data-duration="121.2"
939 data-track-index="1"
940 ></video>
941 </div>
942 <!-- Preserve the source program audio while the visual video stays muted. -->
943 <audio
944 id="source-audio"
945 src="input-video.mp4"
946 data-start="0"
947 data-duration="121.2"
948 data-track-index="10"
949 data-volume="1"
950 ></audio>
951
952 <!-- Layer 2: each card-host sits at the bounds dictated by its layout. -->
953 <!-- IMPORTANT: every card-host MUST carry BOTH "card-host" and "clip" classes. -->
954 <!-- - "card-host" → our positioning + pointer-events styles -->
955 <!-- - "clip" → the marker Studio and the linter use to recognise a -->
956 <!-- clip. Visibility itself comes from data-start / -->
957 <!-- data-duration, which the runtime honours with or -->
958 <!-- without this class -->
959 <!-- (lint: timed_element_missing_clip_class, a warning). -->
960 <!-- Example: card-01 with zone="fullscreen" → card-host covers (0,0,1920,1080) -->
961 <div
962 class="card-host clip"
963 data-card-id="card-01"
964 data-start="1.0000"
965 data-duration="6.5000"
966 data-track-index="2"
967 style="left:0;top:0;width:1920px;height:1080px;visibility:hidden;opacity:0;"
968 >
969 <!-- paste the contents of public/cards/card-01.html here -->
970 </div>
971
972 <!-- Example: card-02 with zone="side-panel" (split composition layout) → card on left half -->
973 <div
974 class="card-host clip"
975 data-card-id="card-02"
976 data-start="8.0000"
977 data-duration="12.0000"
978 data-track-index="2"
979 style="left:0;top:0;width:960px;height:1080px;visibility:hidden;opacity:0;"
980 >
981 <!-- card-02 HTML -->
982 </div>
983
984 <!-- ...one "card-host clip" per card with inline bounds matching resolveZoneBounds(card.zone)... -->
985
986 <script src="vendor/gsap.min.js"></script>
987 <script>
988 (function () {
989 // count-up formatter helper
990 window.__fmt = function (v, fmt) {
991 if (typeof fmt === "string" && /^\.[0-9]+f$/.test(fmt)) {
992 return Number(v).toFixed(Number(fmt.slice(1, -1)));
993 }
994 if (fmt === ",d") return Math.round(v).toLocaleString();
995 return String(Math.round(v));
996 };
997
998 const tl = window.gsap.timeline({ paused: true });
999
1000 // ── Card lifecycle (one block per card) ──
1001 // Example for card-01 [1.0, 7.5] with kinetic-chars at +0.3, grow-x at +0.65:
1002
1003 // Enter (fade in over 0.4s)
1004 tl.set('.card-host[data-card-id="card-01"]', { visibility: "visible" }, 1.0);
1005 tl.fromTo(
1006 '.card-host[data-card-id="card-01"]',
1007 { opacity: 0 },
1008 { opacity: 1, duration: 0.4, ease: "power2.out" },
1009 1.0,
1010 );
1011
1012 // Card-internal anims (compile each data-anim-* declaration here)
1013 tl.from(
1014 '.card[data-card-id="card-01"] #card-01-title .char',
1015 { opacity: 0, y: 8, scale: 0.8, duration: 0.5, ease: "power2.out", stagger: 0.04 },
1016 1.3,
1017 );
1018 tl.fromTo(
1019 '.card[data-card-id="card-01"] #card-01-line',
1020 { width: 0 },
1021 { width: 420, duration: 0.5, ease: "power2.out" },
1022 1.65,
1023 );
1024
1025 // Exit (fade out over 0.35s, ending at endSec)
1026 tl.to(
1027 '.card-host[data-card-id="card-01"]',
1028 { opacity: 0, duration: 0.35, ease: "power2.in" },
1029 7.15,
1030 );
1031 tl.set('.card-host[data-card-id="card-01"]', { visibility: "hidden" }, 7.5);
1032
1033 // ── Video framing transitions ──
1034 // When the next card uses a different composition layout, animate the
1035 // video-wrapper to its new bounds. Example: card-01 = fullscreen
1036 // (video hidden behind), card-02 = split composition (zone="side-panel"
1037 // → video on right, card on left).
1038
1039 // Card-02 enters at 8.0s with the split composition. Animate video to
1040 // the right half during the card-01 → card-02 gap (between 7.5 and 8.0s).
1041 tl.set("#video-wrap", { className: "video-wrapper framed" }, 7.5);
1042 tl.to(
1043 "#video-wrap",
1044 { left: 960, top: 0, width: 960, height: 1080, duration: 0.6, ease: "power2.inOut" },
1045 7.5,
1046 );
1047
1048 // Card-02 enter — same pattern as card-01
1049 tl.set('.card-host[data-card-id="card-02"]', { visibility: "visible" }, 8.0);
1050 tl.fromTo(
1051 '.card-host[data-card-id="card-02"]',
1052 { opacity: 0 },
1053 { opacity: 1, duration: 0.4, ease: "power2.out" },
1054 8.0,
1055 );
1056 // ...card-02 internal anims...
1057
1058 // ── repeat for each card; if the NEXT card's layout differs,
1059 // insert another tl.to('#video-wrap', ...) tween before its enter ──
1060
1061 window.__timelines = window.__timelines || {};
1062 window.__timelines["talking-head-recut"] = tl;
1063 })();
1064 </script>
1065 </div>
1066 </body>
1067</html>
1068```
1069
1070#### GSAP Statement Cheat Sheet
1071
1072Compile each `data-anim` attribute into a GSAP statement. Times are
1073**absolute seconds** = card.startSec + data-anim-at, quantized to 1/fps.
1074Selector is `.card[data-card-id="X"] #elementId`.
1075
1076| data-anim | GSAP statement template |
1077| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1078| `fade-in` | `tl.fromTo(SEL, { opacity: 0 }, { opacity: 1, duration: D, ease: 'power2.out' }, T);` |
1079| `fade-out` | `tl.to(SEL, { opacity: 0, duration: D, ease: 'power2.in' }, T);` |
1080| `slide-in` (from=left, dist=80) | `tl.fromTo(SEL, { opacity: 0, x: -80 }, { opacity: 1, x: 0, duration: D, ease: 'power2.out' }, T);` |
1081| `kinetic-chars` (pop) | `tl.from(SEL + ' .char', { opacity: 0, y: 8, scale: 0.8, duration: D, ease: 'power2.out', stagger: S }, T);` |
1082| `count-up` | `(function(){const o={v:FROM};tl.to(o,{v:TO,duration:D,ease:'power2.out',onUpdate:function(){const el=document.querySelector(SEL);if(el)el.textContent=__fmt(o.v,'FMT');}},T);})();` |
1083| `draw-path` | `(function(){const el=document.querySelector(SEL);if(el){const L=el.getTotalLength();tl.set(SEL,{strokeDasharray:L,strokeDashoffset:L},T);tl.to(SEL,{strokeDashoffset:0,duration:D,ease:'power2.inOut'},T);}})();` |
1084| `grow-x` (target-w=W) | `tl.fromTo(SEL, { width: 0 }, { width: W, duration: D, ease: 'power2.out' }, T);` |
1085| `grow-y` (target-h=H) | `tl.fromTo(SEL, { height: 0 }, { height: H, duration: D, ease: 'power2.out' }, T);` |
1086| `scale-pop` | `tl.fromTo(SEL, { opacity: 0, scale: 0.6 }, { opacity: 1, scale: 1, duration: D, ease: 'back.out(1.6)' }, T);` |
1087| `mask-reveal` (direction=left) | `tl.fromTo(SEL, { clipPath: 'inset(0 100% 0 0)' }, { clipPath: 'inset(0 0 0 0)', duration: D, ease: 'power2.inOut' }, T);` |
1088
1089Quantize: `T = Math.round(absSec * fps) / fps`. At 30fps the smallest
1090step is `1/30 ≈ 0.0333s`; rounding to 4 decimals (`.toFixed(4)`) is fine
1091inside the JS literal.
1092
1093#### Video Framing Reference (per `layout` value)
1094
1095The selector for the video container is `#video-wrap`. Animate its
1096bounds between cards using `tl.to('#video-wrap', { ...bounds }, T)`.
1097Initial bounds should be set inline on the element to match card-01's
1098layout. Pick a transition duration of 0.5–0.7s with `ease: 'power2.inOut'`.
1099
1100**Decorative frames** (`clean` / `hairline` / `polaroid`) sit as a
1101**sibling** of `#video-wrap` and follow it through layout transitions.
1102See
1103[`references/frames/`](references/frames/) for each frame's placement
1104HTML, suggested CSS, and which layouts it pairs with. Quick rule:
1105`overlay` layout suppresses decorative frames (the full-bleed video
1106clashes with chrome); PiP layouts already have their own pill treatment
1107(border-radius + white ring + shadow), so add a decorative frame only on
1108top of `split` / `stack`.
1109
1110**GSAP target lookup table** for `#video-wrap` per composition layout
1111(landscape 1920×1080 — for portrait & 4:5 see `references/layouts/*.html`
1112which list all three ratios):
1113
1114| composition layout | typical card.zone | `#video-wrap` GSAP target | extra css class |
1115| ------------------------------------ | ----------------- | ------------------------------------------------------------------------- | ------------------------------------------ |
1116| `split` | `side-panel` | `{ left: 960, top: 0, width: 960, height: 1080 }` | — |
1117| `stack` | `lower-third` | `{ left: 14, top: 14, width: 1892, height: 548 }` (top 52%) | — |
1118| `pip` (bottom-right) | `fullscreen` | `{ left: 1480, top: 760, width: 400, height: 300 }` | `pip-pill` (border-radius + ring + shadow) |
1119| `pip` (top-left) | `fullscreen` | `{ left: 40, top: 40, width: 400, height: 300 }` | `pip-pill` |
1120| `overlay` (video full-bleed) | `video-overlay` | `{ left: 0, top: 0, width: 1920, height: 1080 }` (no change from default) | — |
1121| **hide video** (pure-graphic moment) | `fullscreen` | `{ opacity: 0 }` (or move off-canvas) | — |
1122
1123To toggle the pip-pill chrome (border-radius + white ring + drop shadow)
1124when entering or leaving a pip moment:
1125
1126```js
1127// Enter pip — add chrome
1128tl.set("#video-wrap", { className: "video-wrapper pip-pill" }, T);
1129tl.to(
1130 "#video-wrap",
1131 { left: 1480, top: 760, width: 400, height: 300, duration: 0.6, ease: "power2.inOut" },
1132 T,
1133);
1134
1135// Leave pip — back to clean full-bleed
1136tl.set("#video-wrap", { className: "video-wrapper" }, T_NEXT);
1137tl.to(
1138 "#video-wrap",
1139 { left: 0, top: 0, width: 1920, height: 1080, duration: 0.6, ease: "power2.inOut" },
1140 T_NEXT,
1141);
1142```
1143
1144**Card-host bounds match the zone**. Resolve the card's `zone` into
1145pixel bounds using the table at the top of Step 6, then write those
1146into the card-host's inline `style="left:Xpx;top:Ypx;width:Wpx;
1147height:Hpx;..."`. For `video-overlay` zone (overlay recipe), the
1148card-host fills the full canvas — your CSS inside `.card .root`
1149decides where the actual visible card sits.
1150
1151#### HyperFrames Layout / Animation QA Rules
1152
1153- Build each card's static hero frame first: the moment where the card is fully visible and readable.
1154- Confirm video, cards, subtitles/captions, and diagrams do not unintentionally overlap.
1155- Confirm hidden video areas are clipped by the frame and not visible outside intended bounds.
1156- Register one paused master timeline as `window.__timelines["talking-head-recut"]`.
1157- Build timelines synchronously at page load; no `async`, `setTimeout`, Promises, or media `play()` calls.
1158- Do not use `Math.random()` or `Date.now()` in render paths.
1159- Do not use `repeat: -1`; calculate finite repeats from the video duration.
1160- Prefer GSAP transforms and opacity (`x`, `y`, `scale`, `rotation`, `opacity`) over layout properties (`top`, `left`, `width`, `height`) for motion.
1161- Animate wrappers such as `#video-wrap`, not the video element dimensions directly.
1162- Avoid animating the same property on the same element from multiple timelines at the same time.
1163- Use `data-track-index`, not `data-layer`; use `data-duration`, not `data-end`.
1164- Every timed element (`card-host`, sub-composition, etc.) should include `class="clip"` alongside its own classes — e.g. `class="card-host clip"`. Visibility itself is driven by `data-start` / `data-duration`: the runtime gates every `[data-start]` element to its window whether or not this class is present. `.clip` is the marker Studio and the GSAP clip-ownership rules read to recognise a clip, so leaving it off makes the element harder to edit and to lint (lint: `timed_element_missing_clip_class`, a warning).
1165- For body / global `font-family`, list **concrete font names** (`'Inter', 'Caveat', …`) — not a CSS variable like `var(--font-family)`. The HyperFrames font resolver doesn't expand CSS vars during static analysis (lint: `font_family_without_font_face`). Cards may still use `var(--font-family)` internally since their `@font-face` declarations are loaded.
1166
1167### 10. Render to MP4
1168
1169```bash
1170cd "$WORK_DIR"
1171PRODUCER_BROWSER_GPU_MODE=hardware npx hyperframes render public \
1172 --skill=talking-head-recut \
1173 -o output.mp4 \
1174 --fps 30
1175```
1176
1177`hyperframes render <dir>` reads `<dir>/index.html` and produces the MP4.
1178The canonical composition keeps the visual `<video>` muted and mounts the same
1179source as the root `#source-audio` track, so the rendered MP4 preserves the
1180talking-head audio without a manual remux. This uses a separate audio track
1181rather than `data-has-audio="true"` so its volume and ducking remain independently
1182controllable on the timeline.
1183The flag `PRODUCER_BROWSER_GPU_MODE=hardware` (or `--browser-gpu`) is
1184strongly recommended on macOS — software-only Chrome rendering times out
1185on most laptops.
1186
1187For a sanity check before the full render, capture a single frame at a
1188specific timestamp:
1189
1190```bash
1191npx hyperframes snapshot public --at 5 # → public/snapshots/frame-00-at-5s.png (a single --at ignores --out)
1192```
1193
1194### 11. Report Results
1195
1196Tell the user:
1197
1198- Work directory path
1199- `storyboard.json` (the card outline you designed)
1200- `public/cards/*.html` (one HTML per card)
1201- `public/index.html` (the assembled composition)
1202- `output.mp4` (the final video)
1203- ASR provider used
1204- Card count + how you chose them (in 1 sentence)
1205- Any missing keys or quality caveats
1206
1207**Optional live preview (on request only).** The clip plays unchanged inside `public/index.html` with the overlays on top, so it previews faithfully. **Don't open it during the run.** When the user asks, start a long-lived server **after** render and report the URL:
1208
1209```bash
1210(cd "$WORK_DIR/public" && npx hyperframes preview --background) # or `npx hyperframes play` for a shareable link
1211```
1212
1213Do not delete the work directory unless the user asks.