HyperFrames — Video Composition Authoring#

Write HTML. Render video. Built for agents.

HyperFrames is an open-source video rendering framework where HTML is the source of truth. A composition is an HTML file with data-* attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync.

Requirements: Node.js >= 22, FFmpeg Install: \Created my-video/ AGENTS.md CLAUDE.md hyperframes.json index.html meta.json package.json

Get started:

Install AI coding skills (one-time): npx skills add heygen-com/hyperframes
Open this project with your AI coding agent: cd my-video then start Claude Code, Cursor, or your preferred agent
Try a starter prompt: "Using /hyperframes, create a 15-second intro about [your topic]" More patterns: hyperframes.heygen.com/guides/prompting
Preview in the browser: cd my-video && npm run dev
Check the composition: cd my-video && npm run check
Render to MP4 when ready: cd my-video && npm run render

Full docs: hyperframes.heygen.com License: Apache 2.0 (fully open source)

Core Concepts#

The Composition Model#

Every video is a composition — an HTML document with a root element identified by . Inside it, clips (video, audio, img, div elements) are placed on tracks using . Each clip has a and in seconds. The composition has explicit and in pixels.

Data Attributes Reference#

All Clips#

Attribute	Required	Values
uid=501(salmanqureshi) gid=20(staff) groups=20(staff),12(everyone),61(localaccounts),79(_appserverusr),80(admin),81(_appserveradm),98(_lpadmin),33(_appstore),100(_lpoperator),204(_developer),250(_analyticsusers),395(com.apple.access_ftp),398(com.apple.access_screensharing),399(com.apple.access_ssh),400(com.apple.access_remote_ae),701(com.apple.sharepoint.group.1)	Yes	Unique identifier
	Yes	Seconds or clip ID reference (, )
	Required for img/div/compositions	Seconds. Video/audio defaults to media duration.
	Yes	Integer. Same-track clips cannot overlap.
	No	Trim offset into source (seconds)
	No	0-1 (default 1)

does not affect visual layering — use CSS .

Composition Root#

Attribute	Required	Values
	Yes	Unique composition ID
/	Yes	Pixel dimensions (1920x1080 or 1080x1920)
	No	Path to external HTML file for sub-compositions
	No	JSON object of per-instance variable overrides

Root HTML Element#

Attribute	Values
	JSON array of declared variables for parametrized renders

Step-by-Step: Building a Video#

Discovery Phase (Exploratory Requests Only)#

For open-ended requests ("make a product launch video") where no direction is given, understand intent first:

Audience — who watches? Developers? Executives? General consumers?
Platform — where does it play? Social (15s), website hero, product demo, internal?
Priority — what matters most? Motion quality? Content accuracy? Brand fidelity? Speed?
Variations — offer 2-3 options differing in pacing, energy, or structure.

For specific requests ("add a title card", "fix timing on scene 3"), skip discovery.

Step 1: Design System#

If design.md or DESIGN.md exists in the project, read it first. It defines brand colors, fonts, and constraints. Use exact values — don't invent colors or substitute fonts.

If fonts are named but no fonts/ directory with .woff2 files exists, warn the user.

If no design.md exists, ask:

Named a style or mood? Pick from visual style presets.
Want to browse? Serve a design picker page.
Skip and go fast? Ask: mood, light/dark, brand colors/fonts.

Step 2: Layout Before Animation#

Build the end-state first. Position every element where it should be at its most visible moment. Write as static HTML+CSS. No GSAP yet.

The process:

Identify the hero frame for each scene.
Write static CSS for that frame. The .scene-content container MUST fill the full scene: width:100%; height:100%; padding:Npx; display:flex; flex-direction:column; gap:Npx; box-sizing:border-box. Use padding to push content inward — NEVER position:absolute; top:Npx on a content container.
Add entrances with gsap.from() — animate FROM offscreen/invisible TO the CSS position.
Add exits with gsap.to() — animate TO offscreen/invisible FROM the CSS position.

.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title { font-size: 120px; }
.subtitle { font-size: 42px; }

const tl = gsap.timeline({ paused: true });
// Entrances
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
// Exits
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);

Step 3: Composition Structure#

Standalone compositions (main index.html): Put the data-composition-id div directly in <body>. No <template> wrapper.

Sub-compositions loaded via data-composition-src use a <template> wrapper:

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <style>
      [data-composition-id="my-comp"] { /* scoped styles */ }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

Load in root: <div data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

Step 4: Variables (Parametrized Compositions)#

Render the same composition with different content without editing source HTML.

Three-step pattern:

Declare variables on <html> with data-composition-variables:

<html data-composition-variables='[
  {"id":"title","type":"string","label":"Title","default":"Hello"},
  {"id":"theme","type":"enum","label":"Theme","default":"light","options":[
    {"value":"light","label":"Light"},
    {"value":"dark","label":"Dark"}
  ]}
]'>

Read inside the composition script:

const { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;

Override at render time:

npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4

Sub-composition per-instance values:

<div data-composition-id="card-pro" data-composition-src="compositions/card.html"
     data-variable-values='{"title":"Pro","price":"$29"}'></div>

Types supported: string, number, color, boolean, enum.

Advanced Topics#

Scene Transitions#

Transitions between scenes use the shader-transitions package or CSS approaches:

Transition	Method
Crossfade	GSAP opacity cross between scenes
Wipe	CSS clip-path animation
Slide reveal	GSAP `x` or `y` transforms
Flash through white	Shader transition via catalog
Shader dissolve	WebGL via `@hyperframes/shader-transitions`

Install transitions: npx hyperframes add flash-through-white

Captions & Subtitles#

Generate word-level captions synced to audio:

Generate narration: npx hyperframes tts "Your script" --voice af_heart --output narration.wav
Transcribe: npx hyperframes transcribe narration.wav (produces transcript.json)
Use in composition: Reference the transcript for word-level caption animation with GSAP stagger.

Text-Behind-Subject (Presenter Behind Headline)#

Two key rules:

Wrap the cutout video in a non-timed <div> and animate the wrapper's opacity, not the video element.
Both videos use data-start="0" and data-media-start="0" for frame-accurate sync.

<video src="presenter.mp4" id="bg" data-start="0" data-duration="6" data-track-index="0" muted playsinline></video>
<h1 id="headline" style="z-index:2;">MAKE IT IN HYPERFRAMES</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
  <video src="presenter.webm" data-start="0" data-duration="6" data-track-index="1" muted playsinline></video>
</div>

Animating with Frame Adapters#

Adapter	Registration	Notes
GSAP	`window.__timelines["comp-id"] = tl`	Paused timeline, `paused:true`
Anime.js	`window.__hfAnime`	Registered animations on global
CSS Animations	Automatic discovery	Browser pauses/resumes keyframes
Lottie	`window.__hfLottie`	`lottie-web` or dotLottie players
Three.js	`window.__hfThreeTime`	Uses seek events, not wall-clock
WAAPI	`document.getAnimations()`	Standard Web Animations API

Color Themes & Palettes#

When no design.md exists, offer mood-based presets:

Mood	Theme	Palette
Professional	Light, clean	Slate blues, whites, accent teal
Energetic	Dark, vibrant	Deep navy, bright cyan, amber accents
Warm	Cream/beige	Warm grays, terracotta, gold
Tech-forward	Dark mode	Near-black, electric blue, neon green
Minimal	Light, ample space	White, light gray, single accent
Luxury	Dark, rich	Charcoal, gold, deep burgundy
Playful	Bright, colorful	Pastels, saturated primaries
Cinematic	Dark, high contrast	Black, white, single saturated color

Common Patterns#

Product Intro (10s)#

<div data-composition-id="product-intro" data-width="1920" data-height="1080">
  <div class="scene-content">
    <h1 class="title">Product Name</h1>
    <p class="subtitle">The next generation of productivity</p>
  </div>
  <style>
    .scene-content { display:flex; flex-direction:column; justify-content:center; align-items:center; width:100%; height:100%; padding:120px; gap:24px; box-sizing:border-box; background:linear-gradient(135deg,#0f0c29,#302b63,#24243e); color:white; font-family:system-ui,sans-serif; }
    .title { font-size:120px; font-weight:800; margin:0; }
    .subtitle { font-size:42px; opacity:0.8; margin:0; }
  </style>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
  <script>
    window.__timelines = window.__timelines || {};
    const tl = gsap.timeline({paused:true});
    tl.from(".title", {y:80,opacity:0,duration:0.8,ease:"power3.out"}, 0);
    tl.from(".subtitle", {y:40,opacity:0,duration:0.6,ease:"power3.out"}, 0.3);
    tl.to(".title", {y:-40,opacity:0,duration:0.5,ease:"power2.in"}, 8);
    tl.to(".subtitle", {y:-30,opacity:0,duration:0.4,ease:"power2.in"}, 8.2);
    window.__timelines["product-intro"] = tl;
  </script>
</div>

Animated Bar Chart Race (from CSV)#

Use HTML tables or SVG bars with GSAP stagger animations. Each bar's height animates from 0 to its data value.

TikTok-Style Hook (9:16, 15s)#

Use data-width="1080" data-height="1920" for vertical format. Bouncy captions synced to TTS, fast cuts, bold text.

Best Practices#

Build the end-state first — position all elements at their hero frame before adding GSAP.
Lint before rendering — npx hyperframes lint catches missing IDs, overlapping tracks, unregistered timelines.
Inspect visually — npx hyperframes inspect seeks through the timeline and reports text spilling off-canvas.
Use draft quality while iterating — --quality draft for fast iterations, standard for review, high for final delivery.
FPS tradeoff — 30fps default is sufficient for most content. 60fps doubles render time.
Run npx hyperframes doctor if rendering fails — checks for Chrome, FFmpeg, Node version, and memory.
Consistent timing — sub-comps loaded via data-composition-src mount at data-start; ensure data-media-start="0" for frame-accurate sync.
Test both preview and render — browser preview is not byte-identical to headless Chrome render.
Docker for reproducibility — --docker flag ensures byte-identical output across machines.

Prompt Examples for AI Agents#

Cold start (describe what you want):

Using the hyperframes skill, create a 10-second product intro with a fade-in title, a background video, and background music.

Warm start (turn context into video):

Take this GitHub repo and explain its uses and architecture to me using a hyperframes video.

Summarize this PDF into a 45-second pitch video.

Turn this CSV into an animated bar chart race.

Format-specific:

Make a 9:16 TikTok-style hook video about AI agents, with bouncy captions synced to TTS narration.

Iteration (talk to the agent like a video editor):

Make the title 2x bigger, swap to dark mode, and add a fade-out at the end.

Add a lower third at 0:03 with my name and title.

Troubleshooting#

Issue	Solution
`npx hyperframes` not found	Node.js >= 22 required
FFmpeg not found	Install via `brew install ffmpeg` or `apt install ffmpeg`
Chrome issues	Run `npx hyperframes browser` to manage bundled Chrome
Render fails	Run `npx hyperframes doctor` for diagnostics
Lint errors	Fix missing `data-composition-id`, overlapping tracks, unregistered timelines
Inspect warnings	Check text overflow, clipping containers, off-canvas elements
Version check	`npx hyperframes info` or `npx hyperframes upgrade`

Skill	Purpose
`hyperframes-cli`	CLI dev loop — init, lint, inspect, preview, render, doctor
`hyperframes-media`	Asset preprocessing — TTS, transcribe, background removal

HyperFrames — Video Composition Authoring

HyperFrames — Video Composition Authoring#

Core Concepts#

The Composition Model#

Data Attributes Reference#

All Clips#

Composition Root#

Root HTML Element#

Step-by-Step: Building a Video#

Discovery Phase (Exploratory Requests Only)#

Step 1: Design System#

Step 2: Layout Before Animation#

Step 3: Composition Structure#

Step 4: Variables (Parametrized Compositions)#

Advanced Topics#

Scene Transitions#

Captions & Subtitles#

Text-Behind-Subject (Presenter Behind Headline)#

Animating with Frame Adapters#

Color Themes & Palettes#

Common Patterns#

Product Intro (10s)#

Animated Bar Chart Race (from CSV)#

TikTok-Style Hook (9:16, 15s)#

Best Practices#

Prompt Examples for AI Agents#

Troubleshooting#

More in Development

HyperFrames Media Preprocessing

HyperFrames CLI — Dev Loop

API Documentation

HyperFrames — Video Composition Authoring#

Core Concepts#

The Composition Model#

Data Attributes Reference#

All Clips#

Composition Root#

Root HTML Element#

Step-by-Step: Building a Video#

Discovery Phase (Exploratory Requests Only)#

Step 1: Design System#

Step 2: Layout Before Animation#

Step 3: Composition Structure#

Step 4: Variables (Parametrized Compositions)#

Advanced Topics#

Scene Transitions#

Captions & Subtitles#

Text-Behind-Subject (Presenter Behind Headline)#

Animating with Frame Adapters#

Color Themes & Palettes#

Common Patterns#

Product Intro (10s)#

Animated Bar Chart Race (from CSV)#

TikTok-Style Hook (9:16, 15s)#

Best Practices#

Prompt Examples for AI Agents#

Troubleshooting#

Related Skills#

More in Development

HyperFrames Media Preprocessing

HyperFrames CLI — Dev Loop

API Documentation