Quickstart - HyperFrames

Go from zero to a rendered MP4 — either by prompting your AI agent or by starting a project manually.

Option 1: With an AI coding agent (recommended)

Install the HyperFrames skills, then describe the video you want:

npx skills add heygen-com/hyperframes

The installer shows a picker. Select the core set every project needs — these register as slash commands in Claude Code (Cursor, Gemini CLI, Codex, Google Antigravity, and GitHub Copilot CLI load them too):

Core skill (install all)	What it does
`/hyperframes`	The entry skill — read it first. Orients you to the whole surface and routes “make me a video” to the right workflow
`/hyperframes-core`	Composition contract — HTML structure, `data-*` attributes, clips, tracks
`/hyperframes-animation`	All animation + the GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU runtime adapters
`/hyperframes-creative`	Design direction — palettes, typography, narration, beat planning
`/hyperframes-cli`	Dev-loop CLI — init, lint, preview, render, doctor
`/media-use`	Asset preprocessing — TTS, transcription, background removal
`/hyperframes-registry`	Install catalog blocks and components
`/general-video`	The general authoring workflow — the fallback for any video that doesn’t match a specific workflow

The workflow skills are optional — add the ones that match your inputs, and /hyperframes routes to whichever you’ve installed: /product-launch-video, /website-to-video, /faceless-explainer, /pr-to-video, /embedded-captions, /talking-head-recut, /motion-graphics, /music-to-video, /slideshow, /general-video, /remotion-to-hyperframes. See the skills catalog for the full list with one-line “use when” descriptions.

To skip the picker and install everything (core + every workflow) in one shot, run npx skills add heygen-com/hyperframes --all.

These skills teach your agent how to write correct compositions, GSAP and runtime-adapter animations, Tailwind v4 browser-runtime styles, captions, and voiceovers. Invoking a slash command loads its context explicitly, which produces correct output the first time — and starting at /hyperframes lets it route your request to the right workflow.

Claude Design uses a different entry path. Open docs/guides/claude-design-hyperframes.md on GitHub, click the download button (↓) to save it, then attach to your Claude Design chat. It produces a valid first draft you can refine in any AI coding agent. See the Claude Design guide.

Try it: example prompts

Copy any of these into your agent to get started.

Cold start — describe what you want

Using /hyperframes, create a 10-second product intro with a fade-in title over a dark background and subtle background music.

Warm start — turn existing context into a video

Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using /hyperframes.

Summarize the attached PDF into a 45-second pitch video using /hyperframes.

Turn this CSV into an animated bar chart race using /hyperframes.

Format-specific

Make a 9:16 TikTok-style hook video about [topic] using /hyperframes, with bouncy captions synced to a TTS narration.

Iterate — 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.

The agent handles scaffolding, animation, and rendering. See the prompting guide for more patterns, or the pipeline guide for the 7-step structure (DESIGN, SCRIPT, STORYBOARD, …) that AI agents follow for multi-beat videos.

Skills encode HyperFrames-specific patterns — like required class="clip" on timed elements, GSAP timeline registration, adapter registries such as window.__hfLottie, and data-* attribute semantics — that are not in generic web docs. Using skills produces correct compositions from the start.

Option 2: Start a project manually

Prerequisites

Node.js 22+ — runtime for the CLI and dev server
FFmpeg — video encoding for local renders

Install instructions

Install Node.js 22+

Hyperframes requires Node.js 22 or later. Check your version:

node --version

Expected output

v22.0.0   # or any version >= 22

Install FFmpeg

FFmpeg is required for local video rendering (encoding captured frames into MP4).

brew install ffmpeg

sudo apt install ffmpeg

# Download from https://ffmpeg.org/download.html
# or install via winget:
winget install ffmpeg

Verify the installation:

ffmpeg -version

Expected output

ffmpeg version 7.x ...

Create your first video

Scaffold the project

npx hyperframes init my-video
cd my-video

This starts an interactive wizard that walks you through example selection and media import. To skip prompts (e.g. in CI or from an agent), use --non-interactive:

npx hyperframes init my-video --non-interactive --example blank

See Examples for all available examples.This generates a project structure like:

my-video

meta.json

index.html

compositions

intro.html

captions.html

assets

video.mp4

Path	Purpose
`meta.json`	Project metadata (name, ID, creation date)
`index.html`	Root composition — your video’s entry point
`compositions/`	Sub-compositions loaded via `data-composition-src`
`assets/`	Media files (video, audio, images)

If you have a source video, pass it with --video for automatic transcription and captions:

npx hyperframes init my-video --example warm-grain --video ./intro.mp4

hyperframes init installs AI agent skills automatically, so you can hand off to your AI agent at any point.

Preview in the browser

npx hyperframes preview

This starts the Hyperframes Studio and opens your composition in the browser. Edits to index.html reload automatically.

The dev server supports hot reload — save your HTML file and the preview updates instantly, no manual refresh needed.

Edit the composition

Open the project with your AI coding agent (Claude Code, Cursor, etc.) — skills are installed automatically and your agent knows how to create and edit compositions.Or edit index.html directly — here’s a minimal composition:

index.html

<div id="root" data-composition-id="my-video"
     data-start="0" data-width="1920" data-height="1080">

  <!-- 1. Define a timed text clip on track 0 -->
  <h1 id="title" class="clip"
      data-start="0" data-duration="5" data-track-index="0"
      style="font-size: 72px; color: white; text-align: center;
             position: absolute; top: 50%; left: 50%;
             transform: translate(-50%, -50%);">
    Hello, Hyperframes!
  </h1>

  <!-- 2. Load GSAP for animation -->
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>

  <!-- 3. Create a paused timeline and register it -->
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
    window.__timelines = window.__timelines || {};
    window.__timelines["my-video"] = tl;
  </script>
</div>

Three rules to remember:

Root element must have data-composition-id, data-width, and data-height
Timed elements need data-start, data-duration, data-track-index, and class="clip"
GSAP timeline must be created with { paused: true } and registered on window.__timelines

Render to MP4

npx hyperframes render --output output.mp4

Expected output

✔ Capturing frames... 150/150
✔ Encoding MP4...
✔ output.mp4 (1920x1080, 5.0s, 30fps)

Your video is now at output.mp4. Open it with any media player.

Requirements summary

Dependency	Required	Notes
Node.js 22+	Yes	Runtime for CLI and dev server
npm or bun	Yes	Package manager
FFmpeg	Yes	Video encoding for local renders
Docker	No	Optional — for deterministic, reproducible renders

Next steps

Browse the Catalog

50+ ready-to-use blocks — transitions, overlays, data visualizations, and effects

GSAP Animation

Add fade, slide, scale, and custom animations to your videos

Examples

Start from built-in examples like Warm Grain and Swiss Grid

Rendering

Explore render options: quality presets, Docker mode, and GPU acceleration

​Option 1: With an AI coding agent (recommended)

​Try it: example prompts

Cold start — describe what you want

Warm start — turn existing context into a video

Format-specific

Iterate — talk to the agent like a video editor

​Option 2: Start a project manually

​Prerequisites

​Create your first video

​Requirements summary

​Next steps

Browse the Catalog

GSAP Animation

Examples

Rendering

Option 1: With an AI coding agent (recommended)

Try it: example prompts

Option 2: Start a project manually

Prerequisites

Create your first video

Requirements summary

Next steps