mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
Vance Ingalls
9cbfec1eca
* feat(skills): add hyperframes-cli skill for CLI workflow guidance Adds a new skill that teaches AI agents how to use the HyperFrames CLI (init, lint, dev, render, doctor). Previously, agents had no way to discover the CLI — the compose-video skill only covered HTML authoring. This led to agents searching for binaries, finding the monorepo, and running bun run studio manually instead of using npx hyperframes dev. Also registers the skill in init.ts so new projects get it bundled alongside hyperframes-compose and hyperframes-captions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor(cli): rename dev command to preview The command starts a preview server — "preview" describes what users are doing more accurately than "dev". Updates the command name, file name, all CLI references, docs, skills, and template CLAUDE.md. 22 files updated across CLI source, docs, skills, and templates. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(skills): replace stale dev reference with preview in CLI skill Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(docs): catch remaining dev references missed in rename - testing-local-changes.mdx: two inline command examples - troubleshooting.mdx: anchor link #dev → #preview, "dev server" → "preview server" - cli.mdx: "dev server" → "preview server" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
118 lines
5.2 KiB
Markdown
118 lines
5.2 KiB
Markdown
# Hyperframes
|
|
|
|
[](https://www.npmjs.com/package/hyperframes)
|
|
[](LICENSE)
|
|
[](https://nodejs.org)
|
|
|
|
**Write HTML. Render video. Built for agents.**
|
|
|
|
Hyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents via MCP.
|
|
|
|
## Why Hyperframes?
|
|
|
|
- **HTML-native** — AI agents already speak HTML. No React required.
|
|
- **Frame Adapter pattern** — bring your own animation runtime (GSAP, Lottie, CSS, Three.js).
|
|
- **Deterministic rendering** — same input = identical output. Built for automated pipelines.
|
|
- **AI-first design** — not a bolted-on afterthought.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
npx hyperframes init my-video
|
|
cd my-video
|
|
```
|
|
|
|
Then open the project with your AI coding agent (Claude Code, Cursor, etc.) — it has HyperFrames skills installed and knows how to create and edit compositions.
|
|
|
|
```bash
|
|
npx hyperframes preview # preview in browser (live reload)
|
|
npx hyperframes render # render to MP4
|
|
```
|
|
|
|
**Requirements:** Node.js >= 22, FFmpeg
|
|
|
|
## Documentation
|
|
|
|
Full documentation at **[hyperframes.heygen.com](https://hyperframes.heygen.com)** — start with the [Quickstart](https://hyperframes.heygen.com/quickstart), then explore guides, concepts, API reference, and package docs.
|
|
|
|
## How It Works
|
|
|
|
Define your video as HTML with data attributes:
|
|
|
|
```html
|
|
<div id="stage" data-composition-id="my-video" data-start="0" data-width="1920" data-height="1080">
|
|
<video
|
|
id="clip-1"
|
|
data-start="0"
|
|
data-duration="5"
|
|
data-track="0"
|
|
src="intro.mp4"
|
|
muted
|
|
playsinline
|
|
></video>
|
|
<img id="overlay" data-start="2" data-duration="3" data-track="1" src="logo.png" />
|
|
<audio
|
|
id="bg-music"
|
|
data-start="0"
|
|
data-duration="9"
|
|
data-track="2"
|
|
data-volume="0.5"
|
|
src="music.wav"
|
|
></audio>
|
|
</div>
|
|
```
|
|
|
|
Preview instantly in the browser. Render to MP4 locally. Let AI agents compose videos using tools they already understand.
|
|
|
|
## Packages
|
|
|
|
| Package | Description |
|
|
| -------------------------------------------- | ----------------------------------------------------------- |
|
|
| [`hyperframes`](packages/cli) | CLI — create, preview, lint, and render compositions |
|
|
| [`@hyperframes/core`](packages/core) | Types, parsers, generators, linter, runtime, frame adapters |
|
|
| [`@hyperframes/engine`](packages/engine) | Seekable page-to-video capture engine (Puppeteer + FFmpeg) |
|
|
| [`@hyperframes/producer`](packages/producer) | Full rendering pipeline (capture + encode + audio mix) |
|
|
| [`@hyperframes/studio`](packages/studio) | Browser-based composition editor UI |
|
|
|
|
## AI Agent Skills
|
|
|
|
HyperFrames ships skills that teach AI coding agents (Claude Code, Gemini CLI, Codex, Cursor) how to write correct compositions and GSAP animations. **Use these instead of writing from scratch — they encode framework-specific patterns that generic docs don't cover.**
|
|
|
|
### Install via CLI (recommended)
|
|
|
|
```bash
|
|
# Install all skills (HyperFrames + GSAP) — runs automatically during `hyperframes init`
|
|
npx hyperframes skills
|
|
|
|
# Or install to a specific agent
|
|
npx hyperframes skills --claude
|
|
npx hyperframes skills --cursor
|
|
```
|
|
|
|
### Or via `npx skills add`
|
|
|
|
```bash
|
|
# HyperFrames skills (hyperframes-compose, hyperframes-captions)
|
|
npx skills add heygen-com/hyperframes
|
|
|
|
# GSAP skills (gsap-core, gsap-timeline, gsap-scrolltrigger, gsap-plugins, gsap-performance, gsap-utils, gsap-react, gsap-frameworks)
|
|
npx skills add greensock/gsap-skills
|
|
```
|
|
|
|
### Installed Skills
|
|
|
|
| Source | Skills | What they teach |
|
|
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
| **HyperFrames** | `hyperframes-compose`, `hyperframes-captions` | HTML composition structure, `class="clip"` rules, `data-*` attributes, timeline registration, rendering constraints |
|
|
| **[GSAP](https://github.com/greensock/gsap-skills)** | `gsap-core`, `gsap-timeline`, `gsap-performance`, `gsap-plugins`, `gsap-scrolltrigger`, `gsap-utils`, `gsap-react`, `gsap-frameworks` | Core API, timeline sequencing, ScrollTrigger, plugin usage, performance best practices |
|
|
|
|
In Claude Code, invoke with `/hyperframes-compose`, `/hyperframes-captions`, `/gsap-core`, etc.
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute.
|
|
|
|
## License
|
|
|
|
See [LICENSE](LICENSE) for details.
|