Merge pull request #2979 from heygen-com/docs/rewrite-guides

docs: rewrite the guides and landing pages
This commit is contained in:
Ular Kimsanov
2026-08-04 02:43:37 -07:00
committed by GitHub
24 changed files with 1597 additions and 3992 deletions
+94 -261
View File
@@ -1,274 +1,107 @@
---
title: Examples
description: "Built-in examples for common video patterns. Hover to preview animations."
title: "Examples"
description: "Watch finished HyperFrames videos, inspect real production projects, or start from a working template."
---
Hyperframes includes starter examples to help you scaffold compositions quickly. Each example gives you a working project with the correct [composition structure](/concepts/compositions), [data attributes](/concepts/data-attributes), and a [GSAP timeline](/guides/gsap-animation) already wired up.
import { DocsVideo } from "/snippets/docs-video.jsx";
<Note>
Looking for finished videos and production projects? Start with the [Showcase](/showcase).
</Note>
## Finished films
```bash Terminal
Each preview links to the complete source project.
<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-4 my-7">
<a className="group overflow-hidden rounded-xl border border-zinc-200 bg-white text-inherit no-underline dark:border-zinc-800 dark:bg-zinc-950" href="https://github.com/heygen-com/hyperframes-launches/tree/main/hyperframes-launch">
<video className="aspect-video w-full object-cover" src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/hyperframes-launch-preview.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/hyperframes-launch-poster.jpg" autoPlay muted loop playsInline preload="metadata" />
<div className="p-4">
<strong className="block text-sm">HyperFrames launch</strong>
<span className="mt-1 block text-xs text-zinc-500 dark:text-zinc-400">Product film · source included</span>
</div>
</a>
<a className="group overflow-hidden rounded-xl border border-zinc-200 bg-white text-inherit no-underline dark:border-zinc-800 dark:bg-zinc-950" href="https://github.com/heygen-com/hyperframes-launches/tree/main/timeline-launch">
<video className="aspect-video w-full object-cover" src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/timeline-editor-preview.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/timeline-editor-poster.jpg" autoPlay muted loop playsInline preload="metadata" />
<div className="p-4">
<strong className="block text-sm">Timeline editor launch</strong>
<span className="mt-1 block text-xs text-zinc-500 dark:text-zinc-400">Feature reveal · source included</span>
</div>
</a>
<a
className="group overflow-hidden rounded-xl border border-zinc-200 bg-white text-inherit no-underline dark:border-zinc-800 dark:bg-zinc-950"
href="https://github.com/heygen-com/hyperframes-launches/tree/main/website-to-hyperframes"
>
<video
className="aspect-video w-full object-cover"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/website-to-hyperframes-preview.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/website-to-hyperframes-poster.jpg"
autoPlay
muted
loop
playsInline
preload="metadata"
/>
<div className="p-4">
<strong className="block text-sm">Website to HyperFrames</strong>
<span className="mt-1 block text-xs text-zinc-500 dark:text-zinc-400">
Product story · source included
</span>
</div>
</a>
<a className="group overflow-hidden rounded-xl border border-zinc-200 bg-white text-inherit no-underline dark:border-zinc-800 dark:bg-zinc-950" href="https://github.com/heygen-com/hyperframes-launches/tree/main/texture-launch-video">
<video className="aspect-video w-full object-cover" src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/texture-launch-preview.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/texture-launch-poster.jpg" autoPlay muted loop playsInline preload="metadata" />
<div className="p-4">
<strong className="block text-sm">Texture launch</strong>
<span className="mt-1 block text-xs text-zinc-500 dark:text-zinc-400">Motion design · source included</span>
</div>
</a>
</div>
## One project, open end to end
The same ten-second project the Quickstart builds. This is its actual render,
and the folder behind it is public — not a sealed demo.
<div style={{ maxWidth: "36rem", margin: "1.5rem auto" }}>
<DocsVideo
title="The verified 10-second Reference Project render"
src="https://static.heygen.ai/hyperframes-oss/docs/reference-project/live/reference-project-v2.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/reference-project/live/poster-v2.jpg"
/>
</div>
<Card title="Open the project on GitHub" icon="folder-open" href="https://github.com/heygen-com/hyperframes/tree/main/examples/docs-reference-project" horizontal arrow>
Every file exactly as it renders — the composition, the caption overlay, the
measured word timings, and the brief the agent worked from.
</Card>
## Start from a template
Create a project with a working example:
```bash
npx hyperframes init my-video --example <name>
```
## Landscape Templates
<div className="not-prose grid grid-cols-2 gap-4 my-6">
<div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
<video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/warm-grain.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/warm-grain.png" muted loop playsInline preload="metadata" />
<div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.7))"}}><strong className="text-sm font-semibold text-white block">Warm Grain</strong><span className="text-xs text-zinc-300">Branding & lifestyle</span></div>
</div>
<div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
<video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/play-mode.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/play-mode.png" muted loop playsInline preload="metadata" />
<div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Play Mode</strong><span className="text-xs text-zinc-300">Social media</span></div>
</div>
<div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
<video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/swiss-grid.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/swiss-grid.png" muted loop playsInline preload="metadata" />
<div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Swiss Grid</strong><span className="text-xs text-zinc-300">Corporate & technical</span></div>
</div>
<div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
<video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/kinetic-type.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/kinetic-type.png" muted loop playsInline preload="metadata" />
<div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Kinetic Type</strong><span className="text-xs text-zinc-300">Promos & title cards</span></div>
</div>
<div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
<video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/decision-tree.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/decision-tree.png" muted loop playsInline preload="metadata" />
<div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Decision Tree</strong><span className="text-xs text-zinc-300">Explainers & tutorials</span></div>
</div>
<div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
<video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/product-promo.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/product-promo.png" muted loop playsInline preload="metadata" />
<div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Product Promo</strong><span className="text-xs text-zinc-300">Product showcases</span></div>
</div>
<div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
<video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/nyt-graph.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/nyt-graph.png" muted loop playsInline preload="metadata" />
<div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">NYT Graph</strong><span className="text-xs text-zinc-300">Data stories</span></div>
</div>
</div>
## Portrait Templates
<div className="not-prose grid grid-cols-3 gap-3 my-6">
<div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
<video className="w-full object-cover block" style={{aspectRatio: "9/16"}} src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/vignelli.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/vignelli.png" muted loop playsInline preload="metadata" />
<div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Vignelli</strong><span className="text-xs text-zinc-300">Headlines & announcements</span></div>
</div>
</div>
| Example | Good starting point for |
| --------------- | -------------------------------------------- |
| `warm-grain` | Branding, lifestyle, and editorial work |
| `play-mode` | Energetic social videos and product launches |
| `swiss-grid` | Technical, structured, and corporate stories |
| `kinetic-type` | Type-led promos, intros, and title cards |
| `decision-tree` | Explainable diagrams and tutorials |
| `product-promo` | Multi-scene product showcases |
| `nyt-graph` | Editorial charts and data stories |
| `vignelli` | Bold portrait announcements |
| `blank` | Agent-generated or fully custom work |
<Tip>
Looking for a minimal starting point? Use **blank** — it gives you an empty composition with just the scaffolding, no visual design.
```bash Terminal
npx hyperframes init my-video --example blank
```
Choose a template for its structure and tone, then replace the sample content. If none fits, start
with `blank` and let the agent build from the brief.
</Tip>
## Choosing an Example
## Related topics
| Example | Style | Format | Best for |
|----------|-------|--------|----------|
| `warm-grain` | Organic, textured | Landscape | Lifestyle, branding, editorial |
| `play-mode` | Energetic, elastic | Landscape | Social media, product launches |
| `swiss-grid` | Clean, structured | Landscape | Corporate, data, technical |
| `kinetic-type` | Dramatic type | Landscape | Promos, intros, title cards |
| `decision-tree` | Diagrammatic | Landscape | Explainers, tutorials |
| `product-promo` | Multi-scene | Landscape | Product showcases, demos |
| `nyt-graph` | Editorial data | Landscape | Data stories, reports |
| `vignelli` | Bold, typographic | Portrait | Headlines, announcements |
| `blank` | Minimal scaffolding | — | Full control, agent-generated |
## Example Details
<Tabs>
<Tab title="warm-grain">
### warm-grain
Cream-toned aesthetic with grain texture overlay.
**What it produces:** A composition with warm color grading, textured grain, and smooth transitions. Includes an intro sub-composition and captions support.
```
my-video/
├── meta.json
├── index.html
├── compositions/
│ ├── intro.html
│ ├── graphics.html
│ └── captions.html
└── assets/
```
</Tab>
<Tab title="play-mode">
### play-mode
Playful elastic animations with bold, energetic motion.
```
my-video/
├── meta.json
├── index.html
├── compositions/
│ ├── intro.html
│ ├── stats.html
│ └── captions.html
└── assets/
```
</Tab>
<Tab title="swiss-grid">
### swiss-grid
Structured grid layout inspired by Swiss/International Typographic Style.
```
my-video/
├── meta.json
├── index.html
├── compositions/
│ ├── intro.html
│ ├── graphics.html
│ └── captions.html
└── assets/
```
</Tab>
<Tab title="vignelli">
### vignelli
Bold typography with red accents (1080×1920 portrait).
```
my-video/
├── meta.json
├── index.html
├── compositions/
│ ├── overlays.html
│ └── captions.html
└── assets/
```
</Tab>
<Tab title="kinetic-type">
### kinetic-type
Bold kinetic typography promo with dramatic text animations.
```
my-video/
├── meta.json
├── index.html
└── compositions/
└── main-graphics.html
```
</Tab>
<Tab title="decision-tree">
### decision-tree
Animated flowchart with branching paths and progressive reveal.
```
my-video/
├── meta.json
├── index.html
└── compositions/
└── decision_tree.html
```
</Tab>
<Tab title="product-promo">
### product-promo
Multi-scene product showcase with SVG assets.
```
my-video/
├── meta.json
├── index.html
├── compositions/
│ ├── scene1-logo-intro.html
│ ├── scene2-4-canvas.html
│ └── scene5-logo-outro.html
└── assets/
├── figma-cursors.svg
├── figma-logo-pieces.svg
└── figma-logo-pills.svg
```
</Tab>
<Tab title="nyt-graph">
### nyt-graph
Animated data chart in print editorial style.
```
my-video/
├── meta.json
├── index.html
└── compositions/
└── nyt-chart.html
```
</Tab>
<Tab title="blank">
### blank
Empty composition with just the scaffolding.
```
my-video/
├── meta.json
├── index.html
└── compositions/
└── captions.html
```
</Tab>
</Tabs>
## Passing a Source Video
```bash Terminal
npx hyperframes init my-video --example warm-grain --video ./my-clip.mp4
```
The CLI will probe the video for duration, resolution, and codec. If the video uses an incompatible codec, it will be automatically transcoded to H.264 MP4 if FFmpeg is available.
## Custom Examples
Any directory with an `index.html` can serve as an example. Your custom example needs:
1. An `index.html` with a [`data-composition-id`](/concepts/data-attributes#composition-attributes) root element
2. A [GSAP timeline](/guides/gsap-animation) registered in `window.__timelines`
3. Any assets in the same directory or a subdirectory
```html index.html
<div id="root" data-composition-id="my-example"
data-start="0" data-width="1920" data-height="1080">
<!-- Your elements here -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
const tl = gsap.timeline({ paused: true });
// Add your animations...
window.__timelines = window.__timelines || {};
window.__timelines["my-example"] = tl;
</script>
</div>
```
After creating a custom example, validate it with the [linter](/packages/cli#lint):
```bash Terminal
npx hyperframes lint
```
## Next Steps
<CardGroup cols={2}>
<Card title="Quickstart" icon="rocket" href="/quickstart">
Create, preview, and render your first video
</Card>
<Card title="Launch Videos" icon="github" href="/launch-videos">
Real production projects from HeyGen's launches — open-source for you to read and remix.
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Add animations to your example
</Card>
<Card title="Compositions" icon="layer-group" href="/concepts/compositions">
Understand the composition data model
</Card>
</CardGroup>
- [Make your first video](/quickstart)
- [Choose a creation workflow](/workflows)
- [Take more control of an existing project](/go-further)
+45 -142
View File
@@ -1,167 +1,70 @@
---
title: 4K Rendering
description: "Render any composition to 4K (3840×2160) without rewriting it — the CLI supersamples a 1080p composition via Chrome's device scale factor."
title: Render in 4K
description: Author at 4K or supersample an existing composition at render time.
---
Hyperframes renders to 4K (3840×2160) two ways. Both produce a true 4K MP4; pick the one that matches your project.
## Render an existing project in 4K
<CardGroup cols={2}>
<Card title="Author at 4K" icon="ruler">
Scaffold the project at 4K so the composition is laid out at 4K natively. Best when you want crisp 4K-native typography and assets.
```bash
npx hyperframes init my-video --resolution 4k
```
</Card>
<Card title="Supersample at render" icon="up-right-and-down-left-from-center">
Keep your existing 1080p composition. Pass `--resolution 4k` at render time and Chrome renders at 2× DPR so the screenshot lands at 4K.
```bash
npx hyperframes render --resolution 4k --output 4k.mp4
```
</Card>
</CardGroup>
## Quickstart
<Steps>
<Step title="Render an existing project at 4K">
```bash Terminal
npx hyperframes render --resolution 4k --output my-video-4k.mp4
```
The composition's `data-width` / `data-height` are unchanged. Chrome's `deviceScaleFactor` is set to `2`, so the captured screenshot for each frame is 3840×2160. ffmpeg auto-detects the dimensions from the screenshot stream and encodes at 4K.
</Step>
<Step title="Or scaffold a new project at 4K">
```bash Terminal
npx hyperframes init my-video --resolution 4k
```
Every scaffolded HTML file is patched in place: `data-width="3840"`, `data-height="2160"`, `data-resolution="landscape-4k"`, `#stage` CSS dimensions, and the `<meta viewport>` tag.
</Step>
<Step title="Verify the output is 4K">
```bash Terminal
ffprobe -v error -select_streams v:0 -show_entries stream=width,height my-video-4k.mp4
```
Expected:
```
width=3840
height=2160
```
</Step>
</Steps>
## Resolution presets
`--resolution` accepts these values on both `init` and `render`:
| Preset | Dimensions | Aliases |
|--------|-----------|---------|
| `landscape` | 1920×1080 | `1080p`, `hd` |
| `portrait` | 1080×1920 | `1080p-portrait` |
| `square` | 1080×1080 | `1080p-square`, `square-1080p` |
| `landscape-4k` | 3840×2160 | `4k`, `uhd` |
| `portrait-4k` | 2160×3840 | `4k-portrait` |
| `square-4k` | 2160×2160 | `4k-square` |
Examples:
```bash Terminal
npx hyperframes render --resolution 4k # landscape 4K
npx hyperframes render --resolution portrait-4k # vertical 4K (TikTok / Reels at max quality)
npx hyperframes render --resolution 1080p # explicit 1080p (no-op on 1080p compositions)
```bash
npx hyperframes render --resolution 4k --output final-4k.mp4
```
## How `--resolution` works (supersampling)
HyperFrames keeps the composition's layout unchanged and captures it at a higher device-pixel ratio. A 1920×1080 composition becomes a 3840×2160 file.
The composition stays at its authored dimensions. Hyperframes computes a `deviceScaleFactor` from the ratio of output to composition dimensions and passes it to Chrome:
Use the matching preset for portrait or square work:
| Composition | `--resolution` | `deviceScaleFactor` | Output |
|-------------|---------------|--------------------|--------|
| 1920×1080 | `4k` | 2 | 3840×2160 |
| 1080×1920 | `portrait-4k` | 2 | 2160×3840 |
| 3840×2160 | `4k` | 1 (no-op) | 3840×2160 |
| Preset | Output |
| --- | --- |
| `4k` or `landscape-4k` | 3840×2160 |
| `portrait-4k` | 2160×3840 |
| `square-4k` | 2160×2160 |
Chrome then renders the page at the higher DPR — effectively rendering each CSS pixel as 2×2 device pixels — so the captured screenshot is at the requested resolution.
## Author a project at 4K
<Tip>
This approach is intentionally simple — no composition edits, no second authoring pass. The tradeoff: 4K renders take roughly 4× as long per frame because there are 4× the pixels to capture and encode.
</Tip>
If the project should use a 4K canvas from the start:
## What scales, what doesn't
```bash
npx hyperframes init my-video --resolution 4k
```
Supersampling re-renders the page at higher DPR. That genuinely helps anything the browser rasterizes from a vector or high-resolution source, and does nothing for content already locked to a fixed pixel grid. Knowing which is which sets correct expectations before a 4K render:
Choose this when canvas or WebGL code, fixed-resolution media, or layout decisions need to know the final pixel dimensions while you author.
| Asset type | Behavior at `--resolution 4k` |
|------------|------------------------------|
| Text (HTML, SVG `<text>`, web fonts) | ✅ **Re-rasterized at 4K.** Glyphs are vector and the browser shapes/rasterizes them at the new DPR. Crisp at any scale. |
| SVG / vector graphics | ✅ **Re-rasterized at 4K.** Same story as text — paths are vector. |
| CSS shapes, gradients, borders, shadows | ✅ **Re-rasterized at 4K.** Browser-generated raster. |
| Images with intrinsic dimensions ≥ 4K | ✅ **Full benefit.** A 3840×2160 source serves all the detail. |
| Images smaller than 4K (e.g. a 1920×1080 PNG) | ⚠️ **No new detail.** Browser upscales the source bitmap; output is no sharper than rendering at 1080p and upscaling externally — but no worse either. |
| `<video>` elements | ❌ **Locked to source resolution.** A 1080p MP4 stays 1080p; the supersample only helps the surrounding DOM. Encode source video at the target resolution if you need 4K throughout. |
| `<canvas>` (2D and WebGL) | ❌ **Locked to canvas's intrinsic dimensions.** `<canvas width="1920" height="1080">` is a 1080p bitmap regardless of DPR. To render canvas content at 4K, multiply `canvas.width` / `canvas.height` by your target DPR and scale the drawing context (`ctx.scale(2, 2)` for a 2× canvas with the same logical layout). |
| Pre-rendered video frames injected by the engine | ❌ **Locked to extraction resolution.** When the producer pre-extracts `<video>` frames via ffmpeg, they're decoded at the source video's dimensions. |
## What gets sharper
**Rule of thumb**: if the asset is *vector or generated by the browser*, supersampling helps. If it's a *bitmap with fixed pixel dimensions* (video, canvas, low-res PNG), it doesn't — author it at the target resolution instead.
| Content | Result when supersampled |
| --- | --- |
| HTML text, SVG, CSS shapes, gradients | Re-rasterized at 4K |
| High-resolution images | Use their available source detail |
| 1080p images and video | Scaled up; no new source detail |
| `<canvas>` and WebGL | Limited by the canvas's intrinsic dimensions |
For a fully sharp 4K result, use 4K source media and size canvas/WebGL buffers for the target resolution.
## Constraints
`--resolution` enforces three guards before any frames are captured. If any fail, the render exits before doing work.
`--resolution` only works when:
### Aspect ratio must match
- the preset has the same aspect ratio as the composition;
- the target is an integer multiple of the authored dimensions;
- the target is not smaller than the composition;
- the output is MP4 rather than an alpha format;
- HDR is not forced for the same render.
HyperFrames checks these conditions before opening the browser. Render at the composition's native size and resize separately when a combination is unsupported.
## Verify the file
```bash
# OK — both landscape
hyperframes render --resolution 4k # composition is 1920×1080
# Error — composition is landscape, target is portrait
hyperframes render --resolution portrait-4k # composition is 1920×1080
# → outputResolution portrait-4k (2160×3840) does not match the aspect ratio
# of the composition (1920×1080). Pick a preset whose orientation matches.
ffprobe -v error -select_streams v:0 \
-show_entries stream=width,height final-4k.mp4
```
### The scale must be an integer
For landscape 4K, the output should report `3840` by `2160`.
The width ratio (output ÷ composition) must be a positive integer. 1080p → 4K is exactly `2×`. 720p → 4K would be `3×` and works. Non-integer scales like 900p → 4K (`2.4×`) introduce aliasing on subpixel-positioned text — Hyperframes refuses rather than producing a blurry render.
4K captures four times as many pixels as 1080p, so expect more render time, memory use, and output data. Start with `--quality draft` for review, then render the approved version at the quality you need.
### Downsampling is not supported
## Related topics
`--resolution` only supersamples. A 4K composition cannot be downsampled to 1080p with this flag — render at the composition's native resolution and downscale separately with ffmpeg if needed.
### Not yet supported with `--hdr`
The HDR layered compositor processes pixel buffers at composition dimensions; supersample + HDR would need parallel scaling for those buffers. The combination is rejected with a clear error message. Render in two passes if you need both: HDR at composition resolution, then upscale separately.
## Performance
A 1080p → 4K supersample is roughly 4× more pixels to capture, encode, and write. Expect:
- **Per-frame capture**: 3–4× slower (Chrome paints 4× the pixels and the screenshot transfer is 4× larger)
- **Encoding**: 2–3× slower (depends on codec; H.264 scales sublinearly with resolution)
- **Memory**: bounded — the engine's frame data-URI cache is byte-budgeted (default 1500 MB per worker, configurable via `PRODUCER_FRAME_DATA_URI_CACHE_BYTES_MB`)
- **Output file size**: at the default CRF, expect 3–5× the file size of the 1080p render. Pass `--video-bitrate 25M` (or higher) for predictable file sizes.
For a 4K render of a 30-second composition, plan on a few minutes of wall time on a modern laptop. Add `--workers 4` (or more) on a render box for parallel capture.
## Studio support
The Renders panel in Studio includes a resolution dropdown next to the format and quality selectors. Pick `4K` (or `4K ↕` for portrait) and hit **Export** — the same supersampling path runs as the CLI flag, no composition edits required.
The dropdown defaults to `Auto` (render at the composition's authored size). Available presets:
- **Auto** — composition's native dimensions
- **1080p ↔** / **1080p ↕** — 1920×1080 / 1080×1920
- **4K ↔** / **4K ↕** — 3840×2160 / 2160×3840
The resolution applies per render, not per project — your composition files are unchanged. The same [constraints](#constraints) apply; when the producer rejects a combination, the failure surfaces in the Studio render queue.
You can also drive resolution from the CLI:
- **New project**: `hyperframes init my-video --resolution 4k`
- **Existing project**: `hyperframes render --resolution 4k --output 4k.mp4`
## See also
- [`render` CLI reference](/packages/cli#render) — every render flag including `--video-bitrate` and `--crf`
- [`init` CLI reference](/packages/cli#init) — the `--resolution` flag at scaffold time
- [HDR Rendering](/guides/hdr) — color pipeline guide; HDR + 4K is not yet a supported combination
- [Render from the command line](/guides/rendering)
- [Improve render performance](/guides/performance)
- [Deliver an HDR project](/guides/hdr)
+46 -12
View File
@@ -1,9 +1,12 @@
---
title: Authentication & API keys
description: "Sign in to HeyGen, and how the keys for voice, music, and capture resolve across the CLI and skills — including the priority order and the fully local fallback."
description: "Sign in to HeyGen and understand how agent workflows choose voice, music, sound, and optional capture-description providers."
---
HyperFrames uses a HeyGen credential for premium voiceover (TTS) and the music / sound-effects library. Other providers are optional, and **everything runs without any key** — voice and music fall back to fully local engines. This page covers signing in, the keys each capability uses, and the order they resolve.
You can create and render locally without an account. Voice and music can fall
back to local engines when no provider key is available. Sign in when you want
HeyGen voice and music, managed cloud rendering, hosted MCP, or ownership of a
published project that you can update later.
## Sign in
@@ -37,12 +40,15 @@ Signing in is the same OAuth step as creating an account — new users land on t
The credential lives in `~/.heygen/credentials` (mode `0600`) — no per-repo `.env` to manage. Browser OAuth is a `hyperframes auth login` feature. The separate [`heygen` CLI](https://github.com/heygen-com/heygen-cli) (its own install — there's no `npx heygen`) is API-key-only, so `heygen auth login` just stores a key you paste. Both read the same `~/.heygen/credentials`, so signing in with one carries to the other.
<Tip>
No account needed to try HyperFrames. With no credential, voice uses **Kokoro** and music uses **MusicGen**, both fully local and offline — see [Working offline](#working-offline).
No account is needed to try HyperFrames locally. With no credential, voice can
use **Kokoro** and music can use **MusicGen** — see [Working
offline](#working-offline).
</Tip>
## How credentials resolve
## How the HeyGen credential resolves
The HeyGen credential drives TTS and music / SFX **retrieval**. It resolves first-match-wins:
Bundled media workflows use the HeyGen credential for hosted TTS and music /
sound retrieval. It resolves first-match-wins:
1. `HEYGEN_API_KEY` — environment variable
2. `HYPERFRAMES_API_KEY` — alias, for parity with other tools
@@ -50,28 +56,52 @@ The HeyGen credential drives TTS and music / SFX **retrieval**. It resolves firs
Point at a different config directory with `HEYGEN_CONFIG_DIR`, or a different backend with `HEYGEN_API_URL`.
## Keys by capability
## Providers used by agent workflows
Each capability picks the **first available provider** in order; the last is always a local engine that needs no key. Cloud providers below the HeyGen line need their own key *and* a local Python dependency.
After the workflow's sign-in preflight, each media capability uses the first
available provider in its order. Voice, music, and sound have offline
fallbacks; capture descriptions are optional and are skipped when no supported
vision key is available.
| Capability | Provider order | Key(s) — first match wins | Local dependency |
|------------|----------------|---------------------------|------------------|
| **Voice (TTS)** | HeyGen → ElevenLabs → Kokoro | `HEYGEN_API_KEY` → `HYPERFRAMES_API_KEY` → `~/.heygen` · then `ELEVENLABS_API_KEY` | Kokoro: `pip install kokoro-onnx soundfile` |
| **Music (BGM)** | HeyGen library → Lyria → MusicGen | HeyGen credential (above) · then `GEMINI_API_KEY` → `GOOGLE_API_KEY` | MusicGen: `pip install transformers torch soundfile numpy` |
| **Sound effects** | HeyGen library → bundled library | HeyGen credential (above) | bundled — no deps |
| **Capture descriptions** | OpenRouter → Gemini | `OPENROUTER_API_KEY` → `GEMINI_API_KEY` | — (optional; for [website capture](/guides/website-to-video)) |
| **Capture descriptions** | OpenRouter → Gemini | `OPENROUTER_API_KEY` → `GEMINI_API_KEY` | None; optional for [website capture](/guides/product-launch-video) |
Run `npx hyperframes doctor` to check which local dependencies are installed. The media skills also run `hyperframes auth status` as a preflight before generating, so you always know whether a run will use HeyGen or a local engine before it starts.
Run `npx hyperframes doctor` to check which local dependencies are installed.
The media workflows run `hyperframes auth status` before generation and tell
you which path they will use.
<Note>
`npx hyperframes tts` itself is the local Kokoro CLI. Hosted HeyGen and
ElevenLabs voices are selected by the bundled media workflow helpers, not by
that command.
</Note>
## Working offline
No key configured is a normal state, not an error. The workflow runs entirely on local models:
No key configured is a normal state for local work. After their dependencies
and model files are installed, these fallbacks run locally:
- **Voice** — Kokoro-82M (54 voices), with Whisper for word-level caption alignment.
- **Music** — MusicGen (`facebook/musicgen-small`).
- **Sound effects** — a bundled library.
Local engines are free and offline; HeyGen gives higher-quality voices and a professionally produced music library. Sign in any time to switch a project from local to HeyGen.
Local engines do not call a hosted generation API after setup. Their first use
may download model files. HeyGen provides managed voices and a produced music
library; sign in when you want those services or cloud rendering.
## Publishing without an account
`npx hyperframes publish` works while signed out. It uploads the project and
prints a URL containing a claim token. Open that URL and authenticate in the web
app to claim the project.
Sign in with `npx hyperframes auth login` before publishing when you want the CLI
to own the project immediately, update the same URL with `--update`, or publish
to a shared space with `--space`.
## Environment variables
@@ -85,4 +115,8 @@ Local engines are free and offline; HeyGen gives higher-quality voices and a pro
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Lyria music generation (and capture descriptions). |
| `OPENROUTER_API_KEY` | Capture descriptions; takes priority over Gemini for that step. |
See the [`hyperframes auth`](/packages/cli#hyperframes-auth) command reference for subcommand details, and [Cloud rendering](/deploy/cloud) for using the same credential to render in HeyGen's cloud.
## Related topics
- [Open the authentication command reference](/packages/cli#hyperframes-auth)
- [Render with HyperFrames Cloud](/deploy/cloud)
- [Choose where to create](/guides/choose-creation-path)
+5 -5
View File
@@ -523,7 +523,7 @@ composition with `-c` rather than as a bare path.
npx hyperframes render -o output.mp4
```
1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 3840x2160` to override.
1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 4k` to override.
````
### Skeleton A -- Social Reel (1080x1920, 15s, 6 scenes)
@@ -1231,8 +1231,8 @@ tl.to("#s5-headline", { backgroundSize: "100% 30%", duration: 0.6, ease: "power2
Everything critical is inlined above. These are for edge cases:
- Core composition contract (data attributes, sub-comp wiring): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/SKILL.md
- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/motion-principles.md
- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/typography.md
- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/transitions.md
- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/captions.md
- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-creative/references/motion-principles.md
- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-creative/references/typography.md
- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-animation/transitions/overview.md
- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/embedded-captions/SKILL.md
- Full docs: https://hyperframes.heygen.com/
+97 -470
View File
@@ -1,501 +1,128 @@
---
title: Color Grading
description: "Correct and creatively grade video or image media with presets, scopes, color wheels, curves, HSL selections, and custom LUTs."
title: "Color grade images and footage"
sidebarTitle: "Color grading"
description: "Correct exposure and color, shape a look, apply a LUT, and review the result in Studio."
---
Use Color Grading to correct and creatively grade real `<video>` and `<img>`
media in Studio or through an agent with the same validated SDR/Rec.709 shader
contract in preview and render.
Use Color Grading when an image or video needs correction or a deliberate
visual look. It changes that media element only; text, captions, SVG, and normal
HTML remain separate layers.
## Choose the Right Tool
<Frame caption="The same source before and after a restrained natural-portrait grade.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/color-grading-before-after-v1.png"
alt="The same presenter frame before and after a restrained natural portrait grade"
/>
</Frame>
| Stage | Purpose | HyperFrames tools |
| --- | --- | --- |
| Correct | Fix exposure, contrast, tonal balance, and casts | Adjust controls and source analysis |
| Grade | Shape color and mood | Tonal wheels, RGB curves, hue curves, and HSL color selections |
| Apply a look | Start from a tested style or an existing external look | Presets and custom 3D `.cube` LUTs |
| Finish | Add restrained optical texture | Vignette and grain |
| Stylize | Transform the pixels beyond normal grading | [Media Effects](/guides/media-effects) |
| Dress | Add an authored HUD, flash, light leak, or freeze-frame layer | [Media Overlays](/guides/media-overlays) |
## Work in this order
All pixel-level stages are stored together on the selected media element. An
overlay is different: it is an ordinary editable composition layer whose final
paint order follows its authored track and CSS `z-index`.
## Quick Start
<Tabs>
<Tab title="Studio">
Select a real `<img>` or `<video>` element to open Color Grading in the
Design panel.
<Steps>
<Step title="Correct the source">
Open **Scopes**, then adjust exposure, tonal balance, white balance, and
saturation before applying a stronger look.
</Step>
<Step title="Shape the grade">
Use tonal wheels, curves, or an HSL Color Selection only where the
source needs more precise control.
</Step>
<Step title="Choose a look and verify">
Preview a preset or load a 3D `.cube` LUT, compare with the source, and
scrub representative frames before rendering.
</Step>
</Steps>
</Tab>
<Tab title="Agent / CLI">
Inspect the media, apply one validated payload, then verify representative
frames:
```bash Terminal
npx hyperframes media-treatment \
--project . \
--file compositions/interview.html \
--selector '#interview' \
--analyze \
--json
npx hyperframes media-treatment \
--project . \
--file compositions/interview.html \
--selector '#interview' \
--grading '{"adjust":{"highlights":-0.08,"shadows":0.06},"wheels":{"midtones":{"hue":32,"amount":0.05}}}' \
--apply \
--json
```
Use `--dry-run` when target or scope is uncertain. Use `--clear` to remove
the complete treatment.
</Tab>
</Tabs>
To reuse a grade in Studio, use **Copy grade to**, choose **Current file media**
or **All project media**, then click **Apply**. Project-wide copy refuses
project-relative LUT paths because the same path may resolve differently in
another composition; use current-file copy or a project-root path/data URL. The
copy changes only the treatment payload, not overlays, captions, or DOM layers.
Project-local media is the reliable path. Remote media requires compatible CORS
headers. Color Grading does not process captions, text, SVG, arbitrary DOM, or
CSS background images.
## Professional Controls
### Color Wheels
The three wheels target broad tonal zones:
- **Shadows** shapes dark regions.
- **Midtones** shapes most faces, products, and general scene color.
- **Highlights** shapes bright regions and specular areas.
Use small amounts first. The **Level** control changes the brightness of the
same tonal zone, while hue and amount introduce color.
### RGB Curves
- **Master** remaps overall luminance.
- **Red**, **Green**, and **Blue** remap individual channels.
Curve points are normalized `[input, output]` pairs. Resolved curves contain
input endpoints `0` and `1`; HyperFrames infers missing endpoints, and the
2–16-point limit includes those inferred points. An S-curve increases contrast;
lifting the lower-left region raises shadows; channel curves can build
split-tone or cast-removal adjustments.
### Hue Curves
- **Hue vs Hue** moves a selected hue toward another hue.
- **Hue vs Saturation** changes saturation around a selected hue.
- **Hue vs Luma** changes brightness around a selected hue.
Hue curve points are `[hueDegrees, delta]` pairs and wrap around the color
wheel. An authored hue curve requires 3–16 unique hue inputs from `0` up to,
but not including, `360`.
### HSL Color Selections
A color selection qualifies pixels by hue, saturation, and luma, then applies a
correction only inside that matte. This is useful for restrained tasks such as
reducing an overly saturated shirt, cooling a background color, or protecting
skin from a broad creative grade.
HyperFrames supports up to four ordered selections. These are static
media-level qualifiers: they do not include object tracking, rotoscoping,
facial recognition, or spatial masks. To confine a grade to a region of the
frame rather than a range of colors, see
[Limiting a Grade to Part of the Frame](#limiting-a-grade-to-part-of-the-frame).
### Scopes
| Scope | Use it for |
| Pass | Purpose |
| --- | --- |
| Histogram | Overall distribution from dark to bright |
| Correct | Fix exposure, white balance, contrast, and saturation |
| Grade | Shape tonal ranges or a selected color |
| Apply a look | Start from a preset or a compatible `.cube` LUT |
| Finish | Add restrained detail or film effects |
Correct before stylizing. A strong preset cannot rescue clipped highlights,
unreadable shadows, or the wrong source.
## Grade in Studio
1. Select an image or video on the canvas, in Layers, or on the timeline.
2. Open **Color grading** in **Design**.
3. Start with a preset or small corrections.
4. Use the scopes and compare control to check the result.
5. Scrub several moments before judging moving footage.
The controls answer different questions:
| Control | Use it for |
| --- | --- |
| Preset and strength | Establish a starting look |
| Exposure, contrast, highlights, shadows, white point, black point | Correct brightness and contrast |
| Warmth, tint, vibrance, saturation | Correct or shape color |
| Color wheels | Shift shadows, midtones, or highlights |
| RGB curves | Remap luminance or individual channels |
| Hue curves | Move, saturate, or brighten a selected hue |
| HSL selections | Correct pixels inside a hue, saturation, and luma range |
| Grain, vignette, blur, and effects | Finish or deliberately degrade the image |
| Custom LUT | Apply a known 3D `.cube` transform |
HyperFrames supports up to four ordered HSL selections. They are static
pixel-value qualifiers, not object tracking, rotoscoping, or spatial masks.
Studio scopes are inspection tools:
| Scope | Shows |
| --- | --- |
| Histogram | Overall dark-to-bright distribution |
| Waveform | Brightness by horizontal image position |
| RGB Parade | Channel balance and clipped individual channels |
| RGB Parade | Channel balance and clipping |
| Vectorscope | Hue direction and saturation |
Studio scopes analyze a captured selected-media frame with the current
treatment applied. They refresh as the grade changes, but are inspection tools
and do not modify the grade.
## Give the agent the visible problem
## Presets
You do not need to prescribe shader values:
HyperFrames ships tested shader-setting presets, not bundled LUT files:
```text
The interview looks too dark and slightly cold.
Keep skin natural, recover the background enough to read, and avoid a filtered look.
```
| Intent | Presets |
| --- | --- |
| Natural and corrective | Neutral, Warm Daylight, Clean Studio, Skin Soft, Food Pop, Night Lift |
| Editorial and tonal | Muted Editorial, Vintage Wash, Soft Boost, Bright Pop, Deep Contrast |
| Monochrome | Mono Clean, Mono Fade |
The agent can inspect the current capability contract and analyze a local
source before changing it:
Use these as starting points and tune them for the actual source. Presets that
also activate a stylized shader treatment are documented under
[Media Effects](/guides/media-effects).
## Agent Guidance
Agents should use the CLI as the normal authoring surface. The
`data-color-grading` attribute is the persistence contract, not the first thing
an agent needs to memorize.
Users do not need to name a technical control. Requests such as _"this
interview feels too dark and cold"_ or _"polish the footage without making it
look filtered"_ route through the `media-use` skill, which inspects the source,
discovers the relevant contract, applies a deterministic payload, and verifies
the result.
Start with the concise capability overview, then query only the contract needed
for the current intent:
```bash Terminal
```bash
npx hyperframes media-treatment --capabilities --json
npx hyperframes media-treatment --capability grading --json
npx hyperframes media-treatment --capability curves --json
npx hyperframes media-treatment --selector '#interview' --analyze --json
```
Focused queries such as `wheels`, `hue-curves`, `secondary`, `scopes`, or `lut`
return exact controls, bounds, and examples. Start from source analysis or a
tested preset, then add small, explainable adjustments. Avoid inventing many
unrelated curve and secondary values: they are difficult to review and easy to
overcook.
For source-sensitive prompts and worked A/B examples, continue to
[Color grading and film effects](/prompting/color-grading).
For worked examples — ten graded A/B renders, each with the plain-language
prompt that produced it and the payload it compiled to — see
[Color grading and film effects](/prompting/color-grading) in the Prompt Guide.
It covers the failures this page cannot: choosing a source that actually has
something for the treatment to remove, and separating a subject so one part of
the frame can be graded while the rest is protected.
## Reuse a grade carefully
## Low-Level HTML Contract
In Studio, use **Copy grade to** for other media in the current file or project.
Treat the copy as a starting point and inspect each source.
The CLI and Studio persist the resolved grade in `data-color-grading`:
Project-wide copy rejects project-relative LUT paths because the same path can
resolve differently from another composition. Use a project-root path, a data
URL, or copy only within the current file.
```html index.html
<video
id="interview"
src="assets/interview.mp4"
data-start="0"
data-duration="6"
muted
playsinline
data-color-grading='{
"preset":"clean-studio",
"intensity":0.85,
"adjust":{
"exposure":0.04,
"highlights":-0.08,
"shadows":0.06,
"temperature":0.03
},
"wheels":{
"shadows":{"hue":218,"amount":0.04,"level":-0.01},
"midtones":{"hue":32,"amount":0.05,"level":0.01},
"highlights":{"hue":42,"amount":0.03,"level":0}
},
"curves":{
"master":[[0,0],[0.28,0.25],[0.72,0.76],[1,1]]
},
"hueCurves":{
"hueVsSaturation":[[0,0],[28,-0.05],[52,0]]
},
"secondaries":[{
"enabled":true,
"key":{
"hue":{"center":28,"range":18,"softness":12},
"saturation":{"min":0.15,"max":0.9,"softness":0.08},
"luma":{"min":0.12,"max":0.95,"softness":0.08}
},
"correction":{"saturation":-0.04,"temperature":0.03}
}],
"details":{"vignette":0.05,"grain":0.03},
"colorSpace":"rec709"
}'
></video>
```
## Use LUTs with known intent
The contract rejects unknown keys and clamps numeric values to Core-owned
bounds. Query the current contract instead of copying bounds into agent
instructions:
Import a project-local 3D `.cube` LUT only when you know the look or conversion
it expects. HyperFrames does not identify camera profiles or apply an automatic
ACES/OCIO workflow.
```bash Terminal
npx hyperframes media-treatment --capability secondary --json
npx hyperframes media-treatment --all --json
```
A creative Rec.709 LUT is the safest normal path. LOG or HDR footage requires a
known source transform.
Use `--all` only for exhaustive tooling or contract inspection.
## Animating a Grade
## Current limits
Nine grading properties are exposed as CSS custom properties and can be tweened
directly:
```text
--hf-color-grading-ascii --hf-color-grading-bloom --hf-color-grading-blur
--hf-color-grading-dither --hf-color-grading-exposure --hf-color-grading-intensity
--hf-color-grading-kuwahara --hf-color-grading-pixelate
--hf-color-grading-lut-intensity
```
```js
tl.to("#plate", { "--hf-color-grading-pixelate": 0.5, duration: 3, ease: "power2.inOut" }, 0.3);
```
Start the value at identity in the payload and in an inline `style`, so frame 0
is the ungraded reference and every intermediate value is rendered rather than
just the endpoints.
Two things this list does **not** give you:
- **`--hf-color-grading-intensity` scales the primary grade only.** The shader
mixes between the ungraded sample and the graded one at that value, so it
ramps `adjust`, `wheels`, `curves`, `hueCurves`, `secondaries` and the LUT.
`details` and `effects` sit outside that mix entirely and it scales neither.
Some of them shape the sampled media *before* the mix — CRT warp, blur,
Kuwahara, pixelate, the tape family, chromatic aberration, digital glitch —
and so are already present on both sides of it. Others run *after* it —
grain, halftone, bloom, scanlines, vignette. Either way intensity does not
reach them, so it is not a master "ramp the whole look" dial when the look is
effect-based; animate the specific effect instead.
- **Every other property — `halftone`, `twoInkPrint`, `tapeDamage`, hue curves,
secondaries — has no custom property**, so it cannot be tweened this way.
For some of those, you can drive the payload itself from the timeline.
Rewriting `data-color-grading` re-applies the grade:
```js
const plate = document.getElementById("plate");
const v = { halftone: 0, bloom: 0 };
tl.to(v, {
halftone: 0.72,
bloom: 0.7,
duration: 3.4,
ease: "power2.inOut",
onUpdate: () => {
plate.setAttribute("data-color-grading", JSON.stringify({
intensity: 1,
effects: {
halftone: v.halftone, halftoneSize: 0.38,
bloom: v.bloom, bloomRadius: 18,
},
}));
},
}, 0.3);
```
This stays deterministic: the value is derived from timeline position, never
from wall-clock time, so seeking to a frame always produces the same result.
It costs a payload parse per tick, so prefer a custom property when one exists.
<Warning>
**This does not work for every effect.** It is verified working for `halftone`
and `twoInkPrint`. It is verified *not* working for `crtCurvature`,
`scanlines`, `chromaBleed`, and `chromaticAberration` — the identical payload
applied statically renders correctly, but the same values driven through
`setAttribute` produce no visible change, and seeding them non-zero at init
does not help. Measure the effect you intend to animate before committing to
it, and fall back to a static treatment if the ramp does not move.
</Warning>
## Limiting a Grade to Part of the Frame
Grading qualifies pixels **by value, never by position**. Selections key on hue,
saturation, and luma; the one spatially-varying control, `vignette`, is locked
to the frame centre and cannot be moved or reshaped into a power window. There
are no masks, shapes, or tracked regions in the contract.
A grade also applies to a whole media element. So to treat part of the frame,
split that part into its own layer and grade the layer:
| You want | Build |
| Source or workflow | Status |
| --- | --- |
| Subject graded, background clean | Matted cutout on top, graded; original clip underneath, clean |
| Background graded, subject clean | Original clip underneath, graded; matted cutout on top, clean |
| One region of the subject graded | Two copies of the cutout — clean underneath, graded copy on top clipped to the region |
| SDR image or video | Supported |
| 4K SDR media | Supported with higher preview and render cost |
| iPhone HDR, HLG, or Dolby Vision-style media | Studio can show an SDR preview; native HDR delivery is a separate path |
| LOG footage | Requires a known matching transform or LUT |
| Full-scene grade including HTML text | Not supported; grading targets individual media elements |
| Face or region tracking | Not supported |
| Remote media | Requires compatible CORS headers |
| ACES/OCIO finishing | Outside the current browser shader pipeline |
Two rules that are easy to get wrong:
Continue to [Media effects](/guides/media-effects) for blur, bloom, retro,
print, glitch, and art treatments. Use [HDR rendering](/guides/hdr) when the
final delivery must remain HDR.
- **Use the original clip as the background plate, not a subject-removed
plate.** A subject-removed plate is a hole where the subject was, and a
feathered cutout composited over it produces a dark rim.
- **If your cutout ships premultiplied alpha**, the browser composites it as
straight and edge pixels get multiplied twice, giving a black outline. Rebuild
it from the original plus its matte:
`ffmpeg -i clip.mp4 -i matte.mp4 -filter_complex "[1:v]format=gray[m];[0:v][m]alphamerge" -c:v libvpx-vp9 out.webm`
<Card title="Implement a grade in HTML" icon="code" href="/reference/color-grading">
Persist a grade, animate supported properties, or isolate a graded region.
</Card>
### Worked Example: Redacting a Face
## Related topics
Only the face is pixelated. The rest of the subject and the entire room are
untouched. Three layers, and the region comes from `clip-path` on the third:
```html index.html
<div class="band">
<!-- 1. the room, clean -->
<video src="media/room.mp4" muted
data-start="0" data-duration="4" data-track-index="2"></video>
<!-- 2. the subject, clean -->
<video src="media/subject.webm" muted class="fg"
data-start="0" data-duration="4" data-track-index="3"></video>
<!-- 3. the same subject, graded, clipped to the head -->
<video src="media/subject.webm" muted class="fx"
data-start="0" data-duration="4" data-track-index="4"
style="clip-path: ellipse(9.8% 15.5% at 50.7% 14.5%)"
data-color-grading='{"intensity":1,"effects":{"pixelate":0.5}}'></video>
</div>
```
```css
.band .fg { z-index: 2; }
.band .fx { z-index: 3; }
```
Everything outside the clip falls through to the clean copy beneath. Because the
graded layer *is* the cutout, the ellipse can overshoot the head without
touching the room — there is nothing outside the silhouette to paint — so size
it generously rather than tightly around the features.
Pixelate preserves alpha, so the block grid clips to the silhouette instead of
filling a rectangle.
<Warning>
A fixed `clip-path` is only valid for footage where the subject barely moves.
Measure before relying on it. Anything with real subject movement needs a
tracked matte produced outside HyperFrames — there is no tracking in the
grading pipeline.
</Warning>
The prompt that produces the composition above:
```text
Take room.mp4 and its matted cutout subject.webm and build a 4-second
1920x1080 composition that redacts only the subject's face.
Three stacked layers inside one band, all playing the same 4 seconds:
1. room.mp4, no grading at all
2. subject.webm, no grading at all
3. subject.webm again, on top, carrying the grade
Layer 3 is the only graded element: pixelate at 0.5, held constant for the
whole shot — no ramp and no fade-up. A redaction that animates on reads as an
effect; one that is simply on reads as policy. Mid strength should leave a
recognisable human shape without a readable face.
Limit layer 3 to the head with a CSS clip-path ellipse. Do not try to do this
with the grading payload — it has no spatial masking. Size the ellipse
generously so it takes in the hairline, ears, and jaw rather than sitting tight
on the features; it can overshoot the head safely, because outside the
silhouette the cutout is transparent and there is nothing to paint.
Use the original room clip as the background plate rather than a
subject-removed plate, and if the cutout has premultiplied alpha, rebuild it
with ffmpeg alphamerge first so the edges do not come out with a black rim.
```
## Custom LUTs
HyperFrames supports project-local 3D `.cube` LUTs:
```json data-color-grading
{
"lut": {
"src": "assets/luts/product-look.cube",
"intensity": 0.7
}
}
```
- 3D `.cube` LUTs up to `LUT_3D_SIZE 64` are supported.
- 1D and mixed 1D+3D `.cube` files are not supported.
- Common `DOMAIN_MIN`, `DOMAIN_MAX`, and DaVinci/IRIDAS-style
`LUT_3D_INPUT_RANGE` headers are supported.
- HyperFrames does not bundle third-party LUT packs.
- A LUT is only correct when its expected input color space matches the source.
- Rec.709 creative LUTs are the safest current workflow.
- Camera LOG conversion LUTs can be loaded, but HyperFrames does not identify
camera profiles or apply ACES/OCIO input transforms automatically.
Never paste a `.cube` body into an agent prompt. LUT files commonly contain
tens of thousands of numeric rows. Keep the file local and use metadata,
validation, and rendered comparisons to evaluate it.
## Support Matrix
| Source or workflow | Status | What to expect |
| --- | --- | --- |
| 1080p SDR video | Supported | Recommended default path |
| 4K SDR video or image | Supported | Higher preview/render cost; output resolution still follows the composition |
| iPhone SDR video | Supported | Treated as normal browser-decoded SDR media |
| iPhone HDR, HLG, or Dolby Vision-style upload | Partial | Studio can show an SDR shader preview, but native HDR delivery bypasses the SDR treatment for native HDR source pixels |
| HDR delivery render | Separate workflow | The native HDR compositor preserves HDR source pixels and does not apply this SDR grading/effects pipeline to native HDR layers |
| LOG camera footage | Partial | Requires a known matching transform/LUT; no automatic camera profile management |
| Full-scene grade including DOM/text | Not supported | Current grading targets individual media elements |
| Face or region tracking | Not supported | No masks or tracking in the contract. Isolate the region as its own layer — see [Limiting a Grade to Part of the Frame](#limiting-a-grade-to-part-of-the-frame) |
| Remote media | Partial | Requires compatible CORS headers; project-local assets are reliable |
| ACES/OCIO finishing | Not supported | Outside the current browser shader pipeline |
## Render and Performance
The runtime creates a sibling WebGL canvas, uploads the current image/video
frame as a texture, applies the same grading contract used by Studio, and hides
the native source after a shader frame is ready. During final rendering,
HyperFrames injects exact video frames and waits for the grading runtime to
redraw before capture.
That render-parity statement applies to SDR output. In the native HDR render
path, HyperFrames keeps HDR source pixels out of the SDR DOM capture and
composites them separately at higher bit depth. The current SDR grading canvas
is therefore not applied to native HDR layers. Convert or tone-map the source to
SDR first when these grading controls must appear in the result, or use
[HDR Rendering](/guides/hdr) to preserve the untreated HDR source.
For 4K output, follow [4K Rendering](/guides/4k-rendering). A 1080p source does
not gain new detail merely because the composition is rendered at 4K.
When animating a graded media layer's opacity, animate a wrapper rather than the
`<video>` itself. The visible pixels are drawn by the sibling grading canvas,
so wrapper opacity keeps the media and canvas together.
Project-local media is the safest path. Remote media must provide compatible
CORS headers and should use `crossorigin="anonymous"` when pixel access is
required.
## Next Steps
<CardGroup cols={2}>
<Card title="Media Effects" icon="wand-magic-sparkles" href="/guides/media-effects">
Apply and animate shader-based optical, retro, print, and art treatments.
</Card>
<Card title="Media Overlays" icon="layer-group" href="/guides/media-overlays">
Add editable HUD, flash, light-leak, and freeze-frame composition layers.
</Card>
<Card title="HDR Rendering" icon="sun" href="/guides/hdr">
Render HDR10 outputs and understand the boundary with SDR grading.
</Card>
<Card title="4K Rendering" icon="up-right-and-down-left-from-center" href="/guides/4k-rendering">
Render at 4K and understand source-versus-output resolution.
</Card>
</CardGroup>
- [Apply media effects](/guides/media-effects)
- [Use images and video](/guides/video-components)
- [Deliver an HDR render](/guides/hdr)
+76 -151
View File
@@ -1,184 +1,109 @@
---
title: Deploy
description: "Run a Hyperframes preview + render API in the cloud from an official template."
title: "Deploy a preview and render API"
sidebarTitle: "Hosted templates"
description: "Start from an official Vercel, Cloudflare, or Modal template when you need a hosted preview and MP4 render endpoint."
---
Hyperframes ships three official deployment templates that wrap a composition in a small web app: an in-browser preview and a `/api/render` endpoint that produces an MP4 server-side. All are open source, Apache-2.0 — Vercel and Cloudflare deploy from a single button, Modal from a single `modal deploy`.
HyperFrames has three official hosting templates. Each one previews a bundled
composition in `<hyperframes-player>` and renders it to MP4 on server-side
Chrome and FFmpeg.
| Template | Compute | Storage | Deploy |
|----------|---------|---------|--------|
| [Vercel](https://github.com/heygen-com/hyperframes-vercel-template) | [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) (Firecracker microVM) | [Vercel Blob](https://vercel.com/docs/vercel-blob) | [vercel.com/templates/ai/hyperframes-on-vercel](https://vercel.com/templates/ai/hyperframes-on-vercel) |
| [Cloudflare](https://github.com/heygen-com/hyperframes-cloudflare-template) | [Cloudflare Containers](https://developers.cloudflare.com/containers/) (Workers + Durable Object) | [R2](https://developers.cloudflare.com/r2/) | One-click button in the repo README |
| [Modal](https://github.com/heygen-com/hyperframes-modal-template) | [Modal Functions](https://modal.com/docs/guide/webhooks) (serverless containers, scale-to-zero) | [Modal Volume](https://modal.com/docs/guide/volumes) | `modal deploy src/app.py` |
Use these templates for a small hosted application. For managed rendering,
distributed infrastructure, or a Node backend, start with
[Choose a rendering path](/deploy/overview).
All three templates use the same shape:
| Template | Rendering runtime | Output storage | Best fit |
| --- | --- | --- | --- |
| [Vercel](https://github.com/heygen-com/hyperframes-vercel-template) | Vercel Sandbox | Vercel Blob | A Next.js application already deployed on Vercel |
| [Cloudflare](https://github.com/heygen-com/hyperframes-cloudflare-template) | Cloudflare Container | R2 | A Workers application that needs a containerized renderer |
| [Modal](https://github.com/heygen-com/hyperframes-modal-template) | Spawned Modal Function | Modal Volume | A Python service with render jobs that run outside the web request |
- **Preview** the bundled `ui-3d-reveal` composition in the browser via the [`<hyperframes-player>`](/packages/player) web component.
- **Render** to MP4 by POSTing to `/api/render`. The handler ships the composition to a sandboxed runtime that has Chromium, FFmpeg, and `hyperframes` pre-installed, then streams the MP4 back to storage and returns a URL.
- **Author locally**, deploy the preview + render API. Compositions are still built on your machine with `npx hyperframes init`, then dropped into the template's compositions directory.
## Vercel
## Choosing a template
The Vercel template is a Next.js application. Its `/api/render` route restores
a prepared Sandbox, runs `hyperframes render`, uploads the MP4 to Blob, and
returns a public URL.
<Tabs>
<Tab title="Vercel">
Pick this if you already deploy on Vercel, want zero-config Blob storage, or want to reuse Vercel's CI/preview environments.
[Deploy the Vercel template](https://vercel.com/new/clone?demo-title=HyperFrames+on+Vercel&demo-description=Preview+HTML+video+compositions+in+the+browser+and+render+MP4s+server-side+on+Vercel+Sandbox.&demo-image=https%3A%2F%2Fraw.githubusercontent.com%2Fheygen-com%2Fhyperframes-vercel-template%2Fmain%2Fdocs%2Fpreview.png&demo-url=https%3A%2F%2Fhyperframes-on-vercel.vercel.app&from=templates&project-name=hyperframes-on-vercel&repository-name=hyperframes-on-vercel&repository-url=https%3A%2F%2Fgithub.com%2Fheygen-com%2Fhyperframes-vercel-template&stores=%5B%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22public%22%7D%5D)
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fheygen-com%2Fhyperframes-vercel-template&stores=%5B%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22public%22%7D%5D)
Deployment provisions the Blob store. Sandbox access uses Vercel's runtime
identity. Follow the repository README for current account requirements and
platform limits.
**What you get**
## Cloudflare
- A Next.js app with `<hyperframes-player>` preview and a `POST /api/render` route.
- A pre-baked Vercel Sandbox snapshot built during `next build` — cold renders skip the Chromium/FFmpeg install and restore from snapshot in ~100 ms.
- A Vercel Blob store provisioned automatically on deploy. `BLOB_READ_WRITE_TOKEN` is injected for you.
The Cloudflare template is a TanStack Start application on Workers. A
`RenderContainer` Durable Object runs the renderer and streams the result to
R2. The template also includes optional prompt-based generation with a user's
own OpenRouter credential.
**Performance**
[Deploy the Cloudflare template](https://deploy.workers.cloudflare.com/?url=https://github.com/heygen-com/hyperframes-cloudflare-template)
Renders run on `standard-4` (4 vCPU). With `--workers auto`, three parallel Chrome workers cut render time meaningfully vs. single-worker. Concrete render time depends on composition length, complexity, and asset size.
Cloudflare Containers require a Workers Paid plan. Disable the optional AI
generation surface before hosting a public demo unless you intend visitors to
submit their own compositions.
**Pricing**
## Modal
Vercel Pro plans include Sandbox credit each month. See [Vercel Sandbox pricing](https://vercel.com/docs/vercel-sandbox/pricing) for current per-vCPU and per-GB rates and the up-to-date credit allowance.
The Modal template exposes a FastAPI application. `POST /api/render` starts a
separate render function and returns a call ID; the browser polls until the MP4
is available from a Modal Volume.
<Note>
Vercel Functions cap at 300s and a 50 MB compressed bundle, which can't fit Chromium + FFmpeg. The template uses Vercel Sandbox specifically because it's the purpose-built primitive for this workload — up to 5 hours of runtime and up to 8 vCPUs per render.
</Note>
</Tab>
<Tab title="Cloudflare">
Pick this if you're already on Cloudflare Workers, want R2's free egress, or want full control over the renderer image.
[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/heygen-com/hyperframes-cloudflare-template)
**What you get**
- A Worker that serves preview HTML and forwards `/api/render` requests to a `RenderContainer` Durable Object.
- A pre-built OCI container image with Chromium + FFmpeg + `hyperframes` baked in — no install at request time.
- An R2 bucket (`hyperframes-renders`) provisioned automatically on deploy.
**Performance**
Renders run on `standard-4` (4 vCPU, 12 GiB). With `--workers auto`, three parallel Chrome workers cut render time meaningfully vs. single-worker. Container instances sleep after 10 minutes of inactivity, so the next request after a quiet period pays a cold-start penalty.
**Pricing**
Cloudflare Containers bills per-10ms for memory, CPU, and disk; R2 storage has no egress within Cloudflare's network. Requires a [Workers Paid](https://developers.cloudflare.com/workers/platform/pricing/) plan. See [Cloudflare Containers pricing](https://developers.cloudflare.com/containers/pricing/) and [R2 pricing](https://developers.cloudflare.com/r2/pricing/) for current rates.
<Note>
Cloudflare's hosted [Browser Rendering](https://developers.cloudflare.com/browser-rendering/) API can't install FFmpeg — that's why the template uses Cloudflare Containers, which gives you a real OCI container in a Worker-bound Durable Object with up to 4 vCPUs and 12 GiB RAM.
</Note>
</Tab>
<Tab title="Modal">
Pick this if you already run on Modal, want containers that scale to zero with per-second billing, or want the render to run as a spawned function decoupled from the request.
Modal deploys from the CLI rather than a button:
```bash Terminal
uv sync
source .venv/bin/activate
modal setup # one-time auth
modal deploy src/app.py
```
**What you get**
- A FastAPI app (`@modal.asgi_app`) that serves the `<hyperframes-player>` preview and a `POST /api/render` route.
- A Modal image with Node.js 22, Python 3.12, FFmpeg, `hyperframes`, and `chrome-headless-shell` baked in at build time — no install at request time.
- A Modal Volume (`hyperframes-renders`) that persists the MP4, served back from the `/renders/:name` endpoint.
**Performance**
First deploy takes ~2 min to build the image; subsequent deploys are ~2s. Renders cold-boot in ~1s and containers scale to zero when idle. With `--workers auto`, three parallel Chrome workers cut render time (GPU is disabled via `--no-browser-gpu`). A 12s 1080p30 composition renders in roughly 10–90s depending on complexity.
**Pricing**
You pay per second of render time and nothing while idle, since containers scale to zero. See [Modal pricing](https://modal.com/pricing) for current per-CPU and per-GB rates.
<Note>
Modal web endpoints cap at 150s per request, so `POST /api/render` returns a `call_id` immediately and the render runs in a spawned Modal Function (up to 15 min, `timeout=900`). Poll `GET /api/render/:id` — it returns `202` while the render is still running, then the finished MP4.
</Note>
</Tab>
</Tabs>
## Architecture
All three templates follow the same flow: the browser plays a preview locally, then POSTs to a render endpoint that delegates to a sandboxed runtime with Chromium + FFmpeg.
```
Browser Edge / Function Sandboxed renderer
┌──────────────────┐ ┌────────────────────┐ ┌──────────────────────────┐
│ <hyperframes- │ ────▶ │ /api/render │ ────▶ │ hyperframes render │
│ player> │ │ ship composition │ │ (Chromium + FFmpeg, │
│ preview iframe │ │ → renderer │ │ pre-installed) │
│ │ ◀──── │ ← stream MP4 │ ◀──── │ │
│ │ url │ → upload to blob │ mp4 │ │
└──────────────────┘ └────────────────────┘ └──────────────────────────┘
│
└─▶ Vercel Blob / Cloudflare R2 / Modal Volume
```bash
uv sync
source .venv/bin/activate
modal setup
modal deploy src/app.py
```
The key cost-saver in all three templates is **pre-baking the renderer**. Installing Chromium system libraries plus `chrome-headless-shell` takes 30–60s, which would dominate every cold render. Vercel's template snapshots the sandbox at build time; Cloudflare's and Modal's templates bake everything into the container image. All restore in milliseconds and let you spend the entire request budget on actual rendering.
## Use your own composition
## Swapping the composition
Author and check the project locally first:
All three templates ship with one bundled composition (`ui-3d-reveal`). To use your own:
```bash
npx hyperframes init my-video
cd my-video
npx hyperframes preview
npx hyperframes check
```
<Steps>
<Step title="Author locally">
Compositions are HTML — author them on your machine with the [CLI](/packages/cli):
Then replace the bundled composition in the selected template:
```bash Terminal
npx hyperframes init my-video
cd my-video
npx hyperframes preview
```
</Step>
<Step title="Drop the bundle into the template">
Copy your composition into the template's compositions directory — `public/compositions/<your-name>/` for Vercel and Cloudflare, `compositions/<your-name>/` for Modal.
</Step>
<Step title="Point the template at it">
- **Vercel**: edit `PREVIEW_COMPOSITION_DIR` at the top of `lib/preview.ts` and the dimensions in `app/page.tsx` if it isn't 1920×1080.
- **Cloudflare**: set `PREVIEW_COMPOSITION_DIR=compositions/<your-name>` when running `npm run deploy`, or edit the default in `scripts/build.mjs`. Update player dimensions in `public/index.html` if needed.
- **Modal**: set `PREVIEW_COMPOSITION = "<your-name>"` in `src/app.py`. Update the `<hyperframes-player>` dimensions in `web/index.html` if it isn't 1920×1080.
</Step>
<Step title="Deploy">
```bash Terminal
# Vercel
vercel deploy
| Template | Composition folder | Select the composition |
| --- | --- | --- |
| Vercel | `public/compositions/<name>/` | Update `PREVIEW_COMPOSITION_DIR` in `lib/preview.ts` |
| Cloudflare | `public/compositions/<name>/` | Set `PREVIEW_COMPOSITION_DIR=compositions/<name>` when building or deploying |
| Modal | `compositions/<name>/` | Update `PREVIEW_COMPOSITION` in `src/app.py` |
# Cloudflare
npm run deploy
If the authored canvas is not 1920×1080, also update the player dimensions in
the template. Each repository README names the current file.
# Modal
modal deploy src/app.py
```
</Step>
</Steps>
## Before exposing the endpoint
## When to use a template vs. roll your own
These repositories are working examples, not a complete multi-tenant render
service. Add authentication, request limits, input validation, and cost controls
before accepting public render requests. Add a queue when jobs need retries,
priorities, or controlled concurrency.
Templates are optimized for **a single render endpoint behind a preview UI**. They're the fastest way to get a hosted Hyperframes render API running. If you need:
For infrastructure designed around distributed jobs, use
[AWS Lambda](/deploy/aws-lambda) or [Google Cloud Run](/deploy/gcp-cloud-run).
- A **render queue** with retries, deduplication, or priorities — start from a template, then add your own queue (e.g. Vercel Queues, Cloudflare Queues, SQS).
- **Multi-tenant rendering** with per-user composition uploads — start from a template, replace the bundled composition with a runtime-fetched one.
- **Self-hosted** rendering — see the [Rendering guide](/guides/rendering) and run `hyperframes render --docker` on your own infrastructure.
For everything else, the templates are the recommended starting point.
## Next Steps
## Source
<CardGroup cols={2}>
<Card title="Rendering" icon="film" href="/guides/rendering">
Render compositions locally or in Docker
<Card title="Vercel" icon="github" href="https://github.com/heygen-com/hyperframes-vercel-template">
Next.js, Sandbox, and Blob
</Card>
<Card title="Player package" icon="play" href="/packages/player">
Embed `<hyperframes-player>` in any HTML page
<Card title="Cloudflare" icon="github" href="https://github.com/heygen-com/hyperframes-cloudflare-template">
TanStack Start, Containers, and R2
</Card>
<Card title="Vercel template" icon="github" href="https://github.com/heygen-com/hyperframes-vercel-template">
Source on GitHub
</Card>
<Card title="Cloudflare template" icon="github" href="https://github.com/heygen-com/hyperframes-cloudflare-template">
Source on GitHub
</Card>
<Card title="Modal template" icon="github" href="https://github.com/heygen-com/hyperframes-modal-template">
Source on GitHub
<Card title="Modal" icon="github" href="https://github.com/heygen-com/hyperframes-modal-template">
FastAPI, spawned functions, and Volume storage
</Card>
</CardGroup>
## Related topics
- [Compare every rendering path](/deploy/overview)
- [Deploy distributed rendering on AWS Lambda](/deploy/aws-lambda)
- [Deploy distributed rendering on Google Cloud Run](/deploy/gcp-cloud-run)
+52 -223
View File
@@ -1,248 +1,77 @@
---
title: Feedback Collection
description: "How HyperFrames collects feedback, what data is collected, and how to opt out."
title: "Share feedback"
description: "Report a problem or tell the HyperFrames team what would make the product better."
---
HyperFrames occasionally asks how likely you are to recommend the render experience or Studio. This page explains why we do it, when prompts appear, what data is collected, and how to disable them.
Useful feedback explains the outcome you wanted and what stopped you from reaching it.
## Why We Ask
## Send feedback from the command line
We use anonymous recommendation scores to understand whether the tool is actually working well — not just whether it runs without errors. A render that takes 10 minutes and produces a broken file counts as a success in logs but a failure in practice. The feedback prompt is the only signal we have for that gap.
No account, email, or identity is tied to responses. Each installation generates a random UUID at setup; that is the only identifier.
## How It Works
### CLI — post-render prompt
After a successful `hyperframes render`, a short prompt may appear:
```
How likely are you to recommend HyperFrames? [0=not likely 10=extremely likely, enter to skip]
Any details? (enter to skip)
```
**When it shows:**
- First ever successful render
- Then every 15 renders after that (16th, 31st, 46th...)
- At most once per process — re-renders in the same session don't trigger a second prompt
- Automatically suppressed in quiet mode (`--quiet`), non-TTY shells, and CI environments
The prompt has a **10-second auto-timeout** — if you don't respond, it silently disappears and the CLI continues normally.
The render interval is configurable:
From a HyperFrames project, run:
```bash
# Show prompt every 5 renders instead of 15 (useful for testing)
HYPERFRAMES_FEEDBACK_INTERVAL=5 hyperframes render --output out.mp4
npx hyperframes feedback --rating 7 --comment "The render finished, but the captions were missing."
```
### Studio — session feedback bar
The rating is from 0 to 10. The comment is optional, but a specific example is usually more useful than a score alone.
A thin 32px bar slides in at the bottom of the preview area periodically:
## Report a reproducible bug
- Never on the first session — only starting from the 10th
- Then every 10 sessions (10th, 20th, 30th...)
- Slides in 3 seconds after page load to avoid flash
- Auto-dismisses after 20 seconds if ignored
- After any interaction (dismiss or submit), the session counter resets — next prompt after 10 more sessions
The session interval is configurable at build time:
```
VITE_HYPERFRAMES_FEEDBACK_INTERVAL=3
```
Invalid values (non-integer, zero, negative) fall back to the default.
**Note:** Disabling CLI telemetry (`hyperframes telemetry disable`) does not suppress the Studio bar — Studio feedback is gated separately. The submitted data is still sent through the same anonymous PostHog pipeline, so the same privacy guarantees apply.
### `hyperframes feedback` command
You can submit feedback manually at any time:
Use `--file-issue` when the project can be shared publicly:
```bash
# Quick rating
hyperframes feedback --rating 10
# Rating with details
hyperframes feedback --rating 7 --comment "render succeeded but GSAP timeline didn't animate text overlay"
npx hyperframes feedback \
--rating 3 \
--comment "The timeline freezes when this GSAP scene is opened." \
--file-issue
```
| Flag | Description |
|------|-------------|
| `--rating` | Recommendation score, 0–10 (required) |
| `--comment` | Optional free-text details |
| `--file-issue` | Also open a pre-filled GitHub issue with a published minimal repro (opt-in) |
| `--dir` | Project directory to publish as the repro (default: current directory) |
| `--yes` | Skip the publish + file-issue consent prompt (for scripts) |
<Warning>
This flow asks for confirmation before uploading the selected project directory to a public URL.
It is not a privacy scrubber and may include most of that project. The safest approach is to copy
only the files needed to reproduce the bug into a separate clean folder, inspect it, then pass
that folder with `--dir`. Never publish private media, customer data, credentials, or secrets.
</Warning>
This command collects a doctor summary automatically, flushes telemetry, and exits. It appears under the **Settings** group in `hyperframes --help`.
HyperFrames then opens a prepared GitHub issue in your browser. Review it before submitting; the issue is not posted automatically.
### Filing a GitHub issue (`--file-issue`)
You can also [open a GitHub issue directly](https://github.com/heygen-com/hyperframes/issues).
When a render misbehaves, add `--file-issue` so maintainers can reproduce it:
## Include enough evidence
A useful report includes:
- what you were trying to make;
- the action or command you used;
- what you expected;
- what happened instead;
- the exact error message;
- whether it happens every time;
- a screenshot or short recording for a visual problem;
- a small project when it is safe to share.
Do not include API keys, access tokens, credentials, private media, or customer information.
## About feedback data
HyperFrames may occasionally show a short rating prompt after a render or during a Studio session. You can ignore or dismiss it.
Feedback can include the rating, an optional comment, and basic environment information used to understand the problem. It does not include your composition HTML, video files, project names, file paths, or environment-variable values.
To turn off CLI telemetry:
```bash
hyperframes feedback --rating 3 --comment "GSAP timeline froze on seek" --file-issue
npx hyperframes telemetry disable
```
This is **opt-in** and **consented**. With `--file-issue` set, after the usual feedback is sent the CLI:
That also stops the feedback prompt and takes the install out of any
[canary rollout](/contributing/canary-rollouts) — nothing that reports nothing
is ever picked for a staged release.
1. Asks you to confirm (interactive) or requires `--yes` in non-interactive shells, because it will **publicly publish** the project at `--dir`.
2. Publishes a minimal repro of the project and gets a public URL (the same upload as `hyperframes publish`).
3. Opens your browser with a **pre-filled** GitHub issue draft, labelled `bug`, containing the rating, your comment, the public repro link, and the environment summary. It also prints the URL so you can copy it if no browser opens.
Studio feedback is controlled separately from the CLI setting.
The issue is **not auto-submitted**: you review and file it under your own GitHub account. There is no token, backend, or `gh` invocation; if publishing fails the issue still opens, just without a repro link.
## Related topics
## Agent Runtimes
When an AI agent is detected, HyperFrames **skips the interactive readline prompt** and prints a structured hint instead:
```
[hyperframes] Agent feedback: hyperframes feedback --rating <0-10> --comment "..."
```
Agents can then submit feedback using the `hyperframes feedback` command above.
The same cadence gate applies: the hint only appears on the first render, then every 15th.
**Detected agents and their markers:**
| Agent | Environment markers |
|-------|---------------------|
| Claude Code | `CLAUDECODE` present, or `CLAUDE_CODE_ENTRYPOINT` present |
| Codex | `CODEX_THREAD_ID`, `CODEX_CI`, or `CODEX_SANDBOX_NETWORK_DISABLED` present |
| Cursor | `TERM_PROGRAM` equals `cursor` |
| GitHub Copilot Agent | `GITHUB_ACTIONS` equals `true` and (`COPILOT_AGENT_ID` present or `RUNNER_NAME` equals `Copilot`) |
| Replit | `REPL_ID` or `REPLIT_USER` present |
| Hermes | `HERMES_QUIET` present |
| openclaw | `OPENCLAW_STATE_DIR` or `OPENCLAW_CONFIG_PATH` present |
| Pi | `PI_CODING_AGENT` present |
Only the existence (or in some cases the value) of these variables is checked — API keys and secrets that happen to share a prefix are never read.
## What Is Collected
### CLI feedback
Event: `cli_render_feedback`
| Field | Value |
|-------|-------|
| `rating` | Raw rating (0–10) |
| `rating_scale` | `10` for the current recommendation scale |
| `comment` | Free-text comment (only when provided) |
| `render_duration_ms` | Time the render took in milliseconds |
| `doctor_summary` | System context (see below) |
The `doctor_summary` is a compact string with environment context — included automatically so you don't need to run `hyperframes doctor` when reporting a problem:
```
os=darwin/arm64 node=v22.11.0 cpu=10cores mem=32GB ffmpeg=yes
```
It may also include `wsl` or sandbox runtime flags when those environments are detected.
### Studio feedback
Event: `studio_feedback`
| Field | Value |
|-------|-------|
| `rating` | Raw rating (0–10) |
| `rating_scale` | `10` for the current recommendation scale |
| `comment` | Free-text comment (only when provided) |
| `source` | `studio` |
| `doctor_summary` | Browser context (platform, screen, CPU cores, device memory, network type) |
## What Is NOT Collected
- File paths or project names
- Composition content, HTML, or video files
- Environment variable values
- Personally identifiable information
- IP addresses or precise location
Feedback is anonymous. Each installation has a random UUID (`anonymousId`) — there is no account, login, or email association.
## Rating Scale Compatibility
New feedback stores the raw integer together with `rating_scale: 10`.
Feedback collected before this change remains on the historical 1–5 satisfaction scale. Historical events have no `rating_scale`, and historical Slack or GitHub records retain their `/5` denominator. Consumers must treat a missing scale as legacy 1–5 data and must not reinterpret those scores as NPS.
## Config File
The CLI persists feedback state in `~/.hyperframes/config.json`:
```json
{
"telemetryEnabled": true,
"anonymousId": "a1b2c3d4-...",
"telemetryNoticeShown": true,
"commandCount": 47,
"renderSuccessCount": 14,
"lastFeedbackPromptAt": 1
}
```
| Field | Description |
|-------|-------------|
| `renderSuccessCount` | Total successful renders across all sessions |
| `lastFeedbackPromptAt` | The `renderSuccessCount` value when the prompt last appeared — used to compute whether 15 renders have passed |
Studio stores the equivalent state in `localStorage` under the `hyperframes-studio:` prefix.
## Opting Out
### CLI — disable telemetry entirely
Disabling telemetry suppresses the CLI feedback prompt, all other CLI usage tracking, and enrolment in any [canary rollout](/contributing/canary-rollouts) — an install that reports nothing is never picked for a staged rollout:
```bash
# Via CLI command (persisted to ~/.hyperframes/config.json)
hyperframes telemetry disable
# Or via environment variable (per-session)
HYPERFRAMES_NO_TELEMETRY=1 hyperframes render --output out.mp4
# Or via DO_NOT_TRACK (respects the global standard)
DO_NOT_TRACK=1 hyperframes render --output out.mp4
```
Once disabled, the `hyperframes feedback` command will print `Telemetry is disabled. Feedback not sent.` and exit without sending anything.
### CLI — suppress output without disabling telemetry
```bash
# Quiet mode: renders without any post-render output (including the feedback prompt)
hyperframes render --quiet --output out.mp4
```
### CI environments
The CLI feedback prompt is automatically suppressed when the `CI` environment variable is set (GitHub Actions, CircleCI, etc. set this by default).
### Studio
The Studio feedback bar is not affected by the CLI telemetry setting. To disable it at build time, set:
```
VITE_HYPERFRAMES_NO_FEEDBACK=1
```
When set to `"1"`, the bar never shows — `shouldShowFeedback()` returns `false` unconditionally regardless of session count or `localStorage` state.
The session interval is still configurable independently:
```
VITE_HYPERFRAMES_FEEDBACK_INTERVAL=20
```
## Related
- [Telemetry](/packages/cli#telemetry) — full telemetry settings and what usage data is collected
- [`hyperframes feedback`](/packages/cli#feedback) — CLI command reference
- [Troubleshooting](/guides/troubleshooting) — if a prompt is blocking your pipeline unexpectedly
- [Get unstuck](/help)
- [Diagnose common project and render problems](/guides/troubleshooting)
- [Search or open a GitHub issue](https://github.com/heygen-com/hyperframes/issues)
+34 -12
View File
@@ -1,32 +1,38 @@
---
title: Figma Import
title: Figma integration
description: "Bring Figma designs into HyperFrames — frozen assets, brand tokens, editable components, storyboard reconstruction, and Figma Motion timelines translated to GSAP."
---
The work your designer already did in Figma — layout, color, type, motion — becomes the starting point of a composition instead of a thing to rebuild by hand. Point at a Figma URL; the artifact lands as a native HyperFrames piece: a frozen local file, a composition variable, editable HTML, or a paused GSAP timeline.
Import the parts of a Figma design that should survive into the project: assets,
brand values, editable components, motion, or storyboard states. HyperFrames
stores the result locally so the render does not depend on Figma.
## What you can import
| Capability | What you get | Surface |
| --- | --- | --- |
| **Static assets** | A frame/layer rendered to SVG/PNG/JPG/PDF, frozen under `.media/` | `hyperframes figma asset` |
| **Brand tokens** | Figma variables/styles as composition brand variables | `hyperframes figma tokens` (Enterprise) or the `/figma` skill via MCP (any plan) |
| **Brand tokens** | Figma variables/styles as composition brand variables | `hyperframes figma tokens` or the `/figma` skill via a Figma connector |
| **Components** | A frame as editable HTML with brand-linked colors | `hyperframes figma component` |
| **Motion** | A Figma Motion timeline as an editable, paused GSAP timeline | `/figma` skill (agent, MCP) |
| **Shaders** | A shader fill/effect as a frozen still or clip | `/figma` skill (agent, MCP) |
| **Storyboards** | Scene frames reconstructed as motion — frames read as states, not slides | `/figma` skill (agent) |
| **Storyboards** | Scene frames reconstructed as motion — frames read as states, not slides | `/figma` skill (agent; REST assets are enough) |
Two transports, split by what Figma exposes: assets, tokens, and components run over the **REST API** (headless, works in CI, generous per-minute rate limits). Motion and shaders exist only on Figma's **MCP server**, so an agent drives those. Every path freezes files locally — **renders never call Figma**.
Assets, tokens, and components use Figma's **REST API** and can run headlessly.
Motion and shader data can come through a compatible **Figma connector**; if
that surface is unavailable, provide a native export instead. Storyboard
reconstruction uses ordinary frame exports plus the agent's analysis.
## One-time setup
There are two credentials, and most people only need to set up one to start:
Most people only need one connection:
| You want to import… | Set up |
| --- | --- |
| A logo, image, or a whole frame as HTML (assets, components) | A **token** — Step A below |
| Brand colors (tokens) | Either works, but on a non-Enterprise plan the **MCP connector** (Step B) gets you there in one click — the token path needs an Enterprise plan for this specific pull |
| Motion, shaders, or a storyboard | The **MCP connector** only — no token, no setup beyond connecting it |
| Motion or shaders | A compatible **Figma connector**, or a native export |
| Storyboard frames | A token for frame exports; no connector is required |
Do both if your project needs everything; each is independent, so it doesn't matter which you set up first.
@@ -52,15 +58,20 @@ Needed for anything you run from the `hyperframes figma` CLI.
export FIGMA_TOKEN="figd_…"
```
Add the line to your shell profile or the project's `.env` so future sessions skip this step. The same token covers every Figma file your account can view.
Add the line to your shell profile or the project's `.env` so future
sessions skip this step. The token can read files that its Figma account
and scopes allow.
</Step>
</Steps>
### Step B — Figma MCP connector (motion, shaders, storyboards — and an easier token-free path to brand colors)
### Step B — Figma connector (motion, shaders, and a token-free path to brand colors)
No token, no scopes to pick — connect it once when your agent asks (a one-click OAuth) and it stays connected.
This is also the easiest way to pull brand colors on **any** Figma plan, including free: the connector's variable-reading tool isn't Enterprise-gated, only rate-limited by plan — Starter/free caps at **6 calls/month**, a paid Full/Dev seat gets 200–600/day. Fine for an occasional brand pull; not for iterating call-by-call.
This is also a convenient way to read the brand values used by a selection when
the REST variables endpoint is unavailable on your plan. Connector
availability and usage limits depend on Figma's current plan and client rules,
so the agent should batch requests and cache the result.
## Import an asset
@@ -85,7 +96,10 @@ imported image_007 → .media/images/image_007.svg
hyperframes figma tokens KEY
```
Reads the file's variables (or published styles), writes a `figma-tokens.json` sidecar plus a binding index, and prints entries for the composition's `data-composition-variables`. Every scene that references a brand role — instead of a hard-coded hex — is on-brand automatically, and stays on-brand when the file changes.
Reads the file's variables (or published style metadata), writes a
`figma-tokens.json` sidecar plus a binding index, and prints entries for the
composition's `data-composition-variables`. Scenes that reference those roles
use the same local values. Run `tokens` again when the Figma file changes.
<Tip>
Import tokens **before** components. That's what lets an imported component's colors link to your brand variables instead of baking duplicate literals.
@@ -112,7 +126,9 @@ These run through the `/figma` agent skill:
- **Motion** — a Figma Motion timeline (keyframes, easing, repeats) translates structurally into a paused, finite GSAP timeline registered on `window.__timelines`, seekable frame-by-frame like any hand-authored animation, and editable afterward. Tracks that can't translate faithfully fall back to a baked video clip — the agent tells you which path it took and why.
- **Shaders** — Figma's export path doesn't execute shaders, so the default is a native Figma export (PNG or Motion MP4) imported as an asset/clip.
- **Storyboards** — a section of scene frames is decoded, not slideshowed: frames sharing an element are treated as that element's keyframes over time, diffed into element chains and tweened, with text under the strip read as director notes. When the frames depict one product UI in successive states, the agent escalates further — rebuilds the UI as live DOM and performs each frame delta as a real interaction (cursor, click, navigation), so the result reads as a continuous screen recording. See the `/figma` skill for the full grammar.
- **Storyboards** — a section of scene frames is decoded, not slideshowed:
repeated elements become continuity clues and the differences between frames
become motion or interaction. A connector is not required for this path.
## Provenance and refresh
@@ -129,3 +145,9 @@ Every import records where it came from (`fileKey`, `nodeId`, `version`) in `.me
| `RATE_LIMITED` (429) | Figma's per-minute limit | The client retries with backoff automatically (honoring `Retry-After`); if it still surfaces, wait a minute or batch fewer nodes |
| "Render timeout" on batch export | Too many large frames in one `/v1/images` call | Chunk to ~4 ids per call |
| `ref has no node id` | Link points at a file, not a node | Copy the link with `?node-id=…` (right-click layer → Copy link) |
## Related topics
- [Bring a design into a project](/guides/design-tools)
- [Work on the imported project in Studio](/studio)
- [Manage project media](/guides/media)
+82 -100
View File
@@ -1,134 +1,116 @@
---
title: GSAP Animation
description: "Add animations to your Hyperframes compositions with GSAP."
title: "Animate with GSAP"
sidebarTitle: "GSAP animation"
description: "Create a paused timeline that HyperFrames can seek to any frame."
---
Hyperframes uses [GSAP](https://gsap.com/) for animation. Timelines are paused and controlled by the runtime — you define the animations, the framework handles playback. For background on how animation runtimes plug into Hyperframes, see [Frame Adapters](/concepts/frame-adapters).
GSAP is the primary animation runtime for HyperFrames compositions. You author the motion; HyperFrames owns the playhead.
## Setup
## Minimal contract
Include GSAP and create a paused timeline:
Give the composition a finite duration, create a paused timeline, and register it under the composition ID:
```html index.html
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// 1. Create a paused timeline — the framework controls playback
const tl = gsap.timeline({ paused: true });
```html
<!doctype html>
<html lang="en">
<head>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
</head>
<body>
<div
id="root"
data-composition-id="intro"
data-start="0"
data-duration="3"
data-width="1920"
data-height="1080"
>
<h1 id="title" class="clip" data-start="0" data-duration="3" data-track-index="0">
HyperFrames
</h1>
</div>
// 2. Add animations using the position parameter (3rd arg) for absolute timing
tl.to("#title", { opacity: 1, duration: 0.5 }, 0);
<script>
const timeline = gsap.timeline({ paused: true });
// 3. Initialize the global timelines registry (if not already present)
window.__timelines = window.__timelines || {};
timeline.fromTo(
"#title",
{ opacity: 0, y: 32 },
{ opacity: 1, y: 0, duration: 0.6, ease: "power3.out" },
0,
);
// 4. Register the timeline using the data-composition-id as the key
window.__timelines["root"] = tl;
</script>
window.__timelines = window.__timelines || {};
window.__timelines.intro = timeline;
</script>
</body>
</html>
```
<Note>
The key you use in `window.__timelines` must match the `data-composition-id` attribute on your composition's root element. See [Compositions](/concepts/compositions) for how the root element is structured.
</Note>
The registry key must match `data-composition-id`.
## Key Rules
## Rules that matter
1. **Always create timelines with `{ paused: true }`** — the framework controls playback via [deterministic seeking](/concepts/determinism)
2. **Register timelines on `window.__timelines`** with the [`data-composition-id`](/concepts/data-attributes#composition-attributes) as key
3. **Use the position parameter** (3rd argument) for absolute timing: `tl.to(el, vars, 1.5)`
4. **Only animate visual properties** — never control media playback in scripts
1. Create the timeline with `{ paused: true }`.
2. Register it on `window.__timelines`.
3. Give important tweens an explicit position.
4. Prefer `fromTo()` when both endpoints matter; it remains reliable after backward or random seeks.
5. Animate transforms and opacity for movement. Avoid repeatedly animating layout properties such as `top`, `left`, `width`, or `height`.
6. Let HyperFrames control clip visibility and media playback.
## Supported Methods
The normal timeline methods are `to()`, `from()`, `fromTo()`, and `set()`. GSAP supports many CSS properties, but the [HyperFrames animation skill](https://github.com/heygen-com/hyperframes/tree/main/skills/hyperframes-animation) contains the render-safe patterns used by agents.
| Method | Description |
|--------|-------------|
| `tl.to(target, vars, position)` | Animate to values |
| `tl.from(target, vars, position)` | Animate from values |
| `tl.fromTo(target, fromVars, toVars, position)` | Animate from/to values |
| `tl.set(target, vars, position)` | Set values instantly |
## Duration
## Supported Properties
An explicit root `data-duration` is the composition's render length:
`opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `color`, `backgroundColor`, and other CSS-animatable transform/color properties. Do **not** animate `visibility`, `width`, or `height` — these break deterministic rendering.
## Timeline Duration and Composition Duration
A composition's duration equals its GSAP timeline duration. The two are directly linked:
```javascript compositions/intro-anim.html
// Your last animation ends at 3 seconds...
tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
tl.to("#title", { opacity: 0, duration: 1 }, 2);
// ...so this composition is exactly 3 seconds long.
```html
<div data-composition-id="demo" data-duration="12"></div>
```
If your composition contains a video clip that is 283 seconds long, but your last GSAP animation ends at 8 seconds, the composition will be only 8 seconds long and the video will be cut short. To extend the timeline to match the video:
This is the clearest choice for a complete composition. If the root omits `data-duration`, HyperFrames can infer length from registered timelines and supported media after the page initializes.
```javascript index.html
// All your visual animations
tl.to("#lower-third", { left: -640, duration: 0.6 }, 7.2);
Do not assume a long source video automatically extends a shorter explicit root duration. The authored duration is the output window.
// Extend the timeline to 283 seconds to match the video length.
// This adds a zero-duration tween at 283s without affecting any elements.
tl.set({}, {}, 283);
## Media belongs to the runtime
Do not play or seek media from the GSAP timeline:
```js
// Do not do this.
document.querySelector("video").play();
document.querySelector("audio").currentTime = 5;
```
<Warning>
This is one of the most common mistakes in Hyperframes. If your video cuts off early, the timeline is too short. See [Common Mistakes: Composition Duration Shorter Than Video](/guides/common-mistakes) for more details.
</Warning>
Use media timing attributes instead. If a video needs to move or resize, animate a wrapper around it rather than the video element itself.
## What NOT to Do
## Nested compositions
These patterns will break your composition or cause sync issues:
Each nested composition owns and registers its own timeline. The parent decides when the nested scene appears through its host element:
```javascript index.html
// WRONG: Playing media in scripts — the framework owns media playback
document.getElementById("el-video").play();
document.getElementById("el-audio").currentTime = 5;
// WRONG: Creating a non-paused timeline
const tl = gsap.timeline(); // missing { paused: true }!
// WRONG: Animating dimensions directly on a <video> element
tl.to("#el-video", { width: 500, height: 280 }, 5);
// WRONG: Manually nesting sub-timelines
const masterTL = window.__timelines["root"];
masterTL.add(window.__timelines["intro-anim"], 0);
```html
<div
data-composition-id="intro"
data-composition-src="compositions/intro.html"
data-start="2"
data-duration="4"
></div>
```
The framework automatically manages [media playback](/reference/html-schema#framework-managed-behavior), [clip lifecycle](/concepts/compositions#two-layers-primitives-and-scripts), and [sub-composition nesting](#sub-composition-timelines). Scripts that duplicate this behavior will conflict.
Do not manually add the child timeline to the parent's GSAP timeline. HyperFrames maps the parent playhead into the nested scene.
## Sub-Composition Timelines
## Verify the motion
Each [nested composition](/concepts/compositions#nested-compositions) registers its own timeline. The framework automatically nests sub-composition timelines into the parent based on [`data-start`](/concepts/data-attributes#timing-attributes):
```javascript compositions/intro-anim.html
// In compositions/intro-anim.html
const tl = gsap.timeline({ paused: true });
tl.from(".title", { opacity: 0, y: -50, duration: 1 });
window.__timelines["intro-anim"] = tl;
// DO NOT manually add sub-timelines to the master:
// masterTL.add(window.__timelines["intro-anim"], 0); // UNNECESSARY
```bash
npx hyperframes lint
npx hyperframes check
npx hyperframes snapshot --at 0,0.6,2.9
```
<Warning>
Don't animate `width`, `height`, `top`, or `left` directly on `<video>` elements — this can cause the browser to stop rendering frames. Wrap the video in a `<div>` and animate the wrapper instead. See [Common Mistakes](/guides/common-mistakes) for a detailed explanation.
</Warning>
Check the first frame, the moving state, and the end state. A timeline that looks correct only during continuous browser playback may still fail when the renderer seeks directly to a frame.
## Next Steps
## Related topics
<CardGroup cols={2}>
<Card title="Compositions" icon="layer-group" href="/concepts/compositions">
Understand the building blocks that timelines animate
</Card>
<Card title="Frame Adapters" icon="plug" href="/concepts/frame-adapters">
Learn how GSAP plugs into the render pipeline
</Card>
<Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
Avoid pitfalls that break animations
</Card>
<Card title="HTML Schema Reference" icon="code" href="/reference/html-schema">
Full reference for composition attributes
</Card>
</CardGroup>
- [Edit animation and keyframes in Studio](/studio/animation)
- [Understand deterministic rendering](/concepts/determinism)
- [Use the HTML composition schema](/reference/html-schema)
+35 -168
View File
@@ -1,133 +1,27 @@
---
title: HDR Rendering
description: "Render compositions to HDR10 MP4 (BT.2020 PQ or HLG, 10-bit H.265) when sources contain HDR video or images."
title: Render HDR video
description: Preserve BT.2020 PQ or HLG sources in a 10-bit H.265 MP4.
---
Hyperframes can render to HDR10 MP4 (H.265 10-bit, BT.2020) when your composition references HDR video or HDR still images. HDR is auto-detected by default from your media sources and falls back to SDR when none are present.
HyperFrames detects HDR media during render. When an MP4 project contains a BT.2020 PQ or HLG source, the output uses 10-bit H.265 and keeps the HDR signal. Projects without HDR media stay SDR.
<Note>
By default, Hyperframes probes your media and enables HDR only when HDR sources are present. Use `--hdr` to force HDR even without HDR sources, or `--sdr` to force SDR even when HDR sources are present.
</Note>
## Render and verify
## Quickstart
<Steps>
<Step title="Add an HDR source to your composition">
Hyperframes detects HDR from the source's color space metadata. The most reliable HDR sources are:
- **HDR video** tagged BT.2020 with PQ (`smpte2084`) or HLG (`arib-std-b67`) transfer
- **HDR still images** as 16-bit PNG with BT.2020 PQ encoding
See [Source Media](#source-media-requirements) for full details.
</Step>
<Step title="Render normally">
```bash Terminal
npx hyperframes render --output output.mp4
```
HDR output requires `--format mp4`. If Hyperframes detects HDR sources, it renders HDR automatically. If you also pass `--format mov` or `--format webm`, Hyperframes logs a warning and falls back to SDR.
</Step>
<Step title="Verify the output is HDR">
Use `ffprobe` to confirm the encoded stream carries HDR color tagging and HDR10 metadata:
```bash Terminal
ffprobe -v error -show_streams output.mp4 | grep -E 'color_transfer|color_primaries|color_space'
```
See [Verifying HDR output](#verifying-hdr-output) for what to look for.
</Step>
</Steps>
## How HDR Mode Works
During render, the producer:
<Steps>
<Step title="Probes every video and image source">
Runs `ffprobe` on each `<video>` and `<img>` source to read its color space (primaries, transfer function, matrix). This probe drives the default auto-detect behavior and is skipped only when you explicitly force SDR with `--sdr`.
</Step>
<Step title="Picks the dominant HDR transfer">
If any source uses PQ (`smpte2084`), the output uses **PQ**. Otherwise, if any source uses HLG (`arib-std-b67`), the output uses **HLG**. If no HDR sources are found, the render stays SDR.
</Step>
<Step title="Encodes to H.265 10-bit BT.2020">
The video encoder switches to `libx265` with `-pix_fmt yuv420p10le`, color tagging `colorprim=bt2020:transfer=<smpte2084|arib-std-b67>:colormatrix=bt2020nc`, and HDR10 static metadata (`master-display` and `max-cll`). Without that metadata, players (QuickTime, YouTube, HDR TVs) tone-map the stream as if it were SDR BT.2020 — which looks wrong.
</Step>
<Step title="Composites HDR sources natively, converts SDR overlays">
HDR videos and images are extracted as 16-bit linear-light pixels via FFmpeg, kept out of the DOM screenshot, and composited server-side at full bit depth. SDR DOM overlays (text, shapes, UI from your HTML) are converted from **sRGB** to **BT.2020** before being layered on top, so colors do not shift.
</Step>
</Steps>
## Source Media Requirements
### HDR video
Hyperframes recognizes HDR video from its `ffprobe` color space metadata:
| Indicator | Recognized as HDR |
|-----------|-------------------|
| `color_primaries` contains `bt2020` | Yes |
| `color_space` contains `bt2020` | Yes |
| `color_transfer = smpte2084` (PQ) | Yes — PQ |
| `color_transfer = arib-std-b67` (HLG) | Yes — HLG |
| All else (e.g. `bt709`, `smpte170m`) | No — treated as SDR |
A valid HDR source is any MP4 whose stream metadata reports BT.2020 primaries plus PQ or HLG transfer. Hyperframes will detect it automatically:
```bash Terminal
ffprobe -v error -show_streams assets/clip.mp4 | grep color
# color_primaries=bt2020
# color_transfer=smpte2084
# color_space=bt2020nc
```bash
npx hyperframes render --output final-hdr.mp4
```
### HDR still images
Check the result:
Hyperframes supports HDR still images delivered as **16-bit PNGs** tagged with BT.2020 primaries and PQ transfer. Drop them into the composition as a normal `<img>`:
```html index.html
<img class="clip" data-start="0" data-duration="3"
src="./assets/hdr-photo.png" />
```bash
ffprobe -v error -select_streams v:0 -show_entries \
stream=codec_name,pix_fmt,color_space,color_primaries,color_transfer \
final-hdr.mp4
```
When HDR is enabled, the image is decoded once to 16-bit linear-light RGB and composited natively into the HDR output.
A PQ output should report values equivalent to:
<Note>
HDR `<img>` decoding is limited to **16-bit PNG**. JPEG, WebP, AVIF, and APNG are not recognized as HDR sources — they load through the normal SDR DOM path. For HDR motion, use a `<video>` element.
</Note>
### SDR sources mixed with HDR
You can freely mix SDR and HDR media in the same composition:
- **SDR videos** stay in the DOM screenshot path and get the sRGB → BT.2020 conversion described above
- **HDR videos** are extracted natively at 16-bit and composited underneath the SDR DOM layer
- **SDR images and DOM elements** (text, shapes, gradients, GSAP animations) are converted from sRGB to BT.2020
This is the same pipeline that handles compositions where, for example, an HDR drone clip plays under an SDR lower-third with animated text.
## Output Format Requirements
| Output format | HDR supported |
|---------------|---------------|
| `mp4` | Yes — H.265 10-bit BT.2020, HDR10 metadata |
| `mov` | No — falls back to SDR |
| `webm` | No — falls back to SDR |
| `gif` | No — falls back to SDR |
If HDR is enabled and you also pass `--format mov`, `--format webm`, or `--format gif`, Hyperframes logs a message and produces the equivalent SDR render. There is no error — the render still completes — so check the logs (or your verification step) to confirm you got HDR.
## Verifying HDR Output
Use `ffprobe` to confirm both the color tagging and the HDR10 static metadata are present:
```bash Terminal
ffprobe -v error -show_streams -select_streams v:0 output.mp4 \
| grep -E 'codec_name|pix_fmt|color_transfer|color_primaries|color_space'
```
For a PQ HDR10 render you should see:
```
```text
codec_name=hevc
pix_fmt=yuv420p10le
color_space=bt2020nc
@@ -135,63 +29,36 @@ color_primaries=bt2020
color_transfer=smpte2084
```
Then check the HDR10 SEI / container boxes:
HLG reports `arib-std-b67` as the transfer.
```bash Terminal
ffprobe -v error -show_frames -read_intervals "%+#1" \
-show_entries frame=side_data_list output.mp4
```
## Control detection
You should see entries for **Mastering display metadata** and **Content light level metadata**. Without them, HDR-aware players will treat the file as SDR BT.2020 and the colors will look washed-out or wrong on an HDR display.
| Command | Use it when |
| --- | --- |
| `hyperframes render` | Let source metadata decide between HDR and SDR |
| `hyperframes render --hdr` | Force HDR; without detected HDR media, HyperFrames uses HLG and warns |
| `hyperframes render --sdr` | Deliver an SDR version even when the project contains HDR media |
For HLG renders the only difference is `color_transfer=arib-std-b67` — the rest of the checks are the same.
The source files must contain correct color metadata. HyperFrames recognizes video tagged as BT.2020 with PQ (`smpte2084`) or HLG (`arib-std-b67`). It can also preserve supported HDR still images through the native HDR image path.
## Docker Rendering
## Mixed compositions
Docker uses the same auto-detect logic as local rendering, so you can produce HDR10 MP4 output from the containerized renderer without extra flags:
You can place HTML text, CSS graphics, and SDR media over HDR footage. HyperFrames keeps native HDR layers outside the normal browser screenshot, converts the SDR DOM layer into the HDR color space, and composites the result before encoding.
```bash Terminal
npx hyperframes render --docker --output output.mp4
```
This is why a lower third or animated interface can remain visually consistent over an HDR source instead of forcing the whole project through an SDR screenshot.
The container runs the same probe → composite → encode pipeline as the local renderer. Verify the output with the same `ffprobe` checks described in [Verifying HDR output](#verifying-hdr-output).
## Limits
<Note>
Docker HDR rendering currently runs **CPU-side** for the SDR DOM layer (the container falls back to software WebGL because GPU passthrough is not configured by default). Frame capture is therefore slower than local headed Chrome — measure your own composition with `--quiet` off and compare wall-clock times before sizing CI runners. The encoded HDR10 metadata and pixel data are identical to a local render.
</Note>
- HDR output is MP4 only. MOV, WebM, GIF, PNG sequence, and alpha output fall back to SDR.
- HDR and `--resolution` supersampling cannot be combined in one render. Author at the target dimensions or resize in a separate step.
- Distributed AWS Lambda and Cloud Run renders are currently SDR.
- Hardware H.265 encoding carries the color tags but does not include the same static mastering metadata as the software `libx265` path. Use software encoding for HDR10 delivery.
- Browser playback depends on the host browser, display, and operating system; `<hyperframes-player>` does not add its own HDR playback pipeline.
## Limitations
If the file looks SDR, run `ffprobe` on both the source and output before changing the composition. Missing or incorrect source metadata is the most common cause.
- **MP4 only** — HDR output with `--format mov` or `--format webm` falls back to SDR
- **HDR images: 16-bit PNG only** — other formats (JPEG, WebP, AVIF, APNG) are not decoded as HDR and fall through the SDR DOM path
- **H.265 only — H.264 is stripped** — calling the encoder with `codec: "h264"` and `hdr: { transfer }` is rejected; the encoder logs a warning, drops `hdr`, and tags the output as SDR/BT.709. `libx264` cannot encode HDR, so the alternative would be a "half-HDR" file (BT.2020 container tags but a BT.709 VUI block in the bitstream) which confuses HDR-aware players.
- **GPU H.265 emits color tags but no static mastering metadata** — `useGpu: true` with HDR (nvenc, videotoolbox, amf, qsv, vaapi) tags the stream with BT.2020 + the correct transfer (smpte2084 / arib-std-b67) but does **not** embed `master-display` or `max-cll` SEI. ffmpeg does not let those flags pass through hardware encoders. The output is suitable for previews and authoring but not for HDR10-aware delivery (Apple TV, YouTube, Netflix). For spec-compliant HDR10 production output, leave `useGpu: false` so the SW `libx265` path embeds the mastering metadata.
- **Player support** — the [`<hyperframes-player>`](/packages/player) web component plays back the encoded MP4 in the browser and inherits whatever HDR support the host browser provides; it does not implement its own HDR pipeline
- **Headed Chrome HDR DOM capture** — the engine ships a separate WebGPU-based capture path for rendering CSS-animated DOM directly into HDR (`initHdrReadback`, `launchHdrBrowser`). It requires headed Chrome with `--enable-unsafe-webgpu` and is not used by the default render pipeline. See [Engine: HDR](/packages/engine#hdr-apis) if you are building a custom integration.
## Related topics
## Common Pitfalls
| Symptom | Likely cause |
|---------|--------------|
| Output looks identical to SDR | Source media is SDR, or SDR was forced with `--sdr`. Run `ffprobe` on your inputs and check the render logs |
| Output is "kind of HDR" but tone-mapped wrong on YouTube/QuickTime | Missing HDR10 static metadata on the encoded stream. Verify with the ffprobe snippet above |
| Docker render is much slower than local | Expected — the container falls back to software WebGL for SDR DOM capture. Pixel output is the same |
| Used `--format webm` and got SDR | Expected — HDR output is MP4 only |
| HDR `<img>` looks SDR / washed out | Source is not a 16-bit PNG. Re-export as 16-bit PNG (BT.2020 PQ) or use a `<video>` element instead |
## Next Steps
<CardGroup cols={2}>
<Card title="Rendering" icon="film" href="/guides/rendering">
Local vs Docker, quality presets, workers
</Card>
<Card title="CLI" icon="terminal" href="/packages/cli">
Full `render` command reference including HDR auto-detect, `--hdr`, and `--sdr`
</Card>
<Card title="Engine: HDR APIs" icon="gear" href="/packages/engine#hdr-apis">
Public HDR utilities exported from `@hyperframes/engine`
</Card>
<Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
Pitfalls that affect render output
</Card>
</CardGroup>
- [Render from the command line](/guides/rendering)
- [Open every render flag](/packages/cli#render)
- [Render at 4K](/guides/4k-rendering)
+82 -108
View File
@@ -1,130 +1,104 @@
---
title: "HTML-in-Canvas"
description: "Render live HTML as WebGL textures — GPU shaders, 3D geometry, and cinematic effects on any DOM content."
title: "HTML in Canvas"
description: "Use live DOM content as a texture for WebGL and canvas effects."
---
# HTML-in-Canvas
HTML in Canvas uses Chrome's experimental `drawElementImage()` API to copy rendered DOM content into a canvas. That canvas can become a Three.js texture or the input to a shader effect.
The HTML-in-Canvas API (`drawElementImage`) lets you capture live, rendered DOM elements directly into a canvas at GPU speed. This means you can take any HTML — dashboards, forms, landing pages, app UIs — and render them as textures in WebGL scenes with shaders, 3D transformations, and post-processing effects.
Use it when the visual treatment depends on both real HTML and GPU effects—for example, an interface inside a 3D device or a DOM scene passing through a distortion shader. It is an advanced, browser-dependent technique.
<Warning>
**Chrome flag required.** The `drawElementImage` API is experimental and must be enabled manually:
## Start with a proven block
1. Open `chrome://flags/#canvas-draw-element` in Chrome or Brave
2. Set **CanvasDrawElement** to **Enabled**
3. Restart the browser
The fastest path is to install a Catalog block that already handles capability detection and fallback behavior:
HyperFrames enables this flag automatically during rendering (`--enable-features=CanvasDrawElement`), so rendered videos work without manual setup. The flag is only needed for live preview in the Studio.
</Warning>
## How it works
1. Place HTML content inside a `<canvas layoutsubtree>` element
2. The browser renders the HTML children as normal DOM
3. Call `ctx.drawElementImage(element, x, y, w, h)` to capture the rendered pixels into the canvas
4. Use the canvas as a Three.js texture, apply shaders, map to 3D geometry
```html
<!-- 1. HTML content lives inside the canvas -->
<canvas id="capture" layoutsubtree width="1920" height="1080">
<div class="my-dashboard">
<h1>Revenue: $4.2M</h1>
<div class="chart">...</div>
</div>
</canvas>
<!-- 2. WebGL canvas for 3D rendering -->
<canvas id="theater" width="1920" height="1080"></canvas>
```bash
npx hyperframes add vfx-iphone-device
```
```javascript
// 3. Capture HTML to canvas
var capCanvas = document.getElementById("capture");
var ctx = capCanvas.getContext("2d");
ctx.drawElementImage(capCanvas.querySelector(".my-dashboard"), 0, 0, 1920, 1080);
Other relevant examples include [Portal](/catalog/blocks/vfx-portal), [Shatter](/catalog/blocks/vfx-shatter), and [Liquid Glass Notification](/catalog/blocks/liquid-glass-notification).
// 4. Use as Three.js texture
var texture = new THREE.CanvasTexture(capCanvas);
var material = new THREE.MeshBasicMaterial({ map: texture });
```
## What makes this different
Traditional approaches like `html2canvas` re-parse and re-render the DOM in JavaScript — they're slow, lossy, and miss CSS features like `backdrop-filter`, complex shadows, and web fonts. The `drawElementImage` API uses the browser's own compositor, so:
- **Pixel-perfect** — every CSS feature is supported because the browser renders it natively
- **GPU-accelerated** — captures at 60fps, fast enough for real-time animation
- **Live content** — the HTML can animate, scroll, and change between captures
- **Multiple captures simultaneously** — no nesting restrictions, multiple `<canvas layoutsubtree>` elements can capture different content in the same composition
## Feature detection
Always feature-detect before using the API. Compositions should fall back gracefully for browsers without the flag enabled.
```javascript
function isSupported() {
var tc = document.createElement("canvas");
if (!("layoutSubtree" in tc)) return false;
tc.setAttribute("layoutsubtree", "");
var ctx = tc.getContext("2d");
return ctx && typeof ctx.drawElementImage === "function";
}
if (isSupported()) {
ctx.drawElementImage(element, 0, 0, w, h);
} else {
// Fallback: draw text directly on canvas, use static image, etc.
}
```
## Re-capturing every frame
For animated content (scrolling, transitions, counters), call `drawElementImage` inside your render loop to update the texture every frame:
```javascript
function render() {
// Update HTML state
scrollContainer.style.transform = "translateY(-" + scrollOffset + "px)";
counterEl.textContent = Math.round(currentValue);
// Re-capture
ctx.clearRect(0, 0, W, H);
ctx.drawElementImage(htmlElement, 0, 0, W, H);
texture.needsUpdate = true;
// Render 3D scene with updated texture
renderer.render(scene, camera);
}
```
## Catalog blocks
Install all HTML-in-Canvas blocks at once:
Install every block tagged `html-in-canvas` only when you want to compare the full set:
```bash
npx hyperframes add html-in-canvas
```
Or install individually:
## Browser support
| Block | Description | Install |
|-------|-------------|---------|
| [iOS 26 Liquid Glass Home Screen](/catalog/blocks/ios26-liquid-glass) | iPhone home screen with live Liquid Glass notifications and widgets | `npx hyperframes add ios26-liquid-glass` |
| [macOS Tahoe Liquid Glass Desktop](/catalog/blocks/macos-tahoe-liquid-glass) | MacBook desktop with liquid glass windows, dock, and notifications | `npx hyperframes add macos-tahoe-liquid-glass` |
| [Liquid Glass Notification](/catalog/blocks/liquid-glass-notification) | Native-feeling glass notification stack with progress and reply states | `npx hyperframes add liquid-glass-notification` |
| [iPhone & MacBook](/catalog/blocks/vfx-iphone-device) | Real 3D GLTF devices with live HTML screens | `npx hyperframes add vfx-iphone-device` |
| [Text Cursor](/catalog/blocks/vfx-text-cursor) | Dramatic text reveal with chromatic shadows | `npx hyperframes add vfx-text-cursor` |
| [Portal](/catalog/blocks/vfx-portal) | Dimension breach with volumetric light | `npx hyperframes add vfx-portal` |
| [Shatter](/catalog/blocks/vfx-shatter) | HTML shatters into glass fragments | `npx hyperframes add vfx-shatter` |
| [Magnetic](/catalog/blocks/vfx-magnetic) | Magnetic field particle visualization | `npx hyperframes add vfx-magnetic` |
| [Liquid Background](/catalog/blocks/vfx-liquid-background) | Organic liquid simulation | `npx hyperframes add vfx-liquid-background` |
`drawElementImage()` is an experimental Chromium feature. The feature flag only works in browser builds that contain the API.
## Rendering
HyperFrames enables `CanvasDrawElement` when it launches Chrome and checks whether the API is actually available. The render engine can fall back to its normal capture path when the fast-capture API is unavailable or unsafe for a composition.
HyperFrames enables the Chrome flag automatically during rendering. No special configuration needed:
To refresh the browser used by the CLI:
```bash
npx hyperframes render --output my-video.mp4
npx hyperframes browser ensure --force
```
For Docker renders, the flag is also enabled automatically inside the container.
For a normal browser preview, enable `chrome://flags/#canvas-draw-element` in a compatible Chrome or Brave build and restart it. Keep a visual fallback because collaborators may open the composition in a browser without the feature.
## Minimal pattern
```html
<canvas id="capture" layoutsubtree width="1920" height="1080">
<section id="source">
<h1>Revenue: $4.2M</h1>
</section>
</canvas>
<canvas id="scene" width="1920" height="1080"></canvas>
```
```javascript
var captureCanvas = document.getElementById("capture");
var source = document.getElementById("source");
var captureContext = captureCanvas.getContext("2d");
function supportsHtmlInCanvas() {
var probe = document.createElement("canvas");
probe.setAttribute("layoutsubtree", "");
var context = probe.getContext("2d");
return "layoutSubtree" in probe && typeof context?.drawElementImage === "function";
}
if (supportsHtmlInCanvas()) {
captureContext.drawElementImage(source, 0, 0, 1920, 1080);
} else {
// Draw a simpler canvas version or use a static image.
}
```
After capture, use `captureCanvas` like any other canvas texture:
```javascript
var texture = new THREE.CanvasTexture(captureCanvas);
var material = new THREE.MeshBasicMaterial({ map: texture });
```
If the DOM changes, capture it again and set `texture.needsUpdate = true`.
## Know the limits
The browser's paint-record path does not reproduce every compositor effect. Filters, backdrop filters, some 3D transforms, masks, blend modes, and similar effects can force HyperFrames back to the normal capture path.
That fallback protects the final result, but it also means HTML in Canvas is not a promise of universal CSS support or faster rendering. Test the actual composition:
```bash
npx hyperframes lint
npx hyperframes check
npx hyperframes render --output html-in-canvas.mp4
```
Review transition frames and effects in the rendered file, not only in a live preview.
## Related topics
<CardGroup cols={2}>
<Card title="Shader transitions" icon="wand-magic-sparkles" href="/packages/shader-transitions">
Apply built-in WebGL transitions between scenes.
</Card>
<Card title="Browse visual blocks" icon="grid-2" href="/catalog">
Start from a working effect instead of rebuilding its capture logic.
</Card>
</CardGroup>
+63 -122
View File
@@ -1,162 +1,103 @@
---
title: Hyperframes vs Remotion
description: "Why we built Hyperframes, how it differs from Remotion in practice, and where each tool fits."
title: "HyperFrames or Remotion?"
description: "A practical comparison of HTML-first HyperFrames and React-first Remotion."
---
[Remotion](https://www.remotion.dev) is an awesome project, and we used Remotion in HeyGen's production pipelines for many months. Remotion promoted the idea of using code to orchestrate and animate video production, and it proved that headless Chrome could be a reliable, deterministic video renderer. Several patterns in the Hyperframes source come directly from what the Remotion team pioneered — Chrome launch flags, port selection, image2pipe streaming into FFmpeg, in-order frame buffering. We kept attribution comments in our code on purpose so the lineage stays visible to anyone reading the source.
Both tools create videos with web technology and render them through a browser. The main difference is the authoring model.
This guide is the honest breakdown of where Hyperframes and Remotion differ, written by the team that built Hyperframes. We picked different bets; each one has strengths the other doesn't, and this doc walks through both.
- **HyperFrames** treats HTML, CSS, and browser animation as the composition.
- **Remotion** treats React components and frame-based React code as the composition.
## Why we built Hyperframes
As we scaled our code-to-video pipelines at HeyGen, we kept running into the same kinds of limits inside a React-first authoring model. We debated internally whether to keep building on Remotion or write a renderer from scratch. Two factors pushed us to build Hyperframes.
### 1. The agent-native workflow
In our evals, LLMs writing Remotion compositions produced less creative visual outputs and needed a lot more guardrails and prompting than the same LLMs writing HTML + [GSAP](/guides/gsap-animation) compositions directly.
Two related issues compounded it:
- Animation libraries with their own internal clocks (GSAP, Anime.js, Motion One) don't compose cleanly with React's per-frame render.
- Arbitrary HTML or CSS that wasn't written as React doesn't have a clean path into a React composition — you have to rewrite it.
### 2. The human editing workflow
We want the same code to be the render layer _and_ the data layer, because we need a UI for humans on top of the agentic experience.
HTML is both the render layer and the editable source of truth — the same DOM is what you see and what you edit. That makes a real visual editor (selection, drag-and-drop, property panels, timeline) much more natural to build, the same way [Paper.Design](https://paper.design) does it. With Remotion, the source of truth is code plus a build step, so round-tripping through a visual editor is painful and fragile. The Remotion team has made progress here, but it's much more difficult to build a real-time editor on top of React than on top of HTML.
We architected Hyperframes to be the most native to agents while making it easy to build a human interface on top.
Neither choice is universally better. Pick the one that fits the source material, team, and workflow.
## At a glance
| | **Hyperframes** | **Remotion** |
| Question | HyperFrames | Remotion |
| --- | --- | --- |
| Authoring | HTML + CSS + GSAP | React components (TSX) |
| Runtime | Browser DOM, no framework | React reconciliation per frame |
| Build step | None; `index.html` plays as-is | Required (webpack, bundler) |
| Library-clock animations (GSAP, Anime.js, Motion One) | Seekable; frame-accurate | Plays at wall-clock during render |
| Arbitrary HTML / CSS passthrough | Paste and animate | Rewrite as JSX |
| Distributed rendering | [AWS Lambda](/deploy/aws-lambda) support | [Remotion Lambda](https://www.remotion.dev/lambda), mature and production-tested |
| [HDR output](/guides/hdr) | Supported | Documented as unsupported |
| Visual editor over render source | Native; same DOM is editable | Source is code plus a build step |
| License | [Apache 2.0](https://github.com/heygen-com/hyperframes/blob/main/LICENSE) | [Commercial](https://www.remotion.pro/license) |
| Main authoring surface | HTML, CSS, and JavaScript | React and TypeScript |
| Agent workflow | Built around agent skills and plain HTML projects | Provides agent skills and React video workflows |
| Visual editing | HyperFrames Studio edits the rendered DOM and project source | Remotion Studio can edit and animate React compositions visually, then save changes back to code |
| Existing web material | Can often be used directly or adapted as HTML | Usually translated into React components |
| Animation model | Seeks registered browser timelines frame by frame | Commonly derives visuals from the current frame in React |
| Reuse | HTML scenes, components, and Catalog items | React components and the React ecosystem |
| Cloud rendering | Local, hosted cloud, AWS Lambda, and other deployment paths | Mature AWS Lambda and server-rendering options |
| License | Apache 2.0 | Custom license with free and paid eligibility rules |
The rest of this guide walks through what each row means and where each tool actually wins.
## Choose HyperFrames when
## The core difference: React vs HTML
HyperFrames is a strong fit when:
Hyperframes and Remotion both drive headless Chrome. Both are deterministic. Both ship agent skills. They differ on one decision: what the primary author writes.
- an AI agent will do most of the authoring;
- the source is a website, HTML prototype, design artifact, or browser animation;
- you want GSAP and other browser timelines to be seeked deterministically;
- a human should review and edit the same DOM the renderer consumes;
- Apache 2.0 licensing matters;
- you want a project that can remain mostly plain HTML.
Remotion's bet is React. Video compositions are React components. You get typed JSX, the React ecosystem, component reuse, and the whole of React tooling. Remotion's strengths come from committing to that surface: years of production use, Lambda at hyperscale, a large community, careful type-safe APIs.
The main tradeoff is ecosystem maturity. HyperFrames is newer, and some advanced deployment and integration surfaces have less history than Remotion’s.
Hyperframes' bet is HTML. Video compositions are HTML pages. You can paste in a landing page, a design-system component, or a CodePen demo and animate it. We think that's the right surface for two specific use cases: AI agents writing video, and visual editors built directly on the DOM the renderer consumes.
## Choose Remotion when
Different bets, different strengths. The rest of this doc breaks down where each shows up.
Remotion is a strong fit when:
## What the difference means in practice
- your team already builds in React and TypeScript;
- you want to reuse React components and tooling;
- frame-driven React code is a natural way to express the animation;
- you depend on Remotion’s established templates, community, or production infrastructure;
- its mature Lambda ecosystem is important;
- your organization is comfortable with its current license.
### Agents express visuals better in HTML than in React
The main tradeoff is translation. Existing HTML, imperative browser animation, or a non-React design artifact may need to be adapted into React’s model.
When an LLM writes Hyperframes, it's writing the medium it was trained on most heavily. The web as browsers see it — HTML, CSS, JavaScript, GSAP idioms from CodePen, 25+ years of accumulated web animation content — is the deepest well in a model's training data. React-specific sources are a much smaller slice.
## Animation is the deepest technical difference
From running both systems in production: an agent asked to write a Remotion composition spends tokens learning framework rules (which hooks are allowed, which APIs are forbidden, how to scaffold a project) before it can be creative. Output tends to converge on a narrow visual vocabulary — centered titles, stock transitions, conventional typography. The same agent writing HTML with GSAP reaches for a wider creative range, because that's what its training data looks like.
Remotion compositions commonly calculate visual state from the current frame. This is explicit and works naturally with React.
### Animation libraries with their own clocks
HyperFrames can also use frame-derived logic, but its distinctive path is a **frame adapter**: the renderer pauses a browser animation timeline and seeks it to the exact output time before capturing the frame.
Asking an agent to port a GSAP animation or an existing web page into Remotion loses details on the first try: timing nuances, audio level relationships, text sizing. The HTML-first path avoids the translation step entirely.
That makes GSAP, Web Animations, Lottie, and other supported browser runtimes usable without letting their wall clock control the render.
We gave both tools the same 4-second GSAP timeline: 11 letters of "HYPERFRAMES" enter staggered with a back-out ease, hold for 1.5 seconds, then each letter rotates and falls out of frame. Identical animation code, identical easings, identical stagger. The only thing we changed was the renderer.
See [Frame adapters](/concepts/frame-adapters) and [Deterministic rendering](/concepts/determinism).
**Hyperframes output — what the animation is meant to look like:**
## Studio works differently
<img src="https://static.heygen.ai/hyperframes-oss/docs/images/comparisons/gsap-hf.gif" alt="Hyperframes GSAP render — letters enter, hold, then fall away over the full 4 seconds" />
HyperFrames Studio selects and edits elements in the live composition DOM. It includes Storyboard and Preview views, direct canvas editing, layers, a timeline, animation controls, assets, captions, variables, source files, lint handoff, and export.
All four seconds are used. Letters fly in one by one, the full word holds in the center for about a second and a half, then the letters spin and drop away.
That does not mean every structural change should be made visually. Broader story and source changes are often better handled by the agent.
**Remotion output — same timeline, same code:**
Remotion Studio is a development and visual-editing environment for React compositions. It supports direct manipulation and animation controls, then saves the result back to React code. Remotion also publishes tooling for building custom editing applications.
<img src="https://static.heygen.ai/hyperframes-oss/docs/images/comparisons/gsap-remotion.gif" alt="Remotion GSAP render — GSAP plays through its entire timeline in the first second, leaving most of the render as an empty stage" />
The two Studios are not interchangeable. HyperFrames Studio operates on the DOM and HTML project that HyperFrames renders; Remotion Studio operates on React compositions.
GSAP plays through its entire 4-second animation in roughly the first second of render wall-clock time. By the time Remotion captures later frames, GSAP's timeline has already completed and every letter has exited — the remainder of the render captures an empty stage.
## Rendering and deployment
**Why:** GSAP drives its own timeline via `performance.now()`, which ticks at real-time speed during render. Hyperframes pauses GSAP and seeks it to `frame / fps` before capturing each frame, so the library runs in lockstep with the output. Remotion has no equivalent primitive, so GSAP's internal ticker races through the timeline at wall-clock speed while Remotion captures a handful of frames during the entrance and mostly-empty frames after.
Remotion Lambda is a mature distributed-rendering system with extensive AWS documentation.
Everything GSAP supports — SplitText, ScrollTrigger, MotionPath, physics, 15 years of snippets on CodePen — works the same way in Hyperframes. The pattern generalizes to Anime.js, Motion One, and any other library with its own clock; any JS library without its own clock just works. Wrapping a library clock in a Remotion component is possible but awkward, and you give up most of what the library is good at.
HyperFrames supports local rendering, HeyGen-hosted cloud rendering, AWS Lambda, Google Cloud Run, and custom deployment. The right comparison depends on the destination, expected volume, and how much infrastructure the team wants to operate.
See the [GSAP animation guide](/guides/gsap-animation) for how this integrates, and [Deterministic Rendering](/concepts/determinism) for how seek-driven capture works under the hood.
See [HyperFrames deployment](/developers) and [Remotion Lambda](https://www.remotion.dev/docs/lambda).
### Arbitrary HTML, CSS, JavaScript
## Licensing
Every web page is a potential Hyperframes composition. Landing pages. Claude Design artifacts. Design-system docs. CodePen embeds. You paste in the HTML and render.
HyperFrames is available under the [Apache 2.0 license](https://github.com/heygen-com/hyperframes/blob/main/LICENSE).
Remotion asks you to translate first: rewrite HTML as JSX, convert CSS for React, wrap imperative code (Canvas, WebGL, GSAP) in React components with refs and effects. Every translation step is a chance for an agent or a human to lose fidelity or introduce bugs. The translation is round-tripping work anyway — both frameworks ultimately serve HTML to the browser to render.
Remotion uses its own license. Its current terms allow free use for individuals and companies of up to three people, with a Company License required for larger organizations. Pricing and eligibility can change, so check the [official Remotion license page](https://www.remotion.pro/license) instead of relying on a copied price here.
The [website-to-video guide](/guides/website-to-video) walks through the full capture-to-render pipeline that the HTML-first model enables.
## Moving an existing project
### Auto-fallback for edge primitives
Do not migrate only because one framework looks newer. First identify what the current project depends on:
Hyperframes has two capture modes.
- React components and React-specific libraries;
- imperative browser animation;
- cloud-rendering infrastructure;
- visual editing;
- licensing;
- team familiarity.
- **BeginFrame mode** (Linux + `chrome-headless-shell`) drives Chrome's compositor atomically via `HeadlessExperimental.beginFrame`, producing byte-for-byte reproducible frames across machines.
- **Screenshot mode** (macOS, Windows, and as an automatic fallback) runs Chrome in real time and takes ordinary screenshots — the same approach Remotion uses.
If a Remotion composition is a good candidate for HyperFrames, ask `/hyperframes` to route the work through the Remotion-to-HyperFrames migration workflow. Validate the result scene by scene; source migration is not a mechanical file conversion.
The renderer inspects each composition at compile time and falls back to screenshot mode when it spots primitives BeginFrame can't handle: inline `<iframe>`s, raw `requestAnimationFrame` loops outside a [Frame Adapter](/concepts/frame-adapters). It injects a virtual-time shim so rAF and iframe content stay frame-driven instead of wall-clock-driven. You get a diagnostic explaining the fallback, and the render produces visibly-correct output. When the composition can run in BeginFrame mode, you get determinism for free.
## Related topics
In practice: GSAP timelines, CSS `@keyframes` (via the Web Animations API adapter), Lottie, Three.js, and the Web Animations API all render deterministically in BeginFrame mode. Raw canvas loops and live-web embeds get screenshot mode automatically.
### React component reuse (Remotion's home turf)
If your team already has a design system in React components, Remotion lets you compose videos from the same primitives you ship in your app. Type safety, IDE completion, cross-file refactoring — everything React brings to developer ergonomics. For teams with existing React investment, this is a real advantage Hyperframes doesn't try to match.
### Distributed rendering
[Remotion Lambda](https://www.remotion.dev/lambda) splits long videos across hundreds of AWS Lambda functions. It's mature, production-tested, and well-documented — a thing teams have used in production for years.
Hyperframes now ships an [AWS Lambda deployment path](/deploy/aws-lambda): one Lambda function behind a Step Functions workflow that fans renders out across chunk workers, stores intermediates in S3, and exposes `lambda render`, `lambda render-batch`, progress polling, and SDK usage. The surface is newer than Remotion Lambda, so the practical tradeoff is maturity versus Hyperframes' HTML-native composition model.
### Visual editing over the render source (Hyperframes' natural bet)
The DOM you render is the DOM you edit. [Hyperframes Studio](/packages/studio) previews compositions in a live iframe, and because the renderer and the editor share one DOM, direct manipulation works against the same source of truth the render pipeline consumes. That UX — click to select, drag to reposition, edit properties in a panel — already ships for captions today, with broader element coverage building out from the same architectural foundation.
Building the same editor on top of React is harder because the source of truth is code plus a build step. Round-tripping a visual edit back to JSX means re-compiling. That's why tools like [Paper.Design](https://paper.design) chose HTML as the editable source in the first place.
### HDR output
Both tools currently render through headless Chrome, which outputs sRGB. Remotion [documents this as unsupported](https://www.remotion.dev/docs/hdr). Hyperframes [supports HDR output](/guides/hdr) via a two-pass compositing pipeline that combines a DOM layer with native HLG/PQ video.
## Open source vs source-available
This is one of the clearest differences between the two projects, and one of the most common reasons teams pick one over the other.
| | **Hyperframes** | **Remotion** |
| --- | --- | --- |
| Classification | Open source ([OSI-approved](https://opensource.org/licenses/Apache-2.0)) | Source-available, not open source |
| License | [Apache 2.0](https://github.com/heygen-com/hyperframes/blob/main/LICENSE) | [Custom Remotion License](https://www.remotion.pro/license) |
| Commercial use | Free at any scale | Requires a paid company license above small-team thresholds |
| Per-render fees | None | Yes, above thresholds |
| Redistribution | Permitted under Apache 2.0 | Restricted by the Remotion License |
Both projects publish their source on GitHub, but the licenses work very differently. Apache 2.0 is an [Open Source Initiative-approved license](https://opensource.org/licenses/Apache-2.0) — you can self-host, modify, redistribute, and use Hyperframes commercially at any scale with no per-render fees and no seat caps. The Remotion License is a custom commercial license: you can read the code and self-host for small teams, but commercial use above their thresholds requires a paid company license.
If open-source licensing matters to you — OSI compliance, redistribution rights, no per-use fees, long-term independence from a vendor's pricing decisions — this is a first-order decision point. If your use case fits within Remotion's free tier or your company is comfortable with a commercial license, it's a non-issue. See the [Remotion license page](https://www.remotion.pro/license) for their current terms.
We open-sourced Hyperframes under Apache 2.0 so anyone can build on it — including commercially, at any scale — and so the project can outlive any single company's priorities.
## Recap
The single difference between Remotion and Hyperframes is the choice of React vs HTML (+ CSS + JavaScript). That decision leads to many differences downstream. For our needs — most native to agents, architected to support a UI layer for humans — HTML + CSS + JavaScript was the obvious bet:
1. Agents already "think" in HTML. LLMs have seen massive amounts of web code.
2. True "one file in, video out." No `package.json`, no installs, no bundler config, no composition setup. Fewer moving parts = way fewer random failures in automated and agentic workflows.
3. Highest creative ceiling — anything the browser can render, HTML can represent.
4. HTML is both the render layer and the editable source of truth. The same DOM is what you see and what you edit.
We at HeyGen are all-in on Hyperframes, but we can't do this alone — that's why we open-sourced it under Apache 2.0, so together we can build the foundation for agentic video creation.
## Further reading
- [Deterministic Rendering](/concepts/determinism) — how seek-driven frame capture works
- [GSAP animation guide](/guides/gsap-animation) — library-clock integration in practice
- [Frame Adapters](/concepts/frame-adapters) — the extension point for animation runtimes
- [Website to video](/guides/website-to-video) — the HTML-first capture-to-render pipeline
- [Understand the HyperFrames project model](/concepts)
- [Choose a rendering path](/deploy/overview)
- [Build on HyperFrames](/developers)
+100 -278
View File
@@ -1,332 +1,154 @@
---
title: HyperFrames MCP
description: "Author, preview, and render HyperFrames videos directly inside Claude.ai, ChatGPT, and Grok — no local install required."
title: "Create through an AI chat"
description: "Use the hosted HyperFrames MCP connector to create and render without installing the local CLI."
---
The HyperFrames MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server that lets you create, edit, preview, and render HyperFrames video compositions from inside Claude.ai, ChatGPT, or Grok.
HyperFrames MCP is a hosted connector for supported AI chat products. It lets
the chat call HyperFrames creation and rendering tools through your HeyGen
account without installing the local CLI.
<Note>
**In beta.** Features and pricing may change. Found a bug or have feedback? [File an issue on GitHub](https://github.com/heygen-com/hyperframes/issues).
This path is in beta. Availability, interface wording, features, credits, and plan requirements
can change.
</Note>
## What you can do
## Choose hosted or local
- Create compositions from natural-language prompts
- Edit existing compositions conversationally — *"make the title 2x bigger"*, *"add hype-style captions"*
- Preview the result inline in the chat with a video player widget
- Render to `mp4`, `webm`, or `mov` — output URL streamed back to chat
- Revisit compositions you've created previously
- Check your render credits
Use the hosted connector when you want:
The agent behind `compose` has 25+ HyperFrames-specific skills baked in — typography, color palettes, motion principles, GSAP effects, audio-reactive animation, and captions. You don't have to specify any of this directly; describe the video you want and the agent picks the right tools.
- no local HyperFrames setup;
- a conversational creation flow;
- cloud rendering;
<Note>
Looking for the open-source CLI? See the [Quickstart](/quickstart). The MCP is a hosted product for zero-install authoring inside an LLM chat. The CLI gives you full control of rendering and runtime; the MCP gives you instant authoring with cloud rendering.
</Note>
Use the [local Quickstart](/quickstart) when you need:
## Setup
- full project files;
- local rendering;
- direct Studio and source editing;
- custom automation or deployment;
- precise debugging and validation.
### 1. Get a HeyGen account
## Connect HyperFrames
The MCP requires a HeyGen account for authentication and credits. Sign up at [heygen.com](https://heygen.com) if you don't have one.
The production MCP address is:
### 2. Add the connector
```text
https://mcp.heygen.com/mcp/hyperframes/
```
You need a HeyGen account and access to the HyperFrames connector.
Each host controls where custom connectors appear and which plans or workspace
roles can add them. Use the steps below as orientation, then follow the linked
host documentation when its interface differs.
<Tabs>
<Tab title="Claude.ai">
<Steps>
<Step title="Open Settings → Connectors">
In Claude.ai web or desktop: **Settings → Connectors**.
</Step>
<Step title="Find HyperFrames">
Search the connector catalog for **HyperFrames** and click **Connect**.
<Tab title="Claude">
1. Open **Customize → Connectors**.
2. Choose **Add custom connector** and enter the MCP address above.
3. Complete the HeyGen sign-in.
4. In a new chat, open the **+** menu, choose **Connectors**, and enable HyperFrames.
Don't see it in the catalog? Add it manually: **Add custom connector**, then paste:
```
https://mcp.heygen.com/mcp/hyperframes
```
</Step>
<Step title="Sign in to HeyGen">
OAuth opens in a new window. Authorize the HyperFrames connector to access your HeyGen account.
</Step>
<Step title="Start a new chat">
Open a new Claude.ai chat. Try:
See [Anthropic’s current connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for plan and workspace requirements.
> Make me a 10-second product intro for [your product] with bouncy captions and a high-energy soundtrack.
</Step>
</Steps>
</Tab>
<Tab title="ChatGPT">
<Steps>
<Step title="Open Apps & Connectors">
In ChatGPT: **Settings → Apps & Connectors → Add MCP server**.
</Step>
<Step title="Enter the URL">
Paste:
```
https://mcp.heygen.com/mcp/hyperframes
```
</Step>
<Step title="Sign in to HeyGen">
Authorize via OAuth.
</Step>
<Step title="Start a new chat">
Open a new chat. Same prompts work as in Claude.ai.
</Step>
</Steps>
If HyperFrames appears in **Settings → Apps**, choose **Connect** and complete HeyGen authorization.
To add the MCP address as a custom app, an authorized user enables the host's developer mode, creates an app from the endpoint, scans the tools, and completes OAuth. Workspace admins may control publishing and action access.
See [OpenAI’s current MCP app instructions](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta).
</Tab>
<Tab title="Grok">
<Steps>
<Step title="Open Settings → Connectors">
In Grok: **Settings → Connectors**.
</Step>
<Step title="Find HyperFrames">
Search the connector catalog for **HyperFrames** and click **Connect**.
1. Open [grok.com/connectors](https://grok.com/connectors).
2. Choose **New Connector → Custom**.
3. Enter the MCP address above.
4. Complete HeyGen authorization.
See [xAI’s current connector instructions](https://docs.x.ai/grok/connectors) for workspace requirements.
Don't see it in the catalog? Add it manually: **Add custom connector**, then paste:
```
https://mcp.heygen.com/mcp/hyperframes
```
</Step>
<Step title="Sign in to HeyGen">
Authorize via OAuth.
</Step>
<Step title="Start a new chat">
Open a new chat. Same prompts work as in Claude.ai.
</Step>
</Steps>
</Tab>
</Tabs>
## Available tools
Host products change their connector interfaces independently. If a menu or button is missing, check that host’s current plan and workspace permissions before treating it as a HyperFrames failure.
The MCP exposes six tools to the LLM. You don't call them directly — the model picks the right tool based on your message.
## Create a first composition
| Tool | What it does | Cost |
|---|---|---|
| `compose` | Create a new composition or edit an existing one | Author credits |
| `list_compositions` | List your previously created compositions | Free |
| `get_composition` | Open a specific composition with an inline player | Free |
| `render_video` | Submit a cloud render to mp4 / webm / mov | Render credits |
| `get_render_status` | Poll a long-running render job | Free |
| `get_credits` | Check your remaining credits and tier | Free |
Describe the video as you would to an editor:
### compose
Authors a new composition or applies an edit to an existing one. The HyperFrames agent handles captions, blocks, layout, transitions, color, and timing internally based on your natural-language prompt.
**Triggered by prompts like:**
- "Make a 30-second product intro about [topic]" → creates a fresh composition
- "Change the title font to a bold serif" → edits the most recent composition
- "Add a flash transition before the call-to-action" → applies a structured edit
**Returns:** A composition reference (id, title, thumbnail) plus an inline player widget. Progress notifications stream during the run so you can see what the agent is doing — *"Drafting outline...", "Selecting style...", "Generating HTML...", "Rendering preview frame..."*
### list_compositions
Lists compositions you've previously created. Newest first, paginated.
**Triggered by prompts like:** *"show me my recent videos"*, *"what did I work on yesterday?"*
### get_composition
Fetches metadata for a single composition along with an inline player widget.
**Triggered by prompts like:** *"open that video again"*, *"show me the one I made about [topic]"*
### render_video
Submits a cloud render. Defaults to `mp4` at `30fps`.
**Format options:**
| Format | Codec | Use it for |
|---|---|---|
| `mp4` (default) | H.264 | Broadest compatibility, social media, web |
| `webm` | VP9 | Smaller files; supports alpha channel for transparent overlays |
| `mov` | ProRes | Lossless quality for editing pipelines |
**Frame rate options:** `24`, `30` (default), `60`.
**Returns:** Either the rendered video URL (if the render finishes within 25 seconds) or a `job_id` for polling. Either way, an inline render-progress widget shows live status.
**Triggered by prompts like:** *"render this"*, *"export to webm"*, *"render at 60fps for editing"*.
### get_render_status
Polls an in-progress render. Used internally by the model when `render_video` returns a `job_id` (long renders).
### get_credits
Returns your tier and remaining credits.
**Triggered by:** *"how many renders do I have left?"*, *"what's my plan?"*
## Prompting tips
### Be specific about what you want
The agent has lots of creative latitude — give it enough direction to use it well.
| Less effective | More effective |
|---|---|
| "make a video" | "make a 15-second TikTok hook about home composting with bouncy captions and a warm earthy palette" |
| "add captions" | "add hype-style captions in my brand color #FF6A00" |
| "make it shorter" | "trim to 10 seconds total — cut the third scene" |
| "more energetic" | "swap to a neon-electric palette and tighten all transitions to 200ms" |
### Iterate conversationally
Once a composition exists, the agent loads the current state and applies edits in place. Keep talking to it.
```
You: "20-second product intro for my app, dark theme, hype style"
Agent: [composition + player widget appears]
You: "make the logo bigger and add a pulse animation on the CTA"
Agent: [updated player widget]
You: "render to webm with alpha"
Agent: [render-progress widget, then player widget with download link]
```text
Make a 15-second vertical product intro for a meditation app.
Audience: people who have trouble falling asleep.
Style: quiet, spacious, and warm.
Show the breathing timer and end with “Rest starts here.”
```
### Reference your existing HeyGen assets
The connector proposes and builds the composition through the tools exposed in
that chat. Follow the returned tool result rather than expecting a specific
preview widget: hosts present MCP output differently.
If you've uploaded logos, fonts, or other assets to your HeyGen account, the agent can use them. Just say *"use my logo"* or *"use my brand font."* The agent resolves the asset by name and recency.
## Revise it conversationally
### Pick the right format up front
Continue in the same conversation:
Mention the output format if you have a specific use case:
- *"render to mp4"* — default, social media
- *"render to webm with alpha"* — transparent overlay you'll composite later
- *"render to mov for After Effects"* — ProRes for editing
## Debugging
### Inspect the MCP with MCP Inspector
For developers building integrations or debugging tool responses, the MCP Inspector lets you see exactly what tools are exposed and what they return:
```bash
npx @modelcontextprotocol/inspector npx -y mcp-remote https://mcp.heygen.com/mcp/hyperframes
```text
Reveal the product two seconds earlier.
Keep the current colors.
Make the captions smaller and slow down the final transition.
```
Complete the OAuth flow in the inspector's browser tab. Once authenticated, you can call each tool with custom parameters and see raw responses, including `tool_data` and `widget_data`.
Name the visible problem and desired outcome. Avoid restarting the full brief for every revision.
### Watch progress notifications
## Render
The MCP emits MCP `notifications/progress` events during long-running `compose` and `render_video` calls. The host (Claude.ai, ChatGPT, or Grok) displays them inline:
Ask for the destination you need:
```
You: "make me a 30-second product intro"
Agent: [calls compose]
↳ "Drafting outline..." ← progress notification
↳ "Selecting style..." ← progress notification
↳ "Generating HTML..." ← progress notification
↳ "Rendering preview frame..." ← progress notification
↳ [composition + player widget]
Agent: "Here's your video — [player]"
```text
Render this as an MP4 at 30 fps.
```
If progress stops mid-flow, the run failed. The agent's next message should explain what went wrong.
MP4 is the normal sharing format. WebM can be useful for web delivery and transparent overlays. MOV can be useful for another editing workflow.
### Common issues
The connector renders on hosted infrastructure. Keep any composition or render
identifier the tool returns so you can refer to the same work in a follow-up.
<AccordionGroup>
<Accordion title="OAuth keeps failing or loops">
Verify you're using the production URL: `https://mcp.heygen.com/mcp/hyperframes`. The dev URL (`mcp.dev.heygen.com`) only accepts dev accounts.
OAuth connects the server to your current HeyGen account. Plans, limits, and
billing can change independently of HyperFrames, so confirm them in the account
before starting repeated or long renders.
If OAuth completes but you see "not authorized" errors, your HeyGen account may not have access to the MCP — contact support or check your tier.
</Accordion>
## Current limits
<Accordion title="Render is stuck or never completes">
Renders normally finish in 10-90 seconds depending on length, fps, and format.
- Rendering runs on HeyGen infrastructure. Use the local path when you need local rendering or self-hosting.
- The exact tool list and result presentation depend on the deployed server and the chat host.
- Hosted output does not give you the same local project folder, Studio surface, or debugging access as the local path.
- Precise source and pixel-level editing belongs in the local project and Studio.
If `get_render_status` shows `status: rendering` for more than 5 minutes, something has stuck. Try:
## Troubleshooting
1. Start a new chat thread
2. Run `compose("regenerate this composition")` — the underlying composition may reference an asset that's failing to load
3. If the issue persists, file an issue at [github.com/heygen-com/hyperframes/issues](https://github.com/heygen-com/hyperframes/issues) including the `job_id` from `render_video`
</Accordion>
If authorization loops:
<Accordion title='"Composition not found" error'>
The `composition_id` is owned by the HeyGen space (account) that created it. If you're signed into a different space, you can't access compositions from another. Run `list_compositions` to see what's available from your current account.
</Accordion>
1. confirm the production MCP address;
2. disconnect and reconnect HyperFrames;
3. confirm that your host plan and workspace permit the connector;
4. confirm that pop-ups and the HeyGen sign-in window are not blocked.
<Accordion title="Player widget shows blank or loads forever">
Usually a transient connection issue between the widget and `mcp.heygen.com`. Refresh the chat or call `get_composition` again.
If a create or render action stalls:
If it persists, your composition may reference a media asset that failed to upload — recreate the composition with `compose("regenerate this")`.
</Accordion>
1. keep the last tool result and any identifier it returned;
2. retry from a new chat if the host session has expired;
3. report the prompt, expected result, actual result, host, and identifier.
<Accordion title="Out of credits">
The MCP returns an error with an upgrade URL when your credits are exhausted. Visit [heygen.com/pricing](https://heygen.com/pricing) to upgrade your tier.
</Accordion>
Use [Share feedback](/guides/feedback) when the failure belongs to HyperFrames. Use the host product’s support when the connector cannot be installed or invoked at all.
<Accordion title="Tool call timed out in the host">
`compose` runs can take 30+ seconds for complex prompts. If your client times out before the response comes back, the underlying run is likely still progressing — wait 30 seconds and run `list_compositions`. The composition is probably already created.
</Accordion>
<Warning>
Only connect the production HyperFrames server shown on this page. As with any external connector,
review the permissions and do not send secrets or private material that the destination should not
receive.
</Warning>
<Accordion title="Agent ignored part of my prompt">
The agent prefers structural decisions (palette, layout, motion) over fine-grained pixel positioning. If a specific edit doesn't land, try rephrasing more directively:
## Related topics
- Less effective: *"the title is a little off"*
- More effective: *"move the title 40px down and increase its weight to 800"*
For pixel-precise control, use the [open-source CLI](/quickstart) — the MCP is optimized for fast natural-language iteration.
</Accordion>
</AccordionGroup>
### Reporting issues
For bugs or feature requests, file an issue at [github.com/heygen-com/hyperframes/issues](https://github.com/heygen-com/hyperframes/issues). Include:
- The prompt you used
- The `composition_id` and `job_id` (if applicable) — these are visible in the tool response details
- A description of what you expected vs. what happened
- The host (Claude.ai web/desktop, ChatGPT, Grok, etc.)
## Limitations
- **Cloud-only rendering.** All renders run on HeyGen infrastructure. Use the [CLI](/quickstart) if you need local rendering.
- **Single-user.** Each composition is owned by one HeyGen account. No team sharing in v1.
- **No binary uploads from chat.** You can reference assets you've already uploaded to HeyGen via the web UI, but the MCP does not currently accept new file uploads through chat. Upload via [app.heygen.com](https://app.heygen.com) first, then reference the asset by name.
- **Aspect ratios:** `16:9`, `9:16`, `1:1`, `4:5`. Other ratios fall back to the closest match.
- **No fine-grained editing tools.** Edits go through the agent. For pixel-precise control, use the [CLI](/quickstart) and a coding agent like Claude Code or Cursor.
- **Widget rendering requires a host that supports MCP widgets.** Claude.ai web/desktop, ChatGPT (Apps SDK), and Grok support widgets today. Text-only MCP clients (Claude Code CLI, Cursor, Windsurf) will see a clickable preview URL instead — full text-mode support is on the roadmap.
## How this relates to the open-source framework
[HyperFrames itself is open source](https://github.com/heygen-com/hyperframes) — the HTML composition format, CLI, renderer, and player. You can use HyperFrames locally without the MCP.
The MCP is a HeyGen-hosted product that wraps:
- The HyperFrames composition agent (the LLM that authors compositions)
- HeyGen's cloud rendering pipeline
- HeyGen's asset libraries
- OAuth, credits, and tier management
| You want… | Use… |
|---|---|
| Zero local install, fast natural-language authoring | The MCP |
| Pixel-precise control, custom rendering, self-hosting | The [CLI](/quickstart) |
| Both | Author with the MCP, then download and refine with the CLI (planned export feature) |
## Next steps
<CardGroup cols={2}>
<Card title="Quickstart" href="/quickstart">
Try HyperFrames locally with the open-source CLI.
</Card>
<Card title="Prompting guide" href="/prompting/overview">
Tips for getting the best results when working with AI agents.
</Card>
<Card title="Catalog" href="/catalog/blocks/data-chart">
Browse 50+ ready-to-use blocks the agent draws from.
</Card>
<Card title="Examples" href="/examples">
Reference compositions you can clone.
</Card>
</CardGroup>
- [Make a locally editable first video](/quickstart)
- [Choose where to create](/guides/choose-creation-path)
- [Share connector feedback](/guides/feedback)
+77 -292
View File
@@ -1,323 +1,108 @@
---
title: Media Effects
description: "Apply deterministic shader effects to video and image media, combine them with color grading, and animate supported strengths with GSAP."
title: "Apply media effects"
sidebarTitle: "Media effects"
description: "Apply editable blur, bloom, retro, print, glitch, and art treatments to images and video."
---
Use Media Effects to transform real `<video>` and `<img>` pixels with
deterministic blur, retro, print, and art treatments that can share one payload
with [Color Grading](/guides/color-grading).
Media effects transform a selected image or video without baking a new source
file. They stay editable in Studio and render from the same project data.
## Effect Families
<Frame caption="Four current HyperFrames renders from one source. Effects stay on the media element, so the original file remains unchanged.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/media-effects-grid-v1.png"
alt="One presenter frame shown as the original, pixelated, two-ink print, and ASCII treatments"
/>
</Frame>
### Essentials
## Choose the effect
| Effect | What it does |
| --- | --- |
| Blur | Defocuses or softens the complete media layer |
| Pixelate | Converts the layer into a block mosaic |
| Bloom | Adds thresholded glow around bright regions |
| Intent | Start with |
| ------------------------------------------------------- | ---------------------------------- |
| Soften, conceal, or lift bright areas | Blur, Pixelate, or Bloom |
| Add tape, film, CRT, or digital damage | Retro & Glitch |
| Turn media into dots, ink, or a limited palette | Print |
| Create ASCII, engraving, crosshatch, or painted media | Art |
| Add grain or darkened edges | Grain or Vignette in Color Grading |
| Add a HUD, light leak, flash, or freeze-frame treatment | A [Catalog](/catalog) overlay |
### Retro & Glitch
Effects apply to the complete selected media element. They do not track a face,
screen, or object. Isolate a region into its own cropped or masked media layer
when only that region should change.
| Effect | What it does |
| --- | --- |
| Chroma Softening | Smears chroma while retaining central luma |
| Tape Damage | Adds deterministic tracking errors, noise, ghosting, and dropouts |
| Film Artifacts | Adds deterministic dust and short scratches |
| Scanlines | Adds configurable horizontal display lines |
| CRT Curvature | Warps media toward curved display geometry |
| Channel Separation | Offsets color channels along an angle |
| Digital Glitch | Combines line tears, blocks, displacement, pixelation, and channel split |
## Try effects in Studio
When authoring JSON directly, **Chroma Softening** uses `chromaBleed` and
**Channel Separation** uses `chromaticAberration`. Query the capability command
for the canonical payload keys of all other controls.
Select an image or video and open **Effects** in the Inspector. The effect
browser is grouped into:
### Print
- **Essentials:** Blur, Pixelate, Bloom
- **Retro & Glitch:** Chroma Softening, Tape Damage, Film Artifacts, Scanlines,
CRT Curvature, Channel Separation, Digital Glitch
- **Print:** Halftone, Two-Ink Print, Ordered Dither, Mono Screen
- **Art:** ASCII, Engraving, Crosshatch, Kuwahara Paint
| Effect | What it does |
| --- | --- |
| Halftone | Renders source color through a print-dot raster |
| Two-Ink Print | Reduces media to the built-in two-ink treatment |
| Ordered Dither | Quantizes media into an ordered limited palette |
| Mono Screen | Builds monochrome dot, shape, or line artwork |
Choose one effect for the job, adjust its controls, then play or scrub the
beginning, middle, and end. Some effects are much more expensive to render than
others, especially Blur, Bloom, and Kuwahara Paint across large media layers.
### Art
## Ask the agent
| Effect | What it does |
| --- | --- |
| ASCII | Renders media as configurable procedural glyph cells |
| Engraving | Translates luminance into directional engraved lines |
| Crosshatch | Translates media into layered hand-hatched lines |
| Kuwahara Paint | Applies edge-preserving painterly smoothing |
Describe the result instead of guessing control values:
## Quick Start
```text
Make this product clip feel like a clean two-ink editorial print.
Keep the product shape and label readable.
```
<Tabs>
<Tab title="Studio">
<Steps>
<Step title="Select real media">
Select a real `<img>` or `<video>` in the preview, Layers panel, or
Timeline. Effects do not appear for arbitrary divs or CSS background
images.
</Step>
<Step title="Choose and tune an effect">
Preview an effect preset or open **Effects**. Enabling an effect uses a
calibrated default; expand it to adjust only the controls relevant to
the intended result.
</Step>
<Step title="Verify motion and framing">
Play and scrub videos at the beginning, middle, and end. Confirm that
moving effects and object-fit/object-position framing remain correct.
</Step>
</Steps>
</Tab>
<Tab title="Agent / CLI">
Discover the narrow effect contract, then apply the complete treatment in
one mutation:
The agent can inspect the live capability catalog before editing:
```bash Terminal
npx hyperframes media-treatment --capabilities --json
npx hyperframes media-treatment --capability digitalGlitch --json
npx hyperframes media-treatment \
--project . \
--file compositions/scene.html \
--selector '#hero' \
--grading '{"effects":{"digitalGlitch":0.55,"digitalGlitchColorSplit":0.25,"digitalGlitchLineTear":0.25,"digitalGlitchPixelate":0.15,"digitalGlitchBlockAmount":0.5,"digitalGlitchBlockDisplacement":0.25,"digitalGlitchSpeed":0.5}}' \
--apply \
--json
```
</Tab>
</Tabs>
Project-local media is recommended; remote media requires compatible CORS.
[Media Overlays](/guides/media-overlays) are separate editable composition
layers rather than shader properties.
<Warning>
Media Effects use the SDR/Rec.709 shader pipeline. Studio can preview that
pipeline on browser-decoded HDR media, but native HDR rendering preserves the
HDR source separately and does not apply these SDR effects to native HDR
layers. Convert or tone-map to SDR when an effect must appear in the final
output. See [Color Grading support](/guides/color-grading#support-matrix) and
[HDR Rendering](/guides/hdr).
</Warning>
## Effect Presets
`Creator Camcorder`, `VHS Playback`, `8mm Home Movie`, `Editorial Halftone`, and
`Two-Ink Print` provide tested combinations of effect, correction, and
finishing settings. Preview one as a starting point, then tune the underlying
controls. They are normal shader payloads, not baked media or bundled LUTs.
## Agent Guidance
Agents should discover only the part of the toolbox relevant to the user's
intent:
The user may simply ask for _"an old home-video feel"_, _"a useful privacy
reveal"_, or _"something more graphic for this poster."_ The `media-use` skill
classifies that intent, then queries the narrow effect or recipe details instead
of loading the exhaustive contract.
```bash Terminal
```bash
npx hyperframes media-treatment --capabilities --json
npx hyperframes media-treatment --capability retro-glitch --json
npx hyperframes media-treatment --capability digitalGlitch --json
npx hyperframes media-treatment --capability twoInkPrint --json
```
The concise overview lists capability families. A focused query returns the
effect's calibrated apply payload, controls, render lane, palette support, and
seek-safe animation path. Use the canonical payload instead of guessing
sub-control defaults.
Then it can apply a validated patch:
Recipes are tested shortcuts, not a closed list. An agent may assemble a custom
payload when the source and intent justify it, but it should:
1. Choose one primary visual intent.
2. Query the exact effect or family contract.
3. Add only controls that visibly support that intent.
4. Avoid stacking several dominant stylizations without a reason.
5. Verify representative frames and a short render.
## Palettes
`palette` accepts two to six exact `#RRGGBB` colors in authored order.
Dark-to-light order creates normal luminance mapping; reversing the array
intentionally inverts that mapping.
```json data-color-grading
{
"effects": {
"dither": 1,
"ditherSize": 0.5
},
"palette": ["#080717", "#3c185f", "#d9339f", "#ff6b66", "#aafae0"]
}
```bash
npx hyperframes media-treatment \
--selector '#product' \
--grading '{"preset":"two-ink-print"}' \
--apply --json
```
Compatible effects are ASCII, Ordered Dither, Mono Screen, Engraving, and
Crosshatch. A palette alone does not activate an effect.
Use `--dry-run` to inspect the exact mutation without writing, `--analyze` for
bounded source measurements and a suggested primary correction, or `--clear`
to remove the selected treatment. The command writes the same
`data-color-grading` contract that Studio uses.
Discover built-in palettes without copying their values into instructions:
## Keep the treatment useful
```bash Terminal
npx hyperframes media-treatment --capability palettes --json
npx hyperframes media-treatment --capability electric-ink --json
```
- Use blur or pixelation for a real reveal, focus shift, or privacy need.
- Use a named stylization strongly enough to read; keep ordinary correction
restrained.
- Compare against the original and inspect representative rendered frames.
- Remove the treatment when it competes with the story.
## Animation and Keyframes
## Performance and delivery
The following paths have seek-safe CSS custom properties and may be animated by
a paused, registered GSAP timeline:
Several overlapping, full-frame treated layers can slow preview and rendering,
especially at 4K. Simplify the stack or pre-render a finished layer when
playback drops frames.
- Global treatment intensity
- LUT intensity
- Exposure
- Blur
- Bloom
- Kuwahara Paint
- Pixelate
- ASCII
- Ordered Dither
Effects use the SDR/Rec.709 shader pipeline. Native HDR delivery preserves HDR
source pixels through a separate path, so these SDR effects do not appear on
native HDR layers. Convert or tone-map to SDR when the effect must appear in
the final result.
Example blur-to-focus reveal:
Project-local media is the reliable default. Remote media must allow browser
pixel access through compatible CORS headers.
```html index.html
<div
class="clip"
data-composition-id="media-effect-demo"
data-start="0"
data-duration="4"
>
<video
id="hero"
src="assets/hero.mp4"
muted
playsinline
style="--hf-color-grading-blur: 0.8"
data-color-grading='{"effects":{"blur":0.8}}'
></video>
</div>
The [Color Grading guide](/guides/color-grading) covers correction, wheels,
curves, selective color, finishing, and LUTs. The [HTML
schema](/reference/html-schema#color-grading-and-media-effects) contains the
persistence contract.
<script>
const tl = gsap.timeline({ paused: true });
tl.to(
"#hero",
{
"--hf-color-grading-blur": 0,
duration: 1.2,
ease: "power2.out",
},
0,
);
window.__timelines = window.__timelines || {};
window.__timelines["media-effect-demo"] = tl;
</script>
```
## Related topics
Author the initial custom-property value inline. Do not use timers, unseeded
randomness, frame-zero `set()` calls, or `onUpdate` callbacks. Query an effect's
focused capability to get its exact animation property and range.
Tape damage, digital glitch, film artifacts, and similar effects may contain
deterministic internal motion even when their overall strength is not one of
the keyframeable paths above.
## Important Effect Behavior
- **Tape Damage** is the primary analog-tape amount. Tracking controls moving
tears, Noise controls row jitter/noise, and Speed controls their deterministic
motion. Those subordinate controls do not activate tape damage by themselves.
- **Film Artifacts** adds sparse deterministic dust and scratches. Grain,
vignette, color, and optional wrapper motion such as a subtle gate weave are
separate choices.
- **Halftone** uses fixed print-oriented channel angles and edge behavior.
Cell size remains adjustable.
- **Two-Ink Print** is HyperFrames' own fixed two-ink mapping. Do not describe
it as a named commercial print process or stack it with Halftone by default.
- **ASCII** uses procedural glyph cells. Size, style, ink behavior, rotation,
and a compatible palette remain configurable.
- **Ordered Dither** uses a temporally stable 4x4 Bayer matrix. It is not
Floyd-Steinberg or another sequential error-diffusion algorithm.
- **Bloom** extracts bright regions before blurring them; it is different from
raising highlights or whites.
- **Kuwahara Paint** smooths regions while preserving major edges. Radius,
sharpness, and saturation shape the result.
## Deterministic Pipeline Order
HyperFrames evaluates combined treatment stages in one fixed order:
1. Source framing and multipass Blur/Kuwahara preparation
2. Chromatic and digital-glitch transforms
3. Primary correction, color grading, and LUT blended by global intensity
4. Grain and film artifacts
5. Mono, engraving, crosshatch, halftone, two-ink, dither, and ASCII
6. Bloom, scanlines, vignette, and CRT display masking
7. Before/after comparison
The order cannot currently be rearranged. A fixed order keeps Studio,
playback, seeking, and final rendering deterministic and prevents agents from
inventing incompatible effect graphs.
## Performance
Performance follows the number of treated pixels and the selected render lane,
not only the number of elements.
- Blur, Bloom, and Kuwahara use multipass rendering.
- Several tiled media elements can be cheaper than several overlapping
full-frame elements.
- When more than two full-frame multipass-treated elements are visible
together, verify continuous playback on the target machine.
- Simplify or pre-render a stack when preview frames drop.
- Kuwahara uses bounded half-float intermediate targets when supported and
otherwise reports itself unavailable.
For 4K delivery, verify the effect at the final composition size. Resolution-
aware effects preserve their intended scale, but 4K still processes more pixels
than 1080p.
## Low-Level HTML Contract
Media effects live in the same persisted contract as grading:
```html index.html
<img
id="poster"
src="assets/poster.jpg"
data-color-grading='{
"effects":{
"ascii":1,
"asciiSize":0.066,
"asciiStyle":0,
"asciiColor":1,
"asciiRotation":0
},
"palette":["#001100","#00ff00"],
"colorSpace":"rec709"
}'
/>
```
Unknown keys are rejected and values are normalized by the Core contract. The
CLI should remain the primary authoring surface for agents.
## Next Steps
<CardGroup cols={2}>
<Card title="Color Grading" icon="palette" href="/guides/color-grading">
Correct and grade media with scopes, wheels, curves, selections, and LUTs.
</Card>
<Card title="Media Overlays" icon="layer-group" href="/guides/media-overlays">
Add authored HUD, flash, light-leak, and freeze-frame layers.
</Card>
<Card title="Keyframes" icon="diamond" href="/guides/keyframes">
Edit and verify deterministic GSAP animation in Studio.
</Card>
<Card title="Performance" icon="gauge-high" href="/guides/performance">
Diagnose source resolution, browser, decoder, and composition cost.
</Card>
</CardGroup>
- [Color grade images and footage](/guides/color-grading)
- [Use images and video](/guides/video-components)
- [Browse ready-made visual effects](/catalog)
+1 -1
View File
@@ -414,7 +414,7 @@ as the canonical reference and follow its patterns verbatim:
- HDR / wide-gamut color handling
- Audio-reactive animation (`hf-seek` + `window.__hfAudio`)
- Captions / TTS integration
- The `hyperframes add` registry (50+ blocks and components)
- The `hyperframes add` registry of blocks and components
This skill stays focused on what Open Design needs at emission time — the
structural rules, the active-`DESIGN.md` binding, and the 5-dim self-critique
+40 -115
View File
@@ -1,139 +1,64 @@
---
title: Performance
description: "How to keep preview playback smooth and diagnose expensive compositions."
title: Fix a slow preview or render
description: Find the expensive part of a composition and make it cheaper.
---
Preview plays your composition in real time, so any frame that takes longer than 33ms (at 30fps) shows up as stutter. This page covers the patterns that blow that budget and how to spot them.
A finished render can be smooth even when preview stutters. Preview must draw each frame in real time; render can take as long as it needs to capture the same frames.
## Preview vs. render
## Start with the symptom
Render captures frames one at a time and stitches them into a video. Slow frames make the render take longer, but you never see the pauses — you watch the finished mp4.
| What you see | Check first |
| --- | --- |
| Preview stutters in one scene | Large blurs, masks, shadows, or many animated layers in that scene |
| Preview pauses the first time an image appears | Oversized source images or image decoding |
| The whole page becomes slow | Script work, layout thrashing, or too many DOM nodes |
| Render is slow but the result is correct | Source-video extraction, frame capture, or encoding |
| WebM takes much longer than MP4 | VP9 encoding; transparent WebM is CPU-heavy |
Preview does the same work in real time. If a frame takes 200ms to paint, you see a 200ms freeze.
## Reduce expensive browser work
This is why "render looks fine, preview stutters" is expected for paint-heavy compositions. It doesn't mean preview is broken — it means individual frames are too expensive for real-time playback.
- Use fewer large `backdrop-filter` and `filter: blur()` layers.
- Avoid animating dozens of shadowed elements at once.
- Replace a static blur or texture stack with a pre-rendered image.
- Size images near their actual delivery dimensions. A very large JPEG still decodes into a very large bitmap.
- Keep work inside animation callbacks small. Do not repeatedly read layout and write styles in the same frame.
## Expensive CSS patterns
For a 1920×1080 composition, a 3840×2160 source already provides enough detail for a 2× display. Larger sources usually add memory and decode work without improving the frame.
These are the patterns that most often cause preview to drop below 30fps.
## Measure instead of guessing
### backdrop-filter: blur()
1. Run `npx hyperframes preview`.
2. Open Chrome DevTools and select **Performance**.
3. Record the part that stutters.
4. Inspect the longest tasks:
- **Paint** or **Composite Layers** points to filters, shadows, masks, or large layers.
- **Layout** or **Recalculate Style** points to layout work.
- **Script** points to author code.
Each `backdrop-filter: blur(radius)` sampled over a large area forces the compositor to read pixels from behind the element, run a blur kernel across them, and composite the result. Cost scales with both the blurred area and the radius.
Change one expensive feature, record again, and keep the version that moves the bottleneck.
Stacked blur layers multiply the cost. Eight layers at progressively larger radii (1, 2, 4, 8, 16, 32, 64, 128px) will happily take 200ms per frame over a 1920x1080 region on mid-tier GPUs.
## Make a fast review render
**What to do:**
- Keep stacked layers to 2-3 maximum, with manually tuned radii
- Avoid `blur(128px)` or `blur(64px)` over large areas — the biggest radii dominate the cost
- For a static blur, render it once into a PNG and use a regular `<img>` overlay
If the composition is intentionally too heavy for real-time playback, review an encoded file:
### filter: blur() and filter: drop-shadow()
Same story as `backdrop-filter` but applied to the element itself rather than behind it. Fine on small elements, expensive on large ones.
### Shadows on many elements
`box-shadow` and `text-shadow` on a few elements are fine. On dozens of elements that also animate, the compositor re-rasterizes each shadowed layer on every frame.
### Large gradients with mask-image
Combined with `backdrop-filter`, `mask-image` can force additional compositor passes. If you have both on the same element, consider whether you need both.
## Image sizing
Image source resolution matters more than file size. Chrome decodes JPEGs and PNGs to raw RGBA bitmaps before displaying them — a decoded bitmap is:
```
bitmap_bytes = width × height × 4
```bash
npx hyperframes render --quality draft --output review.mp4
```
A 7000×5000 source image is 140MB decoded, regardless of whether the JPEG on disk is 2MB or 5MB.
Use `standard` or `high` for delivery. Draft changes capture and encoder quality; it does not change the composition's timing.
**Rule of thumb:** resize source images to at most 2x the canvas dimensions. For a 1920x1080 canvas, 3840x2160 source images are already overkill. Anything above that is paying for memory and texture-upload cost that never shows on screen.
## Tune transparent WebM only when needed
```bash Terminal
# ImageMagick one-liner to downsize a directory of images
mogrify -path resized -resize 3840x3840\> *.jpg
```
WebM uses the CPU-heavy VP9 encoder. The default is suitable for most work. To trade more encoding time for compression quality:
## Measuring a slow composition
Don't guess — measure. Chrome DevTools has everything you need.
<Steps>
<Step title="Run preview">
Start the preview server and open it in Chrome:
```bash Terminal
npx hyperframes preview
```
</Step>
<Step title="Open DevTools → Performance">
`Cmd+Option+I` (macOS) or `Ctrl+Shift+I` (Linux/Windows), then switch to the **Performance** tab.
</Step>
<Step title="Record during playback">
Hit the record button, click play in the preview, let it run 3-5 seconds through the jank-prone scene, then stop recording.
</Step>
<Step title="Read the main thread track">
Look for long tasks (red-flagged in the timeline). Expand the tallest bars and check what Chrome labels them:
- **Composite Layers / Paint** with a large duration = compositor cost (backdrop-filter, shadows, large textures)
- **Decode Image** = image decode on first paint (rare in Chrome 131+, images decode off-thread by default)
- **Layout / Recalculate Style** = layout thrashing from script
- **Script** = JS work (rare for compositions, check author scripts)
</Step>
</Steps>
Once you know which category dominates, you know what to change.
<Tip>
A composition that runs at 60fps in isolation but stutters only during specific scenes is usually a composite-cost problem. Check which layers become visible during those scenes.
</Tip>
## When preview is unavoidable slow
Some compositions are legitimately too expensive for real-time playback. If you've reduced what you can and preview still stutters, render-to-mp4 and watch the output is a fine workflow — render is still accurate.
```bash Terminal
npx hyperframes render --quality draft --output preview.mp4
```
Draft quality renders fast and is visually close to the final render for everything except encoder-level detail.
## WebM encode speed
Transparent WebM output uses FFmpeg's `libvpx-vp9` encoder. VP9 is CPU-heavy, so short overlay renders can spend most of their wall time in the encode stage even when frame capture is fast.
HyperFrames sets `-cpu-used 4` for VP9 by default. On a devbox check using an 8s 1280×720, 15fps VP9-alpha encode, explicit `-cpu-used 4` cut encode time from 6.3s to 2.6s versus libvpx's default, with SSIM 0.9986 and PSNR 50.5dB against the default encode. Your composition and host CPU will move those numbers, but the direction is consistent: higher values trade some compression efficiency for faster WebM encodes.
Tune per deployment with:
```bash Terminal
PRODUCER_VP9_CPU_USED=2 npx hyperframes render --format webm --output overlay.webm
```
For one-off local renders, pass the same value directly:
```bash Terminal
```bash
npx hyperframes render --format webm --vp9-cpu-used 2 --output overlay.webm
```
Valid values are integers from `-8` to `8`; HyperFrames clamps out-of-range values before passing them to FFmpeg.
`--vp9-cpu-used` accepts integers from `-8` to `8`; higher values are faster with a larger quality/size tradeoff.
## Next Steps
## Related topics
<CardGroup cols={2}>
<Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
Environment, tooling, and rendering issues
</Card>
<Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
Composition pitfalls that break rendering
</Card>
<Card title="Rendering" icon="film" href="/guides/rendering">
Rendering modes, options, and flags
</Card>
<Card title="CLI Reference" icon="terminal" href="/packages/cli">
Full list of CLI commands
</Card>
</CardGroup>
- [Diagnose a failed or stalled render](/guides/troubleshooting)
- [Render from the command line](/guides/rendering)
- [Render at 4K](/guides/4k-rendering)
+84 -388
View File
@@ -1,424 +1,120 @@
---
title: Remove Background (transparent video)
description: "Remove the background from a video or image and drop it into any composition as a transparent overlay."
title: "Remove a background"
description: "Turn footage of a person or a portrait image into transparent media you can layer over a HyperFrames scene."
---
Background removal — also called *matting* in VFX — separates a foreground subject (typically a person) from its background. The output is a video with an alpha channel: fully transparent where the background was, opaque where the subject is. Drop it into any HyperFrames composition as a `<video>` tag and the subject floats over whatever you put behind them.
Use background removal when a person needs to appear over designed text,
graphics, or another scene. HyperFrames runs the included human-segmentation
model locally; it does not upload the source or require an API key.
The CLI ships a built-in `remove-background` command that runs locally — no API keys, no cloud upload, no green screen.
<Frame caption="The same real frame before and after the local model. The softer hair and hand edges are the model’s actual limit on this source.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/remove-background-before-after-v1.png"
alt="The original presenter frame beside its transparent cutout over a green background"
/>
</Frame>
## Quick Start
## Create the transparent file
<Steps>
<Step title="Verify ffmpeg is installed">
The pipeline needs `ffmpeg` and `ffprobe` for decode + encode. Most systems already have them; if not:
Make sure FFmpeg is installed, then run:
```bash Terminal
# macOS
brew install ffmpeg
# Ubuntu / Debian
sudo apt install ffmpeg
```
Confirm with `npx hyperframes doctor` — both should be green.
</Step>
<Step title="Remove the background from your video">
```bash Terminal
npx hyperframes remove-background subject.mp4 -o transparent.webm
```
On the first run, the CLI downloads ~168 MB of model weights to `~/.cache/hyperframes/background-removal/models/`. Subsequent runs reuse the cache.
Output:
```
◇ Removed background from 240 frames in 38.4s (6.3 fps, CoreML) → ./transparent.webm
```
</Step>
<Step title="Drop it into a composition">
The output is a standard VP9-with-alpha WebM. Chrome's `<video>` element decodes the alpha plane natively — no special player needed:
```html composition.html
<div class="scene">
<!-- background layer -->
<img src="city.jpg" class="bg" />
<!-- transparent subject floats on top -->
<video src="transparent.webm" autoplay muted loop playsinline></video>
</div>
```
Render the composition with the usual `hyperframes render`.
</Step>
</Steps>
## How it works
The pipeline runs four stages, all locally:
```
ffmpeg decode → u²-net_human_seg inference → alpha composite → ffmpeg encode
(raw RGB) (320×320 mask, then upsampled) (VP9-alpha)
```bash
npx hyperframes remove-background subject.mp4 -o subject.webm
```
The model is **u²-net_human_seg** (MIT license, ~168 MB ONNX). It runs through `onnxruntime-node` with the best-available execution provider on your machine: CoreML on Apple Silicon, CUDA on NVIDIA, CPU otherwise.
The first run downloads the model. Later runs reuse it.
The output is encoded with the exact ffmpeg flags Chrome's `<video>` element needs to decode alpha — `-pix_fmt yuva420p` plus the `alpha_mode=1` metadata tag. Get those wrong and the alpha plane is silently discarded by browsers.
Choose the output by destination:
## Output formats
| Output | Use it for |
| ------------------- | ---------------------------------------------------------------- |
| Transparent `.webm` | A subject layered inside a web or HyperFrames composition |
| Transparent `.mov` | A ProRes 4444 round trip through Premiere, Resolve, or Final Cut |
| Transparent `.png` | A single portrait image |
| Extension | Codec | When to use | Size (4s @ 1080p) |
|-----------|-------|-------------|-------------------|
| `.webm` (default) | VP9 with alpha | Drop into `<video>` for HTML5-native transparent playback | ~1 MB |
| `.mov` | ProRes 4444 with alpha | Editing round-trip in Premiere / Resolve / Final Cut | ~50 MB |
| `.png` | PNG with alpha | Single-image cutout (only when the input is also a single image) | varies |
```bash Terminal
npx hyperframes remove-background subject.mp4 -o transparent.webm # web playback
npx hyperframes remove-background subject.mp4 -o transparent.mov # editing
npx hyperframes remove-background portrait.jpg -o cutout.png # still image
```bash
npx hyperframes remove-background subject.mp4 -o subject.mov
npx hyperframes remove-background portrait.jpg -o portrait.png
```
## Layer separation: emit the cutout and the background plate together
## Use the cutout
Pass `--background-output` (alias `-b`) to write a *second* transparent video alongside the cutout. Same source RGB, alpha is the *inverse* mask — opaque where the surroundings were, transparent where the subject is. The result is a clean two-layer separation in a single inference pass:
Import the transparent file into the project and place it above the
background, text, or graphic it should cover. Then check the complete clip,
especially hair, hands, fast movement, and the first and last frames.
```bash Terminal
If you animate the subject, animate a wrapper around the video. This keeps the
transparent media and the composition’s timing behavior together.
## Compositing patterns and pitfalls
Keep the media element stable and animate a wrapper when the cutout must move,
resize, or reveal. This avoids mixing media playback with the transform that
controls the composition.
When a cutout and its original background must remain frame-aligned, give both
media elements the same `data-start` and playback offset. Hide or reveal them
through wrappers instead of mounting one source later. Then scrub the cut point
and check the rendered frame, not only normal playback.
## Put something behind the subject
For text-behind-subject or another three-layer effect, you can create both the
foreground cutout and an inverse-alpha background plate in one pass:
```bash
npx hyperframes remove-background subject.mp4 \
-o subject.webm \
--background-output plate.webm
```
| Output | Alpha | Use it as |
| ------ | ----- | --------- |
| `subject.webm` | Mask — subject opaque | Foreground layer (top of stack) |
| `plate.webm` | `255 − mask` — subject region transparent | Background layer; place anything you want **under the subject's silhouette** between this and `subject.webm` |
The plate keeps the original surroundings and leaves a transparent
person-shaped hole. It is not an inpainted empty background. Place an opaque
graphic or scene beneath the hole, then place `subject.webm` above it.
Both encoders share the source W/H/fps and your `--quality` preset, so the layers are pixel-aligned. Encode cost roughly doubles; segmentation cost is unchanged.
## Know when it will work well
<Tip>
**This is a hole-cut plate, not an inpainted clean plate.** The subject region in `plate.webm` is fully transparent — you have to composite something opaque under it (a graphic, a blurred copy, a different scene) to fill the hole. If you need an actual filled background where the subject was, use a video inpainter (LaMa, ProPainter, RunwayML Inpaint) — `remove-background` is not the right tool for that.
</Tip>
The included model is designed for people. It works best with a clear human
subject, stable framing, and reasonable contrast from the background.
### Hole-cut vs. clean plate — when does the difference matter?
Use another segmentation or masking tool when:
A **hole-cut plate** keeps the original surroundings and makes the subject region transparent. A **clean plate** fills the subject region with reconstructed background — produced by a separate inpainting model. Display each alone over black:
- the subject is a product, animal, or other object;
- fine hair crosses a busy background;
- frame-to-frame edge stability must meet high-end VFX standards;
- you need the original background reconstructed after removing the person.
| | Hole-cut plate (this command) | Clean plate (inpainted) |
| --- | --- | --- |
| Subject region | Transparent silhouette | Reconstructed background pixels |
| What you see alone | A person-shaped hole | An empty room |
| Cost | One inference pass, one extra ffmpeg encode | A second model (LaMa, ProPainter, E2FGVI) |
| Tool | `remove-background --background-output` | Outside this CLI |
Background removal is preprocessing. Run it once, keep the transparent result
in the project, and reuse it.
The line is: **does anything ever need to be visible *through* the subject's silhouette where the subject used to be?**
## Balance quality and speed
| Use case | What you need |
| --- | --- |
| Text/graphics live *between* the cutout and the plate (the example above) | **Hole-cut** — the graphics fill the hole. |
| Composite the subject onto an unrelated scene | Neither. Just use `subject.webm`; the plate is irrelevant. |
| Show "the room without the person" as a real background | **Clean plate** — a hole-cut plate would show a transparent void. |
| Replace the person with a different subject (re-target) | **Clean plate** — the new subject needs real pixels under it. |
| VFX rotoscoping / "remove an extra from this take" | **Clean plate** — the canonical inpainting use case. |
`--device auto` chooses the best available local provider. Inspect the detected
provider with:
If something opaque always covers the silhouette, hole-cut is sufficient and ~1000× cheaper than running an inpainter.
### The two-layer composition pattern
The two-layer pattern is functionally a drop-in for [text-behind-subject](#text-behind-subject-the-recommended-layout) without needing the original `presenter.mp4` in the project — the plate replaces it as the bottom layer:
```html
<!-- z=1 inverse-alpha plate fills everything except the subject's silhouette -->
<video src="plate.webm" data-start="0" data-duration="6" data-track-index="0" muted playsinline></video>
<!-- z=2 anything you want occluded by the subject lives here -->
<h1 style="z-index:2; position:absolute; top:50%; left:50%; transform:translate(-50%,-50%);">
MAKE IT IN HYPERFRAMES
</h1>
<!-- z=3 the cutout puts the subject back on top -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
<video src="subject.webm" data-start="0" data-duration="6" data-track-index="1" muted playsinline></video>
</div>
```bash
npx hyperframes remove-background --info
```
Constraints: the flag requires a video input and `.webm` or `.mov` for both outputs. It's not valid for image inputs (no temporal pairing to do) and won't accept `.png` for the plate.
For WebM output, `--quality balanced` is the default. Use `best` when the
cutout sits directly over its original source and edge color must match; use
`fast` for a smaller file over an unrelated background.
## Performance
## Common problems
Real-world numbers from the [matting eval](https://www.heygenverse.com/a/0dd5a431-1832-4858-862d-de7fb7d02654), running u²-net_human_seg on a 4-second 1080p clip:
| Problem | What to check |
| --------------------------------- | ----------------------------------------------------------------------------------------------- |
| The background is still opaque | Confirm the output is transparent WebM, MOV, or PNG and preview it over a colored background. |
| Edges flicker | Use a cleaner source, reduce fast movement, or use a stronger external matting tool. |
| Processing is slow | Check `--info`; CPU processing works but is much slower than an available accelerated provider. |
| The subject has a color halo | Use `--quality best`, especially when layering over the original source. |
| The “background plate” has a hole | Expected: it is inverse alpha, not an inpainted clean plate. |
| Platform | Provider | ms/frame | 30-second clip |
|----------|----------|----------|----------------|
| Apple Silicon (M2 Pro / M3 / M4) | CoreML | ~263 | ~2 min |
| NVIDIA GPU (T4, A10, RTX) | CUDA | ~80–150 | ~30–60 s |
| Linux x86 | CPU | ~1100 | ~16 min |
| macOS Intel | CPU | ~900 | ~13 min |
The [CLI reference](/packages/cli#remove-background) lists every flag and
supported input.
Matting is offline preprocessing — you run it once per asset and reuse the output. CPU-only is slow but always works; if you reuse the same subject clip repeatedly, run it once on a faster machine and check the transparent output into your project.
## Related topics
## Picking a device explicitly
`--device auto` is the default and right for almost everyone. The flag exists for two cases:
- **Force CPU on a GPU box** when you want to keep the GPU free for other work, or are debugging an EP-specific issue:
```bash Terminal
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
```
- **Opt into CUDA** by setting `HYPERFRAMES_CUDA=1` and providing a GPU-enabled `onnxruntime-node` build (the bundled build is CPU + CoreML only, to keep the install small for the 99% of users who don't have a GPU):
```bash Terminal
HYPERFRAMES_CUDA=1 npx hyperframes remove-background subject.mp4 -o transparent.webm --device cuda
```
Run `npx hyperframes remove-background --info` to see what providers are detected on your machine and which one `auto` would pick.
## Using the transparent video in a composition
The transparent WebM behaves like any other video element. The two patterns you'll use most:
**Subject over a background image:**
```html
<div style="position: relative; width: 1920px; height: 1080px;">
<img src="background.jpg" style="position: absolute; inset: 0;" />
<video
src="transparent.webm"
autoplay
muted
loop
playsinline
style="position: absolute; right: 80px; bottom: 0; height: 90%;"
></video>
</div>
```
**Subject over a HyperFrames scene:**
```html
<!-- scene contents (text, animations, etc.) -->
<div class="title-card">Welcome</div>
<!-- subject layered on top -->
<video src="transparent.webm" autoplay muted loop playsinline class="subject"></video>
```
The cutout inherits the composition's frame rate and timeline — it plays through once during the scene's duration, so match the source clip length to the scene length when possible. If the scene is longer than the clip, `loop` handles it.
<Tip>
When rendering a composition that contains a `<video>` element, the renderer reads the source via ffmpeg internally. Transparent WebMs are decoded with the alpha plane preserved.
</Tip>
## Compositing patterns and pitfalls
The cutout webm is a **re-encoded copy** of the source mp4's RGB — the matter pipeline decodes the source to raw RGB, runs segmentation, and re-encodes to VP9 with alpha. That choice has consequences depending on what you put behind it.
### The three patterns
| Pattern | Behind the cutout | Result |
|---|---|---|
| **Cutout over a different scene** *(most common)* | Static image, gradient, animated bg, or unrelated footage | Clean. The cutout is the only source of the subject — no doubling, no edge halo. Use any `--quality`. |
| **Cutout over its own source mp4** *(text-behind-subject, talking-head with overlays)* | The same mp4 the cutout was generated from | Two RGB sources for the same person. At default `--quality balanced` (crf 18) the doubling is barely visible; at `--quality fast` (crf 30) you'll see a slight color shift / soft edge on the silhouette. Use `--quality best` (crf 12) for hero shots. |
| **Cutout over different footage of the same subject** | Another take of the same person | Looks like two overlapping people. Avoid — re-shoot or re-cut the source. |
### Text-behind-subject: the recommended layout
Putting a headline *behind* a presenter so their silhouette occludes the text:
```html
<!-- z=1 base mp4: full lobby + presenter, plays the whole scene -->
<video
id="cf-base"
data-start="0" data-duration="6" data-media-start="0" data-track-index="0"
src="presenter.mp4"
muted playsinline
></video>
<!-- z=2 headline -->
<h1 id="cf-headline" style="position:absolute;top:50%;left:50%;
transform:translate(-50%,-50%); z-index:2;
color:#fff; text-shadow:0 6px 32px rgba(0,0,0,.55);
clip-path:inset(0 0 100% 0); font-size:220px; font-weight:900;">
MAKE IT IN HYPERFRAMES
</h1>
<!-- z=3 cutout: same source, alpha around presenter, hidden until the cut.
The wrapper carries the opacity, NOT the <video> itself. -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
<video
id="cf-cutout"
data-start="0" data-duration="6" data-media-start="0" data-track-index="1"
src="presenter.webm"
muted playsinline
></video>
</div>
```
```js
const tl = gsap.timeline({ paused: true });
const CUT = 3.3;
// Reveal the headline early
tl.to("#cf-headline", { clipPath: "inset(0 0 0% 0)", duration: 0.6, ease: "expo.out" }, 0.25);
// At the cut, flip the cutout wrapper visible — silhouette punches through the headline
tl.set(".cutout-wrap", { opacity: 1 }, CUT);
// Sentinel: extend timeline to the composition's full duration so the renderer
// doesn't bail past the last meaningful tween.
tl.set({}, {}, 6);
```
### Two non-obvious rules
**1. Wrap the cutout video in a non-timed `<div>` and animate the wrapper, not the video.**
The framework forces `opacity: 1` on any element with `data-start`/`data-duration` while it's "active" — that's how it controls clip visibility. CSS `opacity: 0` on the video element is silently overwritten by the framework's clip lifecycle, so an opacity tween on the video element won't do anything. Wrap the video in a `<div>` that has no `data-*` attributes; the wrapper is owned entirely by your CSS/GSAP.
**2. Both videos start at `data-start="0"` and decode in sync from t=0.**
It's tempting to "late-mount" the cutout (`data-start="3.3"` to match the cut). Don't — Chrome does a seek + decoder warm-up at mount, which can land one frame off the base mp4 at the cut moment. With both videos mounted from t=0 and the cutout's wrapper opacity-animated, both decoders advance the same way and stay frame-accurate.
### Quality preset and color match
When the cutout is overlaid on its own source mp4, the encoder's CRF directly affects how visible the doubling is at edges:
| `--quality` | CRF | File size (12s @ 1080p) | When to use |
|---|---|---|---|
| `fast` | 30 | ~2 MB | Cutout sits over an unrelated background and file size matters |
| `balanced` *(default)* | 18 | ~6 MB | Recommended for text-behind-subject and any pattern that overlays on the source |
| `best` | 12 | ~12 MB | Hero shots, masters, or anything you'll re-encode downstream |
The encoder also writes BT.709 + limited-range color metadata so Chrome's YUV→RGB pipeline matches the source mp4's. Without those tags, the cutout would render slightly differently from the underlying mp4 even at lossless quality (visible red/skin shift).
## What u²-net_human_seg is and isn't good for
The model is purpose-built for **portrait / human matting**. It excels when:
- ✅ The subject is a person, head-and-shoulders or full-body
- ✅ The framing is reasonably stable (not a wide handheld shot)
- ✅ The background contrasts with the subject
It struggles or fails on:
- ❌ Non-human subjects (products, animals, objects). The model will return a mostly-empty mask.
- ❌ Very fine hair detail on a busy background. The 320×320 inference resolution means hair tips get softened — fine for most use cases, but compositors notice.
- ❌ Frame-to-frame temporal consistency. Each frame is processed independently, so static backgrounds with moving subjects can show subtle edge flicker. For most web playback this is invisible; for high-end VFX it may matter.
- ❌ Live streams or real-time capture. The pipeline is batch-only.
If your use case hits one of these, see the alternatives below.
## Alternatives — when the built-in command isn't the right tool
The CLI ships **one model on purpose** — the one that's MIT-licensed, runs everywhere, and produces production-quality output for person/portrait video. The list below leads with **free, open-source tools** that pair naturally with HyperFrames. Each entry calls out the actual catch — license, install effort, hardware needs — so you can pick the right one for your situation. Full benchmarks are in the [matting eval](https://www.heygenverse.com/a/0dd5a431-1832-4858-862d-de7fb7d02654).
### Free, open-source CLIs and libraries
These all run locally with no account, no upload, no watermark.
| Tool | When to use it | Catch |
|------|----------------|-------|
| [`rembg`](https://github.com/danielgatis/rembg) (Python, MIT) | You need a different subject type — `isnet-general-use` for objects/animals/products, `birefnet-portrait` for a quality ceiling on hair, `silueta` for a tiny ~40 MB footprint. Same family as our default model, more variety. | Requires Python + `pip install rembg`. Some bundled models (`birefnet-*`) need ~4 GB RAM and are CPU-only |
| [BiRefNet](https://github.com/ZhengPeng7/BiRefNet) (PyTorch, MIT) | Highest-fidelity portrait mattes available — visibly better hair edges than u²-net | Heavy (~4 GB inference RAM), slow on CPU, broken on Apple CoreML at the time of the eval |
| [Robust Video Matting (RVM)](https://github.com/PeterL1n/RobustVideoMatting) (PyTorch, **GPL-3.0**) | The only widely-available model with **temporal consistency** built in — no edge flicker on moving subjects. Best choice when you're matting a long talking-head clip and frame-to-frame stability matters | GPL-3.0 license is incompatible with most commercial / proprietary codebases. Read your repo's license before using |
| [Backgroundremover](https://github.com/nadermx/backgroundremover) (Python, MIT) | Simple `pip install` wrapper around u²-net; nice if you want a Python API instead of our Node CLI | Same model family as ours, no quality difference — pick whichever fits your stack |
| [ComfyUI](https://github.com/comfyanonymous/ComfyUI) (open-source, GPL-3.0 core) | Custom workflows: chain a segmentation model + alpha refinement + temporal smoothing. The right tool for tricky cases (multiple subjects, hair against a similar background, sports footage) | Setup is involved (Python, models, node graph). Worth it for repeat specialty work |
After running any of these externally, encode the output as a HyperFrames-compatible transparent WebM with:
```bash Terminal
ffmpeg -i frames-%04d.png -c:v libvpx-vp9 \
-pix_fmt yuva420p \
-metadata:s:v:0 alpha_mode=1 \
-auto-alt-ref 0 -cpu-used 4 -b:v 0 -crf 30 \
transparent.webm
```
### Free desktop / GUI tools
| Tool | When to use it | Catch |
|------|----------------|-------|
| [DaVinci Resolve — Magic Mask](https://www.blackmagicdesign.com/products/davinciresolve) | You're already editing in Resolve, want a brush-based UI with manual refinement, and need to round-trip the alpha into a larger edit | macOS / Windows / Linux desktop install. The free tier covers Magic Mask; paid Studio version unlocks higher resolutions on some features |
| [Backgroundremover.app](https://backgroundremover.app) (web) | One-off image cutout, no signup, no watermark | Single images only, not video. Free tier is hosted but the underlying tool is the same `rembg` model family |
| [PhotoRoom Background Remover](https://www.photoroom.com/tools/background-remover) (web) | Quick one-off image, polished UI, no signup | Single images only, e-commerce-tuned model |
### Web SaaS tools (free tiers, with strings)
| Tool | When to use it | Catch |
|------|----------------|-------|
| [unscreen.com](https://www.unscreen.com) | Quick one-off video, no install, drag-and-drop | **Free tier is watermarked and capped at short clips** (~10s preview). Paid removes both. Run by the team behind remove.bg |
| [RunwayML — Green Screen](https://runwayml.com) | Polished UI with brush refinement and time-aware tracking; the closest a SaaS gets to professional roto | Free tier exists but is credit-limited; serious use is a subscription |
| [Kapwing — Background Remover](https://www.kapwing.com/tools/remove-video-background) | Browser-based, integrates with their video editor | Free tier is watermarked; paid removes it |
### How to choose
- **Person / portrait video, web playback, MIT-clean** → use the built-in `hyperframes remove-background` (this is what it's tuned for).
- **Non-human subject** (product, animal, object) → `rembg` with `isnet-general-use`.
- **Maximum portrait quality, especially hair** → `BiRefNet` via Python.
- **Long video where edge flicker would be visible**, GPL is OK → `RVM`.
- **One-off marketing clip, no install** → DaVinci Resolve (free) for video, Backgroundremover.app for a still image.
- **Specialty case the off-the-shelf models can't handle** → ComfyUI with a custom graph.
## Troubleshooting
### Model download fails or hangs
The weights live on GitHub Releases (rembg's `v0.0.0` release, ~168 MB). If your network blocks GitHub or the download is interrupted:
```bash Terminal
# Manually download and drop into the cache
mkdir -p ~/.cache/hyperframes/background-removal/models
curl -L -o ~/.cache/hyperframes/background-removal/models/u2net_human_seg.onnx \
https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net_human_seg.onnx
```
Subsequent `remove-background` runs skip the download and use your local copy.
### "ffmpeg and ffprobe are required"
The pipeline shells out to ffmpeg for decode + encode. Install via `brew install ffmpeg` on macOS or `sudo apt install ffmpeg` on Debian/Ubuntu. Verify with `npx hyperframes doctor`.
### The output WebM looks fully opaque in the browser
Chrome only reads the alpha plane when the WebM is encoded as `yuva420p` with the `alpha_mode=1` metadata tag. The CLI sets both. If you re-encode the output yourself (e.g. with another ffmpeg invocation), preserve those flags:
```bash Terminal
ffmpeg -i in.webm -c:v libvpx-vp9 \
-pix_fmt yuva420p \
-metadata:s:v:0 alpha_mode=1 \
-auto-alt-ref 0 -cpu-used 4 \
out.webm
```
To verify a WebM has alpha, extract the first frame and inspect:
```bash Terminal
ffmpeg -y -c:v libvpx-vp9 -i out.webm -frames:v 1 -pix_fmt rgba -update 1 frame0.png
```
The decoded `frame0.png` should be RGBA and have non-trivial alpha values.
### CoreML is "available" but inference fails to start
The pipeline auto-falls-back to CPU if CoreML fails to bind, with a warning. If you want to skip the CoreML attempt entirely, force CPU:
```bash Terminal
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
```
### The alpha mask has rough or jagged edges
That usually means the source frame is high-contrast against a similar-toned background and the model's 320×320 inference resolution is showing through. Two paths forward:
1. Re-frame or re-shoot to give the subject a more contrasting background.
2. Try `birefnet-portrait` via `rembg` (see [Other open-source models](#other-open-source-models)) — it's higher quality at hair edges but slower and heavier.
## Reference
- CLI: [`hyperframes remove-background`](/packages/cli#remove-background)
- Eval: [Matting eval — v7](https://www.heygenverse.com/a/0dd5a431-1832-4858-862d-de7fb7d02654)
- Source model: [danielgatis/rembg](https://github.com/danielgatis/rembg)
- ONNX runtime: [`onnxruntime-node`](https://www.npmjs.com/package/onnxruntime-node)
- [Use images and video](/guides/video-components)
- [Add an avatar presenter](/guides/avatar-presenter)
- [Apply media effects without changing the source file](/guides/media-effects)
+105 -390
View File
@@ -1,444 +1,159 @@
---
title: Rendering
description: "Render compositions to MP4, MOV, WebM, GIF, or PNG sequences locally or in Docker."
title: "Render from the command line"
description: "Check a project and render MP4, MOV, WebM, GIF, or PNG output."
---
Render your Hyperframes [compositions](/concepts/compositions) to MP4, MOV, WebM, GIF, or PNG sequences with the [CLI](/packages/cli). The rendering pipeline is frame-by-frame and seek-driven — see [Deterministic Rendering](/concepts/determinism) for how this works under the hood.
Studio is the simplest place to export a project. Use the command line when an agent, script, CI job, or advanced delivery workflow needs to control the render.
## Getting Started
## Render a normal video
<Steps>
<Step title="Verify your environment">
Run the diagnostics command to check for required dependencies:
```bash Terminal
npx hyperframes doctor
```
Expected output:
```
✓ Node.js v22.x
✓ FFmpeg 7.x
✓ FFprobe 7.x
✓ Chrome (bundled)
✓ Docker available
```
</Step>
<Step title="Preview your composition">
Before rendering, preview your composition in the browser to verify it looks correct:
```bash Terminal
npx hyperframes preview
```
</Step>
<Step title="Render to MP4">
Run the render command from your project directory:
```bash Terminal
npx hyperframes render --output output.mp4
```
Expected output:
```
⠋ Rendering composition "root" (30fps, standard quality)
✓ Captured 240 frames in 8.2s
✓ Encoded to output.mp4 (8.0s, 1920x1080, 4.2MB)
```
</Step>
</Steps>
## Rendering Modes
<Tabs>
<Tab title="Local Mode">
### Local Mode (default)
Uses Puppeteer (bundled Chromium) and your system's FFmpeg. Fast for iteration during development.
**Requires:** FFmpeg installed on your system. See [Troubleshooting](/guides/troubleshooting) if FFmpeg is not found.
```bash Terminal
npx hyperframes render --output output.mp4
```
**Pros:**
- Fast startup, no container overhead
- Can use your system GPU for Chrome/WebGL capture by default
- Can use your system GPU for hardware-accelerated encoding (with `--gpu`)
- Best for iterative development
**Cons:**
- Output may vary across platforms due to font and Chrome version differences
- Not suitable for CI/CD pipelines that require reproducibility
</Tab>
<Tab title="Docker Mode">
### Docker Mode
[Deterministic](/concepts/determinism) output with an exact Chrome version and font set. Use this for production renders and CI pipelines.
**Requires:** Docker installed and running.
```bash Terminal
npx hyperframes render --docker --output output.mp4
```
**Pros:**
- Identical output on every platform — same Chrome, same fonts, same FFmpeg
- The same pipeline used in production
- Ideal for CI/CD and automated workflows
**Cons:**
- Slower startup due to container initialization
- Browser capture stays on the deterministic software-GL path
- GPU encoding requires Docker host GPU passthrough and is not cross-platform on Docker Desktop
<Note>
Docker mode uses `chrome-headless-shell` with [BeginFrame](/concepts/determinism#how-it-works) control for frame-perfect, deterministic capture.
</Note>
</Tab>
</Tabs>
## When to Use Each Mode
| Scenario | Recommended Mode |
|----------|-----------------|
| Local development and iteration | Local |
| CI/CD pipeline | Docker |
| Sharing renders with a team | Docker |
| Quick preview export | Local |
| AI agent-driven rendering | Docker |
| Benchmarking performance | Local |
## Options
| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--output` | path | `renders/<name>.mp4` | Output file path |
| `--format` | mp4, mov, webm, gif, png-sequence | mp4 | Output format (see [Transparent Video](#transparent-video) below) |
| `--fps` | 1-240 or rational (e.g. `30000/1001`) | 30 | Frames per second |
| `--gif-loop` | 0-65535 | 0 | GIF loop count. `0` loops forever |
| `--quality` | draft, standard, high | standard | Encoding quality preset |
| `--crf` | 0–51 | — | Override CRF (lower = higher quality). Cannot combine with `--video-bitrate` |
| `--video-bitrate` | e.g. `10M`, `5000k` | — | Target bitrate encoding. Cannot combine with `--crf` |
| `--video-frame-format` | auto, jpg, png | auto | Source video frame extraction format. Use `png` for UI recordings, screen captures, and color-sensitive source videos |
| `--workers` | 1-24 or `auto` | auto | Parallel render workers (see [Workers](#workers) below) |
| `--max-concurrent-renders` | 1-10 | 2 | Max simultaneous renders via the producer server (see [Concurrent Renders](#concurrent-renders) below) |
| `--batch` | path | — | JSON array of variable rows (or `{ "rows": [...] }`), rendering one output per row |
| `--batch-concurrency` | integer | 1 | Maximum batch rows to render at once |
| `--batch-fail-fast` | — | off | Stop launching new batch rows after the first row failure |
| `--gpu` | — | off | GPU encoding (NVENC, VideoToolbox, AMF, VAAPI, QSV) |
| `--browser-gpu` / `--no-browser-gpu` | — | on locally, off in Docker | Use or opt out of host GPU acceleration for local Chrome/WebGL capture |
| `--hdr` | — | off | Force HDR output even if no HDR sources are detected (MP4 only). See [HDR Rendering](/guides/hdr) |
| `--sdr` | — | off | Force SDR output even if HDR sources are detected |
| `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) |
| `--quiet` | — | off | Suppress verbose output |
## Quality and Encoding
The `--quality` flag selects a preset that controls the H.264 CRF (Constant Rate Factor) and encoder speed:
| Preset | CRF | x264 Preset | Best For |
|--------|-----|-------------|----------|
| `draft` | 28 | ultrafast | Quick previews, iteration |
| `standard` | 18 | medium | General use — visually lossless at 1080p |
| `high` | 15 | slow | Final delivery, near-lossless quality |
For finer control, use `--crf` or `--video-bitrate` to override the preset:
From the project folder:
```bash
# Near-lossless quality (CRF 15 = very high quality, large file)
npx hyperframes render --crf 15 --output pristine.mp4
# Target a specific bitrate (useful for size-constrained delivery)
npx hyperframes render --video-bitrate 10M --output controlled.mp4
npx hyperframes render --output final.mp4
```
**Tip**: The default `standard` preset (CRF 18) is visually lossless at 1080p — most people cannot distinguish it from the source. Use `--quality draft` for faster iteration, or `--quality high` / `--crf 10` when file size is no concern.
If you omit `--output`, HyperFrames writes the result under `renders/`.
## Input Video Codecs
The normal workflow is:
Video assets referenced by a composition (a `<video src="...">` clip) are decoded by FFmpeg, not by the browser: the pipeline pre-extracts every input video into frame images and injects them during capture, so the render never depends on what the capture browser can play. Any codec your FFmpeg build decodes works as an input, including:
- H.264 / AVC
- **HEVC / H.265, 8-bit and 10-bit** (`hvc1` and `hev1`): common for storage-optimized asset libraries; renders identically on macOS and Linux, no hardware decoder required
- VP8 / VP9 and ProRes 4444 (with alpha; see [Transparent Video](#transparent-video))
- HDR sources (HLG / PQ) are tone-mapped for SDR renders; see the [HDR guide](/guides/hdr)
The one caveat is **live preview**: `preview`, `play`, Studio, and published player pages play the file in a real browser, so playback there depends on that browser's codec support. Chrome (107+), Edge, and Safari hardware-decode HEVC on most modern machines; Firefox does not. Preview handles this automatically: on first use, it transcodes the asset into a cached H.264 proxy (stored under `.transcode-cache/`, safe to delete) and serves that for playback, while render always uses the original file. `check` and `snapshot` prepare the same proxies before opening their browser phase. Publishing bakes the proxies into the published archive so static player pages work too. Opt out per command with `--no-proxy`, or project-wide by setting `media.autoProxy` to `false` in `hyperframes.json`.
`hyperframes lint` emits an info-level `hevc_preview_codec` note when a composition references an HEVC video, naming the affected asset(s).
## Animated GIF
Use GIF when the output needs to autoplay inline in GitHub PRs, READMEs, issue reports, and docs pages:
```bash Terminal
npx hyperframes render --format gif --fps 15 --gif-loop 0 --output demo.gif
```bash
npx hyperframes lint
npx hyperframes check
npx hyperframes render --output final.mp4
```
GIF output uses a two-pass FFmpeg palette encode (`palettegen` with diff statistics, then `paletteuse` with Sierra dithering) for better gradients and text edges than a single-pass conversion. GIFs are still much larger than MP4/WebM at the same dimensions, so prefer short compositions. GIF renders are capped at 30fps; pass `--fps 15` for smaller files.
`lint` checks the project structure. `check` opens the project in a browser and looks for runtime, layout, motion, media, and contrast problems.
GIF does not carry audio and only has 1-bit transparency. For transparent overlays, use `--format webm`, `--format mov`, or `--format png-sequence` instead.
## Choose a format
For UI recordings, screen captures, or other source videos where saturated interface colors matter, pass `--video-frame-format png` to extract source video layers as PNG before browser capture. The default `auto` mode preserves the historical behavior: alpha-capable sources use PNG, opaque sources use JPG.
| Format | Use it for |
| ------------ | ---------------------------------------------------------- |
| MP4 | Normal sharing, publishing, and delivery |
| MOV | ProRes workflows and transparent editing intermediates |
| WebM | Web delivery and transparent overlays |
| GIF | Short previews in issues, pull requests, and documentation |
| PNG sequence | Frame-by-frame handoff to compositing software |
## GPU Acceleration
Examples:
Hyperframes has two separate GPU acceleration surfaces:
```bash
# Transparent web overlay
npx hyperframes render --format webm --output overlay.webm
- `--gpu` uses a hardware video encoder in FFmpeg when one is available. Supported backends include VideoToolbox on macOS, NVENC on NVIDIA systems, AMD AMF on Windows, VAAPI on Linux, and Intel QSV on supported Windows/Linux hosts.
- Browser GPU uses the host GPU for local Chrome/WebGL capture. It is enabled automatically for local renders and disabled in Docker. Use `--no-browser-gpu` to opt out.
# ProRes editing file
npx hyperframes render --format mov --output master.mov
```bash Terminal
# Add hardware FFmpeg encoding to the default local browser-GPU render
npx hyperframes render --gpu --output encoded-fast.mp4
# Short looping preview
npx hyperframes render --format gif --fps 15 --output preview.gif
# Opt out of hardware Chrome/WebGL capture
npx hyperframes render --no-browser-gpu --output software-browser.mp4
# Use browser GPU plus hardware FFmpeg encoding
npx hyperframes render --gpu --output gpu.mp4
# RGBA frames in a directory
npx hyperframes render --format png-sequence --output frames
```
Browser GPU capture is local-mode only. It maps to platform-native Chrome GPU backends: Metal on macOS, D3D11 on Windows, and EGL on Linux. Use `--no-browser-gpu` or Docker mode when exact cross-machine reproducibility matters more than local render speed.
GIF has no audio and limited transparency. Prefer MP4 or WebM for normal playback.
## Workers
### Transparent video
Each render worker launches a **separate Chrome browser process** to capture frames in parallel. More workers can speed up rendering, but each one consumes ~256 MB of RAM and significant CPU.
Use WebM for a transparent web overlay or MOV for a ProRes 4444 editing
intermediate. Leave the composition background unpainted wherever the output
must remain transparent; an opaque `html`, `body`, or full-frame background
will be encoded as visible pixels.
### Default behavior
By default, Hyperframes uses **CPU cores minus 2** (reserving headroom for FFmpeg encoding and your other applications):
| Machine | CPU cores | Default workers |
|---------|-----------|----------------|
| MacBook Air (M1) | 8 | 6 |
| MacBook Pro (M3) | 12 | 10 |
| 4-core laptop | 4 | 2 |
| 2-core VM | 2 | 1 |
Each worker spawns its own Chrome process (~256 MB RAM), so the per-worker overhead is significant. The maximum is 24 workers (hard ceiling).
### Choosing a worker count
```bash Terminal
# Explicit worker count
npx hyperframes render --workers 1 --output output.mp4
# Let Hyperframes pick based on your CPU
npx hyperframes render --workers auto --output output.mp4
# Maximum parallelism (use with caution on laptops)
npx hyperframes render --workers 24 --output output.mp4
```
<Tip>
Start with the default. If renders feel slow and your system has headroom (check Activity Monitor / `htop`), try increasing `--workers`. If you see high memory pressure or fan noise, reduce it.
</Tip>
### When to use 1 worker
- Short compositions (under 2 seconds / 60 frames) — parallelism overhead exceeds the benefit
- Low-memory machines (4 GB or less)
- Running renders alongside other heavy processes (video editing, large builds)
### When to increase workers
- Long compositions (30+ seconds) on a machine with 8+ cores and 16+ GB RAM
- Dedicated render machines or CI runners
- Docker mode on a well-provisioned host
## Batch Rendering
Batch rendering runs the same composition once per variables row:
```json rows.json
[
{ "name": "Alice", "headline": "Welcome, Alice" },
{ "name": "Bob", "headline": "Welcome, Bob" }
]
```
```bash Terminal
npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
```
`--output` is a template. Use `{index}` or any scalar key from the row to make each path unique. Hyperframes preflights the full batch before rendering: malformed rows, missing placeholders, duplicate output paths, and strict variable mismatches fail before the first video starts. A `manifest.json` file is written next to the outputs with per-row status, output path, render time, duration when available, and error details.
Rows continue after failures by default so a bad data row does not discard the rest of the batch. Add `--batch-fail-fast` to stop launching new rows after the first failure, or `--json` to stream machine-readable progress events while the manifest is updated.
## Concurrent Renders
When multiple render requests hit the producer server simultaneously (common with AI agents), each render spawns its own set of Chrome worker processes. Too many concurrent renders can exhaust CPU and cause failures.
The producer server uses a **request-level semaphore** to queue renders. Only `maxConcurrentRenders` renders execute at a time — additional requests wait in a FIFO queue until a slot opens.
### Configuration
```bash Terminal
# CLI flag
npx hyperframes render --max-concurrent-renders 2 --output output.mp4
# Environment variable (for the producer server)
PRODUCER_MAX_CONCURRENT_RENDERS=2
```
The default is **2** concurrent renders, which works well on 8-core machines where each render uses 2-3 workers.
### Queue status
The producer server exposes a `GET /render/queue` endpoint that returns the current state:
```json
{
"maxConcurrentRenders": 2,
"activeRenders": 1,
"queuedRenders": 3
}
```
AI agents can poll this endpoint to decide whether to submit a render or wait.
### SSE queue events
When using the streaming endpoint (`POST /render/stream`), queued requests receive a `queued` event before rendering begins:
```json
{"type": "queued", "requestId": "...", "position": 2}
```
This lets agents report "waiting in queue" to users rather than appearing stuck.
### Choosing a concurrency limit
| Machine | CPU cores | Recommended limit |
|---------|-----------|------------------|
| 4-core VM | 4 | 1 |
| 8-core workstation | 8 | 2 |
| 16-core server | 16 | 3-4 |
| 32-core render box | 32 | 5-6 |
<Tip>
When in doubt, use 1. Renders will queue up and execute sequentially, but each one gets full CPU and finishes as fast as possible. This is better than 3 renders fighting for CPU and all finishing slowly — or failing.
</Tip>
## Transparent Video
Hyperframes supports rendering with a transparent background — useful for overlays, lower thirds, subscribe cards, and any element you want to composite over other footage in a video editor.
### Recommended format: MOV (ProRes 4444)
```bash Terminal
```bash
npx hyperframes render --format webm --output overlay.webm
npx hyperframes render --format mov --output overlay.mov
```
**MOV with ProRes 4444** is the industry standard for transparent video. It works in all major video editors:
MP4 is the normal opaque delivery format. After rendering transparency, inspect
the file over a contrasting background rather than trusting a player that
always shows black behind alpha.
- CapCut
- Final Cut Pro
- Adobe Premiere Pro
- DaVinci Resolve
- After Effects
## Input video codecs
<Warning>
ProRes MOV files are large (typically 5-40 MB for short clips) because ProRes is a high-quality intermediate codec optimized for editing, not delivery. This is expected — the same tradeoff Remotion and professional pipelines make.
</Warning>
Studio, preview, `check`, and published projects normally create cached browser
proxies for local video that Chrome cannot decode reliably, including common
HEVC and ProRes inputs. The original file stays in the project and remains the
render source.
### Format comparison
If a clip is black only in preview, keep automatic proxying enabled, confirm the
source is local, and run `npx hyperframes check`. Disable proxying only when the
browser already supports the source or you are diagnosing the proxy itself.
| Format | Codec | Transparency | Video editors | Browsers | File size |
|--------|-------|-------------|---------------|----------|-----------|
| **MOV** | ProRes 4444 | Yes | CapCut, Final Cut, Premiere, DaVinci, After Effects | No | Large |
| **WebM** | VP9 | Yes | None (shows black background) | Chrome, Firefox | Small |
| **PNG sequence** | RGBA PNGs (no encoding) | Yes (lossless) | After Effects, Nuke, Fusion (image-sequence import) | No | Largest |
| **MP4** | H.264 | No | All | All | Small |
## Choose quality and frame rate
<Note>
**WebM VP9 alpha** is technically supported but all major video editors ignore the alpha channel and render transparent areas as black. Only Chromium-based browsers (Chrome, Arc, Brave, Edge) decode VP9 alpha correctly. Safari does not support it. Use MOV for editor workflows and WebM only for browser-based playback.
</Note>
The default `standard` quality is the right choice for most finished work.
### PNG sequence (no encoding)
```bash
# Faster review version
npx hyperframes render --quality draft --output review.mp4
```bash Terminal
npx hyperframes render --format png-sequence --output frames/
# Larger final master
npx hyperframes render --quality high --output master.mp4
# Explicit frame rate
npx hyperframes render --fps 60 --output final-60fps.mp4
```
`--format png-sequence` skips the encoder entirely. The captured RGBA frames are copied to `<output>/frame_NNNNNN.png` (zero-padded) and, if the composition has audio, an `audio.aac` sidecar is written alongside. Use this when you want lossless frames — for compositing in After Effects / Nuke / Fusion, or as the input to a custom encode pipeline. `--output` is treated as a directory and is created if it doesn't exist.
Use a higher frame rate only when the source or destination needs it. It creates more frames, so rendering takes longer.
### How it works
The CLI uses the composition’s `data-fps` when present and otherwise defaults to 30 fps.
When you render with `--format mov`, `--format webm`, or `--format png-sequence`, Hyperframes:
## Local or Docker
1. Captures each frame as a **PNG with alpha channel** (instead of JPEG for MP4)
2. Sets Chrome's page background to transparent via `Emulation.setDefaultBackgroundColorOverride`
3. Encodes with an alpha-capable codec (ProRes 4444 for MOV, VP9 for WebM); `png-sequence` skips encoding and writes the captured frames directly
Local rendering is the normal choice:
Your composition's HTML should **not** set a `background` on `html` or `body` — leave it unset so the transparent background comes through.
### Authoring transparent compositions
```html
<style>
/* Do NOT set background on html/body — leave them transparent */
* { margin: 0; padding: 0; box-sizing: border-box; }
[data-composition-id="my-overlay"] {
position: relative;
width: 1920px;
height: 1080px;
overflow: hidden;
/* No background here either */
}
</style>
```bash
npx hyperframes render --output final.mp4
```
Only the visible elements (cards, text, images) will appear in the final video. Everything else will be transparent.
It starts quickly and can use the computer’s browser GPU.
### Verifying transparency
Use Docker when a controlled Chrome, FFmpeg, and font environment matters:
- **In a browser:** Open the MOV file — it won't play (ProRes is not a browser codec). Instead, render a WebM copy and open it in Chrome on a checkerboard background page.
- **In a video editor:** Import the MOV file and place it on a track above other footage. Transparent areas should show the footage below.
- **Online tool:** Use [rotato.app/tools/transparent-video](https://rotato.app/tools/transparent-video) to verify your MOV or WebM has working transparency.
```bash
npx hyperframes render --docker --output final.mp4
```
<Note>
**`ffprobe` reports a transparent WebM as `yuv420p`, not `yuva420p`.** This is expected and does not mean the alpha is missing. VP9 stores its alpha plane in a Matroska `BlockAdditional` sidecar, not in the primary stream's pixel format, so `ffprobe` reports the primary stream as `pix_fmt=yuv420p` even when the file genuinely carries alpha. First check that the WebM declares the alpha sidecar, then force the VP9 library decoder to verify per-pixel alpha:
Docker adds startup and infrastructure overhead. It is useful for CI and repeatable production environments, not a requirement for every final render.
```bash
ffprobe -v error -show_streams out.webm | grep -i alpha_mode # ALPHA_MODE=1 or alpha_mode=1
ffmpeg -c:v libvpx-vp9 -i out.webm -frames:v 1 -f rawvideo -pix_fmt rgba frame.raw
```
## Render another composition
A fully transparent corner pixel in `frame.raw` reads `00 00 00 00`. MOV (ProRes 4444) and `png-sequence` report their alpha directly, so this caveat is WebM-only.
</Note>
The root `index.html` is rendered by default. To target another standalone composition:
## Tips
```bash
npx hyperframes render \
--composition compositions/intro.html \
--output intro.mp4
```
Nested compositions that use `<template>` wrappers should be rendered through the root composition that includes them.
## Batch and cloud work
For several variable-driven versions, use batch rendering. For remote infrastructure, use HyperFrames cloud, AWS Lambda, or Google Cloud Run.
Those workflows involve output naming, credentials, concurrency, and infrastructure choices. Start in the [CLI guide](/developers/cli) and use the complete [CLI reference](/packages/cli) when you need every flag.
## If rendering fails
Run:
```bash
npx hyperframes doctor
npx hyperframes lint
npx hyperframes check
```
Keep the first exact error rather than only the final “render failed” message. See [Troubleshooting](/guides/troubleshooting) for the next checks.
<Tip>
Use `draft` quality during development for fast previews. Switch to `standard` or `high` for final output.
Always watch the exported file itself. Preview proves that the project can play; the output file
proves that the delivery is correct.
</Tip>
- Use `npx hyperframes benchmark` to find optimal settings for your system
- Docker mode is slower but guarantees [identical output](/concepts/determinism) across platforms
- For compositions with many frames, `--gpu` can significantly speed up local encoding
## Related topics
## Next Steps
<CardGroup cols={2}>
<Card title="Deterministic Rendering" icon="lock" href="/concepts/determinism">
Understand the determinism guarantees
</Card>
<Card title="HDR Rendering" icon="sun" href="/guides/hdr">
Render HDR10 MP4 from HDR video and image sources
</Card>
<Card title="Cloud Rendering" icon="cloud" href="/deploy/cloud">
Render on HeyGen's hosted cloud — no local Chrome or FFmpeg
</Card>
<Card title="CLI Reference" icon="terminal" href="/packages/cli">
Full list of CLI commands and flags
</Card>
<Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
Fix common rendering issues
</Card>
</CardGroup>
- [Compare local, hosted, and self-managed rendering](/deploy/overview)
- [Render and export from Studio](/studio/export)
- [Diagnose a failed render](/guides/troubleshooting)
+107 -109
View File
@@ -1,131 +1,129 @@
---
title: Skills catalog
description: "Every HyperFrames skill agents load on demand — what each one is for, and how to install them."
title: "Install and update agent skills"
sidebarTitle: "Agent skills"
description: "Teach a coding agent how to create valid HyperFrames projects and load specialized workflows when needed."
---
HyperFrames ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). They teach your agent the framework-specific patterns — `data-*` attributes, GSAP timeline registration, adapter registries, runtime-owned media playback — that generic web docs don't cover. **Install them before writing compositions** and your agent produces valid HyperFrames HTML on the first try.
HyperFrames skills teach coding agents the project format, animation rules, media workflow, validation loop, and creation workflows that generic web knowledge does not cover.
The skills split into three groups:
## Install for a person
- **Router** — the entry skill that confirms the brief up front (the intent layer) and picks a workflow for any "make me a…" request — usually a video, but also a navigable deck (`/slideshow`) or a composition port (`/remotion-to-hyperframes`).
- **Creation workflows** — one per input shape (URL, PR, music track, captions, etc.). Each owns its task end-to-end: project setup, gated steps, and the final deliverable. Read by the router; you can also invoke directly if you already know which one fits.
- **Domain skills** — atomic capabilities (animation, media, CLI, registry) the workflows compose against; they never own the end-to-end task. Load one when you need that specific layer.
## Install
<Steps>
<Step title="Install the core set (default)">
```bash
npx hyperframes skills update
```
Installs exactly the core set — the `/hyperframes` router, the `hyperframes-*` domain skills, and `media-use` — and the router installs each creation workflow on demand the first time it routes there. Always installs from the repo's current `main`. Works with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.sh), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), [GitHub Copilot CLI](/guides/copilot-cli), and [Google Antigravity](/guides/antigravity).
</Step>
<Step title="Or pick what to install (interactive picker)">
```bash
npx skills add heygen-com/hyperframes --full-depth
```
In a terminal this opens a picker — the core set under the "Core Skills" group, the on-demand creation workflows under "Other", nothing pre-selected. Keep `--full-depth`: it installs the current `main`; without it `skills add` fetches the skills.sh registry blob, which lags `main` by hours. The picker is interactive-only: a non-interactive or agent run without `--skill` installs all 19, so agents should use `npx hyperframes skills update` above.
</Step>
<Step title="Or install everything at once (skip the picker)">
```bash
npx skills add heygen-com/hyperframes --all --full-depth
```
Writes every skill to your project in one shot. Use this only when you explicitly want the full set up front — the router installs workflows on demand otherwise.
</Step>
<Step title="Or install one skill at a time">
```bash
npx skills add heygen-com/hyperframes --skill <name> --full-depth
```
Pass the bare skill name (no leading `/`) — e.g. `--skill hyperframes-animation`. Useful when you want a single capability without the full set.
</Step>
<Step title="Read /hyperframes first">
Once installed, invoke `/hyperframes` in your agent. It's the capability map for everything below and routes "make me a…" intent — a video, a deck, or a composition port — to the right creation workflow based on your input.
</Step>
</Steps>
<Tip>
**Don't see a slash command after install?** Open a new agent session, or run `/skills` (Copilot CLI) / restart your agent's skill loader. Most agents pick up new skills on the next prompt.
</Tip>
## Keeping skills current
After the first install, skills stay lean and current on their own — nothing re-pulls the full set behind your back:
- **Core set** — the `/hyperframes` router, the `hyperframes-*` domain skills, and `/media-use`. `npx hyperframes init` (which every creation workflow runs when scaffolding) refreshes the core set plus anything else you already have installed. It never _expands_ the install — workflow skills you haven't used are not pulled — and re-running `init` on an up-to-date machine is a no-op. Offline (or rate-limited) it degrades gracefully and never hard-fails.
- **Workflow skills** (and `/figma`) — install **on demand**, when their workflow is first triggered. The `/hyperframes` router runs `npx hyperframes skills update <workflow>` before entering a workflow, so the one it routes to is guaranteed present.
Check or refresh manually anytime:
Run the interactive installer:
```bash
npx hyperframes skills check # non-zero exit if installed skills are stale or the core set is incomplete
npx hyperframes skills update # refresh the core set + everything installed (never expands)
npx hyperframes skills update <name> # also install a specific workflow / domain skill on demand
npx hyperframes skills # install the full set explicitly
npx skills add heygen-com/hyperframes --full-depth
```
`skills check` reports workflow skills you haven't installed as _available on demand_, not as a failure.
Select **Core Skills**. The `/hyperframes` router installs a specialized creation workflow when the request needs one, so you do not need the full catalog up front.
## Router
Start a fresh agent chat after installation, then ask it to use `/hyperframes`.
The single entry point. Read `/hyperframes` before invoking anything else — it knows what's available and which workflow fits your request.
## Install or refresh from an agent
| Skill | Use when |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/hyperframes` | **Read first** for any request to make / create / edit / animate / render a video, animation, or motion graphic. Capability map for the domain skills, the intent layer that confirms every creation brief up front, and intent router for the creation workflows below. |
For a non-interactive agent or CI environment, use:
## Creation workflows
```bash
npx hyperframes skills update
```
One workflow per input shape. The router (`/hyperframes`) picks one of these for you — but you can invoke them directly when you already know which fits.
This installs or refreshes the core set and any HyperFrames skills already present in the global install, then links those bundles into compatible installed agents. It does not add every optional workflow.
| Skill | Use when |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/product-launch-video` | Any **website** — marketing / launching / promoting a product (from its URL, a brief, or a script), or a site tour / showcase / social clip featuring the site's own visuals. Up to ~3 min (sweet spot 30-90s). |
| `/faceless-explainer` | **Explaining a topic / concept** from arbitrary text — no product, no URL, no website capture; every visual is LLM-invented (typography / abstract / diagram / data-viz). |
| `/pr-to-video` | A **GitHub pull request** (PR URL, `owner/repo#N` ref, or "this PR") → changelog / feature-reveal / fix / refactor explainer, read via the `gh` CLI. |
| `/embedded-captions` | Adding **captions / subtitles** to an existing talking-head video (footage untouched) — verbatim rail, embedded climax behind the subject, or pure-cinematic embed. |
| `/talking-head-recut` | Packaging an existing talking-head / interview / podcast video with **designed graphic overlays** — lower-thirds, data callouts, kinetic titles, pull-quotes, side panels, PiP. |
| `/motion-graphics` | A short, **unnarrated, design-led motion graphic** (~under 10s) — kinetic type, stat / chart hit, logo sting, lower-third, animated tweet / headline. MP4 or transparent overlay. |
| `/music-to-video` | A **music track** (audio file, video to pull audio from, or one generated from a mood brief) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. |
| `/slideshow` | A **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. |
| `/general-video` | **Anything else** — longer or multi-scene pieces, brand / sizzle reel, title card, static loop, freeform composition. Input- and length-agnostic fallback, and the home of companion mode (co-create with the full toolbox). |
| `/remotion-to-hyperframes` | **Porting an existing Remotion** (React) composition's source to HyperFrames HTML. One-way migration, not creation. |
Check freshness without changing anything:
## Domain skills (loaded on demand)
```bash
npx hyperframes skills check
```
Atomic capabilities the creation workflows compose against — pull one when you need that specific layer.
Install or refresh one workflow explicitly:
| Skill | Covers |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/hyperframes-core` | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules. |
| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). |
| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. |
| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. |
| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. |
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus HeyGen-hosted cloud rendering (`cloud render / list / get / delete`) and AWS Lambda rendering (`lambda deploy / render / progress / destroy / policies`). |
| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. |
| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. |
```bash
npx hyperframes skills update pr-to-video
```
## Source of truth
## Use the skills in Google Antigravity
The one-line "use when" for each skill comes from its own `SKILL.md` frontmatter `description:` field in the [hyperframes repo](https://github.com/heygen-com/hyperframes/tree/main/skills). The same catalog lives in the [README's `## Skills` section](https://github.com/heygen-com/hyperframes#skills) and the repo `CLAUDE.md`. Two more surfaces compress the same descriptions and drift the same way, so they belong to the same sync set: the setup tables in the [prompting guide](/prompting/overview#one-time-setup) and the [quickstart](/quickstart). All of them are kept in sync when a skill is added, renamed, or has its contract changed.
Install the skills from the root of the project you open in Antigravity:
## Next steps
```bash
npx skills add heygen-com/hyperframes --full-depth
```
<CardGroup cols={2}>
<Card title="Quickstart" icon="rocket" href="/quickstart">
Install skills, scaffold a project, and render your first video.
</Card>
<Card title="Claude Design" icon="palette" href="/guides/claude-design">
Produce a valid first draft in Claude Design, then refine in any AI coding agent.
</Card>
<Card title="GitHub Copilot CLI" icon="terminal" href="/guides/copilot-cli">
Install and invoke HyperFrames skills from Copilot CLI in your terminal.
</Card>
<Card title="Google Antigravity" icon="atom" href="/guides/antigravity">
Use HyperFrames skills in Google Antigravity.
</Card>
</CardGroup>
Select **Core Skills** and **Antigravity**. This uses Antigravity's supported
project location, `.agents/skills`, and keeps the skills with the project. Start
a fresh Antigravity conversation after installation.
Antigravity also supports a global `~/.gemini/config/skills` directory. See
Google's [current skills guide](https://antigravity.google/docs/skills?app=antigravity-ide)
before managing that directory by hand.
## Use the skills in GitHub Copilot CLI
Run `npx hyperframes skills update`, open the project, and start Copilot:
```bash
copilot
```
If Copilot was already running, use `/skills reload`. Use `/skills list` or
`/skills info hyperframes` to confirm discovery. GitHub's [current skills
guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
lists its project and personal skill locations.
Both agents can use the same first request:
```text
Using /hyperframes, make a 10-second product intro for https://example.com.
```
Continue in the same conversation for revisions. For hosted creation instead
of a local project, use the [HyperFrames MCP guide](/guides/mcp).
## Let the router choose
The normal entry point is `/hyperframes`. It confirms the important intent, then selects a workflow from the input:
| You provide | Workflow |
| --- | --- |
| A product website or product brief | Product launch video |
| A topic or script with no website capture | Faceless explainer |
| A GitHub pull request | PR-to-video |
| Existing talking-head footage | Captions or a designed recut |
| A music track | Music-driven video |
| A short design-led animation | Motion graphic |
| A presentation | Slideshow |
| A Figma file or frame | Figma import with assets, brand tokens, components, and reconstructed motion |
| Anything outside those shapes | General video |
You can invoke a workflow directly when you already know it is the right one, but you do not need to memorize the names to start.
## Install more only when you need it
Install the complete set deliberately with:
```bash
npx skills add heygen-com/hyperframes --all --full-depth
```
Or install one named skill:
```bash
npx skills add heygen-com/hyperframes --skill hyperframes-animation --full-depth
```
Use the full set for an environment that must work across many HyperFrames tasks without fetching later. For a normal project, the core set is smaller and easier to keep current.
## If the agent cannot see a skill
1. Start a new agent session.
2. Confirm that the project or global skill directory belongs to the agent you are using.
3. Run `npx hyperframes skills check`.
4. Run `npx hyperframes skills update` when the check reports a missing or stale core skill.
The individual skill definitions remain the source of truth for agents and are
available in the [HyperFrames repository](https://github.com/heygen-com/hyperframes/tree/main/skills).
## Related topics
- [Make your first video](/quickstart)
- [Choose a specific creation workflow](/workflows)
- [Use authentication and hosted services](/guides/authentication)
+206 -162
View File
@@ -1,185 +1,229 @@
---
title: Troubleshooting
description: "Solutions for common Hyperframes issues."
title: "Troubleshooting"
description: "Solve common Studio, project, media, animation, preview, and rendering problems."
---
If your issue is about a specific coding mistake (animations not working, video cutting off early), see [Common Mistakes](/guides/common-mistakes) first. This page covers environment, tooling, and rendering issues.
Start with the symptom you can see. Keep the exact error and note whether the problem happens in Studio, validation, or only in the final render.
<AccordionGroup>
<Accordion title='"No composition found"'>
Your directory needs an `index.html` with a valid [composition](/concepts/compositions). The root element must have a [`data-composition-id`](/concepts/data-attributes#composition-attributes) attribute.
## Start here
**Fix:** Run `npx hyperframes init` to create a composition from an [example](/examples), or verify your `index.html` has the correct structure:
```html index.html
<div id="root" data-composition-id="my-video"
data-width="1920" data-height="1080">
<!-- elements here -->
</div>
```
</Accordion>
<Accordion title='"FFmpeg not found"'>
Local [rendering](/guides/rendering) requires FFmpeg installed on your system. Install it for your platform:
<CodeGroup>
```bash macOS
brew install ffmpeg
<Steps>
<Step title="Check the machine">
```bash
npx hyperframes doctor
```
```bash Ubuntu/Debian
sudo apt install ffmpeg
This checks the runtime, browser, FFmpeg, and other local requirements.
</Step>
<Step title="Check the project">
```bash
npx hyperframes lint
npx hyperframes check
```
</Step>
<Step title="Inspect the visible result">
Open Studio or capture important frames:
```bash Windows
# Download from https://ffmpeg.org/download.html
# Add the bin directory to your PATH
```bash
npx hyperframes snapshot --at 0,3,8
```
</Step>
<Step title="Give the agent useful context">
Copy the complete error and add what you did, what you expected, and what must not change.
</Step>
</Steps>
```bash Verify installation
ffmpeg -version
```
</CodeGroup>
For selection, canvas, timeline, autosave, and Studio-only failures, use
[Studio troubleshooting](/studio/troubleshooting).
After installing, run `npx hyperframes doctor` to verify the CLI can find it.
## Project and environment problems
<Tip>
If you cannot install FFmpeg, use [Docker mode](/guides/rendering) instead — it bundles FFmpeg inside the container: `npx hyperframes render --docker --output output.mp4`
</Tip>
</Accordion>
### "No composition found"
<Accordion title="Lint errors">
Run `npx hyperframes lint` to check for common structural issues (see [CLI: lint](/packages/cli#lint)):
The project needs an `index.html` containing a valid composition root with `data-composition-id`, width, and height.
| Error | Meaning |
|-------|---------|
| Missing `data-composition-id` | Root element needs this attribute. See [Compositions](/concepts/compositions). |
| Missing `class="clip"` | Timed visible elements need this class. See [Data Attributes](/concepts/data-attributes#element-visibility). |
| Overlapping timelines | Clips on the same [`data-track-index`](/concepts/data-attributes#timing-attributes) cannot overlap in time. |
| Unmuted video elements | Video elements should be `muted` unless `data-has-audio="true"` is set. |
| Deprecated attribute names | `data-layer` and `data-end` have been replaced. Check the [HTML Schema Reference](/reference/html-schema). |
</Accordion>
Create a new project:
<Accordion title="Preview not updating">
Make sure you are editing the `index.html` in the project directory. The [preview server](/packages/cli#preview) watches for file changes and auto-reloads.
If changes still do not appear:
1. Check the terminal for errors from the preview server
2. Stop and restart `npx hyperframes preview`
3. Hard-refresh the browser: **Ctrl+Shift+R** (Windows/Linux) or **Cmd+Shift+R** (macOS)
4. Clear the browser cache if CSS changes are not reflected
</Accordion>
<Accordion title="Preview stutters or plays at a low frame rate">
**Symptom:** Preview playback is jerky or skips frames, but the rendered mp4 looks fine.
**Cause:** Individual frames are taking longer than 16-33ms to paint. Render hides this (it captures frames one at a time), preview does not.
**Common culprits, most to least frequent:**
- Stacked `backdrop-filter: blur()` layers, especially at radii above 32px
- Source images at very high resolution (above 4K) displayed in small regions
- `filter: blur()` or `filter: drop-shadow()` on large elements
- Many elements with `box-shadow` or `text-shadow` that also animate
**First thing to check:** does the stutter happen only during specific scenes, or throughout? Scene-specific stutter usually points at an element, often a blur overlay, that becomes visible in that scene.
**How to diagnose:** open Chrome DevTools, switch to the Performance tab, record a few seconds of playback, and look for long tasks labeled "Composite Layers" or "Paint". See [Performance: Measuring a slow composition](/guides/performance#measuring-a-slow-composition) for the full walkthrough.
**Temporary workaround:** render to mp4 and watch the output. Render is accurate regardless of per-frame cost.
```bash Terminal
npx hyperframes render --quality draft --output preview.mp4
```
See [Performance](/guides/performance) for the full guide on expensive CSS patterns and how to fix them.
</Accordion>
<Accordion title="Render looks different from preview">
Use `--docker` mode for [deterministic output](/concepts/determinism). Local renders may differ due to:
- **Font availability** — different fonts on different platforms cause text reflow
- **Chrome version** — local Chromium vs. Docker's pinned version can render slightly differently
- **System-specific rendering** — GPU compositing, subpixel antialiasing, etc.
```bash Terminal
npx hyperframes render --docker --output output.mp4
```
See [Rendering: When to Use Each Mode](/guides/rendering#when-to-use-each-mode) for guidance on choosing between local and Docker rendering.
</Accordion>
<Accordion title="Docker mode fails to start">
Verify Docker is installed and the daemon is running:
```bash Terminal
docker info
```
Common issues:
- **Docker not running:** Start Docker Desktop or the Docker daemon
- **Permission denied:** Add your user to the `docker` group (`sudo usermod -aG docker $USER`) and restart your shell
- **Image pull fails:** Check your internet connection; the first render downloads the Hyperframes Docker image
</Accordion>
<Accordion title="Render is slow">
Try these optimizations:
1. Use `--quality draft` during development for faster encoding
2. Run `npx hyperframes benchmark` to find the optimal worker count for your system
3. Local Chrome/WebGL GPU capture is enabled automatically; compare with `--no-browser-gpu` if troubleshooting
4. Use `--gpu` for hardware-accelerated encoding (local mode only)
5. Reduce `--fps` to 24 if 30fps is not needed
6. Check that your composition does not have unnecessary elements or overly complex animations
See [Rendering: Options](/guides/rendering#options) for all available flags.
</Accordion>
<Accordion title="Video asset plays black in preview but renders fine (HEVC/H.265)">
Rendering decodes video assets with FFmpeg, so HEVC (H.265) inputs render correctly on every platform. Live preview is different: `preview`, `play`, Studio, and published player pages play the file in your browser, and not every browser decodes HEVC (Chrome 107+, Edge, and Safari do on most modern hardware; Firefox does not). This is now self-healing: preview detects an undecodable asset and automatically swaps in a cached H.264 proxy, so this should no longer show as a persistent black frame.
If a hostile asset is still stuck black in preview:
1. Confirm auto-proxying is not disabled: no `--no-proxy` flag, and `media.autoProxy` is not `false` in `hyperframes.json`.
2. Run `npx hyperframes doctor` to confirm ffmpeg/ffprobe are installed; the proxy transcode needs both.
3. Run `npx hyperframes lint --verbose`: the info-level `hevc_preview_codec` finding names every affected asset.
See [Rendering: Input Video Codecs](/guides/rendering#input-video-codecs).
</Accordion>
</AccordionGroup>
## System Diagnostics
Run `npx hyperframes doctor` to check your environment:
```bash Terminal
npx hyperframes doctor
```bash
npx hyperframes init my-video
```
This checks for Node.js version, FFmpeg availability, Docker status, and other requirements. If `doctor` reports issues, address them before rendering.
Or compare the current source with [Compositions](/concepts/compositions).
## Still Stuck?
### "FFmpeg not found"
If none of the above resolves your issue:
FFmpeg is required for local video encoding.
1. Run `npx hyperframes info` to gather system and project details
2. Check [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for similar reports
3. Open a new issue with the output of `npx hyperframes info` and steps to reproduce
<CodeGroup>
```bash macOS
brew install ffmpeg
```
## Next Steps
```bash Ubuntu or Debian
sudo apt install ffmpeg
```
<CardGroup cols={2}>
<Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
Coding pitfalls that break compositions
</Card>
<Card title="Rendering" icon="film" href="/guides/rendering">
Rendering modes, options, and tips
</Card>
<Card title="CLI Reference" icon="terminal" href="/packages/cli">
Full list of CLI commands
</Card>
<Card title="Contributing" icon="code-branch" href="/contributing">
Report bugs and contribute fixes
</Card>
</CardGroup>
```powershell Windows
# Download a 64-bit Windows build from:
# https://ffmpeg.org/download.html#build-windows
# Then add its bin directory to PATH.
```
</CodeGroup>
Verify with `ffmpeg -version`, then rerun `npx hyperframes doctor`.
### Docker render will not start
Run `docker info`.
Confirm Docker is installed, its daemon is running, your user has permission, and the first image download can reach the registry.
## Media problems
### Video is black in preview but renders
The browser may not decode the source codec even though FFmpeg can.
HyperFrames normally creates and uses a compatible preview proxy. If the frame remains black:
1. confirm automatic proxying is not disabled;
2. run `npx hyperframes doctor`;
3. run `npx hyperframes lint --verbose` to identify affected files;
4. confirm the source file exists and can be read.
### Video, image, or audio is missing
Prefer a local project asset. Confirm its path, filename capitalization, and whether it was moved or renamed.
Remote media can fail because of permissions, expiring URLs, or cross-origin restrictions.
### Preview stutters
Common causes:
- very large source images;
- several large `backdrop-filter` blurs;
- expensive shadows or filters on animated elements;
- too many large overlapping layers.
Check whether the slowdown occurs in one scene. Resize oversized media and simplify the expensive element before reducing the whole project’s quality.
## Animation and composition mistakes
These problems often appear in agent-written or manually edited source.
### A video freezes while its box animates
Do not animate `width`, `height`, `top`, or `left` directly on a `<video>` element.
Put the video inside a wrapper and animate the wrapper:
```html
<div id="video-wrapper">
<video src="./assets/video.mp4" style="width:100%;height:100%"></video>
</div>
```
```javascript
tl.to("#video-wrapper", { width: 500, height: 280, x: 1200 }, 2);
```
### Media plays out of sync
Do not call `play()`, `pause()`, or set `currentTime` from composition scripts.
HyperFrames owns media playback. Use timing and media attributes to describe when the file should play.
### The composition ends too early
Check the resolved composition duration:
```bash
npx hyperframes compositions
```
A short animation timeline can make a project end before the underlying media. Extend the authored root duration or timeline using the correct pattern for that composition.
### A timed element is always visible
Timed visible elements need `class="clip"` as well as their timing attributes.
```html
<h1 class="clip" data-start="2" data-duration="5" data-track-index="0">
Hello
</h1>
```
`npx hyperframes lint` normally catches this.
### Animation is static
Check that the animation is paused and registered using the exact composition ID.
```javascript
const timeline = gsap.timeline({ paused: true });
window.__timelines = window.__timelines || {};
window.__timelines["my-video"] = timeline;
```
`my-video` must match `data-composition-id="my-video"`.
### Changing root duration from a variable does nothing
The root render length is determined before composition scripts run. Author or generate the intended root `data-duration` directly.
Clip durations can still vary. See [Variables](/concepts/variables) for what may be changed safely.
## Render problems
### The render looks different from preview
Check fonts, remote media, browser-specific effects, and the actual exported file.
Use Docker when you need a pinned rendering environment:
```bash
npx hyperframes render --docker --output output.mp4
```
### The render is slow
During iteration:
- use draft quality;
- inspect snapshots before starting another full render;
- resize large source media;
- simplify expensive filters;
- avoid increasing resolution or frame rate before needed.
Run `npx hyperframes benchmark` when tuning worker settings.
### Expected HDR but received SDR
HDR needs a supported output and correct source color metadata. MP4 is the normal HDR output path; WebM and MOV may fall back to SDR.
Use `--hdr` only when the whole source and delivery workflow is intended for HDR. Read [HDR rendering](/guides/hdr) before delivery.
## Still stuck?
Run:
```bash
npx hyperframes info
```
Then search [GitHub issues](https://github.com/heygen-com/hyperframes/issues) or open a report with:
- the exact error;
- steps to reproduce;
- HyperFrames version and operating system;
- whether the issue occurs in preview, checks, or render;
- a small shareable project when possible.
Do not include secrets, private media, or access tokens.
## Related topics
- [Start with the shortest recovery path](/help)
- [Recover from a Studio-only problem](/studio/troubleshooting)
- [Share useful product feedback](/guides/feedback)
+65 -110
View File
@@ -1,124 +1,79 @@
---
title: Video Components
description: "Install production-ready video blocks and components from the HyperFrames catalog with one command — or contribute your own."
title: "Use images and video"
sidebarTitle: "Images and video"
description: "Import, place, replace, trim, and review images and footage in a HyperFrames project."
---
The HyperFrames **catalog** is a registry of 50+ production-ready video components — captions, code animations, social overlays, shader transitions, data viz, and more. Each one installs into any project with a single command and renders to a deterministic MP4. Don't rebuild a scene from scratch — install the one that already exists.
Images and footage should enter the project once, remain easy to identify, and
behave the same in preview and the final render.
```bash Terminal
npx hyperframes add x-post
<Frame caption="Current Studio, changing the real project: inspect the source, change Fit and Position, crop on the canvas, then import another local asset.">
<video
autoPlay
loop
muted
playsInline
preload="metadata"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-media-edit-loop-v1.jpg"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-media-edit-loop-v1.mp4"
/>
</Frame>
## Import a file
In Studio:
1. Open **Assets**.
2. Choose **Import media**, or drop the file into the panel.
3. Preview it.
4. Drag it to the timeline.
Studio accepts common image formats, SVG, MP4, WebM, and MOV. Keep the source
inside the project before the final render.
## Place it deliberately
- Set the start and duration by watching the surrounding edit.
- Choose a crop that preserves the important content.
- Keep source audio only when it belongs in the mix.
- Avoid stretching low-resolution media beyond what it can support.
- Use a wrapper when animating the size or position of video; this keeps frame capture reliable.
For a source-level change, ask the agent in terms of the visible result:
```text
Use assets/product-tour.mp4 from 00:04 to 00:10.
Crop around the editor canvas, keep the source muted, and place it beneath
the existing caption layer.
```
## Browse the catalog
## Change or replace the source
<CardGroup cols={2}>
<Card title="Code Animations" icon="code" href="/catalog/blocks/code-morph">
Typing, diff, morph, highlight, scroll, and GPU 3D/particle/shader code reveals
</Card>
<Card title="Captions" icon="closed-captioning" href="/catalog/components/caption-highlight">
15 caption styles — karaoke, kinetic slam, neon, gradient, glitch, emoji pop
</Card>
<Card title="Social Overlays" icon="share-nodes" href="/catalog/blocks/x-post">
X posts, TikTok / Instagram follow cards, Reddit, Spotify, lower thirds
</Card>
<Card title="Shader Transitions" icon="bolt" href="/catalog/blocks/whip-pan">
14 WebGL transitions — whip pan, glitch, light leak, vortex, iris, burn
</Card>
<Card title="Liquid Glass &amp; VFX" icon="wand-magic-sparkles" href="/catalog/blocks/ios26-liquid-glass">
HTML-in-canvas effects — iOS 26 glass, device frames, portals, shatter, magnetic
</Card>
<Card title="Data" icon="chart-column" href="/catalog/blocks/data-chart">
Animated charts and US / world / region maps with bubbles, flows, and hexes
</Card>
<Card title="CSS Transitions" icon="right-left" href="/catalog/blocks/transitions-3d">
13 zero-dependency transitions — 3D, blur, cover, dissolve, push, radial
</Card>
<Card title="Code Snippets" icon="terminal" href="/catalog/blocks/code-snippet-dark-modern">
24 syntax-highlighted code cards and Apple-terminal themes
</Card>
</CardGroup>
Studio’s Media section shows the current project path and controls Fit,
Position, playback, and audio. Assets imports files and adds new layers. It does
not currently provide a one-click source replacement in that Inspector.
Plus **Effects** (grain, vignette, shimmer, parallax), **Text Effects** (morph text, texture mask), and **Showcases** — browse them all under the [Catalog](/catalog/blocks/data-chart) tab.
To keep the existing layer, ask the agent to change its `src`, or edit the
element in Source. Then recheck the crop, clip length, transition, and any
motion tied to the old dimensions.
## Blocks vs components
Replacing a file should not require rebuilding the whole scene. If the new
content also changes the story or several scenes, ask the agent to make the
broader revision.
The catalog ships two kinds of item, installed the same way but wired differently:
## Avoid fragile sources
| | **Blocks** | **Components** |
|---|---|---|
| What it is | A full standalone scene | A reusable snippet / effect |
| Has its own size & duration | Yes | No — adapts to the host |
| Installs to | `compositions/<name>.html` | `compositions/components/<name>.html` |
| Wired by | `data-composition-src` on a host element | Pasting its HTML / CSS / JS into your composition |
| Examples | `x-post`, `data-chart`, `code-morph` | `grain-overlay`, `caption-highlight`, `shimmer-sweep` |
Temporary signed URLs, private browser sessions, and render-time network
requests can disappear or fail in another environment. Copy required media into
the project, keep filenames stable, and run `npx hyperframes check` before
rendering.
## Install and wire
Continue to [Use Assets and Catalog](/studio/assets-and-blocks) for the Studio
controls, or [Media effects](/guides/media-effects) when the source needs a
non-destructive visual treatment.
<Steps>
<Step title="Find it">
Browse the [Catalog](/catalog/blocks/data-chart) tab, or have your AI agent consult the registry — every item lists its name, description, tags, dimensions, and duration.
</Step>
<Step title="Add it">
```bash Terminal
npx hyperframes add data-chart
```
The CLI writes the files and prints a snippet to paste into your host composition.
</Step>
<Step title="Wire a block">
Blocks are standalone compositions — include them with `data-composition-src` and a timeline position:
```html index.html
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="0"
data-duration="15"
data-track-index="1"
data-width="1920"
data-height="1080"
></div>
```
</Step>
<Step title="Wire a component">
Components are snippets — paste their HTML into your composition's markup, their CSS into your styles, and any JS into your script, then hook their timeline calls into yours.
</Step>
</Steps>
## Related topics
<Tip>
Using an AI agent? Install the HyperFrames skills with `npx skills add heygen-com/hyperframes` and ask it to "add a chart block" — the `/hyperframes-registry` skill discovers, installs, and wires the catalog item for you.
</Tip>
## Contribute a video component
Your agent already knows how to build video components — it writes HTML, HyperFrames renders it. The registry is where that work ships to **every** HyperFrames user. Spotted a caption style on TikTok that doesn't exist yet, or built a transition worth sharing? Add it to the catalog.
<Info>
**Quick version** — Fork the repo. Write one HTML file with a paused GSAP timeline. Add `registry-item.json`. Run `hyperframes lint` + `validate`. Publish with `npx hyperframes publish`. Open a PR.
</Info>
Every item is a single self-contained HTML file with a paused GSAP timeline — no build step, no framework. It must be deterministic (seeded randomness only, no `Date.now()` / `Math.random()`), register its timeline on `window.__timelines`, and meet the production-quality bar.
<CardGroup cols={2}>
<Card title="Contributing to the Catalog" icon="cube" href="/contributing/catalog">
The full idea → scaffold → build → validate → preview → ship workflow, the `registry-item.json` schema, the rules, and the quality bar
</Card>
<Card title="Open a component request" icon="lightbulb" href="https://github.com/heygen-com/hyperframes/issues/new">
No code needed — share a visual reference and tag it <code>component-request</code>
</Card>
</CardGroup>
## Next Steps
<CardGroup cols={2}>
<Card title="Compositions" icon="layer-group" href="/concepts/compositions">
How blocks nest into a host composition
</Card>
<Card title="Variables" icon="sliders" href="/concepts/variables">
Parameterize an installed block to stay on-brand
</Card>
<Card title="The Pipeline" icon="diagram-project" href="/guides/pipeline">
Design → plan → layout → build → validate → render
</Card>
<Card title="Contributing to the Catalog" icon="cube" href="/contributing/catalog">
Add your own block or component to the registry
</Card>
</CardGroup>
- [Use Assets and Catalog in Studio](/studio/assets-and-blocks)
- [Apply a media effect](/guides/media-effects)
- [Remove a human background](/guides/remove-background)
+29 -119
View File
@@ -1,135 +1,45 @@
---
title: Introduction
description: "Write HTML. Render video. Built for agents."
title: "What is HyperFrames?"
sidebarTitle: "What HyperFrames is"
description: "See what an AI agent can make with ordinary web technology."
---
Hyperframes is an open-source framework that turns HTML into deterministic, frame-by-frame rendered video — so you can define a video the same way you build a web page.
import { DocsVideo, ShowcaseWall } from "/snippets/docs-video.jsx";
## See It in Action
Here is a video defined entirely as HTML:
```html
<div id="root" data-composition-id="demo"
data-start="0" data-width="1920" data-height="1080">
<video id="clip-1" data-start="0" data-duration="5"
data-track-index="0" src="intro.mp4" muted playsinline></video>
<h1 id="title" class="clip"
data-start="1" data-duration="4" data-track-index="1"
style="font-size: 72px; color: white;">
Welcome to Hyperframes
</h1>
<audio id="bg-music" data-start="0" data-duration="5"
data-track-index="2" data-volume="0.5" src="music.wav"></audio>
<div className="hf-docs-video-frame">
<DocsVideo
title="What is HyperFrames?"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-introduction-v5.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-introduction-v5.jpg"
/>
</div>
```
Run `npx hyperframes render --output demo.mp4` and this produces an MP4 with deterministic, frame-by-frame capture. Same input, identical output, every time. No timeline editor. No proprietary format. Just HTML.
HyperFrames is an open-source framework that turns HTML into video. You make the request; an AI agent builds an editable project; HyperFrames plays or renders it.
<CardGroup cols={2}>
<Card title="Watch the Showcase" icon="play" href="/showcase">
Finished HyperFrames videos you can watch, read, run, and remix — product launches, website-to-video demos, UI reveals, and VFX experiments.
</Card>
<Card title="Browse the Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
50+ ready-to-use blocks and components — social overlays, shader transitions, data visualizations, and cinematic effects. Install any of them with one command.
</Card>
<Card title="Quick Start" icon="rocket" href="/quickstart">
Go from zero to rendered video in under 5 minutes.
</Card>
<Card title="Skills catalog" icon="sparkles" href="/guides/skills">
Every HyperFrames AI agent skill — router, creation workflows, and domain skills. Install with `npx skills add heygen-com/hyperframes`.
</Card>
</CardGroup>
## What can it make?
## Why Hyperframes?
Every tile below is a finished HyperFrames film. Open one to watch it with sound.
<Tabs>
<Tab title="For developers">
**You already know the stack.** Compositions are HTML files with data attributes. Animations use GSAP, Lottie, CSS, or any runtime that can seek to a given frame. There is no custom DSL, no proprietary component system, and no React requirement. If you can build a web page, you can build a video.
</Tab>
<Tab title="For AI agents">
**Agents already speak HTML.** Most video tools require complex APIs or drag-and-drop interfaces that agents cannot operate. Hyperframes compositions are plain HTML documents — the format LLMs are best at generating. The CLI is non-interactive by default — all inputs via flags, plain text output, fail-fast on errors — so agents can drive every command without prompts or parsing.
</Tab>
<Tab title="For automated pipelines">
**Determinism by design.** The rendering pipeline is seek-driven with no wall-clock dependencies. `frame = floor(time * fps)` — every frame is independently captured via Chrome's `beginFrame` API and encoded with FFmpeg. Same input always produces identical output, making CI testing and batch rendering reliable.
</Tab>
</Tabs>
<ShowcaseWall />
<Tip>
Hyperframes was designed from the ground up for AI agent integration. Compositions are plain HTML that any LLM can generate. The CLI is non-interactive by default — flag-driven with plain text output — so agents can scaffold, render, and lint without interactive prompts. Add `--human-friendly` for the interactive terminal UI. See [CLI](/packages/cli) for details.
</Tip>
## Three things to know
## How It Works
**Agent-built.** You describe the video; the agent writes the HTML, CSS, and JavaScript. You do not need to write code for this path.
<Steps>
<Step title="Write HTML">
Define your video as an HTML document. Each element gets data attributes for timing (`data-start`, `data-duration`) and layout (`data-track-index`). Add animations with GSAP, Lottie, CSS transitions, or any seekable runtime via the Frame Adapter pattern.
</Step>
<Step title="Preview in the browser">
Run `npx hyperframes preview` to open a live preview in your browser. Edit your HTML and see changes instantly — no build step, no compilation.
</Step>
<Step title="Render to MP4">
Run `npx hyperframes render --output output.mp4` to produce a final video. The engine seeks each frame in headless Chrome, captures it with `beginFrame`, and pipes the result through FFmpeg. Run locally or in Docker for fully reproducible output.
</Step>
</Steps>
**Editable.** The result is a project folder, not a flattened black box. An agent, Studio, and your own tools can work on the same files.
## Packages
**Reliable render.** HyperFrames asks the project for each exact frame instead of
depending on live playback, so a slow machine does not drop moments from the
finished video.
<CardGroup cols={2}>
<Card title="@hyperframes/core" icon="cube" href="/packages/core">
Types, HTML parsing, runtime, and composition linter — the foundation everything else builds on.
</Card>
<Card title="@hyperframes/sdk" icon="code" href="/packages/sdk">
Headless composition editing engine for agents, custom editors, patch events, and persistence.
</Card>
<Card title="@hyperframes/engine" icon="gear" href="/packages/engine">
Seekable page-to-video capture engine. Loads HTML in headless Chrome and captures frame-by-frame.
</Card>
<Card title="@hyperframes/player" icon="play" href="/packages/player">
Embeddable web component for playing HyperFrames compositions in any web page.
</Card>
<Card title="@hyperframes/producer" icon="video" href="/packages/producer">
Full rendering pipeline combining capture and FFmpeg encoding into a single API call.
</Card>
<Card title="@hyperframes/shader-transitions" icon="sparkles" href="/packages/shader-transitions">
WebGL shader transitions for scene-to-scene motion and render-time compositing.
</Card>
<Card title="@hyperframes/aws-lambda" icon="cloud" href="/packages/aws-lambda">
AWS Lambda and Step Functions adapter for distributed rendering.
</Card>
<Card title="@hyperframes/gcp-cloud-run" icon="cloud" href="/packages/gcp-cloud-run">
Google Cloud Run and Workflows adapter for distributed rendering.
</Card>
<Card title="@hyperframes/studio" icon="palette" href="/packages/studio">
Visual composition editor UI for building and previewing timelines interactively.
</Card>
<Card title="hyperframes (CLI)" icon="terminal" href="/packages/cli">
Command-line tool for creating, previewing, and rendering compositions.
</Card>
</CardGroup>
## Make one
## Next Steps
<Card title="Make your first video" icon="play" href="/quickstart" horizontal arrow>
Install the skills, make one short request, and choose how you want to continue.
</Card>
<CardGroup cols={2}>
<Card title="Showcase" icon="play" href="/showcase">
Get inspired by finished videos and production launch projects.
</Card>
<Card title="Quickstart" icon="rocket" href="/quickstart">
Build and render your first video in 60 seconds
</Card>
<Card title="Skills catalog" icon="sparkles" href="/guides/skills">
Every HyperFrames AI agent skill — router, creation workflows, and domain skills
</Card>
<Card title="Compositions" icon="layer-group" href="/concepts/compositions">
Understand the HTML-based data model behind every video
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Add timeline-driven animations with GSAP
</Card>
<Card title="Rendering" icon="film" href="/guides/rendering">
Render locally, in Docker, or in a CI pipeline
</Card>
</CardGroup>
## Related topics
- [Watch more finished HyperFrames work](/examples)
- [Go further with an existing project](/go-further)
- [Build on HyperFrames as a developer](/developers)
+58 -251
View File
@@ -1,273 +1,80 @@
---
title: Quickstart
description: "Create, preview, and render your first Hyperframes video in under two minutes."
title: "Make your first video"
description: "Install the HyperFrames skills, make one short request, and continue with your agent, Studio, or the CLI."
---
Go from zero to a rendered MP4 — either by prompting your AI agent or by starting a project manually.
import { QuickstartContinuationGrid } from "/snippets/quickstart-continuation-grid.jsx";
import { DocsVideo } from "/snippets/docs-video.jsx";
## Option 1: With an AI coding agent (recommended)
<div className="hf-docs-video-frame">
<DocsVideo
title="A beginner creates a first HyperFrames video from one short request, then continues with an agent, Studio, or the CLI."
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-quickstart-v5.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-quickstart-v5.jpg"
/>
</div>
Install the HyperFrames skills, then describe the video you want:
<Note>
HyperFrames is free and open-source, and local rendering does not use HeyGen credits. Your coding
agent and any optional hosted, voice, avatar, or generated-media services may have their own
costs.
</Note>
## The short way: hand it to your agent
If you already have a coding agent open in a folder, paste this and skip the
rest of the page. It installs the skills, makes the video, and opens the
preview — you only change the URL.
```text
Set this folder up for HyperFrames and make me a video.
1. Run: npx hyperframes skills update
2. Then, using /hyperframes, make a 10-second product intro for https://example.com
3. Open the local preview when it is done and tell me the project folder.
```
Swap `https://example.com` for the page you want the video to show. Everything
below is the same thing done by hand, if you would rather see each step.
## 1. Install the skills
Run this in your project folder:
```bash
npx skills add heygen-com/hyperframes --full-depth
```
Keep `--full-depth`: it installs the current `main`. Without it, `skills add` fetches the skills.sh registry blob, which lags `main` by hours — you'd get stale skills.
Choose **Core Skills** in the picker. Keep `--full-depth` so the installer uses the current repository version. Then open or restart your coding agent in that folder.
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](/guides/antigravity), and [GitHub Copilot CLI](/guides/copilot-cli) load them too):
## 2. Ask for the video
| 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, check, preview, render, doctor |
| `/media-use` | Asset preprocessing — TTS, transcription, background removal |
| `/hyperframes-registry` | Install catalog blocks and components |
| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes, plus `hyperframes keyframes` diagnostics |
| `/general-video` | The general authoring workflow — multi-scene pieces, reels, montages, remixes, and the home of companion mode; the fallback when no specific workflow fits |
```text
Using /hyperframes, make a 10-second product intro for https://example.com.
```
The **workflow skills** are optional — add the ones that match your inputs, and `/hyperframes` routes to whichever you've installed: `/product-launch-video`, `/faceless-explainer`, `/pr-to-video`, `/embedded-captions`, `/talking-head-recut`, `/motion-graphics`, `/music-to-video`, `/slideshow`, `/general-video`, `/remotion-to-hyperframes`, `/figma`. See the [skills catalog](/guides/skills) for the full list with one-line "use when" descriptions.
Replace `https://example.com` with the real page you want the video to show. The agent will propose
a direction and ask for anything important that is missing. You do not need to write a production
specification.
<Tip>
To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all --full-depth`.
</Tip>
## 3. Continue from the first version
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.**
The agent leaves you with an editable project folder and opens its local preview.
To reopen that preview later, run `npx hyperframes preview` inside the project
folder. Watch the first version once and check the story, facts, readable text,
and sound; it is not a guaranteed final cut. All three paths below work with
the same project.
<Note>
Claude Design uses a different entry path. Open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/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](/guides/claude-design).
</Note>
<QuickstartContinuationGrid />
### Try it: example prompts
Copy any of these into your agent to get started.
<CardGroup cols={1}>
<Card title="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.
</Card>
<Card title="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`.
</Card>
<Card title="Format-specific">
> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.
</Card>
<Card title="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.
</Card>
</CardGroup>
The agent handles scaffolding, animation, and rendering. See the [prompting guide](/prompting/overview) for more patterns, or the [pipeline guide](/guides/pipeline) for the 7-step structure (DESIGN, SCRIPT, STORYBOARD, …) that AI agents follow for multi-beat videos.
<Tip>
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.
</Tip>
## Option 2: Start a project manually
### Prerequisites
- **Node.js 22+** — runtime for the CLI and dev server
- **FFmpeg** — video encoding for local renders
<Accordion title="Install instructions">
<Steps>
<Step title="Install Node.js 22+">
Hyperframes requires Node.js 22 or later. Check your version:
```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>
</Steps>
</Accordion>
### Create your first video
<Steps>
<Step title="Scaffold the project">
```bash
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`:
```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.
</Step>
<Step title="Preview in the browser">
```bash
npx hyperframes preview
```
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>
</Step>
<Step title="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:
```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`
</Step>
<Step title="Validate before rendering">
```bash
npx hyperframes lint
npx hyperframes check
```
`lint` checks the HTML structure statically; `check` runs the composition in a headless browser and reports what a still frame can't — an element overflowing its region, colliding text, a runtime error that only fires mid-timeline, contrast below WCAG AA. Both must pass before you render: a render that took ten minutes will happily contain a defect `check` names in seconds.
</Step>
<Step title="Render to MP4">
```bash
npx hyperframes render --output output.mp4
```
```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.
</Step>
</Steps>
## 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
## Related topics
<CardGroup cols={2}>
<Card title="Browse the Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
50+ ready-to-use blocks — transitions, overlays, data visualizations, and effects
<Card title="Choose a specific workflow" icon="route" href="/workflows">
Product launch, explainer, captions, recut, pull request, music, motion graphic, or
presentation.
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Add fade, slide, scale, and custom animations to your videos
</Card>
<Card title="Examples" icon="rocket" href="/examples">
Start from built-in examples like Warm Grain and Swiss Grid
</Card>
<Card title="Rendering" icon="film" href="/guides/rendering">
Explore render options: quality presets, Docker mode, and GPU acceleration
<Card title="Go further" icon="arrow-right" href="/go-further">
Direct the agent, edit in Studio, build richer projects, and finish with confidence.
</Card>
</CardGroup>
+14 -3
View File
@@ -4,6 +4,8 @@ description: "Curated weekly highlights for HyperFrames."
rss: true
---
import { DocsVideo } from "/snippets/docs-video.jsx";
Weekly HyperFrames highlights across releases, examples, docs, and community updates.
For exact versioned release notes, see the [Changelog](/changelog).
@@ -17,7 +19,10 @@ For exact versioned release notes, see the [Changelog](/changelog).
>
<Frame>
<video controls muted playsinline src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-2026-07-27-2026-08-03.mp4"></video>
<DocsVideo
title="HyperFrames video: Weekly Changelog 2026 07 27 2026 08 03"
src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-2026-07-27-2026-08-03.mp4"
/>
</Frame>
The Studio timeline is the headline. Expanding a track now shows one lane per animated property, with keyframe track headers, drag retiming, and virtualization on by default, and a long correctness sweep makes a keyframe edit land on the element you actually clicked. Three themed registry families add 29 catalog items from an outside contributor. Transparent GIF output works, the engine's media probing is hardened end to end, and a clean install now resolves a dependency graph with no advisories.
@@ -76,7 +81,10 @@ For exact versioned release notes, see the [Changelog](/changelog).
>
<Frame>
<video controls muted playsinline src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-2026-07-20-2026-07-27.mp4"></video>
<DocsVideo
title="HyperFrames video: Weekly Changelog 2026 07 20 2026 07 27"
src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-2026-07-20-2026-07-27.mp4"
/>
</Frame>
Professional color grading is the headline. Master and per-channel curves, hue curves, three-way wheels, and HSL secondaries land in core, Studio, and the CLI, so you can shape shadows, midtones, and highlights on any image or video without leaving the composition. The distributed plan gains an explicit protocol version and can publish artifacts straight to S3 and GCS. Studio adds a keyframe ease editor, registry caption components become transcript-driven, and a long run of audio, download, and capture reliability fixes lands underneath.
@@ -128,7 +136,10 @@ For exact versioned release notes, see the [Changelog](/changelog).
tags={["Weekly update", "Highlights"]}
>
<Frame>
<video controls muted playsinline src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-jul13-20.mp4"></video>
<DocsVideo
title="HyperFrames video: Weekly Changelog Jul13 20"
src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-jul13-20.mp4"
/>
</Frame>
Automatic media proxying is the headline. Any video codec your FFmpeg can decode now plays on every live surface, from preview and Studio to play and published pages, while render keeps using the originals. Media Use gains a video generator, Studio's flat inspector ships on by default, and the engine's timeout errors now name the fix. A large batch of render, lint, and CLI reliability fixes lands alongside.