| title | Quickstart |
|---|---|
| description | Create, preview, and render your first Hyperframes video in under two minutes. |
Go from zero to a rendered MP4 — either by prompting your AI agent or by starting a project manually.
Install the HyperFrames skills, then describe the video you want:
npx skills add heygen-com/hyperframesThis teaches your agent (Claude Code, Cursor, Gemini CLI, Codex, Google Antigravity, GitHub Copilot CLI) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code the skills register as slash commands — /hyperframes for composition authoring, /hyperframes-cli for the dev-loop commands (init, lint, preview, render), /hyperframes-media for asset preprocessing (TTS, transcription, background removal), /tailwind for init --tailwind projects, /gsap for timeline animation help, and /animejs, /css-animations, /lottie, /three, or /waapi when a composition uses those runtimes. Invoking the slash command loads the skill context explicitly, which produces correct output the first time.
Copy any of these into your agent to get started.
> Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music. > 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`.
> 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.- Node.js 22+ — runtime for the CLI and dev server
- FFmpeg — video encoding for local renders
```bash
node --version
```
```bash Expected output
v22.0.0 # or any version >= 22
```
</Step>
<Step title="Install FFmpeg">
FFmpeg is required for local video rendering (encoding captured frames into MP4).
<CodeGroup>
```bash macOS
brew install ffmpeg
```
```bash Ubuntu / Debian
sudo apt install ffmpeg
```
```bash Windows
# Download from https://ffmpeg.org/download.html
# or install via winget:
winget install ffmpeg
```
</CodeGroup>
Verify the installation:
```bash
ffmpeg -version
```
```bash Expected output
ffmpeg version 7.x ...
```
</Step>
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`:
```bash
npx hyperframes init my-video --non-interactive --example blank
```
See [Examples](/examples) for all available examples.
This generates a project structure like:
<Tree>
<Tree.Folder name="my-video" defaultOpen>
<Tree.File name="meta.json" />
<Tree.File name="index.html" />
<Tree.Folder name="compositions" defaultOpen>
<Tree.File name="intro.html" />
<Tree.File name="captions.html" />
</Tree.Folder>
<Tree.Folder name="assets" defaultOpen>
<Tree.File name="video.mp4" />
</Tree.Folder>
</Tree.Folder>
</Tree>
| 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:
```bash
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.
This starts the Hyperframes Studio and opens your composition in the browser. Edits to `index.html` reload automatically.
<Tip>
The dev server supports hot reload — save your HTML file and the preview updates instantly, no manual refresh needed.
</Tip>
Or edit `index.html` directly — here's a minimal composition:
```html 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`
```bash 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.
| 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 |