The Pipeline

The 7-step pipeline for producing any Hyperframes video: capture, design, strategy & messaging, storyboard + script, voiceover, build, validate.

Every well-structured Hyperframes video flows through the same 7 steps, whether it starts from a website, a PDF, a CSV, or a blank page. Each step produces a named artifact that the next step depends on, so your AI agent (and you) always know what’s done, what’s next, and where the creative decisions live on disk.

This pipeline is the backbone of the website-to-video workflow, but it’s just as useful when you’re scripting a brand reel from scratch, turning research notes into a launch teaser, or learning Hyperframes for the first time. Most of the production-grade launch videos HeyGen ships are organized this way.

The seven steps

Each step produces an artifact that feeds the next:

#	Step	Output	What happens
1	Capture	capture/	Extract screenshots, design tokens, fonts, assets, animations from a source
2	Design	DESIGN.md	Brand reference: colors, typography, component stylings, spacing, iteration guide
3	Strategy & Messaging	—	Align on video type, style, the ONE message, narrative arc, and audience
4	Storyboard + Script	STORYBOARD.md + SCRIPT.md	Concept-first storyboard and narration script, written together
5	VO + Timing	narration.wav + transcript.json	TTS audio with word-level timestamps
6	Build	compositions/*.html	Animated HTML compositions, one per beat
7	Validate	Snapshot PNGs + lint/validate pass	Visual verification and runtime checks before delivery

Not every project uses every step. A no-narration brand reel skips Step 5; a hand-authored composition skips Steps 1-2. But the order matters: scene durations come from narration, animation choices come from the storyboard, and the storyboard depends on the design reference. Skip a step only when you don’t need its artifact downstream.

Project layout

A typical project directory after the pipeline runs:

my-video/
├── capture/                    # Step 1, only present when capturing a source
│   ├── screenshots/            # scroll-000.png, scroll-001.png, …
│   ├── assets/                 # downloaded images, SVGs, fonts
│   ├── extracted/              # tokens.json, visible-text.txt, asset-descriptions.md
│   ├── AGENTS.md               # capture summary for AI agents
│   └── CLAUDE.md
├── DESIGN.md                   # Step 2, brand cheat sheet
├── SCRIPT.md                   # Step 3, narration backbone
├── STORYBOARD.md               # Step 4, beat-by-beat creative plan
├── narration.wav               # Step 5, TTS audio
├── narration.txt               # Step 5, exact spoken text (with pronunciation subs)
├── transcript.json             # Step 5, word-level timestamps
├── compositions/               # Step 6, one HTML file per beat
│   ├── beat-1-hook.html
│   ├── beat-2-story.html
│   └── …
├── snapshots/                  # Step 7, visual verification PNGs
├── renders/                    # optional final MP4 outputs
└── index.html                  # root project file wiring compositions into a timeline

Capture artifacts stay in capture/ so they’re cleanly separated from the build outputs. Everything downstream lives at the project root.

Step 1: Capture

Output: capture/

When the video is grounded in an existing source (a website, a brand site, a competitor reference), start with capture. Hyperframes ships a built-in capture command for websites:

npx hyperframes capture https://example.com -o my-video/capture

This extracts screenshots at every scroll depth, pixel-sampled color palettes, the CSS font stack (and downloaded woff2 files), images and SVGs with semantic names, Lottie animations, and detected animations on the page. Optional Gemini vision enrichment adds AI-powered descriptions of every captured asset.

For sources that aren’t websites (PDFs, decks, CSVs, notes), capture isn’t a literal command. It’s the step where you gather assets into capture/ so later steps can reference paths instead of inlining content.

Gate: You can describe the source’s visual identity in one or two sentences and name its top colors, fonts, and standout assets.

Step 2: Design

Output: DESIGN.md in the project root

DESIGN.md is the brand cheat sheet. It encodes the visual identity factually so every downstream decision can reference exact colors, fonts, and components instead of inventing them. It’s a reference document, not a creative plan. The creative work happens in the storyboard.

A typical DESIGN.md has five sections:

Section	What it captures
Visual Theme	3-5 sentences describing the brand’s visual personality — dark/light, contrast, mood, what makes it distinctive
Quick Reference	Colors (8-12 HEX values with semantic roles and WCAG contrast ratios) and fonts (families, weights, roles, file paths)
Component Stylings	Exact CSS-level specs for 6-12 components the brand uses: buttons, cards, containers, distinctive UI patterns
Spacing & Layout	Base spacing unit, scale with usage, max-width / grid, and breakpoint strategy
Iteration Guide	Do’s and don’ts, common failure modes, and rules for modifying the design in later steps

DESIGN.md is also the input format for Open Design and Claude Design; both produce a DESIGN.md you can drop into a Hyperframes project.

Gate: DESIGN.md exists with all five sections filled in from real captured data (or chosen deliberately for greenfield projects).

Step 3: Strategy & Messaging

Output: Alignment on video type, duration, style, and — critically — the ONE message and narrative arc

Before any creative decisions, align with the user on the story this video must tell. Parse the user’s prompt first — they probably already gave you the video type and style. Only ask about things they didn’t specify. If the prompt is detailed enough, confirm the direction in one message and move to Step 4.

The questions to resolve: what type of video (social ad, product demo, brand reel, etc.), what style and energy, what’s the ONE thing this video must communicate, what narrative arc serves that message, and whether narration is wanted.

Gate: Video type, duration, format, and the message and narrative arc are locked. Without those, Step 4 can’t write a concept-first storyboard.

Step 4: Storyboard + Script

Outputs: STORYBOARD.md + SCRIPT.md in the project root

Write the storyboard concept-first: message → narrative arc → beats that serve the arc → techniques per beat → brand accents pass at the end. Then write the narration script to match. The storyboard and script are written together — the storyboard drives the script, not the other way around.

STORYBOARD.md tells the engineer (human or agent) exactly what to build for each beat: mood, camera, animations, transitions, assets, depth layers, sound effects. It’s where the creative choices get pinned down.

Each beat in STORYBOARD.md typically covers:

Field	What it specifies
Timing	0.0s - 5.8s, taken from transcript.json once Step 5 runs
Narration line	The exact words spoken during this beat
Mood & camera	One sentence describing the feel and the shot
Assets	Which captured images, icons, and fonts go in this beat, referenced by path
Techniques	2-3 picks from the techniques library: SVG path drawing, Canvas 2D, CSS 3D, per-word typography, Lottie, video compositing, typing effects, variable fonts, MotionPath, velocity transitions, audio-reactive
Transitions	How this beat enters from the previous one and exits to the next
SFX	Short, specific sound effects (e.g. “woosh on logo entry, soft tick on counter”)

The storyboard typically opens with a global-direction block: format, voiceover direction, style basis, and guardrails that apply to every beat. SCRIPT.md contains the narration backbone: hook (one sentence that earns attention), story (what the product or topic is), proof (numbers, components, customers), CTA (one clear action). For videos without narration, SCRIPT.md becomes a per-beat copy plan with on-screen text and timing notes.

Gate: STORYBOARD.md + SCRIPT.md exist with beat-by-beat direction, an asset audit that names every file used, and user approval of the plan.

Step 5: VO and timing

Outputs: narration.wav (or .mp3), narration.txt, transcript.json

Generate the TTS narration, then transcribe it for word-level timestamps. Those timestamps are the source of truth for every beat duration downstream.

npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav
npx hyperframes transcribe narration.wav

File	What it contains
narration.wav	The TTS audio that ships with the final render
narration.txt	The exact spoken text with pronunciation substitutions applied (API → A P I, $2T → two trillion). Distinct from SCRIPT.md so you can regenerate the audio later with a different voice without redoing the substitutions.
transcript.json	[{ text, start, end }] for every word. Every later step reads this for timing.

Hyperframes ships multiple TTS adapters (Kokoro, ElevenLabs, HeyGen); see /media-use for the skill that picks one. After generating audio, update STORYBOARD.md with the real beat boundaries from transcript.json.

Gate: narration.wav, narration.txt, and transcript.json exist. STORYBOARD.md beat timings reference real timestamps, not estimates.

Step 6: Build

Output: compositions/<beat-name>.html, one HTML file per beat

This is where the storyboard becomes runnable HTML. Each composition is a self-contained file that imports captured assets by path, uses the exact colors and fonts from DESIGN.md, and animates with the techniques the storyboard picked.

For multi-beat videos, spawn a focused sub-agent per beat. Each one gets fresh context, the storyboard section for its beat, the asset paths it needs, and the relevant technique references. That produces noticeably better output than building every beat in one long-running context.

After each composition is built, run a self-review for layout, asset placement, and animation quality. The /hyperframes-core skill encodes the composition rules — required class="clip" attributes, data-* attribute semantics — and /hyperframes-animation covers GSAP timeline registration and adapter registries.

Gate: Every composition is self-reviewed. No overlapping elements, no misplaced assets, no static images sitting unanimated.

Step 7: Validate

Outputs: snapshots/frame-*.png, lint and validate passing with zero errors

Three checks before delivery:

npx hyperframes lint                              # static HTML structure checks
npx hyperframes validate                          # loads in headless Chrome, catches runtime errors
npx hyperframes snapshot my-video --at 2.9,10.4   # PNGs at beat midpoints

lint catches missing attributes, timeline registration issues, tween conflicts, and CSS-transform vs. GSAP conflicts. validate loads each composition in headless Chrome and surfaces runtime JS errors, missing assets, and failed network requests. snapshot captures frames at specific timestamps so you can see your output without a full render.

The pipeline delivers the localhost Studio URL as the handoff. Your AI agent runs npx hyperframes preview and shares the project URL. Rendering to MP4 is on-demand:

npx hyperframes render --output my-video.mp4

For personalized or catalog outputs, render the same validated composition with --batch rows.json --output "renders/{name}.mp4" and use the generated manifest.json as the delivery checklist.

Gate: lint and validate pass with zero errors. Snapshot frames look right. The Studio preview URL is ready to share.

Iterating

The pipeline is built around named artifacts on disk so you can re-enter anywhere without re-running everything:

• To rework the creative plan, edit STORYBOARD.md: change a beat’s mood, swap an asset, retime the entrance, then ask the agent to rebuild just that beat.
• For surgical tweaks, open a composition file directly (e.g. compositions/beat-3-proof.html) and adjust animations, colors, or layout. npx hyperframes preview shows changes live.
• To rebuild one beat from scratch, prompt the agent: “Rebuild beat 2 with more energy. Use the product screenshot as full-bleed background.” It reads STORYBOARD.md, DESIGN.md, and the transcript, then regenerates just that file.
• To swap the voice without redoing Step 3, re-run TTS against narration.txt, which already has the pronunciation substitutions baked in.

Each artifact is a checkpoint, so you can stop, hand off to a human reviewer, or come back tomorrow and the agent still has everything it needs to keep going.

When to use the pipeline

The pipeline is the recommended structure for:

• Capturing a website with the /website-to-video skill, which follows it end-to-end.
• Shipping a product launch. Most of the HeyGen launch videos use this artifact layout.
• Any narrative video with three or more beats, where a storyboard pays for itself.
• Learning Hyperframes, because the artifacts leave every creative decision inspectable on disk.

For a 5-second one-shot animation, a single hand-authored composition is fine; the pipeline is overhead you don’t need. The rough cutoff: if a non-author needs to understand why a beat looks the way it does, write it down in STORYBOARD.md.

Next steps

Website to Video

The full website-to-video workflow built on this pipeline.

Prompting

How to invoke the pipeline through your AI agent.

Launch Videos

Real production projects organized around this pipeline.

CLI Reference

Every command the pipeline calls.