From 98113c24475c1f0def8c12899b90eb18765aba7e Mon Sep 17 00:00:00 2001 From: James Date: Tue, 24 Mar 2026 04:52:14 +0000 Subject: [PATCH 1/3] docs: add per-package READMEs and polish root docs for OSS launch - Add READMEs for all 5 packages (core, engine, producer, cli, studio) with install, overview, basic usage, and links to full docs - Rewrite core README from internal doc to OSS-facing format - Polish root README: add badges, packages table, docs link, requirements - Add AI usage policy and BDFL governance statement to CONTRIBUTING.md - Genericize license references (pending final license decision) - Docs URL set to hyperframes.heygen.com Addresses VA-850. Co-Authored-By: Claude Opus 4.6 (1M context) --- CONTRIBUTING.md | 16 +++- README.md | 22 +++++- packages/cli/README.md | 121 +++++++++++++++++++++++++++++ packages/core/README.md | 151 ++++++++++++------------------------ packages/engine/README.md | 78 +++++++++++++++++++ packages/producer/README.md | 75 ++++++++++++++++++ packages/studio/README.md | 46 +++++++++++ 7 files changed, 405 insertions(+), 104 deletions(-) create mode 100644 packages/cli/README.md create mode 100644 packages/engine/README.md create mode 100644 packages/producer/README.md create mode 100644 packages/studio/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 754b38d3e..36a07f973 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,10 +86,24 @@ gh pr create --title "chore: release v0.2.0" --base main - Search existing issues before creating a new one - Include reproduction steps for bugs +## AI-Assisted Contributions + +We welcome contributions that use AI tools (GitHub Copilot, Claude, ChatGPT, etc.). If you used AI to help write a PR, there is no need to disclose it — we review all code on its merits. However: + +- You are responsible for the correctness of any code you submit, regardless of how it was generated. +- AI-generated tests must actually test meaningful behavior, not just assert truthy values. +- Do not submit AI-generated code you don't understand. If you can't explain what a change does during review, it will be rejected. + +## Governance + +Hyperframes uses a **BDFL (Benevolent Dictator for Life)** governance model. The core maintainers at HeyGen have final say on the project's direction, API design, and what gets merged. This keeps the project focused and moving fast. + +Community input is valued and encouraged — open issues, propose RFCs, and discuss in PRs. But final decisions rest with the maintainers. + ## Code of Conduct This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. ## License -By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). +By contributing, you agree that your contributions will be licensed under the project's license. See [LICENSE](LICENSE) for details. diff --git a/README.md b/README.md index 80f3e52a5..531fdf221 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Hyperframes +[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](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. @@ -14,12 +16,14 @@ Hyperframes is an open-source video rendering framework that lets you create, pr ## Quick Start ```bash -npx create-hyperframe my-video +npx hyperframes init my-video cd my-video npx hyperframes dev # preview in browser npx hyperframes render # render to MP4 ``` +**Requirements:** Node.js >= 22, FFmpeg + ## How It Works Define your video as HTML with data attributes: @@ -49,7 +53,19 @@ Define your video as HTML with data attributes: 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 | + +## Documentation + +Full docs at [hyperframes.heygen.com](https://hyperframes.heygen.com) — includes guides, concepts, API reference, and package documentation. ## Contributing @@ -57,4 +73,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute. ## License -[MIT](LICENSE) +See [LICENSE](LICENSE) for details. diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 000000000..b676f433d --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,121 @@ +# hyperframes + +CLI for creating, previewing, and rendering HTML video compositions. + +## Install + +```bash +npm install -g hyperframes +``` + +Or use directly with npx: + +```bash +npx hyperframes +``` + +**Requirements:** Node.js >= 22, FFmpeg + +## Commands + +### `init` + +Scaffold a new Hyperframes project from a template: + +```bash +npx hyperframes init my-video +cd my-video +``` + +### `dev` + +Start the live preview studio in your browser: + +```bash +npx hyperframes dev +# Server running at http://localhost:3000 +# Watching for changes... +``` + +### `render` + +Render a composition to MP4: + +```bash +npx hyperframes render ./my-composition.html -o output.mp4 +``` + +### `lint` + +Validate your Hyperframes HTML: + +```bash +npx hyperframes lint ./my-composition.html +``` + +### `compositions` + +List compositions found in the current project: + +```bash +npx hyperframes compositions +``` + +### `benchmark` + +Run rendering benchmarks: + +```bash +npx hyperframes benchmark ./my-composition.html +``` + +### `doctor` + +Check your environment for required dependencies (Chrome, FFmpeg, Node.js): + +```bash +npx hyperframes doctor +``` + +### `browser` + +Manage the bundled Chrome/Chromium installation: + +```bash +npx hyperframes browser +``` + +### `info` + +Print version and environment info: + +```bash +npx hyperframes info +``` + +### `docs` + +Open the documentation in your browser: + +```bash +npx hyperframes docs +``` + +### `upgrade` + +Upgrade Hyperframes to the latest version: + +```bash +npx hyperframes upgrade +``` + +## Documentation + +Full documentation: [hyperframes.heygen.com/packages/cli](https://hyperframes.heygen.com/packages/cli) + +## Related packages + +- [`@hyperframes/core`](../core) — types, parsers, frame adapters +- [`@hyperframes/engine`](../engine) — rendering engine +- [`@hyperframes/producer`](../producer) — render pipeline +- [`@hyperframes/studio`](../studio) — composition editor UI diff --git a/packages/core/README.md b/packages/core/README.md index 0cd4fb4a9..487555555 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,125 +1,76 @@ -# HyperFrames Core +# @hyperframes/core -> Create videos by writing HTML. The HTML is the source of truth - timing, layout, content. Scripts define how clips animate. +Types, parsers, generators, compiler, linter, runtime, and frame adapters for the Hyperframes video framework. -HyperFrames Core is the foundational library for video composition. It defines the data attributes and HTML structure that represent video timelines, with GSAP animations to bring clips to life. +## Install -Frame adapter direction: - -- [`../FRAME.md`](../FRAME.md) - repository-level frame model and deterministic renderer direction -- [`adapters/README.md`](adapters/README.md) - adapter contract and contribution guide - -## Philosophy - -``` -HTML = Scene description (content, timing, layout) -CSS = Styling -JS = GSAP animations (motion) +```bash +npm install @hyperframes/core ``` -Every element in the video timeline is represented as an HTML element with data attributes that define its position in time. - ---- +> Most users don't need to install core directly — the [CLI](../cli), [producer](../producer), and [studio](../studio) packages depend on it internally. -## Documentation +## What's inside -### Schema +| Module | Description | +|--------|-------------| +| **Types** | `TimelineElement`, `CompositionSpec`, `Asset`, canvas dimensions, defaults | +| **Parsers** | `parseHtml` — extract timeline elements from HTML; `parseGsapScript` — parse GSAP animations | +| **Generators** | `generateHyperframesHtml` — produce valid Hyperframes HTML from a composition spec | +| **Compiler** | `compileTimingAttrs` — resolve `data-start` / `data-duration` into absolute times | +| **Linter** | `lintHyperframeHtml` — validate Hyperframes HTML (missing attributes, overlapping tracks, etc.) | +| **Runtime** | IIFE script injected into the browser — manages seek, media playback, and the `window.__hf` protocol | +| **Frame Adapters** | Pluggable animation drivers (GSAP, Lottie, CSS, or custom) | -The specification for valid HyperFrames HTML: +## Frame Adapters -- **[schema.md](docs/schema.md)** - Element types, data attributes, HTML patterns +A frame adapter tells the engine how to seek your animation to a specific frame: -### Guides +```typescript +import { createGSAPFrameAdapter } from "@hyperframes/core"; -For AI agents and developers working with HyperFrames: +const adapter = createGSAPFrameAdapter({ + getTimeline: () => gsap.timeline(), + compositionId: "my-video", +}); +``` -| Document | Description | -| --------------------------------------------------------- | -------------------------------------- | -| [Cheat Sheet](docs/guides/cheat-sheet.md) | Quick reference for common actions | -| [Position Guide](docs/guides/position.md) | Natural language → position mappings | -| [Text Style Guide](docs/guides/text-style.md) | Natural language → text style mappings | -| [Motion Design Guide](docs/guides/motion-design/guide.md) | Creating and editing motion designs | -| [Caption Guide](docs/guides/motion-design/captions.md) | Adding captions to videos | +Implement `FrameAdapter` for custom animation runtimes: ---- +```typescript +import type { FrameAdapter } from "@hyperframes/core"; -## Quick Start +const myAdapter: FrameAdapter = { + id: "my-adapter", + getDurationFrames: () => 300, + seekFrame: (frame) => { /* seek your animation */ }, +}; +``` -### Using the Editor (Recommended) +## Parsing and generating HTML -```bash -pnpm install -pnpm dev -``` +```typescript +import { parseHtml, generateHyperframesHtml } from "@hyperframes/core"; -This starts the studio dev server. - -### Writing Compositions Manually - -```html - - - - - - - -
- -
-
Hello World
-
-
- - - +const { elements, metadata } = parseHtml(htmlString); +const html = generateHyperframesHtml(spec); ``` ---- +## Linting -## Element Types +```typescript +import { lintHyperframeHtml } from "@hyperframes/core/lint"; -| Type | HTML Tag | Purpose | -| ----------- | ------------------------------- | -------------------- | -| video | `