open-index/open-npm huggingface dataset:
npm package: @hyperframes/core
Description: Types, parsers, generators, compiler, linter, runtime, and frame adapters for the Hyperframes video framework.
Latest version: 0.2.4

# @hyperframes/core

Types, parsers, generators, compiler, linter, runtime, and frame adapters for the Hyperframes video framework.

## Install

```bash
npm install @hyperframes/core
```

> Most users don't need to install core directly — the [CLI](../cli), [producer](../producer), and [studio](../studio) packages depend on it internally.

## What's inside

| 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)                                           |

## Frame Adapters

A frame adapter tells the engine how to seek your animation to a specific frame:

```typescript
import { createGSAPFrameAdapter } from "@hyperframes/core";

const adapter = createGSAPFrameAdapter({
  getTimeline: () => gsap.timeline(),
  compositionId: "my-video",
});
```

Implement `FrameAdapter` for custom animation runtimes:

```typescript
import type { FrameAdapter } from "@hyperframes/core";

const myAdapter: FrameAdapter = {
  id: "my-adapter",
  getDurationFrames: () => 300,
  seekFrame: (frame) => {
    /* seek your animation */
  },
};
```

## Parsing and generating HTML

```typescript
import { parseHtml, generateHyperframesHtml } from "@hyperframes/core";

const { elements, metadata } = parseHtml(htmlString);
const html = generateHyperframesHtml(spec);
```

## Linting

```typescript
import { lintHyperframeHtml } from "@hyperframes/core/lint";

const result = lintHyperframeHtml(htmlString);
// result.findings: { severity, message, elementId }[]
```

## Documentation

Full documentation: [hyperframes.heygen.com/packages/core](https://hyperframes.heygen.com/packages/core)

## Related packages

- [`@hyperframes/engine`](../engine) — rendering engine that drives the browser
- [`@hyperframes/producer`](../producer) — full render pipeline (capture + encode)
- [`hyperframes`](../cli) — CLI
npm package: @hyperframes/engine
Description: Seekable web page to video rendering engine (Puppeteer + FFmpeg)
Latest version: 0.2.4

# @hyperframes/engine

Seekable web-page-to-video rendering engine built on Puppeteer and FFmpeg.

Framework-agnostic: works with GSAP, Lottie, Three.js, CSS animations, or any web content that implements the `window.__hf` seek protocol.

## Install

```bash
npm install @hyperframes/engine
```

**Requirements:** Node.js >= 22, Chrome/Chromium (auto-downloaded by Puppeteer), FFmpeg

## What it does

The engine opens your HTML composition in a headless Chrome instance, seeks frame-by-frame using Chrome's `HeadlessExperimental.beginFrame` API, captures screenshots, and encodes them into video with FFmpeg.

### Key services

| Service                 | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| **browserManager**      | Launches and pools headless Chrome instances (`chrome-headless-shell`) |
| **frameCapture**        | Manages capture sessions — seek, screenshot, buffer lifecycle          |
| **screenshotService**   | BeginFrame-based capture with CDP (Chrome DevTools Protocol)           |
| **chunkEncoder**        | FFmpeg encoding with chunked concat, GPU detection, faststart          |
| **streamingEncoder**    | Pipe frames to FFmpeg in real time (no intermediate PNGs on disk)      |
| **audioMixer**          | Parse `<audio>` elements and mix audio tracks via FFmpeg               |
| **videoFrameExtractor** | Extract frames from `<video>` elements for compositing                 |
| **parallelCoordinator** | Split frame ranges across worker processes                             |
| **fileServer**          | Serve local HTML files to the browser via Hono                         |

## Usage

```typescript
import {
  acquireBrowser,
  releaseBrowser,
  createCaptureSession,
  initializeSession,
  captureFrame,
  closeCaptureSession,
} from "@hyperframes/engine";

// 1. Launch browser
const browser = await acquireBrowser({ captureMode: "beginFrame" });

// 2. Open a capture session
const session = createCaptureSession({
  browser: browser.browser,
  url: "http://localhost:3000/my-composition.html",
  width: 1920,
  height: 1080,
  fps: 30,
});
await initializeSession(session);

// 3. Capture frames
for (let i = 0; i < totalFrames; i++) {
  await captureFrame(session, i, `/tmp/frames/frame-${i}.png`);
}

// 4. Clean up
await closeCaptureSession(session);
await releaseBrowser(browser);
```

Most users should use `@hyperframes/producer` or the `hyperframes` CLI instead of calling the engine directly.

## Documentation

Full documentation: [hyperframes.heygen.com/packages/engine](https://hyperframes.heygen.com/packages/engine)

## Related packages

- [`@hyperframes/core`](../core) — types, parsers, frame adapters
- [`@hyperframes/producer`](../producer) — high-level render pipeline built on this engine
- [`hyperframes`](../cli) — CLI
npm package: @hyperframes/producer
Description: HTML-to-video rendering engine using Chrome's BeginFrame API
Latest version: 0.2.4

# @hyperframes/producer

Full HTML-to-video rendering pipeline: capture frames with Chrome's BeginFrame API, encode with FFmpeg, mix audio — all in one call.

## Install

```bash
npm install @hyperframes/producer
```

**Requirements:** Node.js >= 22, Chrome/Chromium (auto-downloaded), FFmpeg

## Usage

### Render a video

```typescript
import { createRenderJob, executeRenderJob } from "@hyperframes/producer";

const job = createRenderJob({
  inputPath: "./my-composition.html",
  outputPath: "./output.mp4",
  width: 1920,
  height: 1080,
  fps: 30,
});

const result = await executeRenderJob(job, (progress) => {
  console.log(`${Math.round(progress.percent * 100)}%`);
});

console.log(result.outputPath); // ./output.mp4
```

### Run as an HTTP server

The producer can also run as a render server, accepting render requests over HTTP:

```typescript
import { startServer } from "@hyperframes/producer";

await startServer({ port: 8080 });
// POST /render with a RenderConfig body
```

### Configuration

`RenderConfig` controls the render pipeline:

| Option       | Default      | Description                                        |
| ------------ | ------------ | -------------------------------------------------- |
| `inputPath`  | —            | Path to the HTML composition                       |
| `outputPath` | —            | Output video file path                             |
| `width`      | 1920         | Frame width in pixels                              |
| `height`     | 1080         | Frame height in pixels                             |
| `fps`        | 30           | Frames per second (24, 30, or 60)                  |
| `quality`    | `"standard"` | Encoder preset (`"draft"`, `"standard"`, `"high"`) |

## How it works

1. **Serve** — spins up a local file server for the HTML composition
2. **Capture** — opens the page in headless Chrome, seeks frame-by-frame via `HeadlessExperimental.beginFrame`, captures screenshots
3. **Encode** — pipes frames through FFmpeg (with GPU encoder detection and chunked concat)
4. **Mix** — extracts `<audio>` elements and mixes them into the final video
5. **Finalize** — applies faststart for streaming-friendly MP4

## Documentation

Full documentation: [hyperframes.heygen.com/packages/producer](https://hyperframes.heygen.com/packages/producer)

## Related packages

- [`@hyperframes/core`](../core) — types, parsers, frame adapters
- [`@hyperframes/engine`](../engine) — lower-level capture and encode primitives
- [`hyperframes`](../cli) — CLI
npm package: @hyperframes/studio
Description: Browser-based composition editor UI for Hyperframes. Provides a visual timeline, code editor, and live preview for building video compositions.
Latest version: 0.2.4

# @hyperframes/studio

Browser-based composition editor UI for Hyperframes. Provides a visual timeline, code editor, and live preview for building video compositions.

## Install

```bash
npm install @hyperframes/studio
```

## What it does

The studio is a React application with:

- **Visual timeline** — drag, resize, and arrange elements on tracks
- **Code editor** — edit HTML and GSAP scripts with CodeMirror (syntax highlighting, autocomplete)
- **Live preview** — see changes in real time as you edit
- **Composition inspector** — view and modify element properties

## Development

The studio is embedded in the `hyperframes preview` command. To develop the studio UI itself:

```bash
cd packages/studio
bun run dev        # Start Vite dev server
bun run build      # Build for production
bun run typecheck  # Type-check
```

## Tech stack

- React 18/19, Zustand (state management)
- CodeMirror 6 (editor)
- Tailwind CSS (styling)
- Vite (bundler)
- Phosphor Icons

## Documentation

Full documentation: [hyperframes.heygen.com/packages/studio](https://hyperframes.heygen.com/packages/studio)

## Related packages

- [`@hyperframes/core`](../core) — types and parsers used by the editor
- [`hyperframes`](../cli) — CLI that serves the studio via `hyperframes preview`