mirror of https://github.com/hanzoai/frames.git synced 2026-09-24 00:08:03 +00:00

Files

T

zooqueen 75094e0d60 frames: publish the toolchain as @hanzo/frames

@hanzo/frame is taken by the hero video primitive — one full-bleed video
element — which has held that name on npm since it shipped. This repo is the
video toolchain: a CLI, a renderer, a studio, a player. Plural is what it is,
so the CLI publishes as @hanzo/frames and the workspace packages follow it
(@hanzo/frames-core, @hanzo/frames-engine, and the rest).

The binary stays `frames`, and now actually ships. The manifest mapped it to
bin/frames.mjs while the file on disk was bin/hyperframes.mjs, so a global
install produced no working command.

The paths that name a package to fetch were pointing elsewhere. The update
check read registry.npmjs.org/frames, a different author's package, and the
npm, bun and pnpm installers would have pulled it over the CLI; the render
image installed the upstream hyperframes; scaffolded projects and the docs
pinned the unscoped name. All of them now name @hanzo/frames.

2026-08-13 18:10:14 -07:00

2.8 KiB

Raw Permalink Blame History

@hanzo/frames-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

npm install @hanzo/frames-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

import {
  acquireBrowser,
  createCaptureSession,
  initializeSession,
  captureFrame,
  closeCaptureSession,
} from "@hanzo/frames-engine";

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

// 2. Open a capture session
const session = createCaptureSession({
  browser: browserLease.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 browserLease.release();

Most users should use @hanzo/frames-producer or the frames CLI instead of calling the engine directly.

Documentation

Full documentation: frames.hanzo.ai/packages/engine

@hanzo/frames-core — types, parsers, frame adapters
@hanzo/frames-producer — high-level render pipeline built on this engine
frames — CLI

2.8 KiB Raw Permalink Blame History