@hyperframes/producer

The producer package combines the engine’s frame capture with FFmpeg encoding to deliver a complete HTML-to-video rendering pipeline. It supports MP4 (h264) and WebM (VP9 with alpha transparency), and handles runtime injection, readiness gates, audio mixing, and optional Docker-based deterministic rendering.

npm install @hyperframes/producer

When to Use

Use @hyperframes/producer when you need to:

Render compositions to MP4 or WebM programmatically from Node.js (e.g., in a backend service or CI pipeline)
Build a custom rendering service with fine-grained control over the pipeline
Run visual regression tests against golden baselines
Benchmark render performance across different configurations

Use a different package if you want to:

Render from the command line without writing code — use the CLI (npx hyperframes render)
Preview compositions in the browser — use the CLI or studio
Capture frames without encoding — use the engine
Lint or parse composition HTML — use core

If you are building a web application or script that just needs to render a video, the CLI is the fastest path. The producer package is for when you need programmatic control inside Node.js.

What It Does

The producer orchestrates the full render pipeline:

Load the composition HTML

Reads your index.html and any referenced sub-compositions.

Inject the Hyperframes runtime

Adds the runtime script that manages timeline seeking, clip lifecycle, and media playback.

Wait for readiness gates

Polls for window.__playerReady and window.__renderReady to ensure all assets (fonts, images, video) are loaded before capture begins.

Capture frames via the engine

Uses the engine’s BeginFrame pipeline to capture each frame as a pixel buffer.

Encode to MP4 or WebM via FFmpeg

Pipes frame buffers into FFmpeg with the selected quality preset. MP4 uses h264; WebM uses VP9 with alpha transparency support.

Mix audio tracks

Extracts audio from video clips and audio elements, applies data-volume and data-media-start offsets, and mixes them into the final MP4.

Programmatic Usage

The producer uses a two-step API: create a render job configuration, then execute it.

import { createRenderJob, executeRenderJob } from '@hyperframes/producer';

const job = createRenderJob({
  input: './my-video/index.html',
  output: './output.mp4',
  fps: 30,
  quality: 'standard',
});

const result = await executeRenderJob(job);

Render Configuration

import type { RenderConfig } from '@hyperframes/producer';

const config: RenderConfig = {
  fps: 30,                   // 24, 30, or 60
  quality: 'standard',       // 'draft', 'standard', or 'high'
  format: 'mp4',             // 'mp4' or 'webm' (WebM renders with transparency)
  workers: 4,                // Parallel render workers (1-8)
  useGpu: false,             // GPU-accelerated encoding
  debug: false,              // Debug logging
};

WebM with Transparency

Set format: 'webm' to render with a transparent background using VP9 alpha:

const job = createRenderJob({
  fps: 30,
  quality: 'standard',
  format: 'webm',
});

await executeRenderJob(job, './my-overlay', './overlay.webm');

When format: 'webm':

Frames are captured as PNG (preserves alpha channel)
Chrome’s page background is set to transparent via CDP
FFmpeg encodes with VP9 + yuva420p pixel format
Audio is encoded as Opus (instead of AAC for MP4)

Progress Callbacks

import type { ProgressCallback, RenderStatus } from '@hyperframes/producer';

const onProgress: ProgressCallback = (status: RenderStatus) => {
  console.log(`Status: ${status}`);
  // Statuses: "queued" | "preprocessing" | "rendering" | "encoding"
  //           | "assembling" | "complete" | "failed" | "cancelled"
};

Cancellation

import { RenderCancelledError } from '@hyperframes/producer';

try {
  await executeRenderJob(job);
} catch (err) {
  if (err instanceof RenderCancelledError) {
    console.log(`Cancelled: ${err.reason}`);
    // reason: "user_cancelled" | "timeout" | "aborted"
  }
}

HTTP Server

The producer includes a built-in HTTP server for running as a rendering service:

import { startServer } from '@hyperframes/producer/server';

await startServer({ port: 8080 });

Server Endpoints

Method	Path	Description
`POST`	`/render`	Blocking render — returns JSON result
`POST`	`/render/stream`	Streaming render with Server-Sent Events
`POST`	`/lint`	Lint a composition for issues
`GET`	`/health`	Health check
`GET`	`/outputs/:token`	Download a rendered MP4

For custom server integration, use the lower-level handlers:

import { createRenderHandlers, createProducerApp } from '@hyperframes/producer/server';

// Get individual request handlers
const handlers = createRenderHandlers(options);

// Or get a full Hono app
const app = createProducerApp(options);

Docker Rendering

For deterministic output, the producer can render inside a Docker container with a pinned Chrome version and font set. This guarantees identical output across machines — critical for CI pipelines and production services.

# Via the CLI (recommended)
npx hyperframes render --docker --output output.mp4

Docker mode requires Docker to be installed and running. Run npx hyperframes doctor to verify your environment. See Deterministic Rendering for details on what makes Docker mode deterministic.

Quality Presets

Preset	Resolution	Encoding	Use Case
`draft`	Original	Fast CRF	Quick iteration, previewing edits
`standard`	Original	Balanced CRF	Production renders, sharing
`high`	Original	High-quality CRF	Final delivery, archival

GPU Encoding

The producer supports hardware-accelerated encoding for faster renders:

Platform	Encoder	Flag
NVIDIA	NVENC	Auto-detected
macOS	VideoToolbox	Auto-detected
Linux	VAAPI	Auto-detected

GPU encoding is automatically used when available. To check your system’s capabilities:

npx hyperframes doctor

Additional Exports

The producer also re-exports key engine functionality for convenience:

Export	Description
`createCaptureSession()`	Create a frame capture session
`initializeSession()`	Initialize session with a composition
`captureFrame()` / `captureFrameToBuffer()`	Capture individual frames
`closeCaptureSession()`	Clean up a capture session
`getCompositionDuration()`	Get total composition duration
`getCapturePerfSummary()`	Get capture performance metrics
`createFileServer()`	Create an HTTP file server for serving assets
`createVideoFrameInjector()`	Create a video frame injector for page
`resolveConfig()` / `DEFAULT_CONFIG`	Producer configuration
`createConsoleLogger()` / `defaultLogger`	Logging utilities
`quantizeTimeToFrame()`	Convert time to frame boundary
`resolveRenderPaths()`	Resolve render directory paths
`prepareHyperframeLintBody()` / `runHyperframeLint()`	Linting utilities

Regression Testing

The producer includes a regression harness for comparing render output against golden baselines. This is useful for catching visual regressions when changing the runtime, engine, or rendering pipeline.

cd packages/producer

# Build the test Docker image
bun run docker:build:test

# Run regression tests (compares output against golden baselines)
bun run docker:test

# Regenerate golden baselines after intentional changes
bun run docker:test:update

Benchmarking

Find optimal render settings for your hardware:

# Via the CLI
npx hyperframes benchmark

# Directly from the producer package
cd packages/producer
bun run benchmark

The benchmark runs several compositions with different quality and FPS settings and reports timing for each combination.

External assets (files outside `projectDir`)

A composition can reference absolute paths to assets outside the project directory — a local voiceover in ~/Downloads, a shared-drive image, a generated fixture at an absolute path. The producer handles these by:

Detection. During compilation, the HTML compiler walks every [src] / [href] and every url(...) in <style>. A path that resolves to a file outside projectDir is collected into an externalAssets map.
Sanitised keys. Each absolute path is converted into a safe, cross-platform relative key prefixed with hf-ext/. Windows drive-letter colons are stripped (D:\foo\x.wav → hf-ext/D/foo/x.wav) so that path.join(compileDir, key) stays inside the compile directory on every OS.
Copy + rewrite. The orchestrator copies the file under <compileDir>/hf-ext/... and the HTML is rewritten to point at the sanitised key. The file server then serves both project-internal and external assets from the same root.

The containment check uses path.relative() rather than a hardcoded separator, so external assets work identically on macOS, Linux, and Windows. See packages/producer/src/utils/paths.ts for the helpers.

CLI

Command-line interface that wraps the producer for rendering, previewing, and more.

Engine

The low-level capture pipeline that the producer uses to grab frames.

Core

Types, runtime, and linter that the producer depends on.

Studio

Visual editor for building compositions before rendering with the producer.

​When to Use

​What It Does

​Programmatic Usage

​Render Configuration

​WebM with Transparency

​Progress Callbacks

​Cancellation

​HTTP Server

​Server Endpoints

​Docker Rendering

​Quality Presets

​GPU Encoding

​Additional Exports

​Regression Testing

​Benchmarking

​External assets (files outside projectDir)

​Related Packages

CLI

Engine

Core

Studio

When to Use

What It Does

Programmatic Usage

Render Configuration

WebM with Transparency

Progress Callbacks

Cancellation

HTTP Server

Server Endpoints

Docker Rendering

Quality Presets

GPU Encoding

Additional Exports

Regression Testing

Benchmarking

External assets (files outside `projectDir`)

Related Packages