diff --git a/README.md b/README.md index d70270abec..6fdc508552 100644 --- a/README.md +++ b/README.md @@ -8,40 +8,54 @@

npm version + npm downloads License Node.js

-**Write HTML. Render video. Built for agents.** +

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. +

+ HyperFrames demo — HTML code on the left transforms into a rendered video on the right +

-## 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. +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. ## Quick Start +### Option 1: With an AI coding agent (recommended) + +Install the HyperFrames skills, then describe the video you want: + +```bash +npx skills add heygen-com/hyperframes +``` + +This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. Then just prompt it: + +> "Create a 10-second product intro video with a fade-in title, a background video, and background music" + +The agent handles scaffolding, animation, and rendering. + +### Option 2: Start a project manually + ```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 +npx hyperframes render # render to MP4 ``` +`hyperframes init` installs skills automatically, so you can hand off to your AI agent at any point. + **Requirements:** Node.js >= 22, FFmpeg -## Documentation +## Why Hyperframes? -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. +- **HTML-native** — compositions are HTML files with data attributes. No React, no proprietary DSL. +- **AI-first** — agents already speak HTML. The CLI is non-interactive by default, designed for agent-driven workflows. +- **Deterministic rendering** — same input = identical output. Built for automated pipelines. +- **Frame Adapter pattern** — bring your own animation runtime (GSAP, Lottie, CSS, Three.js). ## How It Works @@ -53,73 +67,80 @@ Define your video as HTML with data attributes: id="clip-1" data-start="0" data-duration="5" - data-track="0" + data-track-index="0" src="intro.mp4" muted playsinline > - + ``` -Preview instantly in the browser. Render to MP4 locally. Let AI agents compose videos using tools they already understand. +Preview instantly in the browser. Render to MP4 locally or in Docker. + +## Catalog + +50+ ready-to-use blocks and components — social overlays, shader transitions, data visualizations, and cinematic effects: + +```bash +npx hyperframes add flash-through-white # shader transition +npx hyperframes add instagram-follow # social overlay +npx hyperframes add data-chart # animated chart +``` + +Browse the full catalog at **[hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart)**. + +## Documentation + +Full documentation at **[hyperframes.heygen.com/introduction](https://hyperframes.heygen.com/introduction)** — [Quickstart](https://hyperframes.heygen.com/quickstart) | [Guides](https://hyperframes.heygen.com/guides/gsap-animation) | [API Reference](https://hyperframes.heygen.com/packages/core) | [Catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart) ## 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 | +| 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 | +| [`@hyperframes/player`](packages/player) | Embeddable `` web component | +| [`@hyperframes/shader-transitions`](packages/shader-transitions) | WebGL shader transitions for compositions | -## AI Agent Skills +## 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) +HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI agents framework-specific patterns that generic docs don't cover. ```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 +npx skills add heygen-com/hyperframes # HyperFrames skills +npx skills add greensock/gsap-skills # GSAP animation skills ``` -### 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`, `hyperframes-registry` | HTML composition structure, `class="clip"` rules, `data-*` attributes, timeline registration, rendering constraints, registry block/component install and wiring | -| **[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. +| Skill | What it teaches | +| ------------------------------------------------- | ---------------------------------------------------------------------- | +| `hyperframes-compose` | HTML composition structure, `data-*` attributes, timeline registration | +| `hyperframes-captions` | Caption/subtitle authoring and transcript integration | +| `hyperframes-registry` | Block and component installation via `hyperframes add` | +| `gsap-core`, `gsap-timeline`, `gsap-plugins`, ... | GSAP animation API, sequencing, ScrollTrigger, performance | ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute. +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License -See [LICENSE](LICENSE) for details. +[Apache 2.0](LICENSE) diff --git a/docs/contributing/testing-local-changes.mdx b/docs/contributing/testing-local-changes.mdx index ae54aacb8a..fb862ab98d 100644 --- a/docs/contributing/testing-local-changes.mdx +++ b/docs/contributing/testing-local-changes.mdx @@ -11,26 +11,25 @@ Build the monorepo first. Every time you change source files, rebuild before tes ```bash # From the monorepo root -pnpm build +bun run build ``` -## Option 1: pnpm link (recommended) +## Option 1: bun link (recommended) -`pnpm link --global` makes the `hyperframes` binary in your `$PATH` point at your local build. It survives across terminal sessions and auto-picks up new builds without re-linking. +`bun link` makes the `hyperframes` binary in your `$PATH` point at your local build. It survives across terminal sessions and auto-picks up new builds without re-linking. ```bash # If you previously installed hyperframes globally, remove it first — -# a global install takes priority over pnpm link and shadows your local build. -pnpm remove -g hyperframes 2>/dev/null || npm uninstall -g hyperframes 2>/dev/null +# a global install takes priority over bun link and shadows your local build. +npm uninstall -g hyperframes 2>/dev/null # Link your local build cd packages/cli -pnpm link --global +bun link # Verify — should print your local version AND point to the monorepo hyperframes --version which hyperframes -# The path should contain your monorepo, NOT pnpm/global/.pnpm/hyperframes@... ``` Now use `hyperframes` normally in any directory: @@ -40,12 +39,12 @@ cd ~/my-video-project hyperframes preview . ``` -**After every `pnpm build`** the linked binary is already up to date — no re-linking needed. +**After every `bun run build`** the linked binary is already up to date — no re-linking needed. To restore the published release when you're done: ```bash -pnpm unlink --global hyperframes +bun unlink hyperframes npm install -g hyperframes@latest ``` @@ -55,13 +54,13 @@ If you don't want to touch your global `$PATH`, add a shell alias or call `node` ```bash # Temporary alias for your current shell session -alias hyperframes="node /path/to/hyperframes-oss/packages/cli/dist/cli.js" +alias hyperframes="node /path/to/hyperframes/packages/cli/dist/cli.js" # Or invoke directly -node /path/to/hyperframes-oss/packages/cli/dist/cli.js preview . +node /path/to/hyperframes/packages/cli/dist/cli.js preview . ``` -Replace `/path/to/hyperframes-oss` with your actual monorepo path. +Replace `/path/to/hyperframes` with your actual monorepo path. ## Option 3: npm pack (test the exact published artifact) @@ -74,9 +73,9 @@ npm pack # Test it in an isolated directory mkdir /tmp/pack-test && cd /tmp/pack-test -npx /path/to/hyperframes-oss/packages/cli/hyperframes-.tgz init my-video +npx /path/to/hyperframes/packages/cli/hyperframes-.tgz init my-video cd my-video -npx /path/to/hyperframes-oss/packages/cli/hyperframes-.tgz preview . +npx /path/to/hyperframes/packages/cli/hyperframes-.tgz preview . ``` ## Testing the fix branches @@ -105,26 +104,23 @@ Common test scenarios: ## Troubleshooting -**Changes not reflected after `pnpm build`** +**Changes not reflected after `bun run build`** -The CLI binary is a single bundled file at `packages/cli/dist/cli.js`. If your change is in `@hyperframes/core` or another workspace package, make sure `pnpm build` rebuilt _all_ packages — the CLI bundles its dependencies at build time. +The CLI binary is a single bundled file at `packages/cli/dist/cli.js`. If your change is in `@hyperframes/core` or another workspace package, make sure `bun run build` rebuilt _all_ packages — the CLI bundles its dependencies at build time. **`hyperframes` still shows the old version / old UI** -A globally installed `hyperframes` package shadows `pnpm link`. Check which binary is active: +A globally installed `hyperframes` package shadows `bun link`. Check which binary is active: ```bash which hyperframes -# BAD: /Users/you/Library/pnpm/hyperframes → pnpm/global/.pnpm/hyperframes@0.x.x/... -# GOOD: /Users/you/Library/pnpm/hyperframes → your-monorepo/packages/cli/dist/cli.js ``` -If it points to the global store, remove the global install and re-link: +If it points to a global store rather than your monorepo, remove the global install and re-link: ```bash -pnpm remove -g hyperframes -npm uninstall -g hyperframes # in case it was installed via npm -cd packages/cli && pnpm link --global +npm uninstall -g hyperframes +cd packages/cli && bun link ``` **Port already in use** diff --git a/docs/images/readme-demo-source.html b/docs/images/readme-demo-source.html new file mode 100644 index 0000000000..e5b13f61ce --- /dev/null +++ b/docs/images/readme-demo-source.html @@ -0,0 +1,505 @@ + + + + + + HyperFrames README Demo + + + + + + + +
+ +
+
+
+ + +
+
+
+
+
+ index.html +
+
+<div data-composition-id="hero"> + + <h1 class="clip" + data-start="0" data-duration="5"> + Launch Day + </h1> + + <p class="clip" + data-start="0.8" data-duration="4"> + The future of video + </p> + + <!-- GSAP handles animation --> + <script> + tl.from("h1", {y: -60, opacity: 0}) + tl.from("p", {y: 40, opacity: 0}) + </script> +</div> +
+
+ + +
+ + + +
+ + +
+ rendered output +
+
+
+ Launch Day + is here. +
+

The future of video

+
Get started
+
+
+
+ + +
+
+
+
+
+
+
+
+
+
+
Data Charts
+
+ +
+
+
+
+
+ HyperFrames + @hyperframes +
+
Write HTML. Render video.
+
+
+
Social Overlays
+
+ +
+
+
+
+
+
Shader Transitions
+
+ +
+
+ BOLD +
+
Kinetic Type
+
+ +
+
+
+
+
+
+
App Showcases
+
+
+ + +
+ Write HTML · Render Video · Built for agents +
+
+ + + + diff --git a/docs/images/readme-demo.gif b/docs/images/readme-demo.gif new file mode 100644 index 0000000000..f12d152da3 Binary files /dev/null and b/docs/images/readme-demo.gif differ diff --git a/docs/images/readme-demo.mp4 b/docs/images/readme-demo.mp4 new file mode 100644 index 0000000000..8ef34ede88 Binary files /dev/null and b/docs/images/readme-demo.mp4 differ