Website To Hyperframes

Website to HyperFrames

Capture a website, then produce a professional video from it.

Users say things like:

• "Capture https://... and make me a 25-second product launch video"
• "Turn this website into a 15-second social ad for Instagram"
• "Create a 30-second product tour from https://..."

The workflow has 7 steps. Each produces an artifact that gates the next.

---

Step 1: Capture & Understand

Read: references/step-1-capture.md

Run the capture, read the extracted data, and build a working summary using the write-down-and-forget method.

Gate: Print your site summary (name, top colors, fonts, key assets, one-sentence vibe).

---

Step 2: Write DESIGN.md

Read: references/step-2-design.md

Write a simple brand reference for the captured website. 6 sections, ~90 lines. This is a cheat sheet, not the creative plan — that comes in Step 4.

Gate: DESIGN.md exists in the project directory.

---

Step 3: Write SCRIPT

Read: references/step-3-script.md

Write the narration script. The story backbone. Scene durations come from the narration, not from guessing.

Gate: SCRIPT.md exists in the project directory.

---

Step 4: Write STORYBOARD

Read: references/step-4-storyboard.md

Write per-beat creative direction: mood, camera, animations, transitions, assets, depth layers, SFX. This is the creative north star — the document the engineer follows to build each composition.

Gate: STORYBOARD.md exists with beat-by-beat direction and an asset audit table.

---

Step 5: Generate VO + Map Timing

Read: references/step-5-vo.md

Generate TTS audio, transcribe for word-level timestamps, and map timestamps to beats. Update STORYBOARD.md with real durations.

Gate: narration.wav (or .mp3) + transcript.json exist. Beat timings in STORYBOARD.md updated.

---

Step 6: Build Compositions

Read: The /hyperframes skill (invoke it — every rule matters) Read: references/step-6-build.md

Build each composition following the storyboard. After each one: self-review for layout, asset placement, and animation quality.

Gate: Every composition has been self-reviewed. No overlapping elements, no misplaced assets, no static images without motion.

---

Step 7: Validate & Deliver

Read: references/step-7-validate.md

Lint, validate, preview. Create a HANDOFF.md for multi-session continuity.

Gate: npx hyperframes lint and npx hyperframes validate pass with zero errors.

---

Quick Reference

Video Types

Format

• Landscape: 1920x1080 (default)
• Portrait: 1080x1920 (Instagram Stories, TikTok)
• Square: 1080x1080 (Instagram feed)

Reference Files

Step 1: Capture & Understand

Run the capture

npx hyperframes capture <URL> -o captures/<project-name>

No API keys required. The capture extracts design tokens, screenshots, fonts, and assets with DOM-context descriptions automatically.

Optional: Set GEMINI_API_KEY (or GOOGLE_API_KEY) in a .env file at the repo root for richer AI-powered image descriptions via Gemini 2.5 Flash vision. Free tier: 5 RPM; paid tier removes the bottleneck.

Wait for it to complete. Print how many screenshots, assets, sections, and fonts were extracted.

Read and summarize

Read each file below. After reading each one, write a 1-2 sentence summary of what you learned. These summaries are your working memory — the raw file content may be cleared from context later.

Must read (do not skip)

1. View the scroll screenshots — viewport-sized captures covering the full page height (the number depends on the page length). Start with:

• screenshots/scroll-000.png — the hero section at full 1920x1080 resolution. This is the most important image. Describe: is the background light or dark? What's the dominant visual element? What colors jump out?
• Then scan through the rest to see the full page. Each screenshot overlaps the previous by ~30%.

After viewing them, write 3-4 sentences describing the site's visual mood, layout patterns, color strategy, and overall feel.

2. `extracted/tokens.json` — Note the top 5-7 colors (HEX), all font families, number of sections, and number of headings/CTAs.

3. `extracted/visible-text.txt` — Note the site's headline, tagline, key selling points, and any notable statistics or social proof.

4. `extracted/asset-descriptions.md` — One-line-per-file summary of all downloaded assets. Note which assets are most visually striking or useful for video (hero images, logos, product screenshots).

Read if they exist

5. `extracted/animations.json` — Note if the site uses scroll-triggered animations, marquees, canvas/WebGL, or named CSS animations.

6. `extracted/lottie-manifest.json` — View each preview image at assets/lottie/previews/ to see what the animations look like.

7. `extracted/video-manifest.json` — View each preview at assets/videos/previews/ to see what each video shows.

8. `extracted/shaders.json` — If present, this contains the actual GLSL shader code that powers the site's WebGL visual effects (gradient waves, particle systems, noise fields). Read the fragment shaders to extract: color values used in gradients, noise algorithms, blend functions. You can recreate similar effects in your compositions using Canvas 2D or by embedding the shader patterns with a <canvas> + WebGL context. See the Canvas 2D and procedural art patterns in techniques.md.

On-demand (read when building scenes)

9. Individual images in `assets/` — Use asset-descriptions.md as your index. View specific images when you need them for a beat.

10. `extracted/assets-catalog.json` — Use to find remote URLs when you need an asset that wasn't downloaded.

For rich captures (30+ images)

Launch a sub-agent to view all images and SVGs:

"Read every image in assets/ and every SVG in assets/svgs/. For each, write one line: filename — what it shows, dominant colors, approximate size. Return the complete catalog."

Use the sub-agent's catalog as your asset reference for the rest of the workflow.

Gate

Print your site summary before proceeding to Step 2:

• Site: [name]
• Colors: [top 3-5 HEX values with roles]
• Fonts: [font families]
• Sections: [count] sections, [count] headings, [count] CTAs
• Key assets: [3-5 most useful assets for video]
• Vibe: [one sentence describing the visual identity]

Step 2: Write DESIGN.md

DESIGN.md is a brand cheat sheet for the captured website. It encodes the visual identity so you can reference exact colors, fonts, and patterns while writing the storyboard and compositions.

DESIGN.md is NOT the creative plan. The STORYBOARD (Step 4) drives creative direction. DESIGN.md is a reference you consult, not a document you follow slavishly.

The 6 Sections

## Overview

3-4 sentences. Describe the visual identity factually: layout patterns (bento grid, logo wall, hero section), color strategy, typography tone, overall feel. Be precise, not poetic.

## Colors

5-10 key colors with HEX values from tokens.json and their roles:

- **Primary Surface**: `#020204` — deep black background
- **Primary Content**: `#FFFFFF` — high-purity white for text and borders
- **Accent Warm**: `#FB923C` — orange for CTAs and highlights

Include semantic colors if the site uses color to differentiate product areas.

## Typography

Font families with weights, roles, and any distinctive usage:

- **Serif**: Cormorant Garamond (Italic). Major headings, brand identity.
- **Monospace**: Geist Mono. Subheaders, labels, terminal readouts. High tracking (0.1-0.3em), all-caps.
- **Sans-Serif**: Inter. Body copy, interface elements. Small sizes (9-14px).

Include sizing hierarchy if notable (hero: 64px, section: 32px, body: 16px).

## Elevation

One paragraph on depth strategy: Does the site use borders, shadows, glassmorphism, or flat color shifts? Reference specific patterns (e.g., "1px borders at white/10 opacity" or "layered backdrop-blur with thin borders").

## Components

Name every notable UI component you see in the screenshot. Be specific:

• "Cinematic Accordion" not "Cards"
• "Logo Marquee" not "Scrolling section"
• "Glass Cards with grain overlay" not "Content containers"

For each, note the distinctive visual treatment (border-radius, spacing, hover behavior).

## Do's and Don'ts

3-5 rules each, derived from what the site actually does and doesn't do:

### Do's
- Use thin subtle borders (white/10) to separate sections
- Keep imagery desaturated with dark gradients for text readability

### Don'ts
- Do not use bright solid background colors — stay in "The Void"
- Do not use standard drop shadows — use radial glow or bloom effects
- Do not use sharp high-speed animations — all motion should be fluid

Rules

• Use exact HEX values from tokens.json. Do not approximate.
• Name components by what you see in the screenshot, not generic terms.
• Keep it under 100 lines. This is a cheat sheet, not a design system document.
• No "Style Prompt" section — the storyboard handles creative direction.
• No "Assets" section — asset-descriptions.md already covers this.
• No "Motion" section — the storyboard specifies motion per-beat.

Example

This is a real DESIGN.md from a production capture (Soulscape 2026):

# Design System

## Overview

Soulscape 2026 is a cinematic, "high-signal" digital experience that positions itself as the vanguard of AI filmmaking. The visual personality is dark, technical, and premium, characterized by high-contrast "Flare" on "Void" (white on black) aesthetics. The layout is dense but organized, utilizing heavy horizontal layering and border-defined sections to evoke a wide-screen cinematic feel. Motion is a core tenet, with atmospheric grain overlays, shifting light leaks, and slow-moving marquees creating constant, breathing texture.

## Colors

- **Primary Surface**: `#020204` (Void) - Deep black for the entire background.
- **Primary Content**: `#FFFFFF` (Flare) - High-purity white for typography and primary borders.
- **Accent 1 (Warm)**: `#FB923C` - Orange for industry/executive tiers and primary CTAs.
- **Accent 2 (Cool)**: `#60A5FA` - Blue for creative voices and summit-focused components.
- **Subtle Overlays**: `rgba(255, 255, 255, 0.02)` to `0.08` for glass backgrounds.

## Typography

- **Serif**: Cormorant Garamond (Italic). Major headings and "Soul" brand identity. Classical cinematic contrast.
- **Monospace**: Geist Mono. Subheaders, labels, terminal readouts. High tracking (0.1-0.3em), all-caps.
- **Sans-Serif**: Inter. Body copy and interface elements. Small sizes (9-14px).

## Elevation

- **Glassmorphism**: Components use backdrop-filter blur(10px) with thin borders (1px solid rgba(255, 255, 255, 0.08)).
- **Layering**: Depth via fixed global grain-overlay and localized light-leak gradients rather than box-shadows.
- **Interaction**: Hover triggers subtle translateY(-5px) and increased border opacity.

## Components

- **Cinematic Accordion**: Expanding horizontal/vertical card system where panels expand from compressed state to reveal full-bleed imagery and large serif typography.
- **HUD Explorer**: Floating mobile navigation trigger styled as a "Lens" with pulsing glow and terminal readouts.
- **Slow Marquees**: Continuous horizontal tickers for partner logos and veteran listings.
- **Glass Cards**: Content containers with subtle gradients, rounded corners (2.5rem), and high-contrast iconography.
- **Grain & Flicker**: Global CSS noise filters and holographic flicker animations on UI labels.

## Do's and Don'ts

### Do's

- Use thin subtle borders (white/10) to separate sections rather than solid color changes.
- Maintain high letter-spacing on all Geist Mono labels.
- Use serif italics for emotional or visionary statements.
- Keep imagery desaturated or stylized with dark gradients for readability.

### Don'ts

- Do not use bright solid background colors — the page must remain in "The Void."
- Do not use standard drop shadows — use radial glow or bloom effects instead.
- Do not use sharp high-speed animations — all motion should be fluid and breathing.

Step 3: Write the Narration Script

Before writing, re-read DESIGN.md — specifically the Overview and Components sections. The script should reference real product features, real stats, and real components that the website highlights. Use exact numbers from extracted/visible-text.txt.

The script is the backbone. Everything downstream — scene durations, animation timing, beat pacing — comes from the narration. Write it before the storyboard.

Save as SCRIPT.md in the project directory.

Pacing

• 2.5 words per second is natural speaking pace
• 15s = ~37 words. 30s = ~75 words. 60s = ~150 words
• Leave room for pauses. Silence between sentences is a feature, not dead air
• The script should feel SHORTER than the video — visual breathing room matters

Tone

Write like a person, not a brochure:

• Use contractions: "it's", "you'll", "that's", "we've"
• Vary sentence length — short punchy phrases mixed with longer flowing ones
• Read it out loud. If it sounds robotic, rewrite it
• Avoid jargon unless the audience expects it

Number Pronunciation

Write what you want the voice to say. TTS reads literally.

The visual can show the exact figure while the voice rounds it.

Structure

For product videos from a website capture:

1. Hook — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. Vary the hook type — don't default to a stat every time. 2. Story — what does the product do? Who uses it? Keep it concrete. 3. Proof — stats, customer names, social proof. Real numbers from the website. 4. CTA — what should the viewer do? "Start building at stripe dot com."

Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story.

The Opening Line

The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds.

Patterns that work:

• A bold claim: "The financial infrastructure that powers the internet economy."
• A question that provokes: "What if your database could think?"
• A contrast: "Your AI agent already knows how to make videos. It just needs the right format."
• A number that shocks: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.)

If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over.

Example

From a 62-second product launch video (team reference):

Your AI agent already knows how to make videos.
It just needs the right format.

This is Hyperframes. An open source framework. HTML in, video out.

A div is a keyframe. Data attributes are your timeline.
CSS is your look. G-Sap is your animation engine.

Anything a browser can render can be a frame in your video.

CSS animations. G-Sap. Lottie. Shaders. Three.js.

Drop in music, sound effects, footage — it all composes together.

No new framework for the agent to learn.
Just HTML.

The agent writes it. The renderer captures every frame as MP4.
It's deterministic. Identical outputs, every time.

Give your agent the CLI. Tell it what to make.
Watch it build.

Hyperframes. Go make something.

Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing.

Step 4: Write the Storyboard

Before writing anything, fully re-read these files:

• DESIGN.md — your color palette, font rules, components, Do's/Don'ts. Every creative decision must be grounded in this brand identity. If it says "white backgrounds with purple accent" — plan light scenes, not dark moody ones.
• `extracted/asset-descriptions.md` — read EVERY line. This is your menu of available visuals. Each line describes what the image actually shows (e.g., "translucent ribbons in orange, pink, and purple on white background" or "a high-speed train under a dark starry sky"). Use these descriptions to decide which assets belong in which beat. Assets you don't understand from the description — view them directly before assigning.
• [techniques.md](techniques.md) — 10 visual techniques (SVG path drawing, Canvas 2D art, CSS 3D, per-word typography, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions). Pick 2-3 per beat and specify them in the storyboard.

The storyboard is the creative north star. It tells the engineer exactly what to build for each beat — mood, camera, animations, transitions, assets, sound. Write it as if you're briefing a motion designer who's never seen the website.

Save as STORYBOARD.md in the project directory.

---

Global Direction

Every STORYBOARD.md starts with global settings:

**Format:** 1920×1080
**Audio:** [TTS provider] voiceover + underscore + SFX
**VO direction:** [voice character — e.g., "mid-age male, calm confident delivery,
Apple keynote register — economy of words, silence between sentences is a feature"]
**Style basis:** DESIGN.md (brand colors, fonts, components from the captured site)

Global guardrails (adapt to the brand):

• Push color presence. Muted is fine, flat is not. Every beat should have at least one color that pulls your eye.
• Motion should be visible and intentional. Err toward more movement than feels safe — subtle reads as static at 30fps.
• Use as many captured assets as the creative vision allows. Scatter framework icons around a dashboard. Layer enterprise photos behind stats. Use product screenshots as floating cards. The assets exist — use them generously.
• Aim for 8-10 visual elements per beat, not 2-3. A great beat has: background texture, midground content, foreground accents, floating decorative elements, animated icons, SVG path drawings, particle effects, typographic details. It should feel DENSE and alive.
• Use at least 2-3 different techniques from techniques.md per beat — not across the whole video, per beat. Don't default to basic fade/scale/opacity — mix in SVG path drawing, CSS 3D transforms, typing effects, counter animations, canvas procedural art. Each beat should feel like its own visual world.

Underscore/music direction (if applicable):

• Describe the mood, reference artists, when it swells or drops
• Example: "Minimal electronic. Warm sustained pad already playing when the video starts. Sits underneath everything, never competing with VO. Swells gently during the flex section, drops to near-nothing for the comparison, resolves on a final chord."

---

Asset Audit

Before writing any beats, audit every captured asset. Print this table:

Minimum utilization:

• At least 50% of product screenshots and hero images must appear
• Brand logo appears in the first AND last beat
• The site's signature visual (gradient wave, hero illustration, key product UI) must appear — it's the most recognizable brand element
• Maximum 2 consecutive text-only beats. The 3rd must contain a visual asset
• Opening beat must contain a visual asset, not text-only

---

Per-Beat Direction

Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:

Mediocre: "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right." Great: "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment."

The first describes pixels. The second describes an experience. Write the second, then figure out the pixels.

Each beat should have:

Concept

The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it.

VO cue

Which narration line plays over this beat.

Visual description

What the viewer sees — described cinematically, not as CSS specs. Use camera language (pan, zoom, drift, settle). Describe at least 5 visual elements, not just text + background. Think in layers — what's moving in the foreground, midground, background simultaneously?

Mood direction

Cultural and design references, not hex codes:

• "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies."
• "Warm workspace. Nice notebook energy, not technical blueprint."
• "Cinematic title sequence. The kind of opening where you lean forward."

Assets

Which captured files to use, referenced by filename:

• "Background: assets/wave-fallback-desktop.png — full-bleed, slow zoom 1→1.04 over beat duration"
• "Logo: assets/svgs/stripe-logo.svg — centered, fades in at 0.5s"
• "Enterprise photo: assets/enterprise-accordion-hertz.png — Ken Burns pan, 70% opacity overlay"

Animation choreography

Specific motion verbs per element — not "it animates in" but HOW:

Every element gets a verb. If you can't name the verb, the element is not yet designed.

Transition

How this beat hands off to the next. Specify the type and parameters.

CSS transitions (choose from skills/hyperframes/references/transitions/catalog.md):

• Velocity-matched upward: exit y:-150, blur:30px, 0.33s power2.in → entry y:150→0, blur:30px→0, 1.0s power2.out
• Whip pan: exit x:-400, blur:24px, 0.3s power3.in → entry x:400→0, blur:24px→0, 0.3s power3.out
• Blur through: exit blur:20px, 0.3s → entry blur:20px→0, 0.25s power3.out
• Zoom through: exit scale:1→1.2, blur:20px, 0.2s power3.in → entry scale:0.75→1, blur:20px→0, 0.5s expo.out
• Hard cut / smash cut (for rapid-fire sequences)

Shader transitions (choose from skills/hyperframes/references/transitions/shader-transitions.md):

• Cross-Warp Morph (organic, versatile) — 0.5-0.8s, power2.inOut
• Cinematic Zoom (professional momentum) — 0.4-0.6s, power2.inOut
• Gravitational Lens (otherworldly) — 0.6-1.0s, power2.inOut
• Glitch (aggressive, high energy) — 0.3-0.5s
• See skills/hyperframes/references/transitions/shader-setup.md for the full WebGL boilerplate

How velocity-matched CSS transitions work: Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.

Depth layers

What's in foreground, midground, and background. Every beat should have at least 2 layers:

• "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right."

SFX cues

What sounds at what moment:

• "On the capture pulse — a soft, warm analog shutter click."
• "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime."

---

Production Architecture

Include this file tree at the bottom of the storyboard:

project/
├── index.html                    root — VO + underscore + beat orchestration
├── DESIGN.md                     brand reference (from Step 2)
├── SCRIPT.md                     narration text (from Step 3)
├── STORYBOARD.md                 THIS FILE — creative north star
├── transcript.json               word-level timestamps (from Step 5)
├── narration.wav                 TTS audio (from Step 5)
├── captures/<name>/              captured website data
└── compositions/
    ├── beat-1-hook.html
    ├── beat-2-features.html
    ├── ...
    └── captions.html

---

Example: Beat-by-Beat Format

Here are three beats from a production storyboard showing the level of detail expected.

BEAT 1 — COLD OPEN (0:00–0:05)

VO: "Your AI agent already knows how to make videos."

Concept: We're already in motion when the video starts. No title card, no fade from black. We're mid-flight over an infinite creative workspace — dozens of living compositions scattered below us like a city seen from a drone. Each one is alive, running a different animation. The message is clear before any words: this tool makes videos. Lots of them.

Visual: Slow smooth diagonal drift over a vast canvas (3600×2200px plane). Scattered across it: 25 composition cards at organic angles (±5-15° rotation), soft shadows, thin borders. Each card contains a DIFFERENT running animation — kinetic type, gradient morph, data viz, particle system, logo assembly, SVG drawing, shader noise, 3D rotating object. Depth-of-field: close cards slightly blurred, focal sweet-spot in mid-distance, far cards smaller and desaturated.

Camera: Diagonal drift top-left to bottom-right, slight 2-3° rotation over 5s. power1.inOut ease. Zoom accelerates in final second as we approach one specific card.

Assets: Product screenshots and logo on cards. Each card is a mini-composition with its own animation.

SFX: Ambient warmth pad already playing. Faint textured hum — overhearing creative activity from a distance.

---

BEAT 5 — THE THESIS (0:20–0:24)

VO: "Anything a browser can render can be a frame in your video."

Mood: Big statement. This sentence gets its own canvas. Clean, spacious, typographic.

Visual: Words appear as staggered kinetic typography. "Anything a browser can render" — distinctive serif, gentle fade + rise (y: 24px → 0, opacity 0 → 1, 0.4s, power2.out). Held beat — one second of stillness. "can be a frame in your video." appears below. As the final word lands, the entire text pulses once — a brief warm flash, subtle scale bump to 101%.

Transition OUT: Whip pan left — x:-400, blur:24px, opacity:0.4, 0.3s power3.in

SFX: Silence under the first line. On the capture pulse — a soft analog shutter click.

---

BEAT 7 — THE CONTRAST (0:38–0:44)

VO: "No new framework for the agent to learn. Just HTML."

Mood: Clean comparison. Light base. Two worlds side by side.

Visual: Left half: dense code, small, compressed, overwhelming. Scrolls slowly upward. Slightly desaturated. Right half: spacious HTML, syntax-highlighted, generous line spacing, inviting. On "Just HTML." — the left side folds inward along its center line, like a book closing. The right side expands to fill the frame. Warm glow rises behind it.

Transition IN: Zoom through — scale 0.75→1, blur 20px→0, 0.5s expo.out Transition OUT: Velocity-matched upward — y:-150, blur:30px, 0.33s power2.in

Assets: Real framework code on the left (actual content, not lorem ipsum). Real HyperFrames HTML on the right.

SFX: Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime as the right side expands.

Step 5: Generate VO + Map Timing

Audition voices

Never use the first voice you find. Audition 2-3 voices with the first sentence of SCRIPT.md:

• Kokoro (try first — free, no API key) — npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav. Runs locally on CPU. Requires Python 3.10+ (macOS system Python 3.9 won't work — if it fails with an onnxruntime error, move to the next option).
• ElevenLabs (best voice quality, widest selection) — mcp__elevenlabs__search_voices to browse, mcp__elevenlabs__text_to_speech to generate. Does not return timestamps — transcribe separately after.
• HeyGen TTS (returns word timestamps automatically — saves a transcribe step) — mcp__claude_ai_HeyGen__text_to_speech. Use when you want timestamps without a separate transcription pass.

Pick the voice that sounds most natural and conversational. Listen for pacing — does it breathe between sentences? Does it sound like a person or a robot?

Generate full narration

Generate the full script as narration.wav (or .mp3) in the project directory.

Transcribe for word-level timestamps

npx hyperframes transcribe narration.wav

Produces transcript.json with [{ text, start, end }] for every word. These timestamps are the source of truth for all beat durations.

Map timestamps to beats

Go through STORYBOARD.md beat by beat. For each beat:

1. Find the first word of that beat's VO cue in transcript.json 2. Find the last word of that beat's VO cue 3. Set beat.start = firstWord.start, beat.end = lastWord.end 4. Add 0.3-0.5s padding at the end for visual breathing room

Update STORYBOARD.md with real durations. Replace estimated times (e.g., "0:00-0:05") with actual timestamps (e.g., "0.00-3.21s").

Beat boundaries land on word onsets — hard cuts to the VO.

Update index.html

Update each scene slot's data-start and data-duration to match the real beat timings from the transcript. Also update the total composition duration and audio element duration.

Step 6: Build Compositions

Before building, fully re-read these files:

• DESIGN.md — your color palette, fonts, components, and Do's/Don'ts. Every composition must use EXACT hex colors and font families from this file. If it says "white backgrounds" — use white, not dark.
• STORYBOARD.md — the beat-by-beat plan you're executing. Each beat specifies assets, animations, transitions, and which techniques to use.
• `extracted/asset-descriptions.md` — when the storyboard assigns an asset to a beat, re-read the description to understand what it shows and how to position/style it correctly.
• [techniques.md](techniques.md) — code patterns for the 10 visual techniques. When the storyboard says "SVG path drawing" or "per-word kinetic typography" — read the code pattern from this file and adapt it.
• transcript.json — word-level timestamps that drive scene durations.

Split the work: spawn a sub-agent for each beat. By this step your context is full of captured data, DESIGN.md, SCRIPT, STORYBOARD, and transcript. Building compositions on top of all that means the detailed rules below compete with thousands of tokens of prior work. Each sub-agent gets a fresh context focused on one beat — dramatically better output.

How to dispatch each sub-agent:

Pass file PATHS, not file contents. The #1 failure mode is reading an asset file and pasting its SVG/image data into the sub-agent prompt. The sub-agent then uses inline content instead of referencing the file on disk. Same with fonts — pass the local woff2 path, don't substitute Google Fonts.

Build the composition for beat 1. Save to compositions/beat-1-hook.html.

STORYBOARD for this beat:
[paste the beat section from STORYBOARD.md]

ASSETS — reference by path, do NOT read/inline the file contents:
- Logo: <img src="../assets/favicon.svg"> (top-left, 40x40px)
- Hero image: <img src="../assets/hero-bg.png"> (full-bleed background)
- Noise texture: ../assets/noise.png (full-frame overlay, 3% opacity)

FONTS — use @font-face with the captured font files, NOT Google Fonts:
@font-face { font-family: 'BrandFont'; src: url('../assets/fonts/BrandFont-Regular.woff2'); }

Read DESIGN.md for exact colors and Do's/Don'ts.
Read techniques.md for animation code patterns.
Invoke /hyperframes for composition structure rules.

After each sub-agent finishes, verify the composition references ../assets/ — if it used inline SVGs or Google Fonts instead of the captured files, fix it before moving on.

Invoke the /hyperframes skill first — it has the rules for data attributes, timeline contracts, deterministic rendering, and layout. Everything below supplements those rules, not replaces them.

---

Per-Composition Process

For each beat in the storyboard:

1. Read the beat's storyboard section

Know the mood, visual description, assets, animation choreography, transition, and SFX before writing any HTML.

2. Build the static end-state first

Position every element where it should be at its most visible moment — the frame where everything is fully entered and correctly placed. Write this as static HTML+CSS. No GSAP yet.

This is the "Layout Before Animation" principle from the compose skill. The CSS position is the ground truth. Animations describe the journey to and from it.

3. Verify the static layout

Look at it. Check:

• Are elements where the storyboard says they should be?
• Are depth layers present (foreground / midground / background)?
• Do any elements overlap unintentionally?
• Are assets sized correctly? (hero images should fill 50-70% of frame, not sit at 100x100px)

4. Add entrance animations

Use gsap.from() — animate FROM offscreen/invisible TO the CSS position. The CSS position is where the element ends up.

5. Add mid-scene activity

Every visible element must have continuous motion. A still image on a still background is a JPEG with a progress bar.

6. Add exit / transition

Check the storyboard's transition specification for this beat:

• CSS transition: implement the exit animation (e.g., y:-150, blur:30px, 0.33s power2.in). The next composition handles its own entry.
• Shader transition: no exit animation needed — the shader handles the blend. Read skills/hyperframes/references/transitions/shader-setup.md for the full WebGL boilerplate and skills/hyperframes/references/transitions/shader-transitions.md for the fragment shader. Copy the FULL boilerplate — a simplified version produces black screens.
• Hard cut: no exit animation. The scene simply ends.

For all CSS transition types and their GSAP implementations, read skills/hyperframes/references/transitions/catalog.md.

7. Asset cross-reference

Before self-review, verify you actually used the assets you planned to:

1. Open STORYBOARD.md and find this beat's asset assignments 2. List every asset that was assigned to this beat 3. Search the composition HTML for each filename (e.g., grep for "wave-fallback-desktop") 4. If any assigned asset is missing from the HTML, add it now 5. Check for the inline anti-pattern: if the HTML contains <svg xmlns= or data:image/ but no ../assets/ references, the assets were inlined instead of referenced. Replace inline content with <img src="../assets/filename.svg"> 6. Check fonts: if the HTML uses fonts.googleapis.com but there are captured fonts in assets/fonts/, replace with @font-face pointing to the local files

This step catches the two most common failures: compositions ending up text-only, and assets being inlined instead of file-referenced.

8. Self-review

After building the composition, check WITH ACTUAL CODE:

• [ ] Asset cross-reference passed (step 7 above — every assigned asset is in the HTML)
• [ ] Elements are where the storyboard says they should be (no misplacement)
• [ ] No overlapping text (text covering text is always ugly)
• [ ] Depth layers present (2+ layers minimum)
• [ ] Every visible element has mid-scene activity (not just entrance + exit)
• [ ] Font sizes above minimum (20px body text, 16px labels — sub-14px is unreadable after encoding)
• [ ] No full-screen dark linear gradients (H.264 creates visible banding — use solid + localized radial glows)
• [ ] Timeline registered: window.__timelines["comp-id"] = tl
• [ ] Colors match DESIGN.md exactly (paste the HEX value, don't approximate)

If `skills/hyperframes-animation-map/` is installed, run it:

node skills/hyperframes-animation-map/scripts/animation-map.mjs <composition-dir>

Read the summaries. Fix every flag: offscreen, collision, invisible, pacing issues.

9. Move to the next composition

---

Asset Presentation

Never embed a raw flat image. Every image must have motion treatment:

• Perspective tilt: use gsap.set(el, { transformPerspective: 1200, rotationY: -8 }) + box-shadow — creates depth. Do NOT use CSS transform: perspective(...) as GSAP will overwrite it.
• Slow zoom (Ken Burns): GSAP scale: 1 → 1.04 over beat duration — makes photos cinematic
• Device frame: Wrap in a laptop/phone shape using CSS border-radius and box-shadow
• Floating UI: Extract a key element and animate it at a different z-depth for parallax
• Scroll reveal: Clip the image to a viewport window and animate y position

---

Audio Wiring

In the root index.html:

• Narration: <audio id="narration" src="narration.wav" data-start="0" data-duration="..." data-track-index="0" data-volume="1">
• Underscore/music (if storyboard specifies): <audio id="underscore" src="underscore.mp3" data-start="0" data-duration="..." data-track-index="3" data-volume="0.15">
• SFX (if storyboard specifies): individual <audio> elements at specific data-start timestamps
• Captions (optional — only if user requests): sub-composition on a parallel track. Skip unless explicitly asked for.

---

Critical Rules

These exist because the capture engine is deterministic. Violations produce broken output.

• No `repeat: -1` — calculate exact repeats from beat duration
• No `Math.random()` — use a seeded PRNG (mulberry32)
• Register every timeline: window.__timelines["comp-id"] = tl
• Synchronous timeline construction — no async/await wrapping timeline code
• Never use ANY CSS `transform` for centering — not translate(-50%, -50%), not translateX(-50%), not translateY(-50%). GSAP animates the transform property, which overwrites ALL CSS transforms including centering. The element flies offscreen. Use flexbox centering instead: display:flex; align-items:center; justify-content:center on a wrapper div. The linter catches this (gsap_css_transform_conflict) but only if you run it.
• Minimum font sizes: 20px body, 16px labels
• No full-screen dark linear gradients — H.264 banding

Step 7: Validate & Deliver

Lint + Validate

Run in sequence. Fix all errors before proceeding to the next command.

npx hyperframes lint
npx hyperframes validate

lint checks HTML structure statically — missing attributes, timeline registration, tween conflicts, CSS transform + GSAP conflicts (including inline styles). validate loads the composition in headless Chrome and catches runtime JS errors, missing assets, and failed network requests.

Visual Verification (snapshot)

After lint and validate pass, capture snapshot frames to SEE your own output:

npx hyperframes snapshot <project-dir> --at <beat-midpoints>

If the snapshot command isn't available, fall back to:

npx tsx packages/cli/src/cli.ts snapshot <project-dir> --at <beat-midpoints>

Calculate the midpoint of each beat from your STORYBOARD.md timings. For a 4-beat video with beats at 0-5.8s, 5.8-15.0s, 15.0-22.5s, 22.5-25.3s:

npx hyperframes snapshot <project-dir> --at 2.9,10.4,18.7,23.9

This renders one frame per beat at the moment when content is most visible. Use timestamps where the most content is on screen — usually 60-70% into each beat, after entrances finish but before exits start.

View every snapshot image carefully. Don't glance and move on. For each frame, check:

Visibility:

• Is there visible content? All-white or all-black frames mean compositions aren't rendering.
• Can you read ALL text? White text on white/light background is invisible. Dark text on dark background is invisible. Every text element needs contrast against what's directly behind it.
• Are images and assets showing? Empty space where an image should be means a path issue or missing file.

Positioning and layout:

• Do background images fill the entire frame? If an image only covers half the screen, the object-fit, width, height, or position values are wrong.
• Are elements where the storyboard says they should be? Compare the snapshot to the beat description.
• Is there too much empty/dead space? If more than 40% of the frame is a flat solid color with nothing on it, the composition is sparse.
• Are elements overlapping incorrectly? Text over text, or content bleeding off the edges?

Visual quality:

• Are overlays too heavy? If a background image is barely visible through a dark overlay, reduce the overlay opacity.
• Is the visual hierarchy clear? One dominant element per frame, supporting elements secondary.
• Do the colors match DESIGN.md? Check actual rendered colors against what was planned.

Code vs. rendered verification:

• For each beat, check: does the snapshot show the assets you referenced in the HTML? If a composition has <img src="...wave.png"> but the snapshot shows no wave — the image isn't loading, the path is wrong, or it's hidden behind another element.
• If a snapshot shows nothing at a timestamp, try a slightly different time (1-2 seconds later). Compositions may still be in entrance animations.
• The snapshot command is fast — run it multiple times at different timestamps if needed.

If any frame has issues, go back to Step 6 and fix that composition before proceeding.

Preview

npx hyperframes preview

Open the studio in a browser. Scrub through every beat.

Create HANDOFF.md

Write a HANDOFF.md for multi-session continuity:

# Handoff — [Project Name]

**Date:** [today]
**Preview:** `npx hyperframes preview`

## What's Built

| Beat | File                 | Dur  | Status | Notes |
| ---- | -------------------- | ---- | ------ | ----- |
| 1    | beat-1-hook.html     | 5.2s | Built  | ...   |
| 2    | beat-2-features.html | 6.8s | Built  | ...   |

## Audio

| Asset           | Status | Notes                                |
| --------------- | ------ | ------------------------------------ |
| narration.wav   | Done   | [provider], [voice name], [duration] |
| transcript.json | Done   | [word count] words, [duration]       |

## What Needs Work

- [any known issues, polish requests, missing SFX]

## Commands

npx hyperframes preview
npx hyperframes lint
npx hyperframes validate
npx hyperframes snapshot <project-dir> --at <beat-midpoints>
npx hyperframes render --output renders/final.mp4

Visual Techniques Reference

10 proven techniques from production HyperFrames videos. Use these in your storyboard and compositions to create visually rich, professional output. Each technique includes a minimal code pattern you can adapt.

These are NOT advanced — they're standard motion design patterns that every composition should use at least 2-3 of.

---

1. SVG Path Drawing

A path draws itself in real-time, like someone tracing with a pen. Use for revealing diagrams, arrows, connector lines, or brand marks.

<svg viewBox="0 0 400 200">
  <path
    class="draw-path"
    d="M 50 100 L 200 50 L 350 100"
    stroke="#c84f1c"
    stroke-width="4"
    fill="none"
    stroke-linecap="round"
  />
</svg>
<style>
  .draw-path {
    stroke-dasharray: 280;
    stroke-dashoffset: 280;
  }
</style>
<script>
  tl.to(".draw-path", { strokeDashoffset: 0, duration: 0.7, ease: "power2.out" }, 0.5);
</script>

Use path.getTotalLength() to calculate the dasharray value dynamically.

---

2. Canvas 2D Procedural Art

Animated noise, particle fields, data visualizations — anything that evolves frame-by-frame. Drive it with a GSAP proxy.

<canvas id="proc-canvas" width="1920" height="1080"></canvas>
<script>
  var canvas = document.getElementById("proc-canvas");
  var ctx = canvas.getContext("2d");

  function hash(x, y) {
    var n = x * 374761393 + y * 668265263;
    n = (n ^ (n >> 13)) * 1274126177;
    return ((n ^ (n >> 16)) & 0x7fffffff) / 0x7fffffff;
  }

  function drawFrame(t) {
    ctx.fillStyle = "#0a0a0a";
    ctx.fillRect(0, 0, 1920, 1080);
    for (var i = 0; i < 200; i++) {
      var x = hash(i, 0) * 1920;
      var y = hash(i, 1) * 1080;
      var brightness = hash(i, Math.floor(t * 10)) * 255;
      ctx.fillStyle = "rgba(255, 255, 255, " + brightness / 255 + ")";
      ctx.beginPath();
      ctx.arc(x, y, 2, 0, Math.PI * 2);
      ctx.fill();
    }
  }

  var proxy = { time: 0 };
  tl.to(
    proxy,
    {
      time: 5,
      duration: 5,
      ease: "none",
      onUpdate: function () {
        drawFrame(proxy.time);
      },
    },
    0,
  );
</script>

The hash() function is deterministic — same frame renders identically every time.

---

3. CSS 3D Transforms

Perspective rotations create depth. Use for product showcases, card flips, architectural reveals.

<div class="stage" style="perspective: 900px;">
  <div class="card-3d" style="transform-style: preserve-3d;">
    <div class="face front">Product</div>
    <div class="face back" style="transform: rotateY(180deg);">Details</div>
  </div>
</div>
<script>
  tl.to(".card-3d", { rotationY: 360, rotationX: 15, duration: 1.2, ease: "sine.inOut" }, 0);
</script>

Always set perspective on the parent, transform-style: preserve-3d on the animated element.

---

4. Per-Word Kinetic Typography

Words appear one-by-one, synced to transcript.json timestamps. The core technique for narration-driven videos.

<div class="headline">
  <span class="word w-0">Anything</span>
  <span class="word w-1">a</span>
  <span class="word w-2">browser</span>
  <span class="word w-3">can</span>
  <span class="word w-4">render</span>
</div>
<style>
  .word {
    display: inline-block;
    opacity: 0;
    margin: 0 0.12em;
  }
</style>
<script>
  // Word onset times from transcript.json (seconds relative to beat start)
  var timings = [0.0, 0.23, 0.28, 0.63, 0.78];
  var slides = [80, 60, 50, 25, 12]; // horizontal slide decay (px)

  document.querySelectorAll(".word").forEach(function (word, i) {
    tl.from(
      word,
      {
        x: slides[i],
        y: 14,
        opacity: 0,
        duration: 0.35,
        ease: "power2.out",
      },
      timings[i],
    );
  });
</script>

The slide distance DECAYS per word (80→12px) — mimics a camera settling.

---

5. Lottie Animation

Vector animations that play inside a composition. Use for logos, character animations, icons.

<script src="https://cdn.jsdelivr.net/npm/@dotlottie/player-component@2.7.12/dist/dotlottie-player.js"></script>
<dotlottie-player
  class="lottie"
  src="../assets/lottie/animation-0.json"
  autoplay
  loop
  speed="1.5"
  style="width:500px;height:500px;"
>
</dotlottie-player>
<script>
  gsap.set(".lottie", { scale: 0.3, opacity: 0 });
  tl.to(".lottie", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);
</script>

Or use lottie-web for more control:

var anim = lottie.loadAnimation({
  container: document.getElementById("anim"),
  renderer: "svg",
  loop: false,
  autoplay: false,
  path: "../assets/lottie/animation-0.json",
});

---

6. Video Compositing

Embed real video footage inside compositions. Videos must be muted with playsinline.

<div class="video-frame" style="width:680px;height:840px;border-radius:16px;overflow:hidden;">
  <video
    id="footage"
    src="../assets/videos/clip.mp4"
    muted
    playsinline
    style="width:100%;height:100%;object-fit:cover;"
  ></video>
</div>
<script>
  // Video playback is controlled by the framework — don't call play() manually
  tl.from(".video-frame", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.out" }, 0);
</script>

The HyperFrames runtime handles video seeking and playback.

---

7. Character-by-Character Typing

Terminal typing effect using tl.call() to update text content character by character.

<div class="terminal-line">
  <span class="prompt">❯</span>
  <span class="typed" id="typed-text"></span>
  <span class="cursor" style="width:11px;height:22px;background:#333;display:inline-block;"></span>
</div>
<script>
  var CMD = "npx hyperframes init";
  var typed = document.getElementById("typed-text");

  // Cursor blinks
  tl.to(".cursor", { opacity: 0, duration: 0.12, yoyo: true, repeat: 20, ease: "steps(1)" }, 0);

  // Type each character
  for (var i = 0; i < CMD.length; i++) {
    (function (idx) {
      tl.call(
        function () {
          typed.textContent = CMD.substring(0, idx + 1);
        },
        null,
        (idx / CMD.length) * 0.9,
      );
    })(i);
  }
</script>

Use ease: "steps(1)" for cursor blink — creates discrete on/off.

---

8. Variable Font Axis Animation

Animate font-variation-settings to reshape glyphs in real-time. Works with variable fonts that have axes like optical size (opsz), weight (wght), softness (SOFT).

<style>
  @import url("https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,100..900&display=block");
  .wordmark {
    --opsz: 144;
    --wght: 440;
    font-family: "Fraunces", serif;
    font-variation-settings:
      "opsz" var(--opsz),
      "wght" var(--wght);
    font-size: 200px;
  }
</style>
<script>
  tl.to(".wordmark", { "--opsz": 72, "--wght": 300, duration: 0.45, ease: "power2.out" }, 0);
</script>

The glyph subtly reshapes as axes animate — optical size adjusts detail, weight changes thickness.

---

9. GSAP MotionPathPlugin

Animate an element along an arbitrary SVG path. Use for sliders following curves, particles along trajectories, guided reveals.

<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/MotionPathPlugin.min.js"></script>
<div class="dot" style="width:20px;height:20px;background:#2a8a7c;border-radius:50%;"></div>
<script>
  gsap.registerPlugin(MotionPathPlugin);
  tl.to(
    ".dot",
    {
      motionPath: { path: "M 12 300 C 280 280 520 80 820 50 S 1200 48 1308 38" },
      duration: 1.5,
      ease: "power2.out",
    },
    0,
  );
</script>

---

10. Velocity-Matched Transitions

Exit one beat and enter the next with matched velocities — creates perceived continuous motion.

// EXIT (in outgoing composition): accelerating with blur
tl.to(
  ".content",
  {
    y: -150,
    filter: "blur(30px)",
    opacity: 0,
    duration: 0.33,
    ease: "power2.in", // accelerates
  },
  beatDuration - 0.33,
);

// ENTRY (in incoming composition): decelerating from blur
gsap.set(".content", { y: 150, filter: "blur(30px)" });
tl.to(
  ".content",
  {
    y: 0,
    filter: "blur(0px)",
    duration: 1.0,
    ease: "power2.out", // decelerates
  },
  0,
);

The fastest point of both curves meets at the cut — the viewer perceives smooth camera motion. Match ease families: .in for exits, .out for entries.

---

When to Use What