ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-11-15 13:49:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2978 from heygen-com/docs/site-structure

Browse Source 
docs: rebuild the site structure — add sections, retire superseded pages
This commit is contained in:
Ular Kimsanov
2026-08-04 02:11:01 -07:00
committed by GitHub
parent edfe66a953 1a82615f64
commit 8e41fa17b9
54 changed files with 3778 additions and 2609 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/docs.yml
+3 -1
View File
@@ -49,4 +49,6 @@ jobs:
- name: Check broken links
working-directory: docs
run: npx mint broken-links
# --check-redirects also resolves every redirect destination, so a
# restructure cannot leave a redirect pointing at a page it removed.
run: npx mint broken-links --check-redirects
docs/catalog/index.mdx
+62
View File
@@ -0,0 +1,62 @@
---
title: "Catalog"
description: "Browse reusable HyperFrames scenes, transitions, captions, overlays, effects, and components."
---
The Catalog is a library of visuals you can add to a project instead of building each one from scratch.
Use a **block** when you want a larger scene or self-contained visual. Use a **component** when you want a smaller effect or behavior inside an existing scene.
## Start with the job
<CardGroup cols={2}>
<Card title="Code animations" icon="code" href="/catalog/blocks/code-typing">
Show code being typed, changed, highlighted, scrolled, or transformed.
</Card>
<Card title="Captions" icon="closed-captioning" href="/catalog/components/caption-highlight">
Keep speech readable or emphasize selected words without designing a caption system from zero.
</Card>
<Card title="Transitions" icon="arrows-left-right" href="/catalog/blocks/cinematic-zoom">
Move between scenes with a quiet cut treatment or a more expressive transition.
</Card>
<Card title="Social overlays" icon="share-nodes" href="/catalog/blocks/x-post">
Show posts, follow prompts, notifications, names, roles, and platform-inspired cards.
</Card>
<Card title="Data and diagrams" icon="chart-column" href="/catalog/blocks/data-chart">
Explain a number, comparison, trend, location, or geographic movement.
</Card>
<Card title="Complete scenes" icon="play" href="/catalog/blocks/app-showcase">
Start from a larger scene that already combines design, media, and animation.
</Card>
</CardGroup>
## Use an item in a real project
1. Open an item and watch the motion preview.
2. Check that its communication job matches the scene.
3. Copy the plain-language request from the item page into your agent chat.
4. Replace the example content with real project content.
5. Match the project's type, color, spacing, and motion language.
6. Review the item inside the complete video, not only in isolation.
The terminal command and source details remain available on each item page for people who need them.
## Before you keep it
<Note>
A Catalog item is a starting point, not a finished design decision. Keep it only when it makes the scene clearer or faster to understand. Remove decorative motion that competes with the story.
</Note>
Check:
- Can the viewer understand why the visual is present?
- Is the real content readable at the final size?
- Does its timing fit the scenes around it?
- Does it feel like part of this project rather than a pasted demo?
- Is a quieter alternative more effective?
## Related topics
- [Add Catalog items in Studio](/studio/assets-and-blocks)
- [Build richer compositions](/go-further)
- [Contribute a Catalog item](/contributing/catalog)
docs/concepts/index.mdx
+163
View File
@@ -0,0 +1,163 @@
---
title: "How a HyperFrames project works"
sidebarTitle: "Project model"
description: "Understand the editable files, compositions, timing, and tools behind a HyperFrames video."
---
A HyperFrames project is a folder your agent can create and you can keep
editing. Its HTML is the video: it describes the scenes, timing, motion, media,
and reusable parts that HyperFrames plays or renders.
## The source is the project
The agent, Studio, CLI, SDK, and Player do not create separate versions of the
video. They work with the same project files.
| What you want to change | Best place to start |
| ---------------------------------------------------- | ------------------- |
| Story, structure, or several scenes | Ask the agent |
| Text, layout, timing, or animation you can see | Studio |
| Preview, checks, snapshots, rendering, or automation | CLI |
| A composition inside your own product | SDK or Player |
<div style={{ maxWidth: "42rem", margin: "1.5rem auto" }}>
<Frame caption="The same editable project open in Studio, with its source, canvas, controls, and timeline.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/overview-v1.jpg"
alt="A HyperFrames project open in Studio with the source tree, canvas, controls, and timeline"
/>
</Frame>
</div>
Studio writes supported edits back into the source. An agent can continue from
those files, Git can track them, and the renderer sees the same result.
## What the agent creates
A larger project often looks like this:
```text
project/
├── BRIEF.md what the video must communicate
├── STORYBOARD.md the planned sequence and review state
├── SCRIPT.md locked narration, when the video has it
├── frame.md visual direction, when the project needs one
├── index.html the main composition
├── hyperframes.json project settings
├── compositions/ scenes and reusable visual parts
├── assets/ images, video, audio, and fonts
└── renders/ finished files
```
Only the project source is essential. Planning files exist to preserve decisions
across reviews and agent sessions. A simple title card may need only
`index.html` and an asset; a narrated launch film benefits from a brief,
storyboard, script, and separate scenes.
## Compositions hold the video together
A **composition** is a finite, seekable piece of the project. The main
composition is the complete sequence. Other compositions can be scenes,
captions, title systems, or visuals reused more than once.
```text
Main video
├── Opening
├── Product demo
├── Customer proof
└── Closing
```
Each part is still HTML. A larger project stays manageable because a scene can
be built and checked on its own, then placed on the main timeline.
```html
<div
data-composition-id="product-demo"
data-composition-src="compositions/product-demo.html"
data-start="4"
data-duration="6"
data-track-index="1"
></div>
```
Edit the nested composition when the scene itself should change everywhere it
is used. Edit its placement in the main composition when only this appearance
should start earlier, run longer, or move to another layer.
## Time is part of the source
Timed elements carry their start, duration, and track in HTML:
```html
<img
id="product-shot"
class="clip"
data-start="2"
data-duration="3"
data-track-index="1"
src="./assets/product.png"
/>
```
This image starts at two seconds, remains for three seconds, and appears on
track one. Animation timelines are paused and seekable, so Studio, the Player,
and the renderer can request an exact moment without playing from the
beginning.
## Variables keep approved parts changeable
A variable exposes something that is meant to change—such as a title, logo,
color, price, or customer name—without rebuilding the layout. One composition
can produce several approved versions while preserving its design and motion.
Use a variable when the structure should stay fixed. Use a normal edit when the
structure itself needs to change.
## How a project moves forward
There is no required seven-step ceremony. The project records only the
decisions its size and review process need.
| Decision | Where it usually lives |
| ------------------------------ | ----------------------------------------------------------- |
| What the video is for | Your request and, for a fuller project, `BRIEF.md` |
| What happens and in what order | `STORYBOARD.md` and optional `SCRIPT.md` |
| How it looks | `frame.md`, project assets, and the compositions themselves |
| The editable result | `index.html`, `compositions/`, and `assets/` |
| The approved delivery | checks plus the file in `renders/` |
Review the message and sequence before polishing individual frames. Once the
project looks right, run the checks, render it, and watch the exported file.
## Why rendering can repeat the same moment
HyperFrames seeks the composition to an exact time, captures the frame, and
advances. Media and audio follow the same timeline.
For the same source, media, and settings, an exact timestamp should resolve to
the same project state. Compositions therefore avoid the current clock,
unseeded randomness, and render-time network requests.
## Go deeper when you need it
<CardGroup cols={2}>
<Card title="Reuse a design with variables" icon="sliders" href="/concepts/variables">
Expose approved content without opening the layout.
</Card>
<Card title="Finish and share a video" icon="circle-check" href="/guides/export-and-share">
Review, check, render, watch, and deliver the same project.
</Card>
<Card title="Composition structure" icon="layer-group" href="/concepts/compositions">
Use nested compositions and exact source attributes.
</Card>
<Card title="HTML schema" icon="code" href="/reference/html-schema">
Look up the complete technical composition contract.
</Card>
</CardGroup>
## Related topics
- [Take more control of an existing project](/go-further)
- [Look up the complete HTML schema](/reference/html-schema)
- [Choose a developer integration surface](/developers/overview)
docs/deploy/overview.mdx
+99
View File
@@ -0,0 +1,99 @@
---
title: "Choose a rendering path"
sidebarTitle: "Rendering overview"
description: "Choose the smallest HyperFrames rendering surface for local work, an application backend, managed cloud, or infrastructure you operate."
---
Every rendering path starts with the same HyperFrames project. The difference is
who operates Chrome and FFmpeg, how the request is submitted, and how much of the
pipeline your application needs to control.
| Need | Start with | You operate |
| --- | --- | --- |
| Render while creating or in CI | **CLI** | The machine running the command |
| Render from a Node application | **Producer** | The Node service and its runtime |
| Control exact frame capture | **Engine** | Capture, encoding, and orchestration |
| Submit a render without managing infrastructure | **HyperFrames Cloud** | Nothing beyond the request and result |
| Run distributed renders in your AWS account | **AWS Lambda** | The deployed AWS stack |
| Run distributed renders in your Google Cloud account | **Cloud Run** | The deployed GCP resources |
| Deploy a preview and render API from a template | **Hosted templates** | The selected hosting account |
## Local or CI: use the CLI
The CLI owns the complete normal pipeline: project loading, checks, browser
capture, audio mixing, and encoding.
```bash
npx hyperframes check
npx hyperframes render --output video.mp4
```
Start here unless an application—not a person or CI job—must initiate the
render. See [Rendering](/guides/rendering) for the normal workflow and the
[complete CLI reference](/packages/cli) for automation flags.
## A Node application: use Producer
`@hyperframes/producer` is the complete programmable render pipeline. It is the
right layer for a backend that needs to provide project input, receive progress,
cancel work, or control encoding without spawning the CLI.
```ts
import { createRenderJob, executeRenderJob } from "@hyperframes/producer";
const job = createRenderJob({ fps: 30, quality: "standard" });
await executeRenderJob(job, "./project", "./video.mp4");
```
Use [Producer](/packages/producer) for its current configuration and exported
API. Use Engine only when Producer performs work your application must replace.
## Exact frame capture: use Engine
`@hyperframes/engine` opens a seekable composition and captures exact frames.
It does not replace the complete Producer pipeline.
Use it when building specialized capture, inspection, or rendering
infrastructure. For an ordinary encoded video, stay with CLI or Producer. See
[Engine](/packages/engine).
## No infrastructure: use HyperFrames Cloud
Managed cloud rendering accepts a project, runs the render, and returns the
finished file without requiring local Chrome or FFmpeg.
```bash
npx hyperframes cloud render ./project --output video.mp4
```
Authentication, variables, webhooks, and job management are covered in
[Cloud rendering](/deploy/cloud).
## Infrastructure you control
Use [AWS Lambda](/deploy/aws-lambda) or [Google Cloud Run](/deploy/gcp-cloud-run)
when renders must run inside your own cloud account. Both paths distribute work
across workers and store intermediate and final media in the corresponding
cloud storage.
Use the [hosted templates](/guides/deploy) when the desired result is a small
preview application plus a render API on Vercel, Cloudflare, or Modal—not a
general distributed-rendering platform.
## The decision
Choose the highest-level surface that completes the job:
```text
CLI → Producer → Engine
```
Moving right gives an application more control and more pipeline responsibility.
Managed Cloud, AWS Lambda, Cloud Run, and hosted templates decide where that
pipeline runs.
## Related topics
- [Render with the CLI](/guides/rendering)
- [Render with HyperFrames Cloud](/deploy/cloud)
- [Use Producer from a Node application](/packages/producer)
docs/developers/cli.mdx
+62
View File
@@ -0,0 +1,62 @@
---
title: "CLI guide"
description: "Find the HyperFrames command for creating, checking, rendering, publishing, and automating projects."
---
Use this page to choose a command. The [CLI reference](/packages/cli) contains
detailed flags, examples, and environment settings. The installed version
remains authoritative: run `npx hyperframes <command> --help`.
## Everyday project loop
| Task | Command |
| --- | --- |
| Create a project | `npx hyperframes init my-video` |
| Open Studio | `npx hyperframes preview` |
| Check HTML structure | `npx hyperframes lint` |
| Run browser, layout, motion, and contrast checks | `npx hyperframes check` |
| Capture review frames | `npx hyperframes snapshot --at 0,2,5` |
| Render a video | `npx hyperframes render --output output.mp4` |
| Publish a browser link | `npx hyperframes publish` |
| Diagnose the machine | `npx hyperframes doctor` |
## Work with media
| Task | Command |
| --- | --- |
| Inspect project metadata | `npx hyperframes info` |
| Transcribe speech | `npx hyperframes transcribe <file>` |
| Generate narration | `npx hyperframes tts <script>` |
| Capture a website | `npx hyperframes capture <url>` |
## Reuse and inspect
| Task | Command |
| --- | --- |
| Add a Catalog item | `npx hyperframes add <name>` |
| List compositions | `npx hyperframes compositions` |
| Inspect keyframe behavior | `npx hyperframes keyframes` |
| Compare outputs | `npx hyperframes compare` |
## Rendering and automation
The CLI also supports:
- batch and variable-driven output;
- image sequences and several video formats;
- managed cloud rendering;
- AWS Lambda and Google Cloud Run workflows;
- machine-readable JSON output;
- publishing and shared spaces.
Start with the simple command, then open the [full reference](/packages/cli) for the exact options needed by automation or infrastructure.
<Tip>
Run `npx hyperframes <command> --help` for the installed version’s exact syntax.
</Tip>
## Related topics
- [Open the complete CLI reference](/packages/cli)
- [Choose a rendering path](/deploy/overview)
- [Diagnose a CLI or project problem](/guides/troubleshooting)
docs/developers/index.mdx
+93
View File
@@ -0,0 +1,93 @@
---
title: "Build on HyperFrames"
sidebarTitle: "Developers"
description: "Choose the smallest HyperFrames surface for automation, editing, playback, rendering, or generated compositions."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
<div className="hf-docs-video-frame">
<DocsVideo
title="A HyperFrames composition shown through the CLI, SDK, Player, and rendering infrastructure."
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-developers-v3.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-developers-v3.jpg"
/>
</div>
Use this path when you want to write a composition yourself, automate a project,
or add HyperFrames to another product. If you only want an agent to make a
video, start with the [first-video guide](/quickstart).
## Write and render a project yourself
Create a blank project and open it in Studio:
```bash
npx hyperframes init my-video --example blank
cd my-video
npx hyperframes preview
```
The project is ordinary HTML. The Reference Project used in the beginner path
starts with this real composition root:
```html
<div
id="root"
data-composition-id="main"
data-start="0"
data-duration="10"
data-width="1920"
data-height="1080"
>
<div class="clip" data-start="0" data-duration="10" data-track-index="1">
<!-- Ordinary HTML, CSS, images, and timed media. -->
</div>
</div>
```
The project template supplies the composition root, viewport, and duration.
HTML and CSS control what appears; `data-*` attributes control when it appears.
You can [inspect the complete project](https://github.com/heygen-com/hyperframes/tree/main/examples/docs-reference-project)
before choosing an integration surface.
When the project is ready:
```bash
npx hyperframes check
npx hyperframes render --output video.mp4
```
## Add HyperFrames to an application
Choose the smallest surface that completes the job:
<CardGroup cols={2}>
<Card title="CLI" icon="terminal" href="/developers/cli">
Run checks and renders from a script or CI job.
</Card>
<Card title="SDK quickstart" icon="code" href="/sdk/quickstart">
Inspect and change composition HTML from an application.
</Card>
<Card title="Player" icon="circle-play" href="/packages/player">
Embed a composition and control playback.
</Card>
<Card title="Rendering infrastructure" icon="cloud" href="/deploy/overview">
Render from a Node service, managed cloud, or infrastructure you operate.
</Card>
</CardGroup>
Start with the CLI for project-level automation. Add the SDK only when code
must inspect or edit the source, and add the Player only when a page needs live
playback. Producer and Engine are lower rendering layers, not required setup.
## Understand the architecture
The [developer overview](/developers/overview) explains how the composition,
CLI, SDK, Player, Producer, and Engine fit together. Use the
[HTML schema](/reference/html-schema) when generating source directly.
## Related topics
- [Understand the complete application architecture](/developers/overview)
- [Automate a project with the CLI](/developers/cli)
- [Edit composition HTML with the SDK](/sdk/quickstart)
docs/developers/overview.mdx
+135
View File
@@ -0,0 +1,135 @@
---
title: "How HyperFrames fits into an application"
sidebarTitle: "Developer overview"
description: "Understand the composition contract, editing surfaces, Player, CLI, and rendering layers before choosing an integration."
---
Building on HyperFrames means using an editable HTML composition as the shared source for automation, playback, editing, and rendering.
## Start with the composition contract
A composition is a finite HTML document with an explicit viewport, timed clips,
media, and zero or more seekable animation runtimes.
```html
<!doctype html>
<html lang="en">
<body>
<div
id="main"
data-composition-id="intro"
data-start="0"
data-duration="5"
data-width="1920"
data-height="1080"
data-no-timeline
>
<img
id="product"
class="clip"
data-start="0"
data-duration="5"
data-track-index="1"
src="./assets/product.png"
/>
</div>
</body>
</html>
```
The runtime reads the timing attributes and controls clip visibility and media
playback. When the composition uses an animation runtime, HyperFrames seeks its
registered timeline as well. The HTML remains inspectable and editable by
normal web tooling.
Use the [composition and schema reference](/reference/html-schema) when generating compositions or building a new authoring surface.
## Choose the smallest integration surface
| What the application must do | Start with | First useful result |
| ------------------------------------------------------- | --------------------------- | ------------------------------------------------ |
| Validate, preview, render, or automate projects | CLI | Check and render one known project |
| Query and change composition HTML | SDK | Find one element, change it, and save |
| Embed a seekable composition | Player | Play and seek one composition in a page |
| Build an editor | SDK + Player | Edit the source and reflect it in a live preview |
| Render from a Node service | Producer | Turn one composition into an encoded file |
| Control frame capture or build rendering infrastructure | Engine | Capture exact frames from a seekable page |
| Run managed or distributed renders | Cloud, Lambda, or Cloud Run | Submit one project and retrieve the result |
Do not start with the rendering engine when the CLI already performs the complete job. Do not add the SDK when the application only needs playback.
## CLI: operate complete projects
The CLI is the highest-level technical surface. It creates projects, opens Studio, validates compositions, captures review frames, renders files, publishes projects, and drives cloud render backends.
```bash
npx hyperframes check
npx hyperframes render --output video.mp4
```
Use the [CLI guide](/developers/cli) for the everyday commands and the [complete CLI reference](/packages/cli) for flags and automation.
## SDK: inspect and edit
`@hyperframes/sdk` opens composition HTML, gives elements stable `data-hf-id` identifiers, applies typed edit operations, emits JSON patches, supports undo and redo, and persists through adapters.
```ts
import { openComposition } from "@hyperframes/sdk";
const html = `<div class="clip" data-start="0" data-duration="5"
data-hf-id="hf-title">Old title</div>`;
const comp = await openComposition(html);
comp.setText("hf-title", "A new title");
const updatedHtml = comp.serialize();
```
Use it for agents, backend jobs, custom editors, versioned template systems, or any application that must change the source rather than merely play it.
Start with the [SDK quickstart](/sdk/quickstart).
## Player: embed and seek
`@hyperframes/player` is a web component that loads a composition in an isolated iframe and exposes video-like playback controls.
```html title="index.html"
<script
type="module"
src="https://cdn.jsdelivr.net/npm/@hyperframes/player"
></script>
<hyperframes-player
src="/compositions/intro.html"
controls
></hyperframes-player>
```
Use its JavaScript API to play, pause, seek, change playback rate, and listen for timeline events. It does not edit or render the composition.
See the [Player reference](/packages/player).
## Rendering: choose the layer you need
- **CLI** — complete local and automated rendering.
- **Producer** — the Node rendering pipeline: capture, encode, and audio mix.
- **Engine** — lower-level seekable page capture and exact-frame control.
- **Managed cloud** — hosted rendering without operating Chrome or FFmpeg.
- **AWS Lambda or Google Cloud Run** — infrastructure you deploy and control.
Most applications should begin with the CLI or Producer. Reach for Engine only when building a specialized capture or rendering system.
Use [rendering infrastructure](/deploy/overview) to compare hosted, local, and self-managed paths.
## The complete mental model
```text
composition → inspect or edit → play or render
```
Every surface works on the same source. Choose the smallest layer that produces the result your application needs, then move lower only when the higher-level layer removes control you genuinely require.
## Related topics
- [Run complete projects from the CLI](/developers/cli)
- [Edit composition HTML with the SDK](/sdk/quickstart)
- [Embed a composition with the Player](/packages/player)
docs/docs.json
+408 -121
View File
@@ -1,11 +1,11 @@
{
"$schema": "https://mintlify.com/docs.json",
"name": "HyperFrames",
"theme": "maple",
"theme": "aspen",
"colors": {
"primary": "#0a0a0a",
"light": "#f6f5f1",
"dark": "#0a0a0a"
"primary": "#16785B",
"light": "#3CE6AC",
"dark": "#16785B"
},
"background": {
"color": {
@@ -20,11 +20,12 @@
}
},
"appearance": {
"default": "light"
"default": "system"
},
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg"
"dark": "/logo/dark.svg",
"href": "https://hyperframes.heygen.com/introduction"
},
"favicon": "/favicon.svg",
"contextual": {
@@ -47,28 +48,39 @@
"navigation": {
"tabs": [
{
"tab": "Documentation",
"tab": "Guides",
"icon": "book-open",
"groups": [
{
"group": "Getting Started",
"group": "Start here",
"pages": [
"introduction",
"changelog",
"weekly-updates",
"quickstart",
"showcase",
"examples",
"launch-videos"
"go-further",
"developers/index"
]
},
{
"group": "Concepts",
"group": "Explore",
"pages": [
"concepts/compositions",
"concepts/data-attributes",
"concepts/variables",
"concepts/frame-adapters",
"concepts/determinism"
"examples",
"product-updates",
"weekly-updates",
"changelog"
]
},
{
"group": "30 Days of HyperFrames",
"pages": [
"thirty-days"
]
},
{
"group": "Choose where to create",
"pages": [
"guides/choose-creation-path",
"guides/mcp",
"guides/design-tools"
]
},
{
@@ -150,53 +162,97 @@
]
},
{
"group": "Guides",
"group": "Workflows",
"pages": [
"guides/pipeline",
"guides/skills",
"guides/authentication",
"guides/video-components",
"guides/color-grading",
"guides/media-effects",
"guides/media-overlays",
"guides/html-in-canvas",
"guides/website-to-video",
"guides/figma",
"guides/antigravity",
"guides/copilot-cli",
"guides/claude-design",
"guides/open-design",
"guides/hyperframes-vs-remotion",
"guides/gsap-animation",
"guides/keyframes",
"guides/rendering",
"guides/remove-background",
"guides/hdr",
"guides/4k-rendering",
"guides/performance",
"guides/timeline-editing",
"guides/video-editor-cheatsheet",
"guides/common-mistakes",
"guides/troubleshooting",
"guides/feedback"
"workflows",
"guides/product-launch-video",
"guides/faceless-explainer",
"guides/pr-to-video",
"guides/captions-and-recuts",
"guides/motion-graphics",
"guides/music-to-video",
"guides/slideshow",
"guides/general-video",
"guides/export-and-share"
]
},
{
"group": "Deploy",
"group": "Build the project",
"pages": [
"deploy/cloud",
"guides/deploy",
"deploy/aws-lambda",
"deploy/gcp-cloud-run",
"deploy/templates-on-lambda",
"deploy/migrating-to-hyperframes-lambda"
"concepts/index",
"guides/media",
"guides/video-components",
"guides/avatar-presenter",
"guides/voice-and-audio",
"guides/remove-background",
"guides/color-grading",
"guides/media-effects"
]
},
{
"group": "Help",
"pages": [
"help",
"guides/troubleshooting",
"guides/feedback"
]
}
]
},
{
"tab": "Studio",
"icon": "palette",
"groups": [
{
"group": "Start in Studio",
"pages": [
"studio/index",
"studio/storyboard"
]
},
{
"group": "Edit",
"pages": [
"studio/canvas",
"studio/timeline",
"studio/animation",
"studio/captions"
]
},
{
"group": "Build and reuse",
"pages": [
"studio/assets-and-blocks",
"studio/variables",
"studio/slideshows"
]
},
{
"group": "Finish and recover",
"pages": [
"studio/export",
"studio/troubleshooting"
]
},
{
"group": "Reference",
"pages": [
"studio/source",
"studio/shortcuts"
]
}
]
},
{
"tab": "Catalog",
"icon": "grid-2",
"groups": [
{
"group": "Overview",
"pages": [
"catalog/index"
]
},
{
"group": "Code Animations",
"pages": [
@@ -233,7 +289,7 @@
]
},
{
"group": "HTML-in-Canvas",
"group": "Interface & VFX",
"pages": [
"catalog/blocks/ios26-liquid-glass",
"catalog/blocks/liquid-glass-context-menu",
@@ -283,7 +339,7 @@
]
},
{
"group": "Shader Transitions",
"group": "Transitions",
"pages": [
"catalog/blocks/chromatic-radial-split",
"catalog/blocks/cinematic-zoom",
@@ -298,12 +354,7 @@
"catalog/blocks/sdf-iris",
"catalog/blocks/swirl-vortex",
"catalog/blocks/thermal-distortion",
"catalog/blocks/whip-pan"
]
},
{
"group": "CSS Transitions",
"pages": [
"catalog/blocks/whip-pan",
"catalog/blocks/beat-freeze-cut",
"catalog/blocks/hw-scribble-transition",
"catalog/blocks/mk-clone-wall-transition",
@@ -324,11 +375,8 @@
]
},
{
"group": "Showcases",
"group": "Code Themes",
"pages": [
"catalog/blocks/app-showcase",
"catalog/blocks/apple-money-count",
"catalog/blocks/blue-sweater-intro-video",
"catalog/blocks/code-snippet-apple-terminal-basic",
"catalog/blocks/code-snippet-apple-terminal-clear-dark",
"catalog/blocks/code-snippet-apple-terminal-clear-light",
@@ -352,7 +400,15 @@
"catalog/blocks/code-snippet-monokai",
"catalog/blocks/code-snippet-solarized-light",
"catalog/blocks/code-snippet-visual-studio-dark",
"catalog/blocks/code-snippet-visual-studio-light",
"catalog/blocks/code-snippet-visual-studio-light"
]
},
{
"group": "Complete Scenes",
"pages": [
"catalog/blocks/app-showcase",
"catalog/blocks/apple-money-count",
"catalog/blocks/blue-sweater-intro-video",
"catalog/blocks/north-korea-locked-down",
"catalog/blocks/nyc-paris-flight",
"catalog/blocks/ui-3d-reveal",
@@ -360,10 +416,16 @@
]
},
{
"group": "Data",
"group": "Data & Diagrams",
"pages": [
"catalog/blocks/data-chart",
"catalog/blocks/flowchart",
"catalog/blocks/flowchart-vertical",
"catalog/blocks/hw-pipeline",
"catalog/blocks/hw-text-cloud",
"catalog/blocks/mk-line-graph",
"catalog/blocks/mk-progress-stat",
"catalog/blocks/mk-specs-list",
"catalog/blocks/spain-map",
"catalog/blocks/us-map",
"catalog/blocks/us-map-bubble",
@@ -373,7 +435,7 @@
]
},
{
"group": "Effects",
"group": "Effects & Annotations",
"pages": [
"catalog/components/caption-blend-difference",
"catalog/components/grain-overlay",
@@ -399,21 +461,15 @@
]
},
{
"group": "Blocks",
"group": "Titles & Layouts",
"pages": [
"catalog/blocks/camcorder-hud",
"catalog/blocks/flowchart",
"catalog/blocks/flowchart-vertical",
"catalog/blocks/hw-frame",
"catalog/blocks/hw-path-text",
"catalog/blocks/hw-pipeline",
"catalog/blocks/hw-text-cloud",
"catalog/blocks/hw-title",
"catalog/blocks/logo-outro",
"catalog/blocks/mk-background",
"catalog/blocks/mk-placeholder-grid",
"catalog/blocks/mk-progress-stat",
"catalog/blocks/mk-specs-list",
"catalog/blocks/yt-lcd-background",
"catalog/blocks/yt-logo-intro",
"catalog/blocks/yt-prism-title",
@@ -423,41 +479,27 @@
]
},
{
"tab": "Packages",
"tab": "Developers",
"icon": "code",
"groups": [
{
"group": "Packages",
"group": "Start here",
"pages": [
"packages/core",
"packages/parsers",
"packages/lint",
"packages/studio-server",
"packages/sdk",
"packages/engine",
"packages/player",
"packages/producer",
"packages/shader-transitions",
"packages/aws-lambda",
"packages/gcp-cloud-run",
"packages/studio",
"packages/cli"
]
}
]
},
{
"tab": "SDK",
"groups": [
{
"group": "Overview",
"pages": [
"sdk/overview",
"sdk/quickstart"
"developers/overview"
]
},
{
"group": "Guides",
"group": "Command line",
"pages": [
"developers/cli",
"packages/cli",
"packages/lint"
]
},
{
"group": "SDK guides",
"pages": [
"sdk/quickstart",
"sdk/guides/querying-and-editing",
"sdk/guides/timing-and-animation",
"sdk/guides/undo-redo-and-patches",
@@ -468,7 +510,7 @@
]
},
{
"group": "Reference",
"group": "SDK reference",
"pages": [
"sdk/reference/open-composition",
"sdk/reference/composition",
@@ -477,20 +519,79 @@
"sdk/reference/adapters",
"sdk/reference/utilities"
]
}
]
},
{
"tab": "Reference",
"groups": [
},
{
"group": "Reference",
"group": "Composition, design & animation",
"pages": [
"reference/html-schema"
"concepts/compositions",
"concepts/variables",
"concepts/data-attributes",
"guides/gsap-animation",
"concepts/frame-adapters",
"concepts/determinism",
"guides/html-in-canvas",
"guides/hyperframes-vs-remotion",
"guides/figma"
]
},
{
"group": "Contributing",
"group": "Composition reference",
"pages": [
"reference/html-schema",
"reference/color-grading"
]
},
{
"group": "Rendering paths",
"pages": [
"guides/rendering",
"deploy/overview",
"deploy/cloud",
"guides/deploy"
]
},
{
"group": "Cloud infrastructure",
"pages": [
"deploy/aws-lambda",
"deploy/gcp-cloud-run",
"deploy/templates-on-lambda",
"deploy/migrating-to-hyperframes-lambda",
"packages/aws-lambda",
"packages/gcp-cloud-run"
]
},
{
"group": "Advanced rendering",
"pages": [
"guides/4k-rendering",
"guides/hdr",
"guides/performance"
]
},
{
"group": "Packages",
"pages": [
"packages/core",
"packages/parsers",
"packages/studio-server",
"packages/sdk",
"packages/engine",
"packages/player",
"packages/producer",
"packages/shader-transitions",
"packages/studio"
]
},
{
"group": "Agent setup",
"pages": [
"guides/authentication",
"guides/skills"
]
},
{
"group": "Contributing & community",
"pages": [
"contributing",
"contributing/catalog",
@@ -498,12 +599,6 @@
"contributing/changelog-process",
"contributing/testing-local-changes",
"contributing/canary-rollouts",
"contributing/studio-manual-dom-editing"
]
},
{
"group": "Community",
"pages": [
"community/adopters"
]
}
@@ -513,14 +608,206 @@
},
"footer": {
"socials": {
"github": "https://github.com/heygen-com/hyperframes"
"github": "https://github.com/heygen-com/hyperframes",
"x": "https://x.com/HeyGen",
"instagram": "https://www.instagram.com/heygen_official/"
},
"links": [
{
"header": "Explore",
"items": [
{
"label": "Introduction",
"href": "/introduction"
},
{
"label": "Make your first video",
"href": "/quickstart"
},
{
"label": "Examples",
"href": "/examples"
}
]
},
{
"header": "Build",
"items": [
{
"label": "Studio",
"href": "/studio"
},
{
"label": "Catalog",
"href": "/catalog"
},
{
"label": "Developers",
"href": "/developers/overview"
}
]
},
{
"header": "Resources",
"items": [
{
"label": "Product updates",
"href": "/product-updates"
},
{
"label": "Playground",
"href": "https://www.hyperframes.dev/"
},
{
"label": "GitHub",
"href": "https://github.com/heygen-com/hyperframes"
}
]
}
]
},
"navbar": {
"links": [
{
"type": "github",
"href": "https://github.com/heygen-com/hyperframes"
}
],
"primary": {
"type": "button",
"label": "Playground",
"href": "https://www.hyperframes.dev/"
}
},
"redirects": [
{
"source": "/guides",
"destination": "/introduction"
},
{
"source": "/showcase",
"destination": "/examples"
},
{
"source": "/launch-videos",
"destination": "/examples"
},
{
"source": "/guides/claude-design",
"destination": "/guides/design-tools"
},
{
"source": "/guides/open-design",
"destination": "/guides/design-tools"
},
{
"source": "/guides/common-mistakes",
"destination": "/guides/troubleshooting"
},
{
"source": "/guides/create-with-agent",
"destination": "/workflows"
},
{
"source": "/guides/choose-your-path",
"destination": "/workflows"
},
{
"source": "/guides/help",
"destination": "/help"
},
{
"source": "/guides/project-tour",
"destination": "/concepts"
},
{
"source": "/guides/media-overlays",
"destination": "/catalog"
},
{
"source": "/guides/common-questions",
"destination": "/help"
},
{
"source": "/contributing/studio-manual-dom-editing",
"destination": "/studio/canvas"
},
{
"source": "/guides/video-editor-cheatsheet",
"destination": "/studio/shortcuts"
},
{
"source": "/guides/timeline-editing",
"destination": "/studio/timeline"
},
{
"source": "/guides/website-to-video",
"destination": "/guides/product-launch-video"
},
{
"source": "/guides/prompting",
"destination": "/prompting/overview",
"permanent": true
},
{
"source": "/guides/pipeline",
"destination": "/workflows",
"permanent": true
},
{
"source": "/guides/quality-checklist",
"destination": "/guides/export-and-share",
"permanent": true
},
{
"source": "/guides/publish-and-share",
"destination": "/guides/export-and-share",
"permanent": true
},
{
"source": "/guides/antigravity",
"destination": "/guides/skills",
"permanent": true
},
{
"source": "/guides/copilot-cli",
"destination": "/guides/skills",
"permanent": true
},
{
"source": "/studio/tour",
"destination": "/studio",
"permanent": true
},
{
"source": "/studio/layers",
"destination": "/studio/canvas",
"permanent": true
},
{
"source": "/studio/design",
"destination": "/studio/canvas",
"permanent": true
},
{
"source": "/guides/keyframes",
"destination": "/studio/animation",
"permanent": true
},
{
"source": "/studio/lint-and-agent",
"destination": "/studio/source",
"permanent": true
},
{
"source": "/guides/transcribe-and-caption",
"destination": "/guides/voice-and-audio",
"permanent": true
},
{
"source": "/sdk/overview",
"destination": "/sdk/quickstart",
"permanent": true
}
]
}
docs/go-further.mdx
+40
View File
@@ -0,0 +1,40 @@
---
title: "Go further with HyperFrames"
sidebarTitle: "Go further"
description: "Take more control of an existing project through your agent, Studio, richer composition tools, and a reliable finish."
---
import { AdvancedPathGrid } from "/snippets/advanced-path-grid.jsx";
import { DocsVideo } from "/snippets/docs-video.jsx";
<div className="hf-docs-video-frame">
<DocsVideo
title="An existing HyperFrames project is revised with an agent, edited in Studio, enriched, checked, and rendered."
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-go-further-v3.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-go-further-v3.jpg"
/>
</div>
The project does not change format as you gain control. Your agent, Studio, the
SDK, the Player, and the renderer all work from the same HTML project.
The [Reference Project](https://github.com/heygen-com/hyperframes/tree/main/examples/docs-reference-project)
continues the first-video example. Its first version is a real page capture on a
10-second timeline. The revised version keeps that source and adds editable
variables, narration, fixed captions, music, and sound.
## Choose by the size of the change
Use the agent for changes to the story or several scenes. Use Studio for the
specific visual or timing detail you can point at.
<AdvancedPathGrid />
For reusable content and nested structure, continue with [Variables](/concepts/variables) and
[Compositions](/concepts/compositions).
## Related topics
- [Edit the project visually in Studio](/studio)
- [Understand how a HyperFrames project works](/concepts)
- [Build on HyperFrames as a developer](/developers)
docs/guides/antigravity.mdx
-150
View File
@@ -1,150 +0,0 @@
---
title: Google Antigravity
description: "Set up HyperFrames in Google Antigravity — install skills, author compositions, and render video from the agent-first IDE."
---
Google Antigravity is Google's agent-first IDE built on VS Code. Its agent discovers and loads HyperFrames skills automatically based on your prompts, so you get correct compositions without memorizing framework internals.
## Install skills
Install the HyperFrames skill package into your project:
```bash
npx skills add heygen-com/hyperframes
```
This places skill directories inside `.agents/skills/` at your workspace root — the location Antigravity scans for workspace-scoped skills.
<Tip>
If you want the skills available across all your Antigravity projects, install them to the global scope instead:
```bash
npx skills add heygen-com/hyperframes --agent antigravity --global
```
Global skills live in `~/.gemini/antigravity/skills/` and load in every workspace.
</Tip>
Verify the skills are installed:
```bash
ls .agents/skills/
```
You should see directories like `hyperframes/` (the entry skill), `hyperframes-core/`, `hyperframes-animation/`, `hyperframes-cli/`, and others — each containing a `SKILL.md` that the agent reads on demand.
## How skills work in Antigravity
Antigravity uses **semantic matching** — when you type a prompt, the agent compares it against the `description` field of every available skill and loads the ones that are relevant. You don't need to invoke skills with a slash command (though you can reference them by name for precision).
| You say | Agent loads |
|---|---|
| "Create a 10-second product intro with captions" | `hyperframes`, `hyperframes-core` |
| "Add a GSAP scale-pop to the title" | `hyperframes-animation` |
| "Use Tailwind for styling" | `hyperframes-core` |
| "Transcribe this audio and add captions" | `media-use` |
| "Add a shimmer sweep transition" | `hyperframes-registry` |
The skill is only injected into the agent's context window when it matches — this keeps the context clean and focused.
<Note>
For the best results, mention "HyperFrames" or "composition" in your prompt so the agent matches the right skills immediately instead of guessing at generic web-video conventions.
</Note>
## Create and preview a video
<Steps>
<Step title="Scaffold a project">
Open Antigravity's integrated terminal and run:
```bash
npx hyperframes init my-video
cd my-video
```
The wizard walks you through example selection and media import. Skills are installed automatically inside the new project.
</Step>
<Step title="Start the preview server">
```bash
npx hyperframes preview
```
This launches the HyperFrames Studio in your browser with hot reload — edits to `index.html` appear instantly.
</Step>
<Step title="Prompt the agent">
In Antigravity's agent sidebar, describe the video you want:
> Create a 15-second dark-themed product intro for my SaaS app with a fade-in title, hype-style captions, and a flash transition to the CTA.
The agent reads the HyperFrames skill, writes valid HTML with `data-*` attributes and GSAP timelines, and saves it to your project files. The preview updates automatically.
</Step>
<Step title="Iterate">
Talk to the agent like a video editor — don't re-prompt from scratch:
> Make the title 2x bigger and swap the transition to a whip pan.
> Add a lower third at 0:03 with my name.
> Replace the background with assets/hero.mp4.
</Step>
<Step title="Render">
```bash
npx hyperframes render --output output.mp4
```
</Step>
</Steps>
## Using multiple agents in Manager view
Antigravity's [Manager view](https://antigravity.google/docs/agent) lets you orchestrate multiple agents in parallel. For complex multi-scene videos, you can split the work:
- **Agent 1:** Author the intro scene and transitions
- **Agent 2:** Generate TTS narration and caption timing
- **Agent 3:** Build the data visualization scene
Each agent picks up the relevant HyperFrames skills independently. Merge the output into a single `index.html` with `data-composition-src` references when all agents finish.
## MCP alternative
If you prefer zero-install cloud authoring, Antigravity supports remote MCP servers. Add the HyperFrames MCP connector to author and render compositions without the CLI — see [Antigravity's MCP documentation](https://antigravity.google/docs/mcp) for the exact setup steps in your version, then use the server URL:
```
https://mcp.heygen.com/mcp/hyperframes
```
Authorize via OAuth with your HeyGen account when prompted. See the [HyperFrames MCP guide](/guides/mcp) for full details on tools and prompting. The MCP handles rendering in the cloud; the CLI gives you local control.
## Agent instruction files
HyperFrames projects created with `npx hyperframes init` scaffold both `CLAUDE.md` and `AGENTS.md` automatically — these give the agent additional composition context beyond what the skills provide.
- **`AGENTS.md`** — the cross-agent convention. Antigravity reads this regardless of which model you've selected (Gemini, Claude, or others).
- **`CLAUDE.md`** — read when Antigravity's agent uses a Claude model (Sonnet or Opus), providing Claude-specific project instructions.
## Tips
- **Mention the skill by name when precision matters.** "Using the hyperframes skill, add a grain overlay" is more reliable than "add a grain overlay" when the agent has many skills loaded.
- **Use `npx hyperframes lint` before rendering.** The linter catches structural issues (missing `class="clip"`, unregistered timelines, muted video violations) that the agent might miss on complex edits.
- **Install registry blocks for advanced effects.** Run `npx hyperframes add shimmer-sweep` to install pre-built blocks, then ask the agent to wire them into your composition.
- **Keep the preview server running.** Antigravity's file watcher + HyperFrames' hot reload means you see every agent edit in real time.
## Next steps
<CardGroup cols={2}>
<Card title="Prompting guide" icon="message" href="/prompting/overview">
Vocabulary and patterns that produce better compositions.
</Card>
<Card title="Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
50+ ready-to-use blocks the agent can install and wire.
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Motion principles and timeline authoring.
</Card>
<Card title="Pipeline guide" icon="list-check" href="/guides/pipeline">
The 7-step structure agents follow for multi-beat videos.
</Card>
</CardGroup>
docs/guides/avatar-presenter.mdx
+96
View File
@@ -0,0 +1,96 @@
---
title: "Add an avatar presenter"
sidebarTitle: "Avatar presenter"
description: "Create or reuse a presenter clip, keep it as project media, and combine it with editable HyperFrames scenes."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
Use an avatar when a person should speak on screen. Use HyperFrames for the
parts around that person: layouts, product scenes, captions, graphics, timing,
music, and the final composition.
<Frame caption="A presenter clip remains the source footage while HyperFrames adds the caption rail and emphasis layer around it.">
<DocsVideo
title="Presenter footage with a readable caption rail and an emphasis moment"
src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/captions-anchor-rail.mp4#t=0.1"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/avatar-presenter-caption-rail-v1.jpg"
/>
</Frame>
## Choose the right path
**The presenter is the whole video.** Use HeyGen Video Agent or an avatar-video
workflow. The result is a rendered HeyGen video, not an editable HyperFrames
composition.
**The presenter is one part of a designed video.** Generate the presenter clip,
keep it as a local project asset, then compose the rest in HyperFrames. This is
the path below.
**You already recorded a person.** Skip avatar generation. Bring the footage
into the project and choose [captions, designed overlays, or a real recut](/guides/captions-and-recuts).
## Ask for the complete result
Tell the agent what the presenter contributes and what remains editable:
```text
Using /hyperframes, make a 20-second product update.
Use a generated presenter only for the opening sentence.
Build the product scenes, captions, and ending in HyperFrames.
Keep the presenter clip as a local project asset.
```
The agent may ask you to sign in to HeyGen before it generates the clip. Check
the active account first:
```bash
npx hyperframes auth status
```
Run `npx hyperframes auth login` if no account is active. Avatar generation can
use the allowance or credits attached to that account; confirm the account and
usage before starting a long or repeated run.
## Build around the clip
Once the presenter video exists:
1. Keep the original file inside the project.
2. Place and trim it like any other video clip.
3. Transcribe the real speech before styling captions.
4. Add product scenes or graphics only where they support what is being said.
5. Render and watch the complete file with sound.
Use **Assets → Import media** in Studio, or ask the agent to add the generated
file. If the presenter must sit over a designed background, create a transparent
version locally:
```bash
npx hyperframes remove-background assets/presenter.mp4 \
-o assets/presenter-transparent.webm
```
Background removal is optional. Keep the original background when it already
belongs in the shot or when difficult hair, hands, or motion produce a weak
matte.
## Check the result
- The presenter says the approved words with the intended voice.
- Captions match the actual audio, including names and numbers.
- The person does not cover the product or another important visual.
- Music stays below speech.
- Generated and source media are stored locally rather than fetched during render.
- The final file has been watched once from beginning to end.
For manual avatar, voice, and image-to-video controls, use the current
[HeyGen CLI guide](https://developers.heygen.com/cli) and
[Create Video reference](https://developers.heygen.com/reference/create-video).
## Related topics
- [Work with captions and talking-head footage](/guides/captions-and-recuts)
- [Work with all project media](/guides/media)
- [Remove the presenter's background](/guides/remove-background)
docs/guides/captions-and-recuts.mdx
+70
View File
@@ -0,0 +1,70 @@
---
title: "Add captions or repackage talking-head footage"
sidebarTitle: "Captions and talking head"
description: "Add captions, add designed overlays, or change the spoken edit."
---
<Frame caption="One source clip, three caption treatments. The spoken edit stays untouched.">
<video
autoPlay
loop
muted
playsInline
preload="metadata"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-captions.jpg"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-captions.mp4"
/>
</Frame>
## Make the request
Name the file and the change you want:
```text
Using /hyperframes, add clear animated captions to assets/interview.mp4.
Keep the footage and its spoken edit unchanged.
```
Ask for designed information cards instead when the footage needs titles,
quotes, statistics, lower thirds, or picture-in-picture.
## What should change?
- **Add captions** — keep the original clip and audio unchanged; add readable, timed words over it.
- **Add designed overlays** — keep the clip underneath and add titles, quotes, statistics, lower thirds, or picture-in-picture.
- **Change the footage** — use General Video when pauses, selected moments, or the spoken order must change.
Captions and designed overlays work best on a clear, single-subject clip with audible speech. Both keep the original footage and audio intact.
If you need to remove pauses, choose different moments, or reorder the speech, use [General Video](/guides/general-video).
## Before it builds
Confirm:
- **Captions:** the intended format and any names or terms the transcript may miss. HyperFrames can recommend a visual treatment after it sees the clip.
- **Designed overlays:** the format, layout, visual style, and how often a title, quote, statistic, or side panel should appear.
- **Either path:** where the speaker, existing text, and important action leave safe room for graphics.
## Review what matters
- Names, product terms, and numbers are correct.
- Captions follow the spoken words.
- Graphics avoid faces and important parts of the footage.
- The video works with sound and muted.
- The final caption or graphic clears before the video ends.
For direct placement changes, use [Captions in Studio](/studio/captions) to
inspect synchronization and save position, scale, or rotation corrections. Ask
the agent or edit the caption source for corrected words and durable timing or
style changes.
<Card title="Finish and share" icon="circle-check" href="/guides/export-and-share">
Review the chosen caption, overlay, or recut path, then render and watch the final file.
</Card>
## Related topics
- [Edit captions in Studio](/studio/captions)
- [Work with voice, music, sound, and captions](/guides/voice-and-audio)
- [Change the spoken edit with a custom video workflow](/guides/general-video)
docs/guides/choose-creation-path.mdx
+70
View File
@@ -0,0 +1,70 @@
---
title: "Choose how to create"
sidebarTitle: "Choose how to create"
description: "Choose between a local HyperFrames project, hosted chat, a design-first handoff, or a HeyGen-generated video."
---
## I want an editable project on my computer
Use a coding agent with the HyperFrames skills. The agent writes an ordinary
HTML project that you can revise with the agent, open in Studio, inspect in
source, render locally, or automate later.
This is the default path for a video that will keep changing.
```text
Using /hyperframes, make a 10-second product intro for https://example.com.
```
<Card title="Make your first local video" icon="play" href="/quickstart" horizontal arrow>
Install the skills and create the first editable version.
</Card>
## I want to create inside an AI chat
Use the hosted HyperFrames MCP connector. It creates and renders through your
HeyGen account without a local HyperFrames setup.
Choose this when convenience matters more than owning the complete project
folder. Rendering and account access are hosted; local Studio, source editing,
self-hosting, and precise debugging belong to the local path.
[Connect HyperFrames to an AI chat →](/guides/mcp)
## I want to establish the visual direction first
Start in Figma, Claude Design, or Open Design when brand, layout, and scene
direction are the unresolved part. Then hand the project to a coding agent for
motion refinement, media, validation, and rendering.
The design tool supplies a first draft, not a substitute for watching and
checking the finished movement.
[Bring a design into a project →](/guides/design-tools)
## I want to create inside HeyGen
Use HeyGen Video Agent when you want a hosted prompt-native workflow that
assembles the script, visuals, narration, avatar, and motion for you. HyperFrames
can power its HTML motion graphics, but the delivery surface is different: the
local path gives you the project folder, source, Studio, and CLI; Video Agent
keeps generation and revision inside HeyGen.
[Learn how HeyGen Video Agent works →](https://help.heygen.com/en/articles/12402907-how-to-get-started-with-video-agent)
If a generated person is only one layer in a locally editable film, [add the
presenter as media inside a HyperFrames project](/guides/avatar-presenter).
HeyGen generation can use an account allowance or credits; local HyperFrames
rendering does not.
## If you are unsure
Start with the local path. It preserves the most options because the project
stays editable. Use the [developer journey](/developers) instead when your goal
is an application or automated pipeline rather than one video.
## Related topics
- [Make a first local video](/quickstart)
- [Create through a hosted AI chat](/guides/mcp)
- [Bring a design into a HyperFrames project](/guides/design-tools)
docs/guides/claude-design.mdx
-152
View File
@@ -1,152 +0,0 @@
---
title: Claude Design
description: "Create HyperFrames video drafts in Claude Design, then refine in any AI coding agent."
---
Claude Design produces a **valid first draft** of a HyperFrames video — brand identity, scene content, layout, animations, and transitions. You then download the ZIP and refine in any AI coding agent (Claude Code, Cursor, Codex, Windsurf, etc.) with linting and live preview.
<Note>
**Sending your design to HeyGen as a URL ("Send to HyperFrames"), rather than downloading a ZIP?** Use the [Send to HyperFrames guide](https://raw.githubusercontent.com/heygen-com/hyperframes/main/docs/guides/claude-design-send-to-hyperframes.md) instead. That flow has different authoring rules; this page covers the Download-ZIP flow.
</Note>
## Get started
<Steps>
<Step title="Download the instruction file">
Open [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub and click the download button (↓) to save it.
</Step>
<Step title="Open Claude Design">
Start a new chat at [claude.ai/design](https://claude.ai/design).
</Step>
<Step title="Attach the file + describe your video">
Drag the `claude-design-hyperframes.md` file into the chat. Describe what you want — include screenshots, brand assets, or a palette if you have them.
</Step>
<Step title="Download the ZIP">
Claude Design produces `index.html`, `preview.html`, `README.md`, and `DESIGN.md`. Download the ZIP.
</Step>
<Step title="Refine in any AI coding agent">
Open the project in Claude Code, Cursor, Codex, or any agent with terminal access for animation polish, timing, and production QA.
```bash
npx skills add heygen-com/hyperframes # install skills (one-time)
npx hyperframes lint # should pass with zero errors
npx hyperframes preview # open the studio
```
</Step>
</Steps>
<Tip>
**Attach the file, don't paste the URL.** Claude Design reads file attachments natively with detail preserved. URL-driven runs produce usable output but consistently miss more rules.
</Tip>
## Which setup to use
| Surface | Recommended setup |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Claude Design | Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub and attach to your chat |
| Claude Code | `npx skills add heygen-com/hyperframes`, then use `/hyperframes` |
| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes` |
## How it works
The instruction file gives Claude Design **pre-valid HTML skeletons** — the structural rules (data attributes, timeline registration, scene visibility, preview token forwarding) are already embedded. Claude Design fills in the creative work:
1. **Palette + typography** — CSS custom properties on `:root`
2. **Scene content** — text, images, layout inside `.scene-content` wrappers
3. **Animations** — GSAP entrance tweens and mid-scene activity
4. **Transitions** — hard cuts for most scenes, shader transitions at 2-3 key moments
This template-first approach means the output passes `npx hyperframes lint` with zero errors on first download — your coding agent can start refining immediately without structural fixes.
## Example prompts
<CardGroup cols={1}>
<Card title="Feature announcement">
```text
Use the attached file. I just shipped dark mode for my app. Make me a
15-second Instagram reel announcing it.
- App name: Taskflow
- Primary color: #6C5CE7
- The vibe is clean, minimal, dark
- Key stat: "47% of users requested this"
```
</Card>
<Card title="Founder pitch">
```text
Use the attached file. 25-second LinkedIn video for my startup.
Problem: Sales teams waste 3 hours/day on manual CRM updates.
Solution: AutoCRM — AI that logs every call, email, and meeting.
Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
CTA: autocrmhq.com
Professional but not corporate. Think Linear or Vercel energy.
```
</Card>
<Card title="Stat highlight">
```text
Use the attached file. 10-second reel. Just one big number:
"$4.2 billion processed in Q1 2026"
Dark background, the number should animate up from zero. Subtle,
confident. End with logo placeholder and "stripe.com"
```
</Card>
<Card title="Sparse brief (let it ask)">
```text
Use the attached file. Make a 30-second launch video for Orbit.
```
The instructions tell Claude Design to ask ONE short clarifying question before generating.
</Card>
</CardGroup>
## What to include in your prompt
Claude Design reads inputs in this order of reliability: **attachments > pasted content > web research > URLs**.
| Input type | What it gives Claude Design |
| --- | --- |
| Screenshots / PDFs / brand guides | Palette, typography, UI patterns, tone — strongest source |
| Pasted hex codes, typefaces, copy | Authoritative for what it covers |
| Brand name (well-known) | Claude Design can research blogs, press, Wikipedia |
| SPA URL (React/Vue homepage) | Returns near-empty shell — pivot to blog/press instead |
The more specific your prompt, the better the output. Include palette, fonts, duration, and scene ideas when you have them.
## Known limitations
- **In-pane preview** — scrubbing is unreliable in Claude Design's iframe sandbox. Download and use `npx hyperframes preview` locally for reliable playback.
- **No linting** — Claude Design can't run `npx hyperframes lint`. The template-first skeletons handle structural validity, but the self-review checklist is the only QA before download.
- **Shaders work at any aspect ratio** — vertical (1080x1920), landscape (1920x1080), and square (1080x1080) all supported.
- **3 fetch limit** — Claude Design limits web fetches per turn. All critical rules are inlined; external references are for edge cases only.
- **Seeking backwards** — scrubbing backwards in the in-pane preview can show blank frames. Forward seeking usually works.
## The handoff to your coding agent
Claude Design's output is a valid first draft. Open it in Claude Code, Cursor, Codex, or any AI coding agent with terminal access:
```bash
npx skills add heygen-com/hyperframes # one-time setup
npx hyperframes lint # verify structure
npx hyperframes preview # open the studio
```
Then iterate:
- "Make scene 3's entrance snappier"
- "Add a counter animation to the stat in scene 5"
- "Tighten the pacing — scenes 4 and 6 feel too long"
- "Change the shader on transition 2 to glitch"
## Next steps
<CardGroup cols={2}>
<Card title="Prompt Guide" icon="message" href="/prompting/overview">
More prompt patterns for HyperFrames across Claude Code, Claude Design, and other agents.
</Card>
<Card title="@hyperframes/player" icon="play" href="/packages/player">
Embed compositions with the official player component.
</Card>
</CardGroup>
docs/guides/common-mistakes.mdx
-289
View File
@@ -1,289 +0,0 @@
---
title: Common Mistakes
description: "Pitfalls that break Hyperframes compositions."
---
These are mistakes that cannot be caught by the linter. For automated checks, run `npx hyperframes lint` (see [CLI](/packages/cli#lint)).
<Warning>
The first two mistakes — animating video element dimensions and controlling media playback in scripts — are the most common causes of broken compositions. If your video looks wrong, check these first.
</Warning>
<AccordionGroup>
<Accordion title="Animating video element dimensions">
**Symptom:** Video frames stop updating, or browser performance drops severely.
**Cause:** GSAP animating `width`, `height`, `top`, `left` directly on a `<video>` element can cause the browser to stop rendering frames.
**Before (broken):**
```javascript index.html
// Animating the video element directly — causes frame rendering to stop
tl.to("#el-video", { width: 500, height: 280, top: 700, left: 1400 }, 26);
```
**After (fixed):**
```html index.html
<!-- Wrap the video in a div and animate the wrapper -->
<div id="pip-wrapper" style="position: absolute; width: 1920px; height: 1080px;">
<video id="el-video" data-start="0" data-track-index="0"
src="./assets/video.mp4" style="width: 100%; height: 100%;"></video>
</div>
```
```javascript index.html
// Animate the wrapper — the video fills it at 100%
tl.to("#pip-wrapper", { width: 500, height: 280, top: 700, left: 1400 }, 26);
```
Use a non-timed wrapper `<div>` for visual effects like picture-in-picture. Animate the wrapper; let the video fill it via CSS.
</Accordion>
<Accordion title="Controlling media playback in scripts">
**Symptom:** Audio/video playback is out of sync, or plays when it should not.
**Cause:** Calling `video.play()`, `video.pause()`, or setting `audio.currentTime` in your scripts. The [framework owns all media playback](/reference/html-schema#framework-managed-behavior).
**Before (broken):**
```javascript index.html
// Conflicts with framework media sync
document.getElementById("el-video").play();
document.getElementById("el-audio").currentTime = 5;
```
**After (fixed):**
```javascript index.html
// Don't control media playback at all. The framework handles it.
// Use GSAP for visual animations only:
tl.to("#el-video", { opacity: 1, duration: 0.5 }, 0);
```
The framework reads [`data-start`](/concepts/data-attributes#timing-attributes), [`data-media-start`](/concepts/data-attributes#media-attributes), and [`data-volume`](/concepts/data-attributes#media-attributes) to control when and how media plays. See [Compositions: Two Layers](/concepts/compositions#two-layers-primitives-and-scripts) for the separation between HTML primitives and scripts.
</Accordion>
<Accordion title="Composition duration shorter than video">
**Symptom:** Video plays for a few seconds then stops. Timeline shows 8-10 seconds even though the video is minutes long.
**Cause:** The composition duration equals the [GSAP timeline duration](/guides/gsap-animation#timeline-duration-and-composition-duration), not `data-duration` on the video. If your last GSAP animation ends at 8 seconds, the composition is 8 seconds long — regardless of how long the video source is.
**Before (broken):**
```javascript index.html
// Timeline is only 7.8s long — video cuts off after 7.8 seconds
tl.to("#lower-third", { left: -640, duration: 0.6 }, 7.2);
```
**After (fixed):**
```javascript index.html
tl.to("#lower-third", { left: -640, duration: 0.6 }, 7.2);
// Extend the timeline to 283 seconds to match the video length
tl.set({}, {}, 283);
```
`tl.set({}, {}, TIME)` adds a zero-duration tween at the specified time, extending the timeline without affecting any elements.
<Tip>
A quick check: run `npx hyperframes compositions` to see the resolved duration of each composition. If it is shorter than expected, your timeline needs extending.
</Tip>
</Accordion>
<Accordion title="Setting the root render length from a script or --variables does nothing">
**Symptom:** You set the **root** composition's `data-duration` from a script (or expose it as a variable and pass `--variables`), but the render length never changes. It stays locked at whatever `data-duration` is written in the source HTML.
**Cause:** The root composition's `data-duration` (the total render length / frame count) is read **once at compile time**, before your scripts run, exactly like `data-width` / `data-height`. A static root `data-duration` is locked at that point, so a later `root.setAttribute("data-duration", ...)` or a `--variables`-driven value is ignored. This is unlike a **clip's** `data-duration`, which the renderer re-reads from the live DOM after scripts run.
**Before (broken):**
```html index.html
<div id="root" data-composition-id="main" data-duration="2" data-width="1920" data-height="1080">
...
</div>
<script>
// Ignored: the root render length was already fixed at 2s at compile time.
document.getElementById("root").setAttribute("data-duration", "5");
</script>
```
**After (fixed):** author the root `data-duration` directly, one value per output. To produce a different length, author (or generate) a variant with that root `data-duration`. See [What can't be a variable](/concepts/variables#what-cant-be-a-variable).
<Tip>
Only the root composition's *total length* is compile-time-fixed. A clip's own `data-duration` (and a `<video>`/`<audio>` trim length) is re-read from the live DOM, so scripts and variables can still drive those, see [Swapping media: do you need to vary duration too?](/concepts/variables#swapping-media-do-you-need-to-vary-duration-too).
</Tip>
</Accordion>
<Accordion title="Missing class='clip' on timed elements">
**Symptom:** Elements are always visible, ignoring their `data-start` and `data-duration` timing.
**Cause:** The [`class="clip"`](/concepts/data-attributes#element-visibility) attribute tells the runtime to manage the element's visibility lifecycle. Without it, the element is always rendered.
**Before (broken):**
```html index.html
<!-- Missing class="clip" — this element is always visible -->
<h1 id="title" data-start="2" data-duration="5" data-track-index="0">
Hello World
</h1>
```
**After (fixed):**
```html index.html
<!-- With class="clip", the runtime shows this only from 2s to 7s -->
<h1 id="title" class="clip" data-start="2" data-duration="5" data-track-index="0">
Hello World
</h1>
```
<Note>
The linter catches this one: `npx hyperframes lint` will flag timed elements missing `class="clip"`.
</Note>
</Accordion>
<Accordion title="Oversized source images">
**Symptom:** Preview stutters during scenes with images on screen. Render is slower than expected.
**Cause:** Source images at much higher resolution than the canvas. Chrome decodes images to raw RGBA bitmaps before displaying them, and bitmap size is `width × height × 4` bytes — independent of file size on disk. A 7000×5000 JPEG is 140MB decoded, even if the file is only 2MB.
Displaying such an image in a 384×1080 region wastes memory and forces the compositor to resample a huge texture every frame.
**Before (bloated):**
```html index.html
<!-- 7000x5000 source, ~140MB decoded -->
<img class="clip" data-start="0" data-duration="3"
src="./assets/hero-scene.jpg" />
```
**After (sized to the canvas):**
```bash Terminal
# Resize a batch of images to fit within 3840x3840, preserving aspect ratio
mkdir -p assets/resized
mogrify -path assets/resized -resize 3840x3840\> assets/*.jpg
```
```html index.html
<!-- ~3840x2560 source, ~40MB decoded -->
<img class="clip" data-start="0" data-duration="3"
src="./assets/resized/hero-scene.jpg" />
```
**Rule of thumb:** source images at most 2x the canvas dimensions. For a 1920×1080 composition, 3840×2160 is already plenty. See [Performance: Image sizing](/guides/performance#image-sizing).
</Accordion>
<Accordion title="Heavy backdrop-filter stacks">
**Symptom:** Specific scenes drop to 5-10fps in preview. The composition is fine elsewhere.
**Cause:** `backdrop-filter: blur()` on large elements, especially stacked at high radii. Each blur layer forces the compositor to sample pixels behind the element, run a blur kernel, and composite the result. Stacked layers multiply the cost.
**Before (expensive):**
```css
/* 8 layers per side = 16 blur passes every frame */
.pb-1 { backdrop-filter: blur(1px); }
.pb-2 { backdrop-filter: blur(2px); }
.pb-3 { backdrop-filter: blur(4px); }
.pb-4 { backdrop-filter: blur(8px); }
.pb-5 { backdrop-filter: blur(16px); }
.pb-6 { backdrop-filter: blur(32px); }
.pb-7 { backdrop-filter: blur(64px); }
.pb-8 { backdrop-filter: blur(128px); }
```
**After (3 tuned layers):**
```css
/* Fewer passes with hand-picked radii — visually similar, much cheaper */
.pb-1 { backdrop-filter: blur(4px); }
.pb-2 { backdrop-filter: blur(16px); }
.pb-3 { backdrop-filter: blur(48px); }
```
**Guidelines:**
- Keep stacked `backdrop-filter` layers to 2-3 per region
- Avoid radii above 64px over large areas — the biggest radii dominate the total cost
- For a static blur effect, pre-render it into a PNG once and overlay with a regular `<img>`
See [Performance: backdrop-filter: blur()](/guides/performance#backdrop-filter-blur) for the full breakdown.
</Accordion>
<Accordion title="Expected HDR output but got SDR">
**Symptom:** Expected an HDR render, but the output looks the same as SDR or `ffprobe` reports `color_transfer=bt709`.
**Cause:** By default, Hyperframes only switches to HDR encoding when a source `<video>` or `<img>` is tagged with BT.2020 / PQ / HLG color metadata. Common reasons HDR is not engaged:
1. **All sources are SDR.** Auto-detect leaves SDR-only compositions in SDR. Verify with `ffprobe`:
```bash Terminal
ffprobe -v error -show_streams source.mp4 | grep color_transfer
# Want: smpte2084 (PQ) or arib-std-b67 (HLG)
# SDR: bt709, smpte170m, bt470bg, etc.
```
2. **Wrong output format.** HDR output requires MP4. `--format mov` and `--format webm` fall back to SDR — Hyperframes logs a warning when this happens.
3. **SDR was forced.** `--sdr` disables HDR even when HDR sources are present.
If you need HDR regardless of source metadata, use `--hdr` to force it.
`--docker` works the same as local rendering — auto-detect, `--hdr`, and `--sdr` are all forwarded into the container and produce the same output decisions (slower, since the container falls back to software WebGL for SDR DOM capture).
See [HDR Rendering](/guides/hdr) for the full source requirements and verification steps.
</Accordion>
<Accordion title="Timeline key doesn't match data-composition-id">
**Symptom:** Animations don't play. The composition appears static.
**Cause:** The key used in `window.__timelines` must exactly match the [`data-composition-id`](/concepts/data-attributes#composition-attributes) attribute on the composition root element.
**Before (broken):**
```javascript index.html
// Mismatch: HTML says "my-video", script registers "root"
// <div data-composition-id="my-video" ...>
window.__timelines["root"] = tl;
```
**After (fixed):**
```javascript index.html
// Key matches the data-composition-id attribute
// <div data-composition-id="my-video" ...>
window.__timelines["my-video"] = tl;
```
</Accordion>
</AccordionGroup>
## Debugging Checklist
When something does not work, check in this order:
1. **Run the linter:** `npx hyperframes lint` — catches most structural issues
2. **Timeline registered?** Is `window.__timelines["<id>"]` set? Does the key match [`data-composition-id`](/concepts/data-attributes#composition-attributes)?
3. **GSAP-only animations?** Only animate visual properties (opacity, transform, color) — see [GSAP Animation](/guides/gsap-animation#key-rules)
4. **Timeline long enough?** Add `tl.set({}, {}, DURATION)` at the end — see [Timeline Duration](/guides/gsap-animation#timeline-duration-and-composition-duration)
5. **Console errors?** Open browser console — runtime errors show as `[Browser:ERROR]`
6. **Still stuck?** See [Troubleshooting](/guides/troubleshooting) for environment and rendering issues
## Next Steps
<CardGroup cols={2}>
<Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
Fix environment and rendering issues
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Review animation rules and patterns
</Card>
<Card title="HTML Schema Reference" icon="code" href="/reference/html-schema">
Full attribute reference and checklist
</Card>
<Card title="Data Attributes" icon="database" href="/concepts/data-attributes">
Timing, media, and composition attributes
</Card>
</CardGroup>
docs/guides/copilot-cli.mdx
-190
View File
@@ -1,190 +0,0 @@
---
title: GitHub Copilot CLI
description: "Set up HyperFrames with GitHub Copilot CLI — install skills, invoke them with slash commands, and render video from the terminal."
---
GitHub Copilot CLI brings AI-powered coding assistance to your terminal. HyperFrames skills teach it how to write correct compositions, GSAP timelines, and framework-specific patterns — so you get valid video HTML without reading the docs yourself.
## Prerequisites
- **GitHub Copilot subscription** — Free, Pro, Pro+, Business, or Enterprise all include CLI access
- **Copilot CLI installed** — `npm install -g @github/copilot` (or via the [install script](https://github.com/github/copilot-cli))
- **Node.js 22+** and **FFmpeg** for the HyperFrames CLI
## Install skills
Install the HyperFrames skill package into your project:
```bash
npx skills add heygen-com/hyperframes
```
This writes skill directories to `.agents/skills/` in your project — the path Copilot CLI scans automatically for workspace-scoped skills.
<Tip>
To make skills available across all your projects, install them globally:
```bash
npx skills add heygen-com/hyperframes --agent github-copilot --global
```
Global skills live in `~/.copilot/skills/` and load in every Copilot CLI session.
</Tip>
If you install skills during an active session, run `/skills` to open the skills picker and verify they appear. New skills installed to the project directory are picked up automatically on the next prompt.
## Using skills
Copilot CLI supports both **explicit invocation** via slash commands and **automatic detection** based on your prompt.
### Slash commands
Prefix a skill name with `/` to load it explicitly:
```
/hyperframes Create a 10-second product intro with a fade-in title and dark background.
```
```
/hyperframes-animation Add a scale-pop animation to the title element.
```
```
/hyperframes-cli How do I render at 60fps with Docker?
```
### Auto-detection
Copilot also matches skills based on the `description` field in each `SKILL.md`. If your prompt mentions compositions, timelines, or video rendering, the agent loads the right skills without you specifying them:
```
Create a 9:16 TikTok hook video about AI productivity with bouncy captions.
```
Explicit invocation is more reliable when you have many skills installed — with large skill sets, the agent's token budget may not fit every skill description, so naming the skill directly guarantees it loads.
### Skill management
| Command | What it does |
|---|---|
| `/skills` | Open the interactive skills picker — browse, enable, or disable skills |
| `/skills add <path>` | Add an additional skill directory to the current session |
## Create and preview a video
<Steps>
<Step title="Scaffold a project">
```bash
npx hyperframes init my-video
cd my-video
```
Skills are installed automatically inside the new project.
</Step>
<Step title="Start the preview server">
```bash
npx hyperframes preview
```
Opens the HyperFrames Studio in your browser. Edits reload automatically.
</Step>
<Step title="Start Copilot CLI in the project directory">
In a second terminal:
```bash
copilot
```
</Step>
<Step title="Prompt with the skill">
```
/hyperframes Create a 15-second dark-themed product intro with hype-style
captions and a flash transition to the CTA.
```
The agent writes valid HyperFrames HTML — `data-*` attributes, `class="clip"` on timed elements, paused GSAP timelines registered on `window.__timelines`. The preview updates as files are saved.
</Step>
<Step title="Iterate">
Keep prompting without re-specifying the full context:
```
Make the title 2x bigger and add a lower third at 0:03.
```
```
Swap the transition to a whip pan.
```
</Step>
<Step title="Render">
```bash
npx hyperframes render --output output.mp4
```
Or ask the agent:
```
/hyperframes-cli Render this composition to output.mp4 at high quality.
```
</Step>
</Steps>
## Agent mode
Copilot CLI's agent mode can handle multi-step tasks autonomously — scaffolding a project, writing the composition, installing registry blocks, and rendering in sequence:
```
/hyperframes Scaffold a new project called "launch-video", create a 30-second
product launch video with 5 scenes, install the flash-through-white transition
block, and render to mp4.
```
In agent mode, Copilot runs terminal commands (like `npx hyperframes init` and `npx hyperframes render`) on your behalf. Review the commands before approving them — especially if the skill pre-approves `shell` in its `allowed-tools`.
<Warning>
Only pre-approve `shell` or `bash` in skill `allowed-tools` for skills you trust. The HyperFrames skills do not pre-approve shell access — the agent will ask for confirmation before running terminal commands.
</Warning>
## MCP alternative
Copilot CLI also supports MCP servers for cloud-based authoring without the local CLI. Use the `--additional-mcp-config` flag to add the HyperFrames MCP server to your session:
```bash
copilot --additional-mcp-config '{"mcpServers":{"hyperframes":{"url":"https://mcp.heygen.com/mcp/hyperframes"}}}'
```
Or save the config to a file and reference it:
```bash
copilot --additional-mcp-config @mcp-config.json
```
Authorize via OAuth when prompted. See the [MCP guide](/guides/mcp) for full details.
## Tips
- **Always start with `/hyperframes`.** It's the entry skill — it orients you to the whole surface and routes your request to the right workflow, pulling in the domain skills (`/hyperframes-core` for composition rules and data attributes, `/hyperframes-animation` for GSAP and other runtime patterns) that generic web knowledge doesn't cover.
- **Use `/skills` to check skill status.** If output looks wrong, open the skills picker to verify the HyperFrames skills are enabled.
- **Run `npx hyperframes lint` before rendering.** The linter catches structural issues the agent might miss on complex multi-scene edits.
- **Keep the preview server running in a separate terminal.** You see every edit reflected in real time while prompting in Copilot CLI.
- **Install registry blocks for transitions and effects.** `npx hyperframes add shimmer-sweep` installs pre-built blocks, then prompt the agent to wire them in.
## Next steps
<CardGroup cols={2}>
<Card title="Prompting guide" icon="message" href="/prompting/overview">
Vocabulary and patterns that produce better compositions.
</Card>
<Card title="Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
50+ ready-to-use blocks the agent can install and wire.
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Motion principles and timeline authoring.
</Card>
<Card title="Pipeline guide" icon="list-check" href="/guides/pipeline">
The 7-step structure agents follow for multi-beat videos.
</Card>
</CardGroup>
docs/guides/design-tools.mdx
+81
View File
@@ -0,0 +1,81 @@
---
title: "Bring a design into a project"
sidebarTitle: "Bring in a design"
description: "Start from Figma, a design-tool draft, or an existing brand system without turning the video into a stack of screenshots."
---
Use an existing design as source material: preserve its visual language, then
rebuild what must move as editable HyperFrames scenes.
## Choose what should remain editable
| Source | Keep as media | Rebuild in HTML |
| --- | --- | --- |
| Logo, icon, illustration, or textured artwork | Usually | Only when individual parts must animate |
| Product screenshot | When a still proves the point | When the scene needs a real interaction or responsive crop |
| Figma component | When exact pixels matter more than editing | When text, color, layout, or states must change |
| Storyboard frames | Use as visual references | Reconstruct the intended motion between states |
| Brand colors and type | Import the files and values | Apply them across the composition |
Do not animate a stack of complete screenshots merely because they came from a
design tool. Use screenshots for proof; use HTML for the parts that need to
change.
## Start from Figma
Send the agent the Figma link and the outcome:
```text
Use this Figma section as the visual source for a 20-second product intro:
https://www.figma.com/design/FILE/Project?node-id=10-20
Preserve the brand type and colors. Import artwork as local assets, rebuild the
product states that need to move, and treat the frames as key moments rather
than separate slides.
```
The agent can use the `/figma` skill to import assets, read brand values,
reconstruct editable components, and translate supported motion. Everything
required by the final render should end up as local project source.
For tokens, API credentials, exact CLI commands, and import troubleshooting,
use the [Figma integration reference](/guides/figma).
## Start from Claude Design or Open Design
These tools can establish layout, palette, type, and scene direction before a
deeper production pass.
1. Give the design tool the current HyperFrames instruction file and your real
brand material.
2. Ask for a valid project rather than isolated mockups.
3. Download or save the project to disk.
4. Open that folder with a coding agent.
5. Let the agent validate timing, motion, media, captions, and rendering.
[Claude Design instruction](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) · [Open Design handoff](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/open-design-hyperframes.md)
## Judge the handoff
A useful handoff has:
- a clear visual direction;
- real assets or honestly labeled placeholders;
- editable source for anything likely to change;
- stable local media and fonts;
- a project that opens and can be checked.
Run:
```bash
npx hyperframes check
npx hyperframes preview
```
Then review the actual movement in [Studio](/studio), not only the design stills.
## Related topics
- [Use the Figma integration](/guides/figma)
- [Work on the project in Studio](/studio)
- [Choose where to create](/guides/choose-creation-path)
docs/guides/export-and-share.mdx
+153
View File
@@ -0,0 +1,153 @@
---
title: "Finish and share a video"
sidebarTitle: "Finish and share"
description: "Review the project, run its checks, render through an agent, Studio, or the CLI, and deliver the right file or link."
---
Finish the same editable project through your agent, Studio, or the command
line. The route can change; the quality gate does not.
## 1. Approve the project, not one good frame
Watch the complete preview from the beginning. Check the message and sequence
before spending time on small visual details.
- Does the opening make the subject clear soon enough?
- Does every scene add something?
- Can text, captions, and product screens be read at delivery size?
- Do narration, visuals, music, and sound effects arrive together?
- Does the ending finish cleanly and make the next action clear?
## 2. Run the project checks
Run the checks in Studio, ask your agent to run them, or use:
```bash
npx hyperframes lint
npx hyperframes check
```
`lint` catches composition-structure mistakes. `check` runs lint plus browser,
runtime, layout, motion, and WCAG contrast verification.
Checks cannot judge the story for you. Fix technical failures, then watch the
project again if a fix changed what the viewer sees.
## 3. Render from where you are working
All three paths render the same source.
### Ask the agent
```text
Run the HyperFrames checks, fix any failures, and show me the final preview.
When I approve it, render an MP4 to renders/final.mp4.
```
Use the agent when a failed check may require a source change or when you want
one person to manage the complete finish. HyperFrames creation workflows wait
for render approval after the final preview.
### Use Studio
Open **Export**, choose the destination's format and size, and start the render.
The Renders panel shows progress and keeps completed files available to
download.
<div style={{ maxWidth: "42rem", margin: "1.5rem auto" }}>
<Frame caption="Studio checking and rendering the same project shown in its editor.">
<video
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-check-render-loop-v2.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-check-render-loop-v2.jpg"
autoPlay
muted
loop
playsInline
/>
</Frame>
</div>
### Use the CLI
```bash
npx hyperframes render --output renders/final.mp4
```
Use the CLI for a direct local render, a script, CI, or a repeatable batch. The
installed version remains authoritative: run
`npx hyperframes render --help` for every available option.
## 4. Choose what the destination needs
MP4 at the project's authored size is the normal delivery choice. Ask for
another format or resolution only when the next tool or platform requires it.
| Need | Start with |
| ------------------------------------------ | ----------------------------------------- |
| Watch, upload, or publish a normal video | MP4 |
| Place a transparent overlay on the web | WebM with an alpha-compatible composition |
| Continue in a professional editing tool | MOV, usually ProRes |
| Deliver a specified high-resolution master | The matching 4K preset |
Higher output resolution does not add detail to low-resolution media. A higher
frame rate creates more frames; it does not improve motion authored for a lower
cadence.
Use [Studio export](/studio/export) for its visible controls or the
[rendering reference](/guides/rendering) for formats, Docker, batch output, and
advanced CLI behavior.
## 5. Watch the rendered file
Open the output itself instead of relying on the preview.
- Watch the first and final seconds.
- Check captions, cuts, and the most complex transition.
- Listen for clipped narration, late sound effects, or an abrupt music ending.
- Confirm duration, dimensions, format, and audio.
- Use a filename that identifies the project and version.
The preview proves the project can play. The exported file proves the delivery
is correct.
## 6. Share the right form
| The recipient needs | Send |
| ------------------------------------- | --------------------------------- |
| A video to watch or upload | The rendered MP4, WebM, or MOV |
| A browser link to the current project | A published project URL |
| The ability to continue editing | The source project and its assets |
Publish the project when a browser link is more useful than a file:
```bash
npx hyperframes publish
```
The command uploads the project and returns a stable URL. An anonymous first
publish creates a claimable link. Sign in when the CLI should own the project
immediately, update an existing link, or publish into a shared space.
Before sharing source, remove secrets and confirm that every included media file
can be shared. Tell a reviewer whether you need feedback on story, visuals,
timing, facts, or final approval.
## If the finish fails
Keep the first exact error and run:
```bash
npx hyperframes doctor
npx hyperframes lint
npx hyperframes check
```
Use [Troubleshooting](/guides/troubleshooting) for project and render failures,
or [Studio troubleshooting](/studio/troubleshooting) when the problem is in the
editor or its render queue.
## Related topics
- [Export and manage renders in Studio](/studio/export)
- [Use advanced rendering options](/guides/rendering)
- [Diagnose a project or render failure](/guides/troubleshooting)
docs/guides/faceless-explainer.mdx
+73
View File
@@ -0,0 +1,73 @@
---
title: "Create a faceless explainer"
sidebarTitle: "Faceless explainer"
description: "Turn notes, an article, or a difficult idea into a visual explanation without product footage."
---
Start from a topic, article, or notes. HyperFrames invents the typography, diagrams, abstract graphics, and data visualization that teach it.
<Frame caption="A short preview from a SpaceX valuation explainer. Every visual was invented from the question and numbers.">
<video
className="aspect-video w-full object-cover bg-zinc-100 dark:bg-zinc-900"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-explainer.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-explainer.jpg"
autoPlay
muted
loop
playsInline
preload="metadata"
/>
</Frame>
## Make the request
Attach or paste the source material:
```text
Using /hyperframes, turn these notes into a short visual explainer for a
general audience: [paste notes]
```
The agent proposes the teaching angle and asks about information that must stay
exact. A topic alone is enough to begin; a script is useful only when its words
are already approved.
## How should the idea land?
- **Understand one idea** — open with a useful question, then reveal the mechanism one layer at a time.
- **Follow a process** — keep one visual stage and show each step in the order the viewer needs it.
- **Remember three points** — make the ideas parallel, concrete, and visually distinct enough to recall later.
- **Learn through a story** — use one case to move from setup and tension to a general lesson.
If you supply an approved script, say whether HyperFrames may restructure it or
must keep every word.
Use a [product and website video](/guides/product-launch-video) when the real interface should provide the proof. Use [captions or designed overlays](/guides/captions-and-recuts) when existing footage should remain underneath.
## From information to understanding
HyperFrames does not turn each paragraph into a scene. It finds the teaching spine, removes asides, and builds a sequence around the one idea the viewer should retain.
The visuals share one coherent language and develop with the explanation. A diagram should reveal a mechanism; a chart should prove a claim; motion should show what changes.
## Review whether it teaches
- The opening creates a question, tension, or surprise.
- The main idea is clear by the second scene.
- Each body scene advances one mechanism, step, example, or implication.
- Numbers and factual claims match the source.
- The ending lands the sentence you wanted the viewer to remember.
Ask the agent when the teaching sequence or evidence must change. Use
[Storyboard](/studio/storyboard) to inspect the sequence directly, or Studio
for a precise visual, timing, or animation correction.
<Card title="Finish and share" icon="circle-check" href="/guides/export-and-share">
Check the final project, render through your preferred surface, and review the file.
</Card>
## Related topics
- [Prompt for explainers](/prompting/explainers)
- [Review the storyboard](/studio/storyboard)
- [Create a product video from real screens](/guides/product-launch-video)
docs/guides/general-video.mdx
+73
View File
@@ -0,0 +1,73 @@
---
title: "Create a custom video"
sidebarTitle: "Custom video"
description: "Combine sources, change existing footage, or co-direct a video when no focused workflow fits."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
Use General Video when the work is genuinely custom: several source types, editable footage, a longer multi-scene story, an unusual format, or close creative collaboration.
<Frame caption="A complete launch film about timeline editing. The custom route combines the story, product evidence, motion, voice, music, and sound.">
<DocsVideo
title="A complete launch film about timeline editing"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/full-timeline.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/general-video-timing-v1.jpg"
/>
</Frame>
## Make the request
Describe the outcome and give the agent whatever source material already
exists:
```text
Using /hyperframes, make a one-minute recruiting film from the interview clips
and office footage in assets. Keep the employees' own words central.
```
The agent proposes a treatment and confirms the important intent before the
build. Use this path when choosing the story together matters more than fitting
one predefined input-to-output workflow.
## How should the agent work with you?
- **Build it for me** — let the agent make the creative decisions and return a complete first preview.
- **Review the story first** — approve the storyboard and rough layouts before detailed production.
- **Co-direct it** — shape the story, visual system, motion, transitions, audio, opening, and ending with the agent.
In companion mode, the agent proposes a complete creative treatment first. You redirect or remove what does not serve the idea; you do not have to request quality layer by layer.
## Use the custom route when
- several kinds of source material must become one video;
- the underlying footage may be trimmed, reordered, or changed;
- the piece needs a longer or unusual multi-scene structure;
- the same idea needs deliberately redesigned versions for different formats;
- you want to shape the creative treatment with the agent.
If one source already determines the job—a product URL, article, pull request, track, talking-head clip, or short motion graphic—start with its [focused workflow](/workflows).
## Keep feedback useful
Review the story before polishing motion. Use Studio for direct changes you can
point to. Ask the agent when feedback affects several scenes, source files,
media, or the overall narrative.
Before export, confirm:
- only source material that serves the story remains;
- narration, music, sound, and silence have a deliberate role;
- each requested format has been composed, not merely cropped;
- the opening and ending feel designed;
- the complete project passes its checks.
<Card title="Finish and share" icon="circle-check" href="/guides/export-and-share">
Check the complete result and render it from your preferred surface.
</Card>
## Related topics
- [Choose a focused workflow](/workflows)
- [Review the story before polishing](/studio/storyboard)
- [Edit the built project in Studio](/studio)
docs/guides/keyframes.mdx
-153
View File
@@ -1,153 +0,0 @@
---
title: Keyframes & Arc Motion
description: "Edit GSAP keyframes visually in Studio — timeline diamonds, arc motion paths, and gesture recording."
---
Studio gives you visual tools to create and edit GSAP keyframes without writing code. You can adjust animation properties in the Design Panel, convert straight-line motion into curved arcs, and record gesture-based motion by dragging elements in the preview.
## Timeline Keyframe Diamonds
When you open a composition in Studio, the timeline shows **diamond markers** on clips that have GSAP animations. Each diamond represents a keyframe — a point in time where a property value is set.
- **Start diamond** — where the tween begins (e.g., `x: 0`)
- **End diamond** — where the tween ends (e.g., `x: 1000`)
- Elements with multiple tweens show multiple diamond pairs
<Note>
Keyframe diamonds are synthesized from your GSAP tweens automatically. Every `.to()`, `.from()`, and `.fromTo()` call produces start and end markers on the timeline.
</Note>
## Editing Animation Properties
Select any animated element in the preview or timeline to open the Design Panel. The **Animation** section shows:
- **Method badge** — `Animate`, `Animate In`, or `From → To` (maps to `.to()`, `.from()`, `.fromTo()`)
- **Timing** — Length (duration) and Starts at (position on timeline)
- **Speed** — The GSAP ease (e.g., `power2.inOut`, `back.out(3)`)
- **Speed curve** — Visual preview of the easing function
- **Properties** — Each animated property (Move X, Move Y, Scale, Opacity, etc.) with its target value
<Steps>
<Step title="Select an element">
Click an animated element in the preview or its clip in the timeline. The Design Panel opens on the right.
</Step>
<Step title="Edit property values">
Change any property value directly — for example, set Move X to `500` to make the element travel 500px. Changes apply immediately via soft reload.
</Step>
<Step title="Change the ease">
Click the ease dropdown (e.g., "Smooth ease") to pick a different easing function. The speed curve preview updates live.
</Step>
<Step title="Verify in Code tab">
Switch to the Code tab to see the generated GSAP code. Every Design Panel edit writes valid GSAP that renders identically in preview and headless export.
</Step>
</Steps>
## Arc Motion
Arc Motion converts a straight-line x/y animation into a curved path using GSAP's MotionPathPlugin. Instead of moving in a straight diagonal, the element follows a smooth arc — like tossing an object into a basket.
### When to Use It
Use Arc Motion when an element has both `x` and `y` properties in a single tween. Common examples:
- Add-to-cart animations (item arcs from product to cart icon)
- Throw/toss effects
- Any motion that should feel physical rather than robotic
### Step-by-Step
<Steps>
<Step title="Select an element with x/y motion">
The element must have a `.to()` tween with both Move X and Move Y properties. Select it in the preview or timeline.
</Step>
<Step title="Toggle Arc Motion ON">
In the Animation section of the Design Panel, find the **Arc Motion** toggle below the property list. Switch it ON.
</Step>
<Step title="Adjust Curviness">
The **Curviness** slider controls how exaggerated the arc is:
- `0` — straight line (no curve)
- `1` — gentle natural arc
- `1.5–2.0` — smooth throw feel (recommended)
- `3.0` — extreme loop
Scrub the timeline to preview the arc in real time.
</Step>
<Step title="Toggle Auto-Rotate (optional)">
Enable **Auto-Rotate** to make the element rotate to face the direction of travel along the arc. This adds a "thrown" feel vs. a "floating" feel.
</Step>
<Step title="Verify the generated code">
Switch to the Code tab. You'll see:
```javascript
tl.to("#element", {
scale: 0.4,
opacity: 0,
duration: 1.0,
ease: "power2.inOut",
motionPath: {
path: [{x: 0, y: 0}, {x: 1400, y: -280}],
curviness: 1.5,
autoRotate: true
}
}, 1.0);
```
The MotionPathPlugin CDN script is added automatically.
</Step>
<Step title="Disable to restore straight motion">
Toggle Arc Motion OFF to restore the original `x` and `y` properties as flat tween values.
</Step>
</Steps>
<Note>
Arc Motion works for flat `.to()` tweens with x/y properties. It synthesizes waypoints from `{x: 0, y: 0}` (start) to `{x: targetX, y: targetY}` (end). For more complex paths with intermediate waypoints, edit the `motionPath.path` array directly in the Code tab.
</Note>
## Gesture Recording
Record motion by physically dragging an element in the preview while the timeline plays. The pointer path is simplified and converted into GSAP keyframes automatically.
<Steps>
<Step title="Select an element">
Click the element you want to animate in the preview.
</Step>
<Step title="Click Record or press R">
In the Animation section of the Design Panel, click **Record gesture (R)** or press the R key. The timeline starts playing.
</Step>
<Step title="Drag the element">
Move the element in the preview by dragging it. Your pointer motion is sampled at ~60fps. A trail overlay shows the path you're drawing.
</Step>
<Step title="Stop recording">
Press R again or wait for the timeline to reach the end. Recording stops, the motion is simplified (reducing ~180 raw samples to 5–15 clean keyframes), and the keyframes are written to the GSAP script immediately.
</Step>
<Step title="Review or undo">
The timeline seeks back to the recording start so you can scrub through the result. If you don't like it, press **Cmd+Z** to undo and try again.
</Step>
</Steps>
## Computed Timelines (Helpers, Loops, Dynamic Data)
Studio reads your timeline statically, so a composition that builds its tweens with a **helper function called several times**, a **bounded loop**, or **data-driven values** still shows every keyframe at its true time on the timeline — and the Arc Motion panel still activates for `motionPath` tweens, even when the path comes from a variable.
How those keyframes are **edited** depends on how they were authored:
- **Literal tweens** (`tl.to("#x", { x: 100 }, 1.3)`) — edit directly in the Design Panel. One source call, one tween.
- **Helper / loop tweens** — a single source line (e.g. `addCycle(1.0, ...)`) expands into many runtime tweens, so editing one keyframe is ambiguous. The Animation card shows a **"Generated by `addCycle()` — not directly editable"** notice with an **Unroll to edit** action: it rewrites the helper or loop into explicit literal tweens (a visual no-op — the render is identical), after which each keyframe edits directly. Undo restores the helper.
- **Computed-value tweens** (the rare case of a value derived at runtime that can't be resolved or unrolled) — stay display-only; edit them in the **Code tab**. HyperFrames compositions are deterministic, so this case is uncommon.
The notice on each computed tween tells you which path applies.
## Clipboard Context
The **clipboard icon** next to the element name in the Design Panel copies structured element context to your clipboard:
```
Element: Title (#title)
File: index.html:15
Position: x=100, y=40
Size: 264×43
Tag: <div>
Animation: from() 0.5s at 0s, ease: power2.out
Properties: x: -40, opacity: 0
```
Paste this into any AI agent prompt to give it spatial context about the element — its position, size, animation, and source location.
docs/guides/media-overlays.mdx
-171
View File
@@ -1,171 +0,0 @@
---
title: Media Overlays
description: "Add editable, timeline-driven HUD, flash, light-leak, and freeze-frame dressing alongside video or image media."
---
Use Media Overlays to add editable, timeline-driven HUD, flash, light-leak, and
freeze-frame dressing around a video or image without baking it into the source
pixels.
## Included Overlays
| Registry block | Purpose |
| --- | --- |
| `camcorder-hud` | Responsive REC indicator, battery, editable date placeholder, and timeline-driven counter |
| `editorial-flash-overlay` | Finite neutral-warm light layers for a camera-flash cut or social reveal |
| `organic-light-leak-overlay` | Finite CSS light leak for memory beats and motivated transitions |
| `freeze-frame-dressing` | Timeline-driven paper, tape, and flash dressing for a freeze frame or background-removed subject |
These are first-party authored blocks. Their Catalog poster/video assets are
previews only; the installed result is editable composition source.
Unlike [Color Grading](/guides/color-grading) and
[Media Effects](/guides/media-effects), overlays are real HTML, CSS, and paused
GSAP timelines installed from the HyperFrames Registry. Their final paint order
follows authored track placement and CSS `z-index`.
## Quick Start
<Tabs>
<Tab title="Studio">
<Steps>
<Step title="Select the media beat">
Select the `<video>` or `<img>` the overlay should accompany.
</Step>
<Step title="Insert an overlay">
Open **Overlays** in the Design panel and choose a preview card. Studio
installs the composition source and aligns it to the selected beat.
</Step>
<Step title="Edit and verify">
Use Layers, Timeline, Design, or Code to change content, timing, color,
animation, or placement, then play through the entrance and exit.
</Step>
</Steps>
</Tab>
<Tab title="Agent / CLI">
Discover the available overlay blocks, then install the one that supports
the intended beat:
```bash Terminal
npx hyperframes media-treatment --capabilities --json
npx hyperframes add camcorder-hud --no-clipboard
```
The command installs editable composition source under the project. Embed
and time it with the host composition's normal sub-composition rules.
</Tab>
</Tabs>
When the selected media has an authored track, Studio starts the overlay on the
next track. Otherwise, normal block placement defaults apply. The left Catalog
remains the browse-all Registry surface; **Overlays** is the selected-media
shortcut.
## Agent Guidance
An agent may combine grading, a shader effect, treatment animation, and an
overlay when they support one coherent intent. A restrained camcorder treatment
can combine a small source correction, tape damage on the media, the
`camcorder-hud` block, and a finite reveal or exit timed to the edit.
Use these constraints:
- Use an overlay when it adds information, motivated light, or useful visual
language.
- Keep text and HUD fields editable.
- Align finite overlays to a deliberate beat rather than leaving them active
for the entire video.
- Avoid adding decorative overlays automatically to accuracy-sensitive,
brand-sensitive, or deliberately clean footage.
- Verify that the overlay does not obscure captions, faces, product UI, or
essential content.
## Choosing the Right Overlay
### Camcorder HUD
Use for creator-camera, home-video, recording, or found-footage language. The
counter is timeline-driven and the REC behavior is deterministic. Edit the
date/label placeholders instead of rendering arbitrary timestamp text into the
source media.
### Editorial Flash
Use as a short cut accent or social reveal. It is finite by design and should
land on a motivated edit, capture, pose, or beat. It is not a permanent glow or
a replacement for shader Bloom.
### Organic Light Leak
Use sparingly for memory, warmth, film-language transitions, or a motivated
light event. It is a CSS/GSAP overlay rather than a LUT and does not permanently
change source color.
### Freeze-Frame Dressing
Use with a held frame or a subject cutout. The block provides paper, tape, and
flash dressing; it does not perform background removal itself.
For a transparent subject:
```bash Terminal
npx hyperframes remove-background subject.mp4 -o subject.webm
npx hyperframes add freeze-frame-dressing --no-clipboard
```
See [Remove Background](/guides/remove-background) for cutout and background
plate behavior.
## How Overlays Combine with Pixel Treatments
The compositing model is:
```text
source <img>/<video>
-> color correction and grading
-> LUT and shader effects
-> visible media canvas
overlay, caption, and other composition layers
-> composed with the visible media canvas by authored track and z-index
```
Color grading does not recolor overlay text or graphics. This is intentional:
HUD labels remain crisp and an organic light leak can be adjusted independently
from the source grade. Place captions, HUD fields, and other important graphics
on the intended track and verify their final stacking in Studio.
If an overlay should appear behind a subject, separate the subject into its own
transparent media layer and place the overlay between the background and
foreground layers.
## Editing and Reuse
Registry overlays are copied into the project rather than fetched at render
time. This keeps rendering deterministic and lets teams:
- Change the HTML and CSS.
- Replace labels and colors.
- Retune the paused GSAP timeline.
- Reuse the block across multiple compositions.
- Remove it without changing the media's `data-color-grading` payload.
Keep host-specific timing and placement in the host composition when possible.
That preserves the Registry block as a reusable visual unit.
## Next Steps
<CardGroup cols={2}>
<Card title="Color Grading" icon="palette" href="/guides/color-grading">
Correct and grade source media before adding visual dressing.
</Card>
<Card title="Media Effects" icon="wand-magic-sparkles" href="/guides/media-effects">
Apply shader-based optical, retro, print, and art treatments.
</Card>
<Card title="Remove Background" icon="scissors" href="/guides/remove-background">
Create transparent subject layers and paired background plates.
</Card>
<Card title="Keyframes" icon="diamond" href="/guides/keyframes">
Edit deterministic overlay and host animation in Studio.
</Card>
</CardGroup>
docs/guides/media.mdx
+81
View File
@@ -0,0 +1,81 @@
---
title: "Work with media"
sidebarTitle: "Overview"
description: "Use footage, images, audio, captions, backgrounds, and color in a HyperFrames project."
---
Media can come from your project, a captured website, an upload, or a generated
asset. Put anything required for the final result inside the project so preview
and rendering use the same file.
## Start with the role, not the effect
| Media | Give it one main job |
| --------------- | ------------------------------------------ |
| Product capture | Prove how the product behaves |
| Footage | Carry a person, place, action, or emotion |
| Image | Hold one idea long enough to understand it |
| Voice | Carry the explanation or story |
| Music | Shape pace and tone |
| Sound effect | Reinforce a meaningful action |
More layers do not automatically make a stronger video. If two assets do the
same job, keep the clearer one.
## Bring it into the project
In Studio, open **Assets**, choose **Import media**, or drop files into the
panel. Preview the file before placing it on the timeline. You can also ask the
agent to capture a website, prepare supplied footage, generate a derivative, or
copy an approved file into the project.
Use names such as `pricing-page-scroll.mp4` or `customer-logo.svg`. Clear names
make later revisions much easier for both people and agents.
## Prepare only what the result needs
- Trim or crop a source when the unused material slows down review.
- Remove a background when the subject must sit over a designed scene.
- Grade footage when sources visibly disagree or the story needs a deliberate look.
- Generate captions from the real speech, then correct words and timing before styling them.
- Keep narration clear above music and use effects only for specific events.
The original and prepared file should remain easy to distinguish.
## Check the final timeline
Watch once from beginning to end and check:
- the first and last frame of every video clip;
- crop and resolution at the intended output size;
- caption timing against the spoken words;
- voice clarity on ordinary headphones and laptop speakers;
- missing files, temporary URLs, and late-loading media.
## Choose a media task
<CardGroup cols={2}>
<Card title="Images and video" icon="photo-film" href="/guides/video-components">
Import, place, replace, trim, and review visual media.
</Card>
<Card title="Avatar presenter" icon="user-video" href="/guides/avatar-presenter">
Generate or reuse a presenter clip and compose around it.
</Card>
<Card title="Voice, music, and sound" icon="waveform" href="/guides/voice-and-audio">
Build an understandable audio mix.
</Card>
<Card title="Remove a background" icon="person-rays" href="/guides/remove-background">
Isolate a person from a real image or clip.
</Card>
<Card title="Color grading" icon="palette" href="/guides/color-grading">
Correct footage or establish a deliberate look.
</Card>
<Card title="Media effects" icon="wand-magic-sparkles" href="/guides/media-effects">
Apply a non-destructive visual treatment.
</Card>
</CardGroup>
## Related topics
- [Use assets and Catalog items in Studio](/studio/assets-and-blocks)
- [Finish, render, and share](/guides/export-and-share)
docs/guides/motion-graphics.mdx
+68
View File
@@ -0,0 +1,68 @@
---
title: "Create a motion graphic"
sidebarTitle: "Motion graphic"
description: "Make a short, motion-led title, statistic, chart, logo sting, or overlay."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
Use Motion Graphics for one short, design-led idea—usually under ten seconds—where the movement carries the message.
<Frame caption="A complete year-in-review graphic. It uses music and sound, but no narration; the motion carries it.">
<DocsVideo
title="A complete year-in-review motion graphic"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/full-hypecard.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-motion.jpg"
/>
</Frame>
## Make the request
State the message and the short result:
```text
Using /hyperframes, make a six-second motion graphic that counts from zero to
10,000 and lands on “Thank you.” No narration.
```
The agent proposes the visual treatment and confirms the output when it could
be either a finished video or a transparent overlay. Exact beat timings are
optional unless a specific moment must land precisely.
## What are you animating?
- **Words** — use kinetic type when movement and emphasis carry the message.
- **One number** — count or reveal a statistic, settle on the result, and hold it long enough to register.
- **Data** — animate a chart or comparison so the sequence makes the conclusion clear.
- **Logo** — build a short sting with a deliberate entrance, completion, and clean hold.
- **Overlay** — create a lower third or callout that enters, holds, and clears completely over footage.
- **Page, post, or map** — capture the real source and animate one detail into the visual payoff.
The same workflow can animate kinetic type, a statistic, chart, logo, lower third, map, real webpage, news headline, or post.
If the result needs narration, several scenes, or a longer story, use [General Video](/guides/general-video).
## Choose the output
- **MP4** for a finished standalone graphic.
- **WebM or MOV with transparency** for a logo sting, lower third, callout, or other overlay placed over footage.
For an overlay, name where it should sit and how long it should hold. The first and final frames must clear cleanly.
## Review the motion
- The words, data, source, and logo are exact.
- The complete message is readable while the video plays.
- The main movement helps communicate the meaning.
- The opening and ending states are deliberate.
- A transparent export has been checked over real footage.
<Card title="Finish and share" icon="circle-check" href="/guides/export-and-share">
Check the motion at full speed, render the chosen format, and review the final file.
</Card>
## Related topics
- [Prompt for motion graphics](/prompting/motion-graphics)
- [Edit animation and keyframes in Studio](/studio/animation)
- [Create a longer narrated video](/guides/general-video)
docs/guides/music-to-video.mdx
+68
View File
@@ -0,0 +1,68 @@
---
title: "Create a music-driven video"
sidebarTitle: "Music video"
description: "Cut footage, images, lyrics, and motion to a track’s beat grid."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
Start with a music file—or a video whose audio should control the edit. Narration is not added; the track is the spine.
<Frame caption="A complete music-driven film. Its sections, visual treatments, and cuts follow the track.">
<DocsVideo
title="A complete music-driven film"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/full-music.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-music.jpg"
/>
</Frame>
## Make the request
Attach the track and any media that must appear:
```text
Using /hyperframes, turn assets/song.wav and the photos in assets/tour into a
30-second music-driven video.
```
The agent analyzes the real track before planning the cut. Mention a required
section, lyric, image order, or delivery format when it cannot be chosen freely.
## What should the track drive?
- **Use your photos or video** — cut approved media to the track's phrases, energy, beats, and ending.
- **Make a lyric video** — verify the words first, then synchronize and design each line around the vocal.
- **Invent the visuals** — build the visual arc from typography, graphic elements, and motion when no media is supplied.
A complete video can also be built entirely from type, graphic templates, and
motion.
## The track sets the structure
HyperFrames maps the track’s phrases, energy, onsets, silences, rolls, drops, and hard stops before it plans the visuals.
A rhythmic track can support cuts on its real beat grid. Calm or loose music should flow by phrase and energy instead of forcing a cut onto every measured beat.
The visual treatments change at meaningful musical moments. More beats do not automatically mean more scenes.
## Review the rhythm
- The correct section of the track is used.
- Required media appears and lyrics match the vocal.
- The strongest visual changes land on meaningful musical changes.
- Important images and text remain long enough to understand.
- The ending reaches a musical landing or forms a deliberate loop.
For direct timing control, use the [Studio timeline](/studio/timeline) to refine
cuts, holds, and the ending against the beat markers. Ask the agent when the
section, media plan, or overall treatment must change.
<Card title="Finish and share" icon="circle-check" href="/guides/export-and-share">
Check the final project, render through your preferred surface, and review the file.
</Card>
## Related topics
- [Edit cuts and holds on the Studio timeline](/studio/timeline)
- [Work with voice, music, sound, and captions](/guides/voice-and-audio)
- [Prompt for music videos and slideshows](/prompting/music-and-slideshows)
docs/guides/open-design.mdx
-175
View File
@@ -1,175 +0,0 @@
---
title: Open Design
description: "Create HyperFrames video drafts in Open Design — the open-source, BYOK Claude-Design alternative — then refine in any AI coding agent."
---
[Open Design](https://github.com/nexu-io/open-design) is an open-source, local-first alternative to Claude Design. It runs on your laptop with `pnpm tools-dev`, deploys the web layer to Vercel, and delegates to whichever coding-agent CLI you already have on your `PATH` (Claude Code, Codex, Cursor Agent, Gemini CLI, OpenCode, Qwen, Copilot, Hermes, Kimi, Pi) — or to any OpenAI-compatible BYOK endpoint.
Open Design produces a **valid first draft** of a HyperFrames composition — palette, scene content, GSAP entrance tweens, mid-scene activity, and shader transitions. You then download the project and refine in any AI coding agent with linting and live preview.
## Get started
<Steps>
<Step title="Download the instruction file">
Open [`open-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/open-design-hyperframes.md) on GitHub and click the download button (↓) to save it.
</Step>
<Step title="Run Open Design locally">
```bash
git clone https://github.com/nexu-io/open-design.git
cd open-design
pnpm install
pnpm tools-dev run web
# open the web URL printed by tools-dev
```
</Step>
<Step title="Drop the file into a skill, or attach it to chat">
**Recommended:** copy `open-design-hyperframes.md` to `skills/hyperframes-handoff/SKILL.md` inside the Open Design repo. The daemon auto-discovers it on the next request and exposes it as a skill in the picker. **Or:** start a new chat and attach the file directly — Open Design reads attachments natively.
</Step>
<Step title="Describe your video">
Pick the `hyperframes-handoff` skill (or your active prototype skill), pick a design system or visual direction, and type the brief. Include screenshots, brand assets, or a palette if you have them.
</Step>
<Step title="Save the project to disk">
Open Design writes `index.html`, `preview.html`, `README.md`, and a `DESIGN.md` snapshot into `.od/projects/<id>/`. Click **Save to disk** or download as a project ZIP.
</Step>
<Step title="Refine in any AI coding agent">
The Open Design project folder is already a real on-disk working directory. Hand it off to Claude Code, Cursor, Codex, or any agent with terminal access:
```bash
cd .od/projects/<id>
npx skills add heygen-com/hyperframes # install skills (one-time)
npx hyperframes lint # should pass with zero errors
npx hyperframes preview # open the studio
```
</Step>
</Steps>
<Tip>
**Drop into `skills/`, don't paste into chat.** Open Design's daemon reads `SKILL.md` files at request time and injects the side files (templates, references) automatically. A pasted URL or chat attachment works, but the skill path gives you the full pre-flight pipeline (template injection + 5-dimensional self-critique gate).
</Tip>
## Which setup to use
| Surface | Recommended setup |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open Design (open-source) | Drop [`open-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/open-design-hyperframes.md) into `skills/hyperframes-handoff/SKILL.md` |
| Claude Code | `npx skills add heygen-com/hyperframes`, then use `/hyperframes` |
| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes` |
| Claude Design (closed-source) | Attach [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) to your chat |
## How it works
The instruction file gives Open Design **pre-valid HTML skeletons** — the structural rules (data attributes, timeline registration, scene visibility, preview token forwarding) are already embedded. Open Design fills in the creative work:
1. **Palette + typography** — driven by the active `DESIGN.md` (Open Design ships 72 systems out of the box, plus 5 deterministic visual directions when no brand is named) bound onto `:root`
2. **Scene content** — text, images, layout inside `.scene-content` wrappers
3. **Animations** — GSAP entrance tweens and mid-scene activity
4. **Transitions** — hard cuts for most scenes, shader transitions at 2-3 key moments
Open Design's [5-dimensional self-critique](https://github.com/nexu-io/open-design/blob/main/apps/web/src/prompts/discovery.ts) runs before emission, so the artifact arrives lint-clean and your coding agent can start refining immediately without structural fixes.
## Example prompts
<CardGroup cols={1}>
<Card title="Feature announcement">
```text
Use the hyperframes-handoff skill. I just shipped dark mode for my app.
Make me a 15-second Instagram reel announcing it.
- App name: Taskflow
- Primary color: #6C5CE7
- The vibe is clean, minimal, dark
- Key stat: "47% of users requested this"
```
</Card>
<Card title="Founder pitch (BYOK with your own CLI)">
```text
Use the hyperframes-handoff skill on Codex CLI. 25-second LinkedIn video.
Problem: Sales teams waste 3 hours/day on manual CRM updates.
Solution: AutoCRM — AI that logs every call, email, and meeting.
Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
CTA: autocrmhq.com
Use the Linear design system. Professional but not corporate.
```
</Card>
<Card title="Brand-driven (use one of the 72 design systems)">
```text
Use the hyperframes-handoff skill. Design system: Stripe. 10-second reel.
One big number: "$4.2 billion processed in Q1 2026"
Dark background, the number animates up from zero. Subtle, confident.
End with logo placeholder and "stripe.com"
```
</Card>
<Card title="Sparse brief (let it ask)">
```text
Use the hyperframes-handoff skill. 30-second launch video for Orbit.
```
Open Design's `RULE 1` always opens with a `<question-form>` before emitting code, so a sparse brief turns into one short question form (surface · audience · tone · brand · scale) instead of an AI-freestyle render.
</Card>
</CardGroup>
## What to include in your prompt
Open Design reads inputs in this order of reliability: **active DESIGN.md > attachments > pasted content > web research > URLs**.
| Input type | What it gives Open Design |
| --- | --- |
| Active design system (72 shipped, switchable from picker) | Full 9-section spec (color, typography, spacing, layout, components, motion, voice, brand, anti-patterns) — strongest source |
| Screenshots / PDFs / brand guides | Palette, typography, UI patterns, tone — read by the agent natively |
| Pasted hex codes, typefaces, copy | Authoritative for what they cover |
| Brand name (well-known) | Open Design can `WebFetch` blogs, press, Wikipedia |
| SPA URL (React/Vue homepage) | Returns near-empty shell — pivot to blog/press instead |
The more specific your prompt, the better the output. Pick a design system or visual direction up front, then describe content.
## Why use Open Design vs. Claude Design
| | Claude Design | **Open Design** |
| --- | --- | --- |
| License | Closed | Apache-2.0 |
| Cost | Pro / Max / Team | BYOK (free with your own CLI / API key) |
| Form factor | Web (claude.ai) only | Web app + local daemon (or deploy to Vercel) |
| Agent runtime | Anthropic only (Opus 4.7) | 10 CLI adapters + OpenAI-compatible BYOK proxy |
| Skills | Proprietary | 31 file-based `SKILL.md` bundles, droppable |
| Design systems | Proprietary | 72 shipped `DESIGN.md` systems |
| Filesystem-grade workspace | ❌ | ✅ Real `cwd`, real `Read` / `Write` / `Bash` / `WebFetch` |
If you want the Claude Design loop without lock-in, Open Design is the same artifact-first mental model — open, local, BYOK.
## Known limitations
- **Render still happens locally** — Open Design produces the HTML; `npx hyperframes render` and HDR encoding still need FFmpeg + Node 22+ on your machine.
- **In-pane preview is sandboxed iframe** — full browser playback is reliable; for frame-accurate scrubbing use `npx hyperframes preview` after handoff.
- **Shader passthrough requires WebGL** — same as the Claude Design path; Open Design's iframe sandbox supports it.
- **Skill pre-flight is daemon-side** — if you bypass the skill picker and paste raw HTML into chat, you lose the side-file injection and 5-dim critique gate. Use the skill.
## The handoff to your coding agent
Open Design's project folder is the agent's `cwd`. There's no "export then re-import" step — open Claude Code, Cursor, Codex, or any AI coding agent against the same directory:
```bash
cd .od/projects/<your-project-id>
npx skills add heygen-com/hyperframes # one-time setup
npx hyperframes lint # verify structure
npx hyperframes preview # open the studio
```
Then iterate the same way as the Claude Design path:
- "Make scene 3's entrance snappier"
- "Add a counter animation to the stat in scene 5"
- "Tighten the pacing — scenes 4 and 6 feel too long"
- "Change the shader on transition 2 to glitch"
## Next steps
<CardGroup cols={2}>
<Card title="Claude Design Guide" icon="message" href="/guides/claude-design">
The closed-source flavor of the same workflow — useful when you don't have a CLI on your laptop.
</Card>
<Card title="Prompt Guide" icon="message" href="/prompting/overview">
More prompt patterns for HyperFrames across Claude Code, Claude Design, Open Design, and other agents.
</Card>
</CardGroup>
docs/guides/pipeline.mdx
-225
View File
@@ -1,225 +0,0 @@
---
title: The Pipeline
description: "The 7-step pipeline for producing any Hyperframes video: capture, design, strategy & messaging, storyboard + script, voiceover, build, validate."
---
Every well-structured Hyperframes video flows through the same 7 steps, whether it starts from a website, a PDF, a CSV, or a blank page. Each step produces a named artifact that the next step depends on, so your AI agent (and you) always know what's done, what's next, and where the creative decisions live on disk.
This pipeline is the backbone of the [website-to-video guide](/guides/website-to-video), but it's just as useful when you're scripting a brand reel from scratch, turning research notes into a launch teaser, or learning Hyperframes for the first time. Most of the production-grade [launch videos](/launch-videos) HeyGen ships are organized this way.
## The seven steps
Each step produces an artifact that feeds the next:
| # | Step | Output | What happens |
|---|-------------------------|-----------------------------------------|-------------------------------------------------------------------------|
| 1 | **Capture** | `capture/` | Extract screenshots, design tokens, fonts, assets, animations from a source |
| 2 | **Design** | `DESIGN.md` | Brand reference: colors, typography, component stylings, spacing, iteration guide |
| 3 | **Strategy & Messaging**| `BRIEF.md` | Lock video type, style, the ONE message, arc, audience — and the run's shape (automation or companion, storyboard or one-shot) |
| 4 | **Storyboard + Script** | `STORYBOARD.md` + `SCRIPT.md` | Concept-first storyboard and narration script, written together |
| 5 | **VO + Timing** | `narration.wav` + `transcript.json` | TTS audio with word-level timestamps |
| 6 | **Build** | `compositions/*.html` | Animated HTML compositions, one per beat |
| 7 | **Validate** | Snapshot PNGs + `lint`/`validate` pass | Visual verification and runtime checks before delivery |
<Tip>
Not every project uses every step. A no-narration brand reel skips Step 5; a hand-authored composition skips Steps 1-2. But the order matters: scene durations come from narration, animation choices come from the storyboard, and the storyboard depends on the design reference. Skip a step only when you don't need its artifact downstream.
</Tip>
## Project layout
A typical project directory after the pipeline runs:
```
my-video/
├── capture/ # Step 1, only present when capturing a source
│ ├── screenshots/ # scroll-000.png, scroll-001.png, …
│ ├── assets/ # downloaded images, SVGs, fonts
│ ├── extracted/ # tokens.json, visible-text.txt, asset-descriptions.md
│ ├── AGENTS.md # capture summary for AI agents
│ └── CLAUDE.md
├── DESIGN.md # Step 2, brand cheat sheet
├── BRIEF.md # Step 3, confirmed intent: message, audience, run shape
├── SCRIPT.md # Step 4, narration backbone
├── STORYBOARD.md # Step 4, beat-by-beat creative plan
├── narration.wav # Step 5, TTS audio
├── narration.txt # Step 5, exact spoken text (with pronunciation subs)
├── transcript.json # Step 5, word-level timestamps
├── compositions/ # Step 6, one HTML file per beat
│ ├── beat-1-hook.html
│ ├── beat-2-story.html
│ └── …
├── snapshots/ # Step 7, visual verification PNGs
├── renders/ # optional final MP4 outputs
└── index.html # root project file wiring compositions into a timeline
```
Capture artifacts stay in `capture/` so they're cleanly separated from the build outputs. Everything downstream lives at the project root.
## Step 1: Capture
**Output:** `capture/`
When the video is grounded in an existing source (a website, a brand site, a competitor reference), start with capture. Hyperframes ships a built-in capture command for websites:
```bash
npx hyperframes capture https://example.com -o my-video/capture
```
This extracts screenshots at every scroll depth, pixel-sampled color palettes, the CSS font stack (and downloaded woff2 files), images and SVGs with semantic names, Lottie animations, and detected animations on the page. Optional [Gemini vision enrichment](/guides/website-to-video#enriching-captures-with-gemini-vision) adds AI-powered descriptions of every captured asset.
For sources that aren't websites (PDFs, decks, CSVs, notes), capture isn't a literal command. It's the step where you gather assets into `capture/` so later steps can reference paths instead of inlining content.
**Gate:** You can describe the source's visual identity in one or two sentences and name its top colors, fonts, and standout assets.
## Step 2: Design
**Output:** `DESIGN.md` in the project root
`DESIGN.md` is the brand cheat sheet. It encodes the visual identity factually so every downstream decision can reference exact colors, fonts, and components instead of inventing them. It's a reference document, not a creative plan. The creative work happens in the storyboard.
A typical `DESIGN.md` has five sections:
| Section | What it captures |
|---------|------------------|
| **Visual Theme** | 3-5 sentences describing the brand's visual personality — dark/light, contrast, mood, what makes it distinctive |
| **Quick Reference** | Colors (8-12 HEX values with semantic roles and WCAG contrast ratios) and fonts (families, weights, roles, file paths) |
| **Component Stylings** | Exact CSS-level specs for 6-12 components the brand uses: buttons, cards, containers, distinctive UI patterns |
| **Spacing & Layout** | Base spacing unit, scale with usage, max-width / grid, and breakpoint strategy |
| **Iteration Guide** | Do's and don'ts, common failure modes, and rules for modifying the design in later steps |
`DESIGN.md` is also the input format for [Open Design](/guides/open-design) and [Claude Design](/guides/claude-design); both produce a `DESIGN.md` you can drop into a Hyperframes project.
**Gate:** `DESIGN.md` exists with all five sections filled in from real captured data (or chosen deliberately for greenfield projects).
## Step 3: Strategy & Messaging
**Output:** `BRIEF.md` in the project root
Before any creative decisions, align with the user on the story this video must tell. Parse the user's prompt first — they probably already gave you the video type and style. Only ask about things they didn't specify. If the prompt is detailed enough, confirm the direction in one message and move to Step 4.
The questions to resolve: what type of video (social ad, product demo, brand reel, etc.), what style and energy, what's the ONE thing this video must communicate, what narrative arc serves that message, and whether narration is wanted.
When the project starts from `/hyperframes`, this step is the [opening interview](/prompting/overview#the-interview-what-the-agent-asks-first) — and it runs before Step 1, since the answers decide whether there's anything to capture at all. Either way, the confirmed answers land in `BRIEF.md`: frontmatter keys for the deterministic fields (`workflow`, `flow`, `storyboard`, `message`, audience, length), prose sections for the intent and any supplied material. A later session resumes from this file instead of re-asking.
**Gate:** `BRIEF.md` exists — video type, duration, format, message, and narrative arc locked. Without those, Step 4 can't write a concept-first storyboard.
## Step 4: Storyboard + Script
**Outputs:** `STORYBOARD.md` + `SCRIPT.md` in the project root
Write the storyboard concept-first: message → narrative arc → beats that serve the arc → techniques per beat → brand accents pass at the end. Then write the narration script to match. The storyboard and script are written together — the storyboard drives the script, not the other way around.
`STORYBOARD.md` tells the engineer (human or agent) exactly what to build for each beat: mood, camera, animations, transitions, assets, depth layers, sound effects. It's where the creative choices get pinned down.
Each beat in `STORYBOARD.md` typically covers:
| Field | What it specifies |
|------------------|-------------------|
| Timing | `0.0s - 5.8s`, taken from `transcript.json` once Step 5 runs |
| Narration line | The exact words spoken during this beat |
| Mood & camera | One sentence describing the feel and the shot |
| Assets | Which captured images, icons, and fonts go in this beat, referenced by path |
| Techniques | 2-3 picks from the [techniques library](https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/techniques.md): SVG path drawing, Canvas 2D, CSS 3D, per-word typography, Lottie, video compositing, typing effects, variable fonts, MotionPath, velocity transitions, audio-reactive |
| Transitions | How this beat enters from the previous one and exits to the next |
| SFX | Short, specific sound effects (e.g. _"woosh on logo entry, soft tick on counter"_) |
The storyboard typically opens with a global-direction block: format, voiceover direction, style basis, and guardrails that apply to every beat. `SCRIPT.md` contains the narration backbone: **hook** (one sentence that earns attention), **story** (what the product or topic is), **proof** (numbers, components, customers), **CTA** (one clear action). For videos without narration, `SCRIPT.md` becomes a per-beat copy plan with on-screen text and timing notes.
**Gate:** `STORYBOARD.md` + `SCRIPT.md` exist with beat-by-beat direction, an asset audit that names every file used, and user approval of the plan.
## Step 5: VO and timing
**Outputs:** `narration.wav` (or `.mp3`), `narration.txt`, `transcript.json`
Generate the TTS narration, then transcribe it for word-level timestamps. Those timestamps are the source of truth for every beat duration downstream.
```bash
npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav
npx hyperframes transcribe narration.wav
```
| File | What it contains |
|------------------|------------------|
| `narration.wav` | The TTS audio that ships with the final render |
| `narration.txt` | The exact spoken text with pronunciation substitutions applied (`API` → `A P I`, `$2T` → `two trillion`). Distinct from `SCRIPT.md` so you can regenerate the audio later with a different voice without redoing the substitutions. |
| `transcript.json`| `[{ text, start, end }]` for every word. Every later step reads this for timing. |
Hyperframes ships multiple TTS adapters (Kokoro, ElevenLabs, HeyGen); see [`/media-use`](/guides/skills#domain-skills-loaded-on-demand) for the skill that picks one. After generating audio, update `STORYBOARD.md` with the real beat boundaries from `transcript.json`.
**Gate:** `narration.wav`, `narration.txt`, and `transcript.json` exist. `STORYBOARD.md` beat timings reference real timestamps, not estimates.
## Step 6: Build
**Output:** `compositions/<beat-name>.html`, one HTML file per beat
This is where the storyboard becomes runnable HTML. Each composition is a self-contained file that imports captured assets by path, uses the exact colors and fonts from `DESIGN.md`, and animates with the techniques the storyboard picked.
For multi-beat videos, spawn a focused sub-agent per beat. Each one gets fresh context, the storyboard section for its beat, the asset paths it needs, and the relevant technique references. That produces noticeably better output than building every beat in one long-running context.
After each composition is built, run a self-review for layout, asset placement, and animation quality. The [`/hyperframes-core`](/guides/skills#domain-skills-loaded-on-demand) skill encodes the composition rules — required `class="clip"` attributes, `data-*` attribute semantics — and [`/hyperframes-animation`](/guides/skills#domain-skills-loaded-on-demand) covers GSAP timeline registration and adapter registries.
**Gate:** Every composition is self-reviewed. No overlapping elements, no misplaced assets, no static images sitting unanimated.
## Step 7: Validate
**Outputs:** `snapshots/frame-*.png`, lint and validate passing with zero errors
Three checks before delivery:
```bash
npx hyperframes lint # static HTML structure checks
npx hyperframes check # one browser session: runtime errors, layout, motion, contrast
npx hyperframes snapshot my-video --at 2.9,10.4 # PNGs at beat midpoints
```
`lint` catches missing attributes, timeline registration issues, tween conflicts, and CSS-transform vs. GSAP conflicts. `validate` loads each composition in headless Chrome and surfaces runtime JS errors, missing assets, and failed network requests. `snapshot` captures frames at specific timestamps so you can _see_ your output without a full render.
The pipeline delivers the localhost Studio URL as the handoff. Your AI agent runs `npx hyperframes preview` and shares the project URL. Rendering to MP4 is on-demand:
```bash
npx hyperframes render --output my-video.mp4
```
For personalized or catalog outputs, render the same validated composition with `--batch rows.json --output "renders/{name}.mp4"` and use the generated `manifest.json` as the delivery checklist.
**Gate:** `lint` and `validate` pass with zero errors. Snapshot frames look right. The Studio preview URL is ready to share.
## Iterating
The pipeline is built around named artifacts on disk so you can re-enter anywhere without re-running everything:
- To change what the video is *for* — the message, the audience, the run's shape — edit `BRIEF.md`; it's the file the agent trusts over chat history.
- To rework the creative plan, edit `STORYBOARD.md`: change a beat's mood, swap an asset, retime the entrance, then ask the agent to rebuild just that beat.
- For surgical tweaks, open a composition file directly (e.g. `compositions/beat-3-proof.html`) and adjust animations, colors, or layout. `npx hyperframes preview` shows changes live.
- To rebuild one beat from scratch, prompt the agent: _"Rebuild beat 2 with more energy. Use the product screenshot as full-bleed background."_ It reads `STORYBOARD.md`, `DESIGN.md`, and the transcript, then regenerates just that file.
- To swap the voice without redoing Step 3, re-run TTS against `narration.txt`, which already has the pronunciation substitutions baked in.
Each artifact is a checkpoint, so you can stop, hand off to a human reviewer, or come back tomorrow and the agent still has everything it needs to keep going.
## When to use the pipeline
The pipeline is the recommended structure for:
- Capturing a website with the [/product-launch-video](/guides/website-to-video) workflow, which follows it end-to-end.
- Shipping a product launch. Most of the [HeyGen launch videos](/launch-videos) use this artifact layout.
- Any narrative video with three or more beats, where a storyboard pays for itself.
- Learning Hyperframes, because the artifacts leave every creative decision inspectable on disk.
For a 5-second one-shot animation, a single hand-authored composition is fine; the pipeline is overhead you don't need. The rough cutoff: if a non-author needs to understand _why_ a beat looks the way it does, write it down in `STORYBOARD.md`.
## Next steps
<CardGroup cols={2}>
<Card title="Website to Video" icon="globe" href="/guides/website-to-video">
The full website-to-video guide built on this pipeline.
</Card>
<Card title="Prompting" icon="comment" href="/prompting/overview">
How to invoke the pipeline through your AI agent.
</Card>
<Card title="Launch Videos" icon="rocket" href="/launch-videos">
Real production projects organized around this pipeline.
</Card>
<Card title="CLI Reference" icon="terminal" href="/packages/cli">
Every command the pipeline calls.
</Card>
</CardGroup>
docs/guides/pr-to-video.mdx
+72
View File
@@ -0,0 +1,72 @@
---
title: "Turn a pull request into a video"
sidebarTitle: "Pull request"
description: "Show what changed, why it matters, and what happens next."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
Give HyperFrames a pull request. It reads the diff, commits, files, and contributors—there is no website capture.
<Frame caption="A real pull request becomes a 32-second explanation with code, before-and-after behavior, and sound.">
<DocsVideo
title="A pull request explained with code and before-and-after behavior"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/full-prvideo.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-pr.jpg"
/>
</Frame>
## Make the request
Send the pull request and name the audience:
```text
Using /hyperframes, explain https://github.com/owner/repo/pull/123 to product
and engineering teammates.
```
The agent reads the actual pull request, proposes the angle, and confirms its
release state before presenting a proposed change as shipped behavior.
## Who needs to understand it?
- **Users** — lead with the visible change, show the before and after, and name any action they must take.
- **Contributors** — explain the architecture change, important tradeoff, and code path reviewers need to understand.
- **Social audience** — make one clear feature reveal with visible proof and only the implementation detail that explains it.
The same pull request needs a different story for users, contributors, or a social audience.
## Before it builds
Confirm:
- the intended pull request and audience;
- whether the angle is a changelog, feature reveal, fix, or refactor;
- whether the change is proposed, merged, or released;
- the visible before and after;
- any breaking change or migration step.
The video should explain the change, not read the pull request description aloud.
## Verify the proof
- The pull request and target branch are correct.
- Proposed, merged, and released are not confused.
- User-facing claims match the actual behavior.
- Code excerpts show only the relevant lines and remain readable.
- Tests and refactoring are not presented as product features.
- Contributor names and release details are accurate.
Ask the agent when the explanation or evidence must change. Use Storyboard to
inspect the sequence directly, or Studio for a precise timing, code-framing, or
caption correction.
<Card title="Finish and share" icon="circle-check" href="/guides/export-and-share">
Check the final project, render through your preferred surface, and review the file.
</Card>
## Related topics
- [Prompt for code changes and pull requests](/prompting/code-and-prs)
- [Review the storyboard](/studio/storyboard)
- [Create a custom video from several sources](/guides/general-video)
docs/guides/product-launch-video.mdx
+82
View File
@@ -0,0 +1,82 @@
---
title: "Create a product or website video"
sidebarTitle: "Product or website"
description: "Turn a product URL or launch brief into a promo, product tour, or social video."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
Give HyperFrames the real URL when the product, website, or brand should appear in the result.
<Frame caption="A real product-launch film, built from the product itself.">
<DocsVideo
title="A narrated Huly product-launch film created with HyperFrames"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/product-launch-huly-v1.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/product-launch-huly-v1.jpg"
/>
</Frame>
## Make the request
Give the agent the real product URL and the result you want:
```text
Using /hyperframes, make a 30-second launch video for https://example.com.
```
The agent inspects the product, proposes a direction, and confirms anything
important that the request did not settle. Add an audience, required claim, or
final action when one must be exact; you do not need to specify every scene.
## What should the video do?
- **Launch video** — turn real product evidence into a persuasive story with one clear action at the end.
- **Product tour** — show one complete task through the product's real screens, from the first action to the result.
- **Short social video** — prove one useful point quickly, show the evidence, and stop after the payoff.
A tour features the product as it exists. A launch video rearranges the same evidence into a persuasive story. A social video proves one point and ends.
If you already have approved wording, paste the script and say whether it must remain verbatim. Say **do not capture the website** when the video should use only the supplied brief.
Use a [faceless explainer](/guides/faceless-explainer) instead when there is no product to show and the visuals should be invented.
## What HyperFrames builds from
<div className="my-5 grid gap-3 sm:grid-cols-3">
<div className="border-b border-zinc-200 pb-3 dark:border-zinc-800">
<div className="font-medium">Real screens</div>
<div className="mt-1 text-sm text-zinc-500">
The interface and product states worth showing.
</div>
</div>
<div className="border-b border-zinc-200 pb-3 dark:border-zinc-800">
<div className="font-medium">Product language</div>
<div className="mt-1 text-sm text-zinc-500">Claims, features, proof, and the final action.</div>
</div>
<div className="border-b border-zinc-200 pb-3 dark:border-zinc-800">
<div className="font-medium">Brand system</div>
<div className="mt-1 text-sm text-zinc-500">Color, type, imagery, motion, and sound.</div>
</div>
</div>
HyperFrames can animate captured product material or rebuild only the part that needs to move. A raw screen recording is not the default.
## Review the result
- Every product claim is current.
- The shown states are realistic and use no private material.
- The important interface remains readable while the video plays.
- The opening proves the product quickly and the ending asks for one clear action.
Ask the agent for a broader story revision. Use Studio for a direct visual or
timing change. Render from the agent, Studio, or the CLI when the result is ready.
<Card title="Finish and share" icon="circle-check" href="/guides/export-and-share">
Check the final project, render it from your preferred surface, and review the file.
</Card>
## Related topics
- [Create a faceless explainer when there is no product to show](/guides/faceless-explainer)
- [Edit the finished project in Studio](/studio)
- [Prompt for product-launch videos](/prompting/product-launch)
docs/guides/slideshow.mdx
+80
View File
@@ -0,0 +1,80 @@
---
title: "Create an interactive presentation"
sidebarTitle: "Presentation"
description: "Build a navigable deck with reveals, notes, optional branches, hotspots, and presenter mode."
---
A HyperFrames slideshow stays interactive. The result is a live, navigable deck—not a linear MP4.
<Frame caption="A real deck: points reveal, slides advance, a hotspot opens optional detail, then the presenter returns to the main story.">
<video
className="aspect-video w-full object-cover bg-zinc-100 dark:bg-zinc-900"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-slideshow.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/wfv2-slideshow.jpg"
autoPlay
muted
loop
playsInline
preload="metadata"
/>
</Frame>
## Make the request
Give the agent the material and the decision the presentation should support:
```text
Using /hyperframes, turn this product strategy outline into a presentation for
our leadership review: [paste outline]
```
The agent confirms the audience, main outcome, and whether the deck needs
reveals, optional branches, or presenter notes. You do not need to prescribe
every slide before seeing the proposed structure.
If the result should play from beginning to end without a presenter, use a normal [video workflow](/workflows). A slideshow cannot currently be exported as one complete linear MP4; per-slide snapshots are supported.
## What control does the presenter need?
- **Present a clear story** — give every slide one claim, one useful visual, and concise speaker notes.
- **Reveal points as you speak** — use progressive reveals where the presenter should control the explanation.
- **Offer optional detail** — keep the main story direct and place deeper material behind clear branches and hotspots.
- **Convert an interactive page** — preserve its visual language and translate its motion into deliberate slide and reveal states.
Attach the source notes, document, page, or existing deck. Name the audience and what should change after the presentation.
## Keep the main story clear
- **Slides** carry one complete claim and one useful visual.
- **Reveals** let the presenter add part of an idea at a time.
- **Branches** hold optional detail without interrupting the story everyone sees.
- **Speaker notes** help the presenter; they should not repeat the slide.
The main story should still make sense when no optional branch is opened.
## Review it as a presenter
- Each slide makes one clear point.
- Reveals help the explanation.
- Hotspots are obvious without distracting.
- Embedded media stops when its slide is left.
- Presenter notes and the audience view stay separate.
- The complete deck works with keyboard, touch, and its visible controls.
Use [Studio’s Slideshow panel](/studio/slideshows) to adjust order, notes, reveals, and branches.
## Present the deck
```bash
npx hyperframes present <project-directory>
```
Open the local URL, then click **Present** or press **P**. The audience gets a clean full-screen view while the presenter keeps the current slide, next slide, notes, and timer.
In Google Meet, share the audience **tab**. In Zoom, move the audience tab into its own window and share that window.
## Related topics
- [Build and revise a slideshow in Studio](/studio/slideshows)
- [Use variables and templates](/studio/variables)
- [Create a linear video instead](/workflows)
docs/guides/timeline-editing.mdx
-110
View File
@@ -1,110 +0,0 @@
---
title: Timeline Editing
description: "What you can edit in the Studio timeline today, how those edits map back to HTML, and the current limitations."
---
The Studio timeline lets you edit the parts of a HyperFrames composition that can be persisted cleanly back into source HTML.
It is not a separate project format or hidden binary state. Every supported timeline action updates the same `data-*` attributes and inline styles that your composition already uses.
## What the Timeline Can Do
- **Move clips in time** — drag a clip horizontally to update `data-start`
- **Move clips between rows** — drag a clip vertically to update `data-track-index`
- **Change visual stacking** — top timeline rows render above lower rows, and that ordering is persisted back into inline `z-index`
- **Trim the end of a clip** — drag the right handle to reduce `data-duration`
- **Trim the start of media clips** — drag the left handle on clips backed by media offsets to advance the clip start and playback offset together
## How Timeline Edits Map To Source
The timeline works directly against your HTML:
- horizontal move updates `data-start`
- vertical move updates `data-track-index`
- right trim updates `data-duration`
- media left trim updates `data-start` and `data-media-start` or `data-playback-start`
- changing row order also updates inline `z-index` so the preview matches the timeline
This means timeline editing stays inspectable and versionable. If you open the file after a move or trim, you can see the exact attributes that changed.
## Current Editing Model By Clip Type
### Generic motion / DOM clips
Examples:
- `div`
- `section`
- `aside`
- GSAP-driven cards, overlays, and text blocks
Supported:
- move the clip later or earlier on the timeline
- move the clip to another row
- trim the end of the clip
Not supported yet:
- true front trim that removes the beginning of the animation itself
### Media clips
Examples:
- `video`
- `audio`
- wrappers backed by `data-media-start` / `data-playback-start`
Supported:
- move the clip later or earlier on the timeline
- move the clip to another row
- trim the end of the clip
- trim the start of the media content itself
## Why Start Trim Is Media-Only
Media clips have a real content-offset model:
- `data-media-start`
- `data-playback-start`
Those attributes let the Studio say:
> Start this clip later on the timeline, and also start reading the media later inside the source.
Generic motion clips do not have an equivalent playback-offset model yet. For a GSAP-driven `section` or `div`, the Studio can:
- move the whole clip later by changing `data-start`
- shorten its visible window by changing `data-duration`
But it cannot yet say:
> Start this animation halfway through its timeline.
That is why generic motion clips do **not** show an interactive left trim handle. The control is hidden instead of implying behavior the runtime cannot currently represent truthfully.
<Note>
A useful mental model is: **move** changes when a clip starts, **right trim** changes when it ends, and **left trim** only appears when the clip can actually skip the beginning of its own content.
</Note>
## Stacking Rule
The Studio follows the normal timeline-editor convention:
- the visually top row renders on top
- lower rows render underneath
If you want captions, lower-thirds, or overlays to sit above other content, place them on a visually higher timeline row.
## Current Limitations
- **No true front trim for generic motion clips yet.**
You can move those clips later in time, but you cannot start their internal animation phase partway through.
- **Layering is still driven by row order plus persisted inline `z-index`.**
If a clip already has custom CSS stacking rules outside the Studio flow, keep that in mind when editing manually.
- **Timeline editing is intentionally scoped.**
The Studio currently focuses on move and trim behavior. It does not yet expose full split, slip, slide, ripple, or roll editing semantics.
## Best Practices
- Use **move** when you want an element to start later but still play its full animation.
- Use **right trim** when you want the element to end sooner.
- Use **media left trim** when you want to remove the beginning of a video or audio clip.
- Put overlays and captions on visually higher rows so they render above base footage.
docs/guides/video-editor-cheatsheet.mdx
-299
View File
@@ -1,299 +0,0 @@
---
title: Video Editor Cheatsheet
description: "Fast reference for video editors and creative people directing agents, cutting timing, tweaking layouts, previewing, and publishing HyperFrames projects."
---
Use this as a fast reference when you are directing agents, cutting timing, making visual layout tweaks, previewing, and sharing HyperFrames projects.
## The Fast Loop
```bash
npx hyperframes init my-video --example blank
cd my-video
npx hyperframes preview
```
Keep the preview running while your agent edits `index.html` or files in `compositions/`. The Studio updates automatically, so you can direct the agent, scrub the result, make manual visual tweaks, then repeat.
Most production work should feel like this:
1. Ask the agent for the first cut, scene, caption pass, transition, or cleanup.
2. Use the Studio preview and timeline to check timing.
3. Use manual DOM editing for Figma-like layout tweaks: select elements, move them, and adjust visual properties directly.
4. Ask the agent to clean up or generalize anything you changed manually.
5. Lint, validate, render, and publish.
Before showing or rendering a project:
```bash
npx hyperframes lint
npx hyperframes check
npx hyperframes render --quality standard --output review.mp4
```
For fast iteration renders, use draft quality:
```bash
npx hyperframes render --quality draft --output draft.mp4
```
For final delivery:
```bash
npx hyperframes render --quality high --fps 30 --output final.mp4
```
## Terminal Shortcuts
Move around projects quickly:
```bash
pwd # show current folder
ls # list files
cd my-video # enter a project folder
cd .. # go up one folder
cd - # jump back to the previous folder
open . # open the current folder in Finder on macOS
code . # open the current folder in VS Code, if installed
```
Common HyperFrames project folders:
```bash
cd assets # source videos, images, audio
cd compositions # reusable scenes and overlays
cd .. # back to the project root
```
Run HyperFrames commands from the project root, where `index.html` lives. If you are not sure where you are, run `pwd` then `ls`. If you see `index.html`, you are in the right place.
## Preview Shortcuts
Start the Studio:
```bash
npx hyperframes preview
```
Use a different port if `3002` is already busy:
```bash
npx hyperframes preview --port 4567
```
Inside the Studio, shortcuts are grouped the same way the playbar's `⌨` panel groups them — playback first, then work-area markers, view controls, and app-level commands. Open the `⌨` panel in the playbar for an in-app cheatsheet, a frame-jump input, and live readouts of the in/out points.
### Playback
| Shortcut | Action |
| --- | --- |
| `Space` | Play or pause |
| `K` | Stop |
| `J` | Play backward (press again to shuttle faster) |
| `L` | Play forward (press again to shuttle faster) |
| `←` / `→` | Step 1 frame |
| `Shift+←` / `Shift+→` | Step 10 frames |
`J` and `L` build the classic NLE shuttle: each repeat ramps the playback rate up. Tap `K` between shuttle bursts to stop. With `K` held, tapping `J` or `L` steps one frame in that direction.
### Work area (in / out points)
| Shortcut | Action |
| --- | --- |
| `I` | Set in-point at the playhead |
| `Shift+I` | Clear in-point |
| `O` | Set out-point at the playhead |
| `Shift+O` | Clear out-point |
| `A` | Jump to in-point (or composition start if unset) |
| `E` | Jump to out-point (or composition end if unset) |
The in and out points define a **work area**. When loop is on, both forward and backward playback loop within those boundaries — useful for tightening a transition or scrubbing a single clip without trimming it. The seek bar renders a teal band between in and out, with tick markers at each point. Clear the markers from the `⌨` panel or with `Shift+I` and `Shift+O`.
### View
| Shortcut | Action |
| --- | --- |
| `Cmd+Scroll` / `Ctrl+Scroll` over the preview | Zoom the preview at the cursor |
### Application
| Shortcut | Action |
| --- | --- |
| `Shift+T` | Show or hide the timeline editor |
| `Cmd+1` / `Ctrl+1` | Switch sidebar to Compositions |
| `Cmd+2` / `Ctrl+2` | Switch sidebar to Assets |
| `Cmd+Z` / `Ctrl+Z` | Undo |
| `Cmd+Shift+Z` / `Ctrl+Shift+Z` / `Ctrl+Y` | Redo |
| `Delete` / `Backspace` | Delete the selected timeline clip or DOM element (when not typing in an editor) |
| `Escape` | Leave a sub-composition or close editor dialogs |
<Tip>
Preview uses the same runtime as rendering, so the visual frame matches the output. If preview stutters on a heavy frame but the render is clean, that is expected — preview plays in real time, render captures one frame at a time.
</Tip>
## Agent-Led Editing
Ask the agent to verify visible changes in the browser. For a user-visible edit, a good handoff is:
```
Run the preview, check it with agent-browser, take a screenshot, and render a draft MP4 to take a look at the frames with ffmpeg.
```
## Manual DOM Editing
In the Studio, you can edit the DOM visually for the final 10% of creative adjustment where dragging is faster than describing.
Use manual DOM editing for:
- moving titles, captions, product cards, logos, and overlays into position
- adjusting size, spacing, opacity, color, and other visual properties
- checking composition balance at an exact timestamp
- making Figma-like placement tweaks
Use agents for:
- creating scenes from scratch
- refactoring repeated visual patterns
- wiring GSAP timelines
- fixing broken timing, layout overflow, or render errors
- turning a manual visual tweak into reusable, clean HTML/CSS
After manual DOM edits, ask the agent to inspect the diff and keep the source clean:
```
I moved the hero title and resized the CTA manually in Studio. Inspect the changes, clean up the CSS if needed, then run lint and validate.
```
## CLI Commands Editors Use Most
| Command | Use it for |
| --- | --- |
| `npx hyperframes init my-video` | Create a new project |
| `npx hyperframes init my-video --example warm-grain` | Start from a visual template |
| `npx hyperframes init my-video --video source.mp4` | Import video and generate captions from the source audio |
| `npx hyperframes capture https://example.com` | Capture a website as source material for a video |
| `npx hyperframes preview` | Open the live Studio preview |
| `npx hyperframes lint` | Catch structural mistakes before preview or render |
| `npx hyperframes check` | Run the composition in headless Chrome to catch runtime errors |
| `npx hyperframes check` | Find text overflow and layout problems across the timeline |
| `npx hyperframes snapshot --at 1,3,5` | Save PNG checks at exact timestamps |
| `npx hyperframes render --output final.mp4` | Render the video |
| `npx hyperframes publish` | Upload the project and get a shareable HyperFrames URL |
| `npx hyperframes doctor` | Check Node.js, FFmpeg, Chrome, Docker, and other dependencies |
| `npx hyperframes docs` | Open local CLI docs |
| `npx hyperframes upgrade` | Check for a newer CLI version |
## Timing Cheatsheet
Every visible timed layer should usually be a clip:
```html
<h1
class="clip"
data-start="0"
data-duration="3"
data-track-index="0"
>
Opening title
</h1>
```
Use these attributes like timeline controls:
| Attribute | Video editor meaning |
| --- | --- |
| `data-start` | When the layer starts |
| `data-duration` | How long the layer stays active |
| `data-track-index` | Timeline track number |
| `data-media-start` | Offset into a media file |
| `data-volume` | Audio volume for an audio or video clip |
| `data-composition-src` | Nested scene or reusable overlay |
For GSAP animation, register one paused timeline per composition:
```html
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.from("#title", { opacity: 0, y: 40, duration: 0.6 });
window.__timelines["main"] = tl;
</script>
```
<Warning>
Render duration comes from `data-duration` on the composition and clips, not from GSAP timeline length. If a video cuts off early, check those timing attributes. Do not pad the timeline with an empty `tl.set()` sentinel.
</Warning>
## Render Presets
| Goal | Command |
| --- | --- |
| Fast iteration | `npx hyperframes render --quality draft --output draft.mp4` |
| Review link | `npx hyperframes render --quality standard --output review.mp4` |
| Final export | `npx hyperframes render --quality high --fps 30 --output final.mp4` |
| Transparent overlay | `npx hyperframes render --format webm --output overlay.webm` |
| Deterministic output | `npx hyperframes render --docker --output final.mp4` |
Use WebM for transparent overlays, captions, and lower thirds. Use `--docker` when you need pixel-consistent output across different machines.
## Publish and Share
Use `publish` when you want to share the editable project, not just the rendered MP4:
```bash
npx hyperframes publish
```
Publish zips the current project, uploads it, and prints a stable `hyperframes.dev` URL. The URL includes a claim token so the recipient can open it, claim the project, and continue editing in the web app.
```bash
npx hyperframes publish ./my-video # publish a specific folder
npx hyperframes publish --yes # skip the confirmation prompt in scripts
```
Publish expects an `index.html` at the project root. It ignores `.git`, `node_modules`, `dist`, `.next`, and `coverage`.
## What Agent Browser Is
`agent-browser` is a browser automation tool for AI agents. It opens Chrome, navigates to your preview, clicks controls, reads page state, and captures screenshots. It is how an agent proves the video preview actually works instead of only saying the code looks right.
Typical verification flow:
```bash
agent-browser open http://localhost:3002
agent-browser snapshot -i
agent-browser screenshot --screenshot-dir ./qa
```
Use it when you want the agent to open the HyperFrames Studio preview, play or scrub the video, click timeline controls, inspect visible UI text, capture screenshots for review, or record proof of a tested flow.
For editor-facing changes, keep `npx hyperframes preview` running, then have the agent use `agent-browser` against the local preview URL.
## Quick Fixes
| Problem | Command or check |
| --- | --- |
| Preview will not start | `npx hyperframes doctor` |
| Port already in use | `npx hyperframes preview --port 4567` |
| Render fails | `npx hyperframes lint` then `npx hyperframes check` |
| Need exact frame checks | `npx hyperframes snapshot --at 1,2.5,5` |
| Text overflows in the frame | `npx hyperframes check` |
| Final render is too slow | Try `--quality draft`, reduce image sizes, or lower `--fps` |
| Need to share editable project | `npx hyperframes publish` |
<CardGroup cols={2}>
<Card title="Prompt Guide" icon="wand-magic-sparkles" href="/prompting/overview">
How to direct AI agents to build better videos
</Card>
<Card title="Timeline Editing" icon="timeline" href="/guides/timeline-editing">
Timing, tracks, and GSAP timeline patterns
</Card>
<Card title="Common Mistakes" icon="circle-exclamation" href="/guides/common-mistakes">
Pitfalls the linter can't catch
</Card>
<Card title="CLI Reference" icon="terminal" href="/packages/cli">
Full command reference
</Card>
</CardGroup>
docs/guides/voice-and-audio.mdx
+127
View File
@@ -0,0 +1,127 @@
---
title: "Use voice, music, sound, and captions"
sidebarTitle: "Voice, sound, and captions"
description: "Build an understandable audio mix, transcribe real speech, and turn it into readable captions."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
Give each audio layer one job. Add another layer only when it helps the viewer
understand or feel the video.
| Layer | Main job |
| ------------- | --------------------------------------------------- |
| Voiceover | Carry the explanation or story |
| Source audio | Preserve speech or sound from existing footage |
| Music | Shape pace, tone, and structure |
| Sound effects | Reinforce a specific action or transition |
| Captions | Make spoken words readable and searchable on screen |
<Frame caption="Play with sound. The same real HyperFrames scene first lets music compete with the line, then gives the voice room while keeping a stable caption rail.">
<DocsVideo
title="A comparison of an obstructed and a clear narration mix"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/audio-mix-proof-v1.jpg"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/audio-mix-proof-v1.mp4"
/>
</Frame>
## Create a voiceover
Give the agent the approved wording and useful voice direction:
```text
Generate the approved SCRIPT.md as a warm, direct voiceover.
Natural pace, no announcer energy. Keep the product-name pronunciation exact.
```
The project can keep the script, audio, and word-level transcript separately.
That lets you regenerate the voice without discarding the timing and caption
work around it.
Listen before building the final edit. Fix wording, pronunciation, or delivery
in the script or voice direction rather than cutting around a bad read.
## Transcribe recorded speech
Transcription creates timed words from an audio or video file. Start with the
automatic engine: it uses Parakeet when installed and falls back to Whisper.
```bash
npx hyperframes transcribe interview.mp4
```
Pass the spoken language when you know it. This filters non-target speech and
lets the Whisper fallback choose a multilingual model when needed.
```bash
npx hyperframes transcribe interview.mp4 --language es
```
For difficult English audio, force the larger English Whisper model. For an
unknown language, use multilingual `large-v3` and let Whisper detect it.
```bash
npx hyperframes transcribe interview.mp4 --engine whisper --model medium.en
npx hyperframes transcribe interview.mp4 --engine whisper --model large-v3
```
Larger models take longer and do not remove the need to read the result.
The command can also import an existing `.srt`, `.vtt`, or supported transcript
JSON file:
```bash
npx hyperframes transcribe subtitles.srt
```
## Turn the transcript into captions
1. Read the complete transcript.
2. Correct names, product terms, numbers, punctuation, and obvious recognition
errors.
3. Group words into short phrases that break on meaning.
4. Open [Captions in Studio](/studio/captions) to inspect the rhythm and adjust
placement, scale, or rotation. Make durable wording, timing, style, and
animation changes in the caption source or ask the agent to update it.
5. Watch once with sound for synchronization and once muted for readability.
Captions should follow what was said. They should not cover a face, product
control, or another important visual. Use emphasis on the few words that carry
the point instead of making every word compete.
For an existing talking-head clip, use [Captions or
recuts](/guides/captions-and-recuts) to choose between plain captions, designed
graphic overlays, and an actual change to the spoken edit.
## Mix for understanding
- Keep voice clear above music.
- Duck music under important speech instead of reducing the whole track
equally.
- Use sound effects for meaningful events, not every movement.
- Avoid cutting words, breaths, or reverb tails accidentally at scene
boundaries.
- Let a deliberate silence remain silent.
- Listen on ordinary headphones and laptop speakers.
When narration drives the project, time visual changes to its real transcript
rather than estimated scene lengths. When music drives the project, use the
[music-video workflow](/guides/music-to-video) and its analyzed structure.
## Review the complete sound pass
- The correct voice and source recordings are used.
- Names, claims, and captions are accurate.
- Speech stays clear through the loudest musical section.
- Effects arrive with the action they support.
- The opening does not surprise the listener with excessive volume.
- Music and ambience finish intentionally instead of stopping at the file edge.
Render a review file and listen without watching once. Audio problems are often
easier to notice when the visuals are not competing for attention.
## Related topics
- [Add captions or repackage talking-head footage](/guides/captions-and-recuts)
- [Edit captions in Studio](/studio/captions)
- [Finish, render, and share](/guides/export-and-share)
docs/guides/website-to-video.mdx
-238
View File
@@ -1,238 +0,0 @@
---
title: Website to Video
description: "Capture any website and turn it into a production video with a single prompt."
---
Give your AI agent a URL and a creative direction. It captures the site, extracts the brand identity, writes a script and storyboard, generates voiceover, builds animated compositions, and delivers a renderable video.
```
"Create a 20-second product launch video from https://linear.app.
Make it feel like an Apple keynote announcement."
```
## Getting Started
<Steps>
<Step title="Install skills">
Skills teach your AI agent how to capture websites and create HyperFrames compositions. Install once — they persist across sessions.
```bash
npx skills add heygen-com/hyperframes
```
Works with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.sh), [Gemini CLI](https://github.com/google-gemini/gemini-cli), and [Codex CLI](https://github.com/openai/codex).
</Step>
<Step title="Prompt your agent">
Open your agent in any directory and describe the video you want:
```
Create a 25-second product launch video from https://example.com. Bold, cinematic, dark theme energy.
```
The agent loads the skill when they see a URL and a video request, and runs the full pipeline — capture, design, strategy & messaging, storyboard + script, voiceover, build, validate.
<Note>
Agents also trigger this skill automatically when they see a URL and a video request.
</Note>
</Step>
<Step title="Preview">
```bash
npx hyperframes preview
```
Opens the video in your browser. Edits reload automatically.
</Step>
<Step title="Render to MP4">
```bash
npx hyperframes render --output my-video.mp4
```
```
✓ Captured 750 frames in 12.4s
✓ Encoded to my-video.mp4 (25.0s, 1920×1080, 6.8MB)
```
</Step>
</Steps>
<Note>
You don't need to run `npx hyperframes capture` manually — the skill instructs the agent to capture as the first step. The capture command is documented [below](#capture-command) for advanced use.
</Note>
## How the Pipeline Works
The skill follows the [Hyperframes pipeline](/guides/pipeline): seven steps, each producing a named artifact that feeds the next.
| Step | Output | What happens |
|------|--------|-------------|
| **Capture** | `capture/` | Extract screenshots, design tokens, fonts, assets, animations |
| **Design** | `DESIGN.md` | Brand reference — colors, typography, component stylings, spacing, iteration guide |
| **Strategy & Messaging** | — | Align on video type, style, the ONE message, and narrative arc |
| **Storyboard + Script** | `STORYBOARD.md` + `SCRIPT.md` | Concept-first storyboard and narration script, written together |
| **VO + Timing** | `narration.wav` + `transcript.json` | TTS audio with word-level timestamps |
| **Build** | `compositions/*.html` | Animated HTML compositions, one per beat |
| **Validate** | Snapshot PNGs + lint/validate pass | Visual verification and runtime checks before delivery |
See [the pipeline guide](/guides/pipeline) for a detailed walkthrough of each step, the contents of every generated file, and how to iterate without re-running the whole pipeline. The structure is useful for any Hyperframes project, not just website captures.
## Video Types
The prompt determines the format. Include a duration and creative direction:
| Type | Duration | Example |
|------|----------|---------|
| Social ad | 10–15s | _"15-second Instagram reel. Energetic, fast cuts."_ |
| Product demo | 30–60s | _"45-second demo showing the top 3 features."_ |
| Feature announcement | 15–30s | _"Feature announcement highlighting the new AI agents."_ |
| Brand reel | 20–45s | _"30-second brand video. Celebrate the design."_ |
| Launch teaser | 10–20s | _"12-second teaser. Super minimal. Just the hook."_ |
<Tip>
Creative direction matters more than format. _"Playful, hand-crafted feel"_ or _"dark, developer-focused, show code"_ shapes the storyboard and drives every visual decision the agent makes.
</Tip>
## Enriching Captures with Gemini Vision
By default, captures describe assets using DOM context — alt text, nearby headings, CSS classes. Add a vision API key for richer AI-powered descriptions.
Create a `.env` file in your project root with **either** a [Gemini API key](https://aistudio.google.com/apikey):
```bash
echo "GEMINI_API_KEY=your-key-here" > .env
```
…**or**, if you don't have Google access, an [OpenRouter key](https://openrouter.ai/keys) — a single API that fronts many vision models:
```bash
echo "OPENROUTER_API_KEY=your-key-here" > .env
```
OpenRouter is used when its key is present (it takes priority if both are set). The default model is `google/gemini-3.1-flash-lite`; override it with `HYPERFRAMES_OPENROUTER_MODEL` (any vision-capable OpenRouter model), just as `HYPERFRAMES_GEMINI_MODEL` overrides the Gemini default.
<Tabs>
<Tab title="Without Gemini">
```
- hero-bg.png — 582KB, section: "Hero", above fold
```
The agent knows the file exists and where it was on the page, but not what it looks like.
</Tab>
<Tab title="With Gemini">
```
- hero-bg.png — 582KB, A gradient wave in purple and blue sweeps
across a dark background, creating an aurora-like effect.
```
The agent knows what the image actually shows, enabling better creative decisions in the storyboard.
</Tab>
</Tabs>
| Tier | Rate limit | Cost per image |
|------|-----------|----------------|
| Free | 5 RPM | Free |
| Paid | 2,000 RPM | ~$0.001 |
A typical capture with 40 images costs about **$0.04** on the paid tier.
## Capture Command
The skill runs capture automatically, but you can run it directly for pre-caching, debugging, or using the data outside of video production.
```bash
npx hyperframes capture https://stripe.com
```
```
◇ Captured Stripe | Financial Infrastructure → capture
Screenshots: 12
Assets: 45
Sections: 15
Fonts: sohne-var
```
| Flag | Default | Description |
|------|---------|-------------|
| `-o, --output` | `./capture` | Output directory (auto-suffixes to `./capture-2/`, `./capture-3/`, … if `./capture/` is taken) |
| `--timeout` | `120000` | Page load timeout in ms |
| `--skip-assets` | `false` | Skip downloading images and fonts |
| `--max-screenshots` | `24` | Maximum screenshot count |
| `--json` | `false` | Output structured JSON for programmatic use |
### What Gets Captured
| Data | Description |
|------|-------------|
| **Screenshots** | Viewport captures at every scroll depth — dynamic count based on page height |
| **Colors** | Pixel-sampled dominant colors + computed styles, including oklch/lab conversion |
| **Fonts** | CSS font families + downloaded woff2 files |
| **Assets** | Images, SVGs with semantic names, Lottie animations, video previews |
| **Text** | All visible text in DOM order |
| **Animations** | Web Animations API, scroll-triggered animations, WebGL shaders |
| **Sections** | Page structure with headings, types, background colors |
| **CTAs** | Buttons and links detected by class names and text patterns |
## Snapshot Command
Capture key frames from a built video as PNGs — verify compositions without a full render:
```bash
npx hyperframes snapshot my-project --at 2.9,10.4,18.7
```
| Flag | Default | Description |
|------|---------|-------------|
| `--frames` | `5` | Number of evenly-spaced frames |
| `--at` | — | Comma-separated timestamps in seconds |
| `--timeout` | `5000` | Ms to wait for runtime to initialize |
## Iterating
You don't need to re-run the full pipeline to make changes:
- **Edit the storyboard** — `STORYBOARD.md` is the creative north star. Change a beat's mood or assets, then ask the agent to rebuild just that beat.
- **Edit a composition** — open `compositions/beat-3-proof.html` directly and tweak animations, colors, or layout.
- **Rebuild one beat** — _"Rebuild beat 2 with more energy. Use the product screenshot as full-bleed background."_
See the [pipeline guide](/guides/pipeline#iterating) for more re-entry patterns.
## Troubleshooting
<AccordionGroup>
<Accordion title="Capture times out">
Increase the timeout for sites with Cloudflare or heavy client-side rendering:
```bash
npx hyperframes capture https://example.com --timeout 180000
```
</Accordion>
<Accordion title="Few assets captured">
Sites using frameworks like Framer lazy-load images via IntersectionObserver. The capture scrolls through the page to trigger loading, but very long pages may miss images near the bottom. Adding a Gemini key improves descriptions of captured assets, but doesn't increase the count.
</Accordion>
<Accordion title="Colors look wrong">
The capture uses pixel sampling combined with DOM computed styles. Dark sites should show dark colors in the palette. Check the scroll screenshots in `<output>/screenshots/` (default `./capture/screenshots/`) to see what the capture actually saw.
</Accordion>
<Accordion title="Agent doesn't find the skill">
Verify skills are installed:
```bash
npx skills add heygen-com/hyperframes
```
Lead your prompt with _"Use the /product-launch-video skill"_ for the most reliable results — site tours route there too. Agents also discover it automatically when they see a URL and a video request.
</Accordion>
</AccordionGroup>
## Next Steps
<CardGroup cols={2}>
<Card title="The Pipeline" icon="list-check" href="/guides/pipeline">
The canonical 7-step structure this workflow follows.
</Card>
<Card title="Quickstart" icon="rocket" href="/quickstart">
New to HyperFrames? Start here.
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Animation patterns used in compositions.
</Card>
<Card title="Rendering" icon="film" href="/guides/rendering">
Render to MP4, MOV, or WebM.
</Card>
</CardGroup>
docs/help.mdx
+133
View File
@@ -0,0 +1,133 @@
---
title: "Get unstuck"
sidebarTitle: "Get unstuck"
description: "Start with what you can see, try the smallest useful fix, and get back to your HyperFrames task."
---
Find the symptom that looks like yours below.
## Studio will not open
The browser never opens, the page is unreachable, or the project does not load.
1. Open a terminal in the HyperFrames project folder.
2. Run `npx hyperframes preview`.
3. Keep that process running while Studio is open.
4. Use the local URL printed in the terminal.
If the command cannot find a project, check that you are inside the project folder rather than its parent.
## Preview is wrong or stale
A change is missing, playback looks old, or the preview is blank. Preview's Code
editor and visual controls save automatically. Storyboard drafts show a Save
action when they still need one. If you edited the project in another
application, save that file first.
1. Wait for the project refresh, then reload Studio once.
2. Check the terminal for a build or runtime error.
3. Run the project checks:
```bash
npx hyperframes lint
npx hyperframes check
```
`lint` checks the composition structure. `check` opens the project in a browser gate and catches runtime, layout, motion, and contrast problems.
## I cannot select or edit something
Selection, canvas controls, timing, or an Inspector field is unavailable.
- Open **Layers** and select the element there when clicking the canvas is difficult.
- Confirm you are in **Preview**, not Storyboard.
- Scrub to a time where the element is actually visible.
- Check whether the visual lives inside a nested composition.
- Ask the agent when the change affects source structure rather than one visible element.
[Open Studio troubleshooting →](/studio/troubleshooting)
## Media is missing or black
An image, video, font, or audio file is absent or does not render. Check that:
- the file still exists inside the project;
- the path and filename capitalisation match;
- the source is local and available during rendering;
- the browser can decode the format;
- the media is visible at the current time;
- the terminal reports no download, decode, or CORS error.
Never rely on a temporary signed URL or a render-time network request. Ask the agent to copy required media into the project.
## Animation is wrong
Motion jumps, drifts, starts at the wrong time, or changes after seeking. First decide whether it happens:
- during normal playback;
- only after scrubbing;
- only in the final render.
That distinction separates a timeline mistake from non-deterministic animation. HyperFrames animation must be seekable: the same frame should look the same every time it is requested.
Run `npx hyperframes check`, then give your agent the smallest affected scene and the exact timestamp.
## Render failed or differs from preview
Export stops, produces the wrong result, or disagrees with Studio.
1. Preserve the complete render error.
2. Run `npx hyperframes check`.
3. Confirm fonts and media are local and load before capture.
4. Check the affected timestamp in Studio.
5. Try the normal MP4 preset before changing codecs or advanced flags.
The [complete troubleshooting guide](/guides/troubleshooting) covers codec, browser, FFmpeg, GPU, HDR, and deployment-specific failures.
## Copy a useful diagnostic
If none of the above resolved it, send this to your agent with the visible facts filled in:
```text
What I was trying to do:
What I clicked or ran:
What I expected:
What happened instead:
Exact error:
Where it happens: Studio / lint / check / render
Does it happen every time?
HyperFrames version:
Operating system:
Affected file or timestamp:
```
Add a screenshot or short recording when the failure is visual. Never paste access tokens, credentials, or private media into a public issue.
## Still stuck
<CardGroup cols={2}>
<Card title="Complete troubleshooting" icon="wrench" href="/guides/troubleshooting">
Less common project, media, animation, rendering, and environment failures.
</Card>
<Card title="Share product feedback" icon="comment" href="/guides/feedback">
Explain a confusing or broken experience with useful context.
</Card>
<Card title="Search GitHub issues" icon="github" href="https://github.com/heygen-com/hyperframes/issues">
Find a known problem, or open a reproducible one.
</Card>
</CardGroup>
## Related topics
- [Troubleshoot a project, preview, or render](/guides/troubleshooting)
- [Recover from a Studio problem](/studio/troubleshooting)
- [Finish and share a video](/guides/export-and-share)
docs/launch-videos.mdx
-73
View File
@@ -1,73 +0,0 @@
---
title: "Launch Videos"
description: "Open-source HyperFrames compositions behind HeyGen's product launch videos — real production projects you can read, run, and remix."
---
The HeyGen team builds its launch videos in HyperFrames. Every composition — including the original HyperFrames announcement, the Timeline Editor reveal, and the Website-to-Video demo — lives in a public repository you can read, run, and remix.
<Card title="hyperframes-launches" icon="github" href="https://github.com/heygen-com/hyperframes-launches">
Open-source HyperFrames compositions behind HeyGen's product launch videos.
</Card>
Want to browse the finished videos first? Start with the [Showcase](/showcase).
This page is the deeper production writeup for the same launch projects.
## What's in there
Each subdirectory is a standalone HyperFrames project — `index.html`, `compositions/`, `assets/`, and a rendered output you can compare against:
| Project | What it shows | Source |
| --- | --- | --- |
| **HyperFrames launch** | The original announcement video — 49.7 s, glass-frame intro, CSS / GSAP / Lottie / shader / Three.js flex section, full narrative arc. | [`hyperframes-launch/`](https://github.com/heygen-com/hyperframes-launches/tree/main/hyperframes-launch) |
| **Website → HyperFrames** | Companion to the [website-to-video](/guides/website-to-video) flow — now handled by `/product-launch-video` — captures a site and animates it. | [`website-to-hyperframes/`](https://github.com/heygen-com/hyperframes-launches/tree/main/website-to-hyperframes) |
| **Timeline Editor launch** | 60 fps reveal video for the HyperFrames Timeline Editor: late-SFX cold open, chat-spiral of fine-tune prompts, editor reveal. | [`timeline-launch/`](https://github.com/heygen-com/hyperframes-launches/tree/main/timeline-launch) |
| **Texture launch** | Texture-mask text + shader-driven background, used as a launch teaser. | [`texture-launch-video/`](https://github.com/heygen-com/hyperframes-launches/tree/main/texture-launch-video) |
| **VFX × HeyGen combined** | Multi-act video chaining a VFX text-cursor scene with the HeyGen iPhone canvas test — useful as a reference for combining two existing projects into one render. | [`vfx-heygen-combined/`](https://github.com/heygen-com/hyperframes-launches/tree/main/vfx-heygen-combined) |
Storyboards (`STORYBOARD.md`), design notes (`DESIGN.md`), and handoff docs (`HANDOFF.md`) sit next to the source so you can see not just the code but the production thinking: VO direction, beat timing, color/style decisions. The structure follows the [Hyperframes pipeline](/guides/pipeline), which documents each artifact in detail.
## Why these are useful
These aren't toy examples. They're the same compositions HeyGen ships in public launch videos, structured the way real production work is structured:
- **Multi-composition projects.** Most launches are 4-8 sub-compositions wired into one root timeline — useful when your `npx hyperframes init --example` starter outgrows a single file.
- **Real adapter mix.** GSAP timelines, Lottie animations, custom shaders, Three.js scenes, and CSS keyframes all coexisting in one render. See how the team [boots multiple adapters](/guides/gsap-animation) inside a single composition.
- **Production-grade timing.** ElevenLabs VO + per-beat SFX + underscore mixed against frame-accurate motion. The storyboards describe the timing decisions; the source shows them executed.
- **No proprietary plugins.** Everything renders with the same `hyperframes render` you have locally — there's no internal-only branch of the engine.
## Cloning
The repo uses Git LFS for video, audio, image, and font assets:
```bash Terminal
brew install git-lfs # macOS — or your platform's git-lfs install
git lfs install
git clone https://github.com/heygen-com/hyperframes-launches.git
cd hyperframes-launches/hyperframes-launch
hyperframes preview # opens the studio for that launch
```
To clone just the source (skip large LFS assets and pull on demand):
```bash Terminal
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes-launches.git
cd hyperframes-launches
git lfs pull --include="hyperframes-launch/assets/*"
```
## Next steps
<CardGroup cols={2}>
<Card title="Examples" icon="layer-group" href="/examples">
Starter templates — what `npx hyperframes init --example` gives you.
</Card>
<Card title="Compositions" icon="diagram-project" href="/concepts/compositions">
The composition data model these launches build on.
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Timeline patterns these projects use.
</Card>
<Card title="Adopters" icon="users" href="/community/adopters">
Other organizations shipping with HyperFrames.
</Card>
</CardGroup>
docs/product-updates.mdx
+53
View File
@@ -0,0 +1,53 @@
---
title: "Product updates"
description: "The HyperFrames changes that matter when you create, edit, and render projects."
---
This page explains meaningful product changes in human terms. Use [Weekly updates](/weekly-updates) for the detailed digest and films, or the [complete release archive](/changelog) for every versioned change.
## July 2026
### Media that previews reliably
Studio, published projects, and the render pipeline can prepare compatible preview versions of difficult video formats automatically. This particularly helps with HEVC and other files that a browser may not decode even though FFmpeg can render them.
What this means:
- fewer black video frames in Studio;
- preview and render use consistent media decisions;
- published projects can include the prepared media;
- projects can opt out when automatic proxying is not wanted.
### A clearer Studio inspector
The flatter Studio inspector is now the normal editing surface. Text, layout, style, motion, media, grade, and element-specific controls are easier to scan without navigating several competing panels.
### More reliable rendering and long-running work
Recent releases improved software-GPU capture, Windows behavior, browser worker reuse, failure diagnostics, audio handling, and composition synchronization.
For most users, the result is simple: fewer cases where a long or media-heavy render stalls or produces a frame that differs from preview.
### Better storyboard and agent review
Storyboard review now has clearer handoff behavior, safer history navigation, and a more explicit relationship between human comments and the next agent pass.
### Safer agent-created motion
Lint and validation now catch more animation problems involving seek order, hidden initial states, conflicting writers, relative values, and SVG drawing.
## Keep your project current
Scaffolded projects can pin a HyperFrames version for reproducibility. Ask your agent to check the project before render-affecting work, or run:
```bash
npx hyperframes@latest upgrade --project . --check
```
Read the [release archive](/changelog) before upgrading a production workflow with custom integrations.
## Related topics
- [Read the complete release archive](/changelog)
- [Make your first video](/quickstart)
- [Review and edit a project in Studio](/studio)
docs/reference/color-grading.mdx
+113
View File
@@ -0,0 +1,113 @@
---
title: "Color grading implementation"
sidebarTitle: "Color grading"
description: "Persist, automate, animate, and spatially isolate media color grading."
---
Use this reference when Studio controls are not enough: you need to write a
grade into HTML, apply it from automation, animate a supported property, or
limit an effect to a composited region. For visual correction and everyday
Studio use, start with [Color grading](/guides/color-grading).
## Persist a grade
Studio and the CLI store the resolved grade in `data-color-grading`:
```html
<video
id="interview"
src="./assets/interview.mp4"
data-color-grading='{"preset":"skin-soft","intensity":0.7}'
></video>
```
Apply the same validated payload from the CLI:
```bash
npx hyperframes media-treatment \
--selector '#interview' \
--grading '{"preset":"skin-soft","intensity":0.7}' \
--apply
```
Add `--dry-run --json` to inspect the change without writing it. Use `--clear`
to remove the treatment.
## Animate a supported property
Nine grading properties expose CSS custom properties that a paused timeline
can tween 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
```
Start the value at identity in both the payload and inline style, then animate
it on the registered timeline:
```js
tl.to(
"#plate",
{
"--hf-color-grading-pixelate": 0.5,
duration: 3,
ease: "power2.inOut",
},
0.3,
);
```
`--hf-color-grading-intensity` scales the primary correction, wheels, curves,
selections, and LUT. It is not a master control for detail and effect families
such as grain, halftone, bloom, tape, or CRT. Animate the specific exposed
property and verify that it moves before relying on it.
## Limit a grade to part of the frame
Grading selects pixels by value, not position. To treat one region, isolate it
as its own media layer:
| Result | Layer stack |
| --- | --- |
| Grade the subject only | Clean original plate, then a graded subject cutout |
| Grade the background only | Graded original plate, then a clean subject cutout |
| Grade one region of the subject | Clean cutout, then a second graded cutout clipped to the region |
```html
<video
src="media/room.mp4"
muted
data-start="0"
data-duration="4"
data-track-index="2"
></video>
<video
src="media/subject.webm"
muted
data-start="0"
data-duration="4"
data-track-index="3"
></video>
<video
src="media/subject.webm"
muted
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>
```
Use the original clip as the background plate. A subject-removed plate leaves a
hole and can create a dark edge beneath a feathered cutout. A fixed `clip-path`
works only when the subject barely moves; real movement needs a tracked matte
produced outside HyperFrames.
docs/showcase.mdx
-262
View File
@@ -1,262 +0,0 @@
---
title: Showcase
description: "Finished HyperFrames videos you can watch, read, run, and remix."
---
The README explains what HyperFrames is. This page shows what you can build with it.
Every project below is a real HyperFrames composition with source you can inspect,
preview, render, and remix.
Want the production notes, repo structure, and clone options behind these videos?
Read [Launch Videos](/launch-videos). This page is the visual gallery; Launch
Videos is the deeper teardown.
## Production Launches
<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-5 my-8">
<div
className="group block overflow-hidden rounded-xl border border-zinc-200 bg-white shadow-sm transition hover:-translate-y-0.5 hover:shadow-lg dark:border-zinc-800 dark:bg-zinc-950"
>
<video
className="aspect-video w-full object-cover bg-zinc-100 dark:bg-zinc-900"
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"
controls
muted
loop
playsInline
preload="metadata"
/>
<div className="p-4">
<div className="text-xs uppercase tracking-wide text-zinc-500">Product launch</div>
<h3 className="mt-1 text-lg font-semibold text-zinc-950 dark:text-zinc-50">HyperFrames launch video</h3>
<p className="mt-2 text-sm text-zinc-600 dark:text-zinc-300">
A full announcement video with CSS, GSAP, Lottie, shader transitions, Three.js,
footage compositing, captions, voiceover, and SFX.
</p>
<a
className="mt-3 block text-sm font-medium text-zinc-950 dark:text-zinc-50"
href="https://github.com/heygen-com/hyperframes-launches/tree/main/hyperframes-launch"
>
View source ->
</a>
</div>
</div>
<div
className="group block overflow-hidden rounded-xl border border-zinc-200 bg-white shadow-sm transition hover:-translate-y-0.5 hover:shadow-lg dark:border-zinc-800 dark:bg-zinc-950"
>
<video
className="aspect-video w-full object-cover bg-zinc-100 dark:bg-zinc-900"
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"
controls
muted
loop
playsInline
preload="metadata"
/>
<div className="p-4">
<div className="text-xs uppercase tracking-wide text-zinc-500">Website to video</div>
<h3 className="mt-1 text-lg font-semibold text-zinc-950 dark:text-zinc-50">Website to HyperFrames demo</h3>
<p className="mt-2 text-sm text-zinc-600 dark:text-zinc-300">
A 41.8-second launch video showing AI agents turning websites into product
promos, social ads, feature showcases, and brand reels.
</p>
<a
className="mt-3 block text-sm font-medium text-zinc-950 dark:text-zinc-50"
href="https://github.com/heygen-com/hyperframes-launches/tree/main/website-to-hyperframes"
>
View source ->
</a>
</div>
</div>
<div
className="group block overflow-hidden rounded-xl border border-zinc-200 bg-white shadow-sm transition hover:-translate-y-0.5 hover:shadow-lg dark:border-zinc-800 dark:bg-zinc-950"
>
<video
className="aspect-video w-full object-cover bg-zinc-100 dark:bg-zinc-900"
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"
controls
muted
loop
playsInline
preload="metadata"
/>
<div className="p-4">
<div className="text-xs uppercase tracking-wide text-zinc-500">Product reveal</div>
<h3 className="mt-1 text-lg font-semibold text-zinc-950 dark:text-zinc-50">Timeline editor launch</h3>
<p className="mt-2 text-sm text-zinc-600 dark:text-zinc-300">
A launch reveal with UI mockups, voiceover, SFX, prompt-driven iteration,
and a narrative arc around fine-tuning rendered video.
</p>
<a
className="mt-3 block text-sm font-medium text-zinc-950 dark:text-zinc-50"
href="https://github.com/heygen-com/hyperframes-launches/tree/main/timeline-launch"
>
View source ->
</a>
</div>
</div>
<div
className="group block overflow-hidden rounded-xl border border-zinc-200 bg-white shadow-sm transition hover:-translate-y-0.5 hover:shadow-lg dark:border-zinc-800 dark:bg-zinc-950"
>
<video
className="aspect-video w-full object-cover bg-zinc-100 dark:bg-zinc-900"
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"
controls
muted
loop
playsInline
preload="metadata"
/>
<div className="p-4">
<div className="text-xs uppercase tracking-wide text-zinc-500">Title system</div>
<h3 className="mt-1 text-lg font-semibold text-zinc-950 dark:text-zinc-50">Texture launch</h3>
<p className="mt-2 text-sm text-zinc-600 dark:text-zinc-300">
Texture-mask typography, shader backgrounds, and transition-heavy title
design built as a full HyperFrames composition.
</p>
<a
className="mt-3 block text-sm font-medium text-zinc-950 dark:text-zinc-50"
href="https://github.com/heygen-com/hyperframes-launches/tree/main/texture-launch-video"
>
View source ->
</a>
</div>
</div>
<div
className="group block overflow-hidden rounded-xl border border-zinc-200 bg-white shadow-sm transition hover:-translate-y-0.5 hover:shadow-lg dark:border-zinc-800 dark:bg-zinc-950"
>
<video
className="aspect-video w-full object-cover bg-zinc-100 dark:bg-zinc-900"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/vfx-heygen-preview.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/vfx-heygen-poster.jpg"
controls
muted
loop
playsInline
preload="metadata"
/>
<div className="p-4">
<div className="text-xs uppercase tracking-wide text-zinc-500">VFX system</div>
<h3 className="mt-1 text-lg font-semibold text-zinc-950 dark:text-zinc-50">VFX x HeyGen combined</h3>
<p className="mt-2 text-sm text-zinc-600 dark:text-zinc-300">
A rendered effects reel combining Three.js, HTML-in-canvas, generated
media, text animation, and product UI beats.
</p>
<a
className="mt-3 block text-sm font-medium text-zinc-950 dark:text-zinc-50"
href="https://github.com/heygen-com/hyperframes-launches/tree/main/vfx-heygen-combined"
>
View source ->
</a>
</div>
</div>
<a
className="group block overflow-hidden rounded-xl border border-zinc-200 bg-white shadow-sm transition hover:-translate-y-0.5 hover:shadow-lg dark:border-zinc-800 dark:bg-zinc-950"
href="https://www.hyperframes.dev/"
>
<div className="aspect-video w-full bg-zinc-950 p-6 text-white">
<div className="flex h-full flex-col justify-between">
<div className="text-sm text-zinc-400">Community playground</div>
<div>
<div className="text-3xl font-semibold">Open. Remix. Publish.</div>
<p className="mt-3 max-w-md text-sm text-zinc-300">
Use hyperframes.dev to preview community projects, share your own,
and keep iterating in the browser.
</p>
</div>
</div>
</div>
<div className="p-4">
<div className="text-xs uppercase tracking-wide text-zinc-500">Playground</div>
<h3 className="mt-1 text-lg font-semibold text-zinc-950 dark:text-zinc-50">hyperframes.dev</h3>
<p className="mt-2 text-sm text-zinc-600 dark:text-zinc-300">
A hosted community surface for previewing, iterating, sharing, and
rendering HTML-native video projects.
</p>
<div className="mt-3 text-sm font-medium text-zinc-950 dark:text-zinc-50">Open playground -></div>
</div>
</a>
</div>
## Go Deeper
<CardGroup cols={2}>
<Card title="Launch Videos" icon="rocket" href="/launch-videos">
Read the production notes, project structure, and Git LFS clone options behind
these launches.
</Card>
<Card title="Source Repository" icon="github" href="https://github.com/heygen-com/hyperframes-launches">
Open the full collection of HeyGen launch compositions.
</Card>
</CardGroup>
## Start from a Use Case
| If you want to build... | Start here | Why |
| --- | --- | --- |
| A product announcement | [HyperFrames launch](https://github.com/heygen-com/hyperframes-launches/tree/main/hyperframes-launch) | Shows a complete launch narrative with multiple animation runtimes. |
| A website-to-video product tour | [Website to HyperFrames](https://github.com/heygen-com/hyperframes-launches/tree/main/website-to-hyperframes) | Shows captured website footage, agent prompts, captions, VO, and SFX. |
| A product UI reveal | [Timeline editor launch](https://github.com/heygen-com/hyperframes-launches/tree/main/timeline-launch) | Shows mockups, interface closeups, and feature storytelling. |
| A texture or title-card system | [Texture launch](https://github.com/heygen-com/hyperframes-launches/tree/main/texture-launch-video) | Shows expressive text treatment and shader-backed motion. |
| An effects-heavy launch reel | [VFX x HeyGen combined](https://github.com/heygen-com/hyperframes-launches/tree/main/vfx-heygen-combined) | Shows Three.js, generated media, and HTML-in-canvas in one render. |
| A starter project | [Examples](/examples) | Scaffold working templates with `npx hyperframes init --example <name>`. |
| A reusable motion part | [Catalog](/catalog/blocks/data-chart) | Add blocks and components to an existing composition. |
## Run One Locally
These launch projects use Git LFS for video, audio, image, and font assets.
Install Git LFS before cloning; otherwise the preview opens with pointer files
instead of the real media.
```bash Terminal
brew install git-lfs # macOS, or your platform's git-lfs install
git lfs install
git clone https://github.com/heygen-com/hyperframes-launches.git
cd hyperframes-launches/website-to-hyperframes
npx hyperframes preview
npx hyperframes render
```
To skip pulling every launch asset up front, clone first and pull only the
project you want to run:
```bash Terminal
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes-launches.git
cd hyperframes-launches
git lfs pull --include="website-to-hyperframes/**"
cd website-to-hyperframes
npx hyperframes preview
```
The launch projects include source HTML, sub-compositions, assets, rendered
outputs, and production notes such as `STORYBOARD.md`, `DESIGN.md`, and
`HANDOFF.md` where available.
## Next Steps
<CardGroup cols={2}>
<Card title="Starter Examples" icon="layer-group" href="/examples">
Scaffold remixable templates with `npx hyperframes init --example`.
</Card>
<Card title="Community Playground" icon="play" href="https://www.hyperframes.dev/">
Open shared projects, preview videos, and publish your own.
</Card>
<Card title="Website to Video" icon="globe" href="/guides/website-to-video">
Turn websites into rendered videos with an agent-friendly workflow.
</Card>
<Card title="Pipeline Guide" icon="diagram-project" href="/guides/pipeline">
Learn the storyboard, script, design, and render loop behind larger videos.
</Card>
</CardGroup>
docs/studio/animation.mdx
+152
View File
@@ -0,0 +1,152 @@
---
title: "Edit animation and keyframes"
sidebarTitle: "Animation and keyframes"
description: "Read existing motion, add and retime keyframes, record gestures, shape paths, and handle generated animation."
---
Animation changes a property over time. A keyframe records an important value
at a particular moment; Studio draws editable keyframes as diamonds on the
timeline.
<div className="not-prose my-7 max-w-2xl overflow-hidden rounded-xl border border-zinc-200 bg-zinc-950 dark:border-zinc-800">
<video
className="aspect-video w-full object-cover"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-animation-keyframe-loop-v1.mp4#t=0.1"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-animation-keyframe-loop-v1.jpg"
autoPlay
muted
loop
playsInline
preload="metadata"
/>
<div className="px-3 py-2 text-sm text-zinc-600 dark:text-zinc-400">
Select an element, place the playhead, and add a keyframe.
</div>
</div>
## Start by reading the existing movement
1. Select the animated element on the canvas, in Layers, or on the timeline.
2. Expand its animation properties.
3. Move the playhead across the existing diamonds.
4. Play from before the movement until after it ends.
Identify the actual problem before editing: the movement may start too late,
take too long, travel along the wrong route, or accelerate in the wrong way.
Those need different changes.
## Add or change a keyframe
Move the playhead to the moment you want to define. Use the keyframe control in
the timeline toolbar, or press **K** while the selected element supports
keyframes. Then change the property that should animate.
To change existing motion:
- drag a diamond earlier or later to retime it;
- change the property value at that keyframe;
- press **Delete** to remove a selected keyframe;
- press **H** to switch selected keyframes between hold and bezier behavior;
- press **U** to expand or collapse the selected element's keyframe properties.
`K` is context-sensitive: it adds a keyframe when an editable animated
selection can use it; otherwise it remains the playback stop shortcut.
## Use auto-keyframe deliberately
Auto-keyframe starts enabled. While it is on, a supported canvas or Inspector
change at the current playhead time is recorded as animation.
This is useful when you want to pose the element at two moments:
1. move the playhead to the first moment and set the first value;
2. move to the second moment and set the next value;
3. play through the movement Studio created between them.
Turn auto-keyframe off before correcting a layout value that should remain
constant throughout the clip.
## Retime before redesigning
Moving keyframes closer together makes the change happen faster. Moving them
farther apart gives the viewer more time to follow it.
Judge the edit inside the scene. A movement that looks smooth by itself can
still arrive too late for the narration or overlap the next action.
## Shape the easing
Easing controls how a value accelerates and slows between keyframes.
- Use a hold when the value should change without interpolation.
- Start with an easing preset when you want a familiar acceleration pattern.
- Use the speed curve when the preset is close but the start, stop, or
overshoot still feels wrong.
Do not choose easing from the curve alone. Play the entrance, readable hold,
and exit together.
## Shape a motion path
Position keyframes can expose a path over the canvas.
- Drag a point to change the route.
- Adjust a segment when the movement should curve.
- Keep a straight route when direct movement is clearer.
- Use auto-rotate only when the element should face its direction of travel.
- Hold **Option/Alt** while dragging the element to move the complete path.
Add path points only when they make the intended route easier to control.
## Record a movement you can perform
Gesture recording is useful when the motion is easier to demonstrate than to
describe.
1. Select the element.
2. Choose **Record gesture** or press **R**.
3. Move the pointer to perform the motion.
4. Press **R** again to stop.
5. Play the result and refine the generated keyframes.
During recording, drag captures position and scroll captures depth. The
built-in shortcuts panel lists modifiers for rotation, 3D rotation, opacity,
and scale.
Recorded motion is a starting performance, not automatic polish. Simplify a
noisy path and retime it against the rest of the scene.
## Edit animation created by an agent or helper
Studio can display motion whose values were generated by a loop, helper, or
runtime expression, but it cannot always rewrite that source safely.
- **Unroll to edit** rewrites supported helper- or loop-generated motion as
explicit tweens that Studio can edit.
- **Computed value — edit it in the Code tab** means the value must be changed
in source.
- When the intent is easier to state than the implementation, copy the element
context to your agent and describe the result you want preserved.
```text
Keep the same curved route, but make the movement finish with the voiceover
instead of two beats later.
```
## Review the finished motion
- The motion should reveal, direct attention, show change, or connect states.
- Important text needs enough still time to be read.
- Several unrelated movements should not compete in the same moment.
- Check the transition into and out of the scene.
- Run the project preview at the intended frame rate before approving it.
For source-level GSAP behavior and the seekable timeline contract, use the
[developer animation guide](/guides/gsap-animation). For every implemented
keyboard action, use [Studio shortcuts](/studio/shortcuts).
## Related topics
- [Edit timing on the timeline](/studio/timeline)
- [Edit the frame](/studio/canvas)
- [Use Studio keyboard shortcuts](/studio/shortcuts)
docs/studio/assets-and-blocks.mdx
+63
View File
@@ -0,0 +1,63 @@
---
title: "Use Assets and Catalog"
description: "Import project media, reuse existing files, and add ready-made visuals."
---
Use **Assets** for media files. Use **Catalog** for reusable visual scenes and components.
<div className="not-prose my-7 max-w-2xl overflow-hidden rounded-xl border border-zinc-200 bg-zinc-950 dark:border-zinc-800">
<video
className="aspect-video w-full object-cover"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-assets-catalog-loop-v1.mp4#t=0.1"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-assets-catalog-loop-v1.jpg"
autoPlay
muted
loop
playsInline
preload="metadata"
/>
<div className="px-3 py-2 text-sm text-zinc-600 dark:text-zinc-400">
Import project media, then add a compatible Catalog scene at the playhead.
</div>
</div>
## Import an asset
1. Open **Assets**.
2. Choose **Import media**, or drop files into the panel.
3. Preview it before adding it to the project.
4. Drag it to the timeline or use it from the relevant inspector control.
Keep clear filenames. `product-dashboard-dark.png` is easier to reuse than `Screenshot 42.png`.
## Reuse project assets
**This project** contains the files available to the open project. **All projects** is a read-only
index of the global `~/.media` cache, where resolved media can be found again across projects. It is
not a file manager, so files cannot be deleted or replaced from that view.
If a large video is still preparing a preview or proxy, wait for that process before judging playback performance.
## Add a Catalog item
1. Open **Catalog**.
2. Browse or search for the visual you need.
3. Preview the result.
4. If the item supports direct insertion, choose **Add** to place it at the current time.
5. Otherwise, copy the generated prompt into your agent chat.
6. Replace sample content and match the project’s timing and design.
Not every Catalog item can be inserted directly. Some are patterns that an agent adapts to the current composition.
Browse the full [Catalog](/catalog) when you want to compare categories and individual examples.
<Tip>
Reusable does not mean finished. Remove sample content and decorative motion that does not support
your story.
</Tip>
## Related topics
- [Work with media](/guides/media)
- [Browse the Catalog](/catalog)
- [Turn values into reusable variables](/studio/variables)
docs/studio/canvas.mdx
+133
View File
@@ -0,0 +1,133 @@
---
title: "Edit the frame"
sidebarTitle: "Edit the frame"
description: "Select the right element, change its content or design, arrange layers, and verify the result in motion."
---
Use this workflow when you can point to the thing that needs to change in the
current frame.
<Frame caption="A selected headline exposes canvas handles and the Design controls that apply to it.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/canvas-v1.jpg"
alt="HyperFrames Studio with a headline selected on the canvas and its Design controls open"
/>
</Frame>
## 1. Pause where the element is visible
Move the playhead to a frame where you can judge the element and its
surroundings. If it enters or exits, pause after the movement has settled.
Click the element on the canvas. When the wrong item is selected, open
**Inspector → Layers** and choose it there. Layers is also the reliable way to
find something that is hidden, outside the frame, or inside a group.
The selection stays connected across the canvas, Inspector, and timeline.
## 2. Change only what is wrong
Use the canvas for spatial edits:
- drag inside the selection to move it;
- drag a handle to resize it;
- use the rotation control for supported elements;
- crop an image or video to change the visible area without moving its box;
- use arrow keys for a small nudge;
- watch the guides when the element snaps to the frame or another element.
Open **Design** for exact properties. The sections shown depend on the selected
element.
| Need | Look in Design |
| -------------------------------------------------------- | -------------- |
| Change wording or typography | Text |
| Set position, size, spacing, or alignment | Layout |
| Change fill, border, radius, shadow, opacity, or effects | Style |
| Replace or fit an image, video, or audio source | Media |
| Adjust supported perspective or transforms | 3D |
| Correct an image or video's appearance | Grade |
Do not change content, layout, style, timing, and motion at once. Make one kind
of edit, play it, then decide whether another edit is still needed.
## 3. Work with overlaps and groups
Layers shows the visual structure of the current composition. Dragging a layer
changes its stacking order when the wrong item covers another. Timeline tracks
organize time; they are not automatically the same as visual stacking order.
Group elements that should move and remain organized together. Use
**Command/Ctrl + G** to group and **Command/Ctrl + Shift + G** to ungroup.
A nested composition is a reusable scene inside another composition. Open the
nested composition when the change should affect that scene itself. Stay in
the parent when you only need to change where or when the scene appears.
## 4. Decide whether the edit should animate
Auto-keyframe starts enabled in the timeline toolbar.
- Turn it **off** for a correction that should stay constant for the clip.
- Leave it **on** when changing the property at the current playhead time
should create motion.
After an animated edit, look for the new keyframe diamond and play through the
complete movement. Use [Animation and keyframes](/studio/animation) when you
need to retime or shape it.
<Warning>
A position change made at one frame can look like a normal layout fix while becoming an unintended
animation during playback. Check auto-keyframe before dragging.
</Warning>
## 5. Replace media without breaking the scene
Select the image, video, or audio element and replace its source from **Media**
or **Assets**. Then check:
- crop and fit;
- visible duration;
- playback start, rate, loop, and volume when those controls apply;
- the transition into and out of the clip.
A new file can have a different aspect ratio or duration even when the source
path changes successfully.
## 6. Play the result, not just the frame
Play from before the edit until after it. Check that:
- the element stays readable at the final output size;
- it does not cross or cover another important element;
- its entrance and exit still work;
- text remains readable over every background it crosses;
- undo returns the project to the expected state if the change was wrong.
## When Studio cannot edit it safely
Some generated, nested, or source-controlled elements do not expose every
property for direct editing. In order:
1. select the exact parent or child in Layers;
2. open the nested composition;
3. check whether Design exposes the property;
4. use **Ask agent** or copy the selected context;
5. edit the source only when you understand the project structure.
Ask the agent for a broad change instead of forcing it through several manual
edits:
```text
Keep this scene's content, but rebuild its layout so the product remains
readable at mobile-video size.
```
Use [the timeline](/studio/timeline) when the problem is when something happens,
or [Animation and keyframes](/studio/animation) when the problem is how it moves.
## Related topics
- [Edit timing on the timeline](/studio/timeline)
- [Edit animation and keyframes](/studio/animation)
- [Work with source and an agent](/studio/source)
docs/studio/captions.mdx
+54
View File
@@ -0,0 +1,54 @@
---
title: "Edit captions"
description: "Review captions in context and understand which Studio edits are saved today."
---
Studio switches to caption editing when the open composition contains `.caption-group` elements and their caption source can be resolved.
<Frame caption="A selected word connects the canvas, caption rail, and the controls that Studio currently saves.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio-captions-panel-v1.jpg"
alt="HyperFrames Studio with one caption word selected, word blocks in the caption rail, and position and transform controls"
/>
</Frame>
## Adjust a word on the canvas
1. Select a caption word. Hold **Shift** to select more than one.
2. Drag the selection, resize it, or rotate it on the canvas.
3. Use the arrow keys for a 1-pixel nudge, or **Shift** + arrow for 10 pixels.
4. Reload the project once to confirm the override was saved.
Position, scale, rotation, color, opacity, font size, weight, and family overrides
are written to `caption-overrides.json` after a short delay.
## Use the timeline to inspect the rhythm
The caption timeline shows one block per word. Select a block to find the same word on the canvas. You can drag an edge to audition different start or end timing, and double-click a word to preview a new group boundary.
<Warning>
Timing changes, group splits, and Animation-tab changes are live-preview tools in the current
Studio. They do not survive a reload. Fix words, durable timing, group structure, and reusable
caption behavior in the caption source or ask the agent to update it, then reopen the project.
</Warning>
This distinction matters: Studio can save word-level visual overrides, but it is
not yet a complete caption-source editor.
Browse [caption components](/catalog/components/caption-highlight) when the source needs a reusable visual treatment.
## Review the result
- Watch with sound.
- Watch once with sound muted.
- Check names and important words against the audio.
- Check captions against cuts, overlays, and changing backgrounds.
- Confirm the final caption disappears cleanly.
If a preview-only edit fixed a real problem, move that change into the source before rendering.
## Related topics
- [Create captions or recut talking-head footage](/guides/captions-and-recuts)
- [Work with voice, sound, and captions](/guides/voice-and-audio)
- [Browse reusable caption treatments](/catalog/components/caption-highlight)
docs/studio/export.mdx
+55
View File
@@ -0,0 +1,55 @@
---
title: "Export and manage renders"
description: "Choose a format, quality, resolution, and frame rate, then manage the render queue."
---
Click **Export** in the top bar when the project is ready for a finished file. Studio opens the **Renders** panel.
<Frame caption="The Renders panel contains delivery settings and the render queue.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/export-v1.jpg"
alt="The Renders panel with format, resolution, frame rate, and quality controls"
/>
</Frame>
## Choose the format
- **MP4** — the normal choice for sharing and uploading.
- **WebM** — useful for web delivery and some transparency workflows.
- **MOV (ProRes)** — useful when another editing or production workflow expects a high-quality intermediate.
Choose the format required by the destination rather than the one with the most options.
## Choose quality and size
Use the project’s authored resolution unless you need a specific delivery size.
The resolution control includes **Auto** and compatible preset sizes. Increasing resolution makes the render slower and the file larger; it does not repair low-resolution source media.
Choose 24, 30, or 60 fps only when the destination or source material requires it. MOV uses a fixed ProRes quality, so the separate quality choice is hidden for that format.
## Start and manage a render
The render queue shows active and completed jobs. From there you can:
- watch progress;
- cancel an active job;
- download a completed file;
- delete an unwanted result;
- choose **Hide finished** to remove completed rows from the list without deleting their files.
## Before you send the file
1. Open the exported file itself.
2. Watch the beginning and end.
3. Check captions, cuts, audio, and the most complex transition.
4. Confirm dimensions and duration.
5. Use a clear filename that identifies the version.
If a render fails, keep the error and open [Studio troubleshooting](/studio/troubleshooting).
## Related topics
- [Finish, render, and share a project](/guides/export-and-share)
- [Render from the command line](/guides/rendering)
- [Recover from a Studio problem](/studio/troubleshooting)
docs/studio/index.mdx
+168
View File
@@ -0,0 +1,168 @@
---
title: "Work on a project in Studio"
sidebarTitle: "Studio overview"
description: "Open a HyperFrames project, understand the workspace, make a safe edit, and finish a version."
---
import { DocsVideo } from "/snippets/docs-video.jsx";
<div className="hf-docs-video-frame">
<DocsVideo
title="A narrated tour of a real HyperFrames Studio project"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-front-door-v2.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-front-door-v2.jpg"
/>
</div>
Studio is the visual editor for the same HTML project your agent and the CLI
use. The Reference Project from the first-video guide opens here without an
import or conversion. Open any project folder, then run:
```bash
npx hyperframes preview
```
## Know the workspace
<Frame caption="Preview keeps project files, the live frame, the Inspector, and time-based editing in one workspace.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/overview-v1.jpg"
alt="HyperFrames Studio Preview showing project tools, a live composition, the Inspector, and the timeline"
/>
</Frame>
- **Storyboard** shows the planned sequence, direction, voiceover, status, and
comments. Use it to review the story.
- **Preview** shows the built project. The live frame is in the middle, the
timeline is below, project tools are on the left, and the Inspector is on the
right.
- **Code**, **Comps**, **Assets**, and **Catalog** expose the project source,
compositions, media, and reusable visuals. **Design**, **Layers**,
**Variables**, and **Renders** control the selected work.
You do not need to learn every panel. Choose the surface that matches the
problem in front of you.
| You want to change | Start with |
| ----------------------------------------------- | -------------------------------- |
| Something visible in the current frame | Canvas, then Design or Layers |
| When something appears or how long it stays | Timeline |
| One movement or transition | Animation controls and keyframes |
| The story, several scenes, or project structure | Your agent |
## Make one safe edit
Pause where the problem is visible. Click the element on the canvas, or choose
it in **Layers** when several elements overlap. Then change only the property
you meant to change.
<div style={{ maxWidth: "42rem", margin: "1.5rem auto" }}>
<Frame caption="The canvas selects the visible element; Design exposes the properties Studio can edit safely.">
<video
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-direct-edit-loop-v2.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-direct-edit-loop-v2.jpg"
alt="Selecting an element and changing it in HyperFrames Studio"
aria-label="Selecting an element and changing it in HyperFrames Studio"
autoPlay
muted
loop
playsInline
preload="metadata"
/>
</Frame>
</div>
Use the canvas to move, resize, rotate, or crop a supported element. Use
**Design** for text, layout, style, media, motion, 3D, or color controls that
apply to the selection. Play through the surrounding moment before accepting
the change; a correct still frame can still create a collision in motion.
<Warning>
Auto-keyframe starts enabled. Turn it off before a normal layout correction that should stay
constant. Leave it on only when the change at the current playhead time should become animation.
</Warning>
For the complete visible-edit workflow, continue to [Edit the
frame](/studio/canvas).
## Change time on the timeline
Drag a clip to move it earlier or later. Drag an edge to change its duration.
Use the razor only when one supported clip must become two.
<div style={{ maxWidth: "42rem", margin: "1.5rem auto" }}>
<Frame caption="Timing changes stay visible beside the frame and neighboring tracks.">
<video
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-timing-loop-v2.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-timing-loop-v2.jpg"
alt="Adjusting clip timing in the HyperFrames Studio timeline"
aria-label="Adjusting clip timing in the HyperFrames Studio timeline"
autoPlay
muted
loop
playsInline
preload="metadata"
/>
</Frame>
</div>
Move the playhead through the surrounding cut after every timing change. Use
[the timeline guide](/studio/timeline) when you need trimming, splitting,
beats, nested scenes, or multi-item editing.
## Hand a broader change back to the agent
Studio is best for a change you can point at. Ask the agent when the request
affects the story, several scenes, source research, or unfamiliar project code.
Use **Ask agent** or **Copy to Agent** when Studio offers it, then add the human
intent that the copied context cannot know:
```text
Make the opening feel faster, but keep the current narration and final scene.
```
The agent and Studio edit the same source. There is no export or conversion
between them.
## Check and render the version
Watch the project from the beginning, run **Lint**, and fix the reported issues.
Before delivery, run the project-level browser gate as well:
```bash
npx hyperframes check
```
Then render through Studio, your agent, or the CLI. Open the exported file and
watch it once before sharing it.
<div style={{ maxWidth: "42rem", margin: "1.5rem auto" }}>
<Frame caption="Studio queues and monitors a render from the same project.">
<video
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-check-render-loop-v2.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-check-render-loop-v2.jpg"
alt="Queuing and monitoring a render in HyperFrames Studio"
aria-label="Queuing and monitoring a render in HyperFrames Studio"
autoPlay
muted
loop
playsInline
preload="metadata"
/>
</Frame>
</div>
## Related topics
<CardGroup cols={2}>
<Card title="Edit the frame" icon="crop" href="/studio/canvas">
Select, style, arrange, group, and replace visible elements.
</Card>
<Card title="Edit timing" icon="timeline" href="/studio/timeline">
Trim, split, move, and retime clips on the project timeline.
</Card>
<Card title="Finish and share" icon="circle-check" href="/guides/export-and-share">
Review, validate, render, and deliver the project.
</Card>
</CardGroup>
docs/studio/shortcuts.mdx
+78
View File
@@ -0,0 +1,78 @@
---
title: "Keyboard shortcuts"
description: "Use Studio shortcuts for playback, editing, navigation, and project actions."
---
Shortcuts depend on the active area. The table below covers the shortcuts
implemented by the current Studio player, canvas, and timeline.
## Playback
| Shortcut | Action |
| --- | --- |
| Space | Play or pause |
| J / K / L | Play backward, stop, or play forward |
| Left / Right arrow | Step one frame, or nudge a selected canvas element horizontally |
| Up / Down arrow | Nudge a selected canvas element vertically |
| Shift + arrow | Step ten frames horizontally, or nudge a selected element farther |
| M | Mute or unmute |
| Shift + L | Toggle loop playback |
| I / O | Set the work-area in or out point |
| Shift + I / Shift + O | Clear the in or out point |
| A / E | Jump to the in or out point |
| F | Toggle fullscreen |
## Editing
| Shortcut | Action |
| --- | --- |
| V | Selection tool |
| B | Toggle the razor tool |
| S | Split the selected eligible clip at the playhead |
| N | Toggle timeline snapping |
| Command/Ctrl + Z | Undo |
| Command/Ctrl + Shift + Z | Redo |
| Command/Ctrl + C / V / X | Copy, paste, or cut the selected element |
| Command/Ctrl + G | Group selected elements |
| Command/Ctrl + Shift + G | Ungroup |
| Delete | Delete the selected keyframe or element |
The selected area decides what a shared shortcut does. For example, arrow keys nudge a selected canvas element; without a nudgeable selection they step through frames.
## Keyframes and recording
| Shortcut | Action |
| --- | --- |
| K | Add a keyframe when the current selection supports it |
| H | Toggle hold or bezier for selected keyframes |
| U | Expand or collapse the selected element’s keyframe properties |
| Left / Right arrow | Nudge selected keyframes by one frame |
| Shift + Left / Right arrow | Nudge selected keyframes by ten frames |
| R | Start or stop gesture recording |
During gesture recording, drag records position, scroll records depth,
Shift-drag records 3D rotation, Option/Alt-drag records rotation, and
Command/Ctrl-drag or scroll records opacity or scale.
## Canvas and panels
| Shortcut | Action |
| --- | --- |
| G | Toggle the canvas grid |
| Command/Ctrl + 1 | Open Compositions |
| Command/Ctrl + 2 | Open Assets |
| Option/Alt + drag | Move an entire animation path |
| Shift + drag a resize handle | Resize uniformly |
<Warning>
A shortcut should not fire while you are typing into a text or source field. If the wrong area has focus, click the canvas or timeline before using an editing shortcut.
</Warning>
Use the **Shortcuts and tools** button beside the playback controls for the
built-in shortcut list, work-area controls, and jump-to-frame field.
## Related topics
- [Edit the frame](/studio/canvas)
- [Edit timing on the timeline](/studio/timeline)
- [Edit animation and keyframes](/studio/animation)
docs/studio/slideshows.mdx
+64
View File
@@ -0,0 +1,64 @@
---
title: "Build a slideshow"
description: "Shape the main presentation, then add reveals, notes, branches, and hotspots where they help."
---
A slideshow is a live, navigable presentation—not one linear video. The **Slideshow** tab appears when the active composition contains a HyperFrames slideshow manifest.
<Frame caption="The Slideshow panel builds the main route from real scenes before optional branches are added.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio-slideshow-panel-v1.jpg"
alt="HyperFrames Studio showing three main-line slides in the Slideshow panel beside the deck timeline"
/>
</Frame>
## Build the main path
Start with the route everyone should see:
1. In **Slides**, check the scenes that belong in the main presentation.
2. Use the arrows to put them in order.
3. Select each slide and confirm that it makes one complete point.
4. In **Slide Inspector**, add speaker notes that help the presenter rather than repeat the slide.
Studio saves slideshow changes into the project’s manifest. Notes save after a short pause; other edits save immediately and participate in project history.
## Add fragment reveals
Move the playhead to the moment when the presentation should pause, then click **Mark** in Slide Inspector. That time becomes a fragment hold-point for the selected slide.
Use fragments when the presenter needs to reveal part of an idea before advancing. A slide does not need a hold-point for every bullet.
## Add an optional path
Branches keep optional detail outside the main story:
1. Open **Branches**, name a branch, and assign its slides.
2. On the slide where the choice appears, select the visible button or object on the canvas.
3. Open **Hotspot Tool**, choose the target branch, add a useful label, and click **Make hotspot**.
4. Keep a clear route back to the main story.
Deleting a branch removes that branch definition and every hotspot that points to it, so Studio asks for confirmation first. The source scenes remain in the project.
## Test it as a presentation
Run the presenter locally:
```bash
npx hyperframes present <project-directory>
```
Test next and previous navigation, every fragment, every hotspot, every branch, and the return path. Click **Present** or press **P** to open the synchronized audience view.
<Note>
A slideshow stays interactive. If the result should simply play from beginning to end as an MP4,
use a [video workflow](/workflows) instead.
</Note>
To create the deck with an agent before refining it here, follow [Create an interactive presentation](/guides/slideshow).
## Related topics
- [Create an interactive presentation](/guides/slideshow)
- [Use variables and templates](/studio/variables)
- [Work with source and an agent](/studio/source)
docs/studio/source.mdx
+121
View File
@@ -0,0 +1,121 @@
---
title: "Work with source and an agent"
sidebarTitle: "Source and agent"
description: "Edit project files, diagnose a failed check, and hand the right context to an AI agent."
---
Studio, your agent, and the CLI work on the same project files. Use **Code** for
a small source change you understand. Use the agent when the change crosses
files, affects project structure, or starts from an unfamiliar failure.
## Choose the smallest safe surface
| Change | Best starting point |
| ---------------------------------------------------------------- | ------------------------------ |
| Visible text, layout, style, media, timing, or supported motion | Canvas, Inspector, or timeline |
| One known value in one known file | Code |
| Story, several scenes, generated animation, or project structure | Agent |
| A reported lint problem with a clear direct fix | Studio or Code |
| An unfamiliar failure or a fix spanning files | Copy to Agent |
The choice is about the change, not a permanent workflow. You can move between
the surfaces without exporting or converting the project.
## Make a focused source edit
1. Open **Code** in the left sidebar.
2. Select the exact file in the project tree.
3. Find the value responsible for the visible result.
4. Make one focused change.
5. Wait for the preview to refresh, then play the affected moment.
The Code editor saves user edits automatically and records them in Studio
history. If a save fails, Studio says that the latest edit was not persisted;
fix the preview-server or connection problem before continuing.
<Warning>
Creating, renaming, moving, or deleting a file can break references elsewhere in the project.
Search for the old path or ask the agent to update every reference.
</Warning>
Avoid editing the same file in Studio and another tool at the same time. If an
external change lands first, the Code editor rejects the conflicting save and
tells you that the latest edit was not persisted. Reload the current file,
review the external change, then apply your edit again. The separate queue for
visual canvas edits can pause and show a banner while a conflict is resolved.
## Ask about the selected element
When a visible element needs source work, select it and choose **Ask agent about
this element**. Studio prepares the element and project context, combines it
with your instruction, and copies the prompt to the clipboard. Paste that
prompt into your agent chat.
<Frame caption="Studio prepares a prompt for the selected element; you paste it into your agent chat.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/ask-agent-v1.jpg"
alt="HyperFrames Studio dialog for copying a prompt about the selected element and project context"
/>
</Frame>
```text
Keep the current narration and scene order. Make this product panel readable
at the final video size, and do not change the following scene.
```
The copied context tells the agent where to look. Your sentence tells it what
must remain true.
## Run Studio Lint
Choose **Lint** at the bottom of the left sidebar. Studio opens **HyperFrame
Lint Results** with errors, warnings, file locations, and fix hints when they
are available.
Fix a simple, understood issue directly, then run Lint again. Use **Copy to
Agent** when the source location is unfamiliar or the fix may affect other
files. Add what happened before the error and what you expected:
```text
This appeared after I shortened the intro clip. I expected the title animation
to keep its current timing. Fix the issue without changing the rest of the
opening.
```
Do not paste only the error message when the intended result matters. A
technically valid repair can still make the wrong creative change.
## Use the project-level gates before delivery
Studio Lint is a quick in-editor pass. The project-level commands remain the
final gate, especially when the project contains nested compositions:
```bash
npx hyperframes lint
npx hyperframes check
```
`lint` checks the composition structure. `check` adds browser, runtime, layout,
motion, and WCAG contrast verification.
Passing checks do not approve the story or the final encode. Play the project
after a source fix, then watch the rendered file before sharing it.
## When the preview and source disagree
1. Stop editing until the latest save finishes.
2. Keep the first exact error or save warning.
3. Reload the project only after checking whether another tool changed the file.
4. Run the project checks.
5. Ask the agent with the error, project path, action that caused it, and result
you expected.
Use [Studio troubleshooting](/studio/troubleshooting) for editor, preview, and
render-queue failures. Use [Finish and share](/guides/export-and-share) for the
complete approval, validation, render, and delivery path.
## Related topics
- [Recover from a Studio problem](/studio/troubleshooting)
- [Understand a HyperFrames project](/concepts)
- [Finish, render, and share](/guides/export-and-share)
docs/studio/storyboard.mdx
+65
View File
@@ -0,0 +1,65 @@
---
title: "Review the storyboard"
description: "Review planned frames, direction, voiceover, status, and feedback before or during the build."
---
The Storyboard view is for reviewing the story, not fine-tuning pixels.
Each frame represents a planned moment and can include visual direction, voiceover, status, source details, and comments.
<Frame caption="Read the arc, inspect each planned frame, and leave story-level feedback before changing the build.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/storyboard-v1.jpg"
alt="Storyboard with the video arc, frame statuses, visual sketches, and comments"
/>
</Frame>
## Use the frame statuses
- **Outline** — the frame is still a plan.
- **Built** — a working scene exists.
- **Animated** — motion has been added and the scene is ready for closer review.
Treat a status as progress information, not proof that the frame is approved.
## Review one frame
1. Open Storyboard.
2. Focus the frame you want to inspect.
3. Read its visual direction and voiceover together.
4. Check whether the frame supports the main message.
5. Leave a concrete comment.
6. Choose **Save & copy message**, then paste the message into your agent chat.
Useful feedback describes the problem and desired outcome:
```text
This frame repeats the previous claim. Use it to show the product
workflow instead, and keep the voiceover line unchanged.
```
## Board view and source view
Use the board when you want to understand the sequence visually.
Use the source view when you need to inspect or edit the storyboard text and structured direction more directly.
The voiceover shown on the board is a guide. When the project has a `SCRIPT.md`, that file is the final source for generated narration.
## When to move to Preview
Built and Animated frames can include **Open in Preview**. Use it when the question becomes:
- Is the timing right?
- Is the text readable?
- Does the animation feel correct?
- Is an element aligned?
- Does the media crop work?
Those questions need the built composition rather than the plan alone.
## Related topics
- [Work on the built project in Studio](/studio)
- [Edit the visible frame](/studio/canvas)
- [Direct an agent more precisely](/prompting/anatomy)
docs/studio/timeline.mdx
+72
View File
@@ -0,0 +1,72 @@
---
title: "Edit timing on the timeline"
description: "Move, trim, split, align, and inspect clips in HyperFrames Studio."
---
The timeline controls when elements appear and how long they remain.
<Frame caption="The selected clip edge changes its duration while the canvas and neighboring tracks remain visible.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/timeline-v1.jpg"
alt="HyperFrames Studio timeline with the edge of a selected clip ready to trim"
/>
</Frame>
## Move a clip
Drag the body of a clip left or right. Its start time changes while its duration stays the same.
Use snapping to align the clip with the playhead, another boundary, or a useful beat.
## Trim a clip
Drag the left or right edge.
- Trimming the left edge changes when the clip begins.
- Trimming the right edge changes when it ends.
Trimming does not automatically rewrite the story. Play the surrounding section to check entrances, exits, media continuity, and narration.
## Split a clip
Splitting is supported for eligible timeline elements.
You can:
- place the playhead, open the clip menu, and choose **Split at…**;
- switch to the razor tool and click the clip;
- hold Shift while using the razor to split every eligible clip under that time.
Use the **B** shortcut to switch to the razor tool. Return to the selection tool when you finish cutting.
<Note>
A split must happen inside the clip, not exactly on its start or end. Some element types cannot be split safely.
</Note>
## Zoom and navigate
Zoom in for keyframes and short edits. Zoom out to understand the complete sequence.
Use the playhead for the exact edit moment. Use playback and frame stepping to check what happens immediately before and after it.
## Work with beats
Beat markers provide timing landmarks, especially for music-driven work. Snap edits to them when the audio should drive the cut; ignore them when the story or voiceover needs a different rhythm.
## Move several items
Select multiple eligible timeline elements when they need to remain aligned. Drag them together, then check for collisions or gaps on their tracks.
## Open a nested scene
Expand a nested composition to see its children, or open it and use the breadcrumb to return. Be clear whether you are changing the scene’s internal timing or its timing in the parent video.
## Undo mistakes
Move, trim, split, and many other timeline actions participate in Studio history. Undo immediately when a result is unexpected, then retry with a closer zoom or a more precise playhead position.
## Related topics
- [Edit the frame](/studio/canvas)
- [Edit animation and keyframes](/studio/animation)
- [Use Studio keyboard shortcuts](/studio/shortcuts)
docs/studio/troubleshooting.mdx
+60
View File
@@ -0,0 +1,60 @@
---
title: "Studio troubleshooting"
description: "Recover from selection, preview, editing, timeline, and export problems."
---
## I cannot select the right element
- Pause on a frame where it is visible.
- Choose it from Layers.
- Check whether it belongs to a group or nested composition.
- Look for an off-canvas indicator.
## A direct edit is unavailable
The selected element may be generated, nested, or unsupported for that operation.
Try the inspector, open the nested composition, copy context to the agent, or make a focused source edit.
## A canvas move became animation
Check whether auto-keyframing is enabled. Undo the edit, turn it off, and make the layout change again.
## The timeline edit landed at the wrong time
Undo, zoom in, place the playhead more precisely, and retry. Check whether snapping moved the boundary to a nearby clip or beat.
## The preview did not update
- Preview's Code editor and visual controls save automatically. Storyboard
narration and feedback drafts show their own Save action. If the change came
from another editor or an agent, confirm that the external file was saved.
- Wait for the project refresh.
- Check the terminal running `hyperframes preview`.
- Reload Studio if the preview process is still healthy.
- Restart `npx hyperframes preview` when the server stopped.
## Media is missing or slow
Confirm that the file exists inside the project and that its path is correct. Large media may need time to prepare a preview. Remote files can fail because of access or cross-origin restrictions.
## An edit failed to save
Keep the error visible, avoid stacking more edits on top of it, and undo if available. Copy the issue to your agent with the action that caused it.
## A render failed
Keep the complete error. Run the project checks, confirm FFmpeg and source media are available, then retry:
```bash
npx hyperframes lint
npx hyperframes check
```
For lower-level failures, continue to [general troubleshooting](/guides/troubleshooting).
## Related topics
- [Work with source and an agent](/studio/source)
- [Finish, render, and share](/guides/export-and-share)
- [Diagnose a project or CLI problem](/guides/troubleshooting)
docs/studio/variables.mdx
+64
View File
@@ -0,0 +1,64 @@
---
title: "Use variables and templates"
description: "Turn a visible value into a reusable input, preview variants, and hand the template off."
---
Variables let one project produce many versions without rebuilding its layout or animation.
<Frame caption="The current Variables panel previews values beside the real composition.">
<img
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio-variables-panel-v1.jpg"
alt="HyperFrames Studio showing a composition beside the Variables panel with Title, Subtitle, and Background inputs"
/>
</Frame>
## Create one reusable input
The quickest path starts from the canvas:
1. Select the element.
2. Open **Variables** in the right panel.
3. Bind the text, media source, text color, background, or font property.
4. Create a new variable or choose a compatible existing one.
For a value that is not tied to the selected element, click **Add variable**. Studio supports string, number, color, boolean, enum, font, and image variables. Number variables can include minimum, maximum, and step values; enums can define their allowed options.
Name the input by meaning—`customerName`, `headline`, or `brandColor`—rather than by its position in the design.
## Preview without changing the template
Change a value in the Variables panel to preview that version immediately. The preview is an override: it does not replace the saved default.
The panel tells you whether you are previewing defaults or custom values. Use **Reset** to clear all preview overrides. When a scalar preview should become the new default, use **Set default**.
<Note>
Variables from other compositions are listed separately. You can edit their declarations, but
their values are not live-previewed in the active composition.
</Note>
## Hand the project off
At the bottom of the panel, **Use this template** can copy either:
- the effective values as JSON;
- a ready-to-run `npx hyperframes render ... --variables ...` command.
This keeps the values you just reviewed attached to the render request instead of asking the next person to reconstruct them.
## Test the fallback
A useful template survives realistic variation. Before handing it off, test:
- long and short names or headlines;
- image aspect ratios;
- color contrast;
- number formatting;
- missing optional values.
For the schema, HTML bindings, and batch-render examples, read [Variables](/concepts/variables).
## Related topics
- [Understand the variables contract](/concepts/variables)
- [Use Assets and Catalog](/studio/assets-and-blocks)
- [Render variable-driven versions](/guides/rendering#batch-and-cloud-work)
docs/thirty-days.mdx
+52
View File
@@ -0,0 +1,52 @@
---
title: 30 Days of HyperFrames
sidebarTitle: 30 Days of HyperFrames
description: "The official 30 Days of HyperFrames lessons, collected in one place as the series is published."
---
The series began on [@HeyGen](https://x.com/HeyGen) and continues on [@HyperFrames_](https://x.com/HyperFrames_). Open any day for the original lesson and example.
## Start and create
1. [**Install HyperFrames**](https://x.com/HeyGen/status/2074176916819685648) — give your coding agent the HyperFrames skills.
2. [**Give your brand a motion language**](https://x.com/HeyGen/status/2074574265714905167) — turn a visual identity into reusable motion direction.
3. [**PR-to-Video**](https://x.com/HeyGen/status/2074954182583554051) — explain an open pull request as a short video.
4. [**Music-to-Video**](https://x.com/HeyGen/status/2075262117964615956) — build a video around a track and its beat.
5. [**Faceless explainer**](https://x.com/HeyGen/status/2075682104302882908) — turn a topic into a designed explainer without footage.
6. [**Talking-head recut**](https://x.com/HeyGen/status/2075998619325604238) — add synchronized graphics to an existing speaker video.
7. [**Motion graphics**](https://x.com/HeyGen/status/2076381187640324427) — make a short, design-led animation.
8. [**Music and SFX with the HeyGen CLI**](https://x.com/HeyGen/status/2076719036742922504) — find and use audio from the command line.
9. [**Figma to HyperFrames**](https://x.com/HeyGen/status/2077072141309382770) — turn an existing design into a video composition.
## Direct and refine
10. [**Anatomy of a prompt**](https://x.com/HeyGen/status/2077438104982667282) — structure a request so the agent gets the important intent right.
11. [**Repurpose an existing video**](https://x.com/HeyGen/status/2077798995762823593) — extract useful patterns from a reference.
12. [**Dynamic captions**](https://x.com/HeyGen/status/2078190361932103716) — make captions part of the visual design.
13. [**Studio preview, part 1**](https://x.com/HeyGen/status/2078589328562016559) — inspect a composition before rendering.
14. [**Studio preview, part 2: keyframes**](https://x.com/HeyGen/status/2078945075787452660) — adjust motion with visible keyframe controls.
15. [**Sample the web**](https://x.com/HeyGen/status/2079251321484722675) — bring useful web motion into a composition.
16. [**Media use**](https://x.com/HeyGen/status/2079609229737111978) — work with the available asset libraries.
17. [**Storyboard**](https://x.com/HeyGen/status/2080012076454719554) — agree on the sequence before building every scene.
18. [**HyperFrames in Video Agent**](https://x.com/HeyGen/status/2080407266755510452) — create with HyperFrames inside HeyGen Video Agent.
19. [**Background removal**](https://x.com/HeyGen/status/2080762012330807438) — use alpha channels to layer subjects into a scene.
## Extend and ship
20. [**Claude Design**](https://x.com/HyperFrames_/status/2081184676430160379) — take a design direction into a HyperFrames project.
21. [**Cloud rendering**](https://x.com/HyperFrames_/status/2081491370485952790) — render without making one local computer the bottleneck.
22. [**Components Catalog**](https://x.com/HyperFrames_/status/2081798071353278651) — add reusable scenes and effects instead of rebuilding them.
23. [**Templates and variables**](https://x.com/HyperFrames_/status/2082197435246600341) — turn one composition into repeatable versions.
24. [**Color grading**](https://x.com/HyperFrames_/status/2082536413829235004) — correct or stylize images and footage in code.
25. [**Prompt Guide**](https://x.com/HyperFrames_/status/2082892893027749917) — find practical language and examples for directing an agent.
26. [**Media effects and overlays**](https://x.com/HyperFrames_/status/2083324288632045910) — add designed treatments to real media.
27. [**Deploy**](https://x.com/HyperFrames_/status/2083633492894900456) — run rendering on your own cloud infrastructure.
28. [**Contribute to the Catalog**](https://x.com/HyperFrames_/status/2084070152975634743) — publish reusable building blocks for other creators.
29. [**Components update**](https://x.com/HyperFrames_/status/2084338269194732003) — combine the expanded component set in a project.
30. **Coming next** — the official Day 30 lesson has not been published yet. Follow [@HyperFrames_](https://x.com/HyperFrames_) for the final entry.
## Continue in the docs
- [Choose a creation workflow](/workflows)
- [Direct your agent with the Prompt Guide](/prompting/overview)
- [Browse reusable Catalog elements](/catalog)
docs/workflows.mdx
+19
View File
@@ -0,0 +1,19 @@
---
title: "Choose a workflow"
sidebarTitle: "Choose a workflow"
description: "Start from the material you already have."
---
import { WorkflowChooser } from "/snippets/workflow-chooser.jsx";
<WorkflowChooser />
When several source types matter equally, use **Direct a custom video**.
You can also make a plain `/hyperframes` request; the agent selects the matching
workflow after it understands what you want.
## Related topics
- [Make your first video](/quickstart)
- [Create a product or website video](/guides/product-launch-video)
- [Direct a custom video](/guides/general-video)