Skip to main content
The producer package combines the engine’s frame capture with FFmpeg encoding to deliver a complete HTML-to-MP4 rendering pipeline. It 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 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:
1

Load the composition HTML

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

Inject the Hyperframes runtime

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

Wait for readiness gates

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

Capture frames via the engine

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

Encode to MP4 via FFmpeg

Pipes frame buffers into FFmpeg with the selected quality preset and encoding settings.
6

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

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

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

console.log(result.duration);    // Total render time in ms
console.log(result.frameCount);  // Number of frames captured
console.log(result.outputPath);  // Absolute path to the output file

​
With All Options

await render({
  input: './my-video/index.html',
  output: './output.mp4',
  fps: 30,
  width: 1920,
  height: 1080,
  quality: 'high',
  docker: true,       // Use Docker for deterministic rendering
});

​
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 -o output.mp4

# Via the producer API
await render({ input: './index.html', output: './out.mp4', docker: true });
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

PresetResolutionEncodingUse Case
draftOriginalFast CRFQuick iteration, previewing edits
standardOriginalBalanced CRFProduction renders, sharing
highOriginalHigh-quality CRFFinal delivery, archival

​
GPU Encoding

The producer supports hardware-accelerated encoding for faster renders:
PlatformEncoderFlag
NVIDIANVENCAuto-detected
macOSVideoToolboxAuto-detected
LinuxVAAPIAuto-detected
GPU encoding is automatically used when available. To check your system’s capabilities: 
npx hyperframes doctor

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

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.