Skip to main content
@hyperframes/engine is the low-level layer beneath the Producer. It opens a page that implements the HyperFrames seek protocol, seeks to an exact time, and captures the resulting frame. Most integrations should use the CLI or Producer. Use the Engine only when you need to own frame capture, encoding, media extraction, or browser management.

Why it is different from screen recording

A screen recorder waits for the wall clock and may miss frames under load. The Engine asks the page to seek to a specific time and captures that state before moving on. That makes frame scheduling repeatable and prevents dropped frames caused by a slow machine. Exact pixels can still vary with Chrome, fonts, codecs, GPU behavior, and the host environment. Pin those dependencies when exact visual reproducibility matters.

Capture frames

The page at serverUrl must expose window.__hf with a duration and a deterministic seek(time) function.
Use captureFrameToBuffer() when the next stage needs an in-memory buffer instead of a file.

WebGPU requirements

A composition marked data-requires-webgpu must be able to create a WebGPU device before capture starts. Finding an adapter alone is insufficient: device creation can still fail because of the browser or graphics driver. The adapter and device check share a ten-second timeout, and failure stops capture with WebGpuUnavailableError. Hardware adapters are required by default. A launch explicitly configured for software WebGPU may use SwiftShader, but it must also create a device. The check releases its temporary device; the composition still creates its own device with any features or limits its renderer needs.

What else the package exposes

Paths passed to encodeFramesChunkedConcat() and concatVideoFiles() may be relative or absolute. Relative paths resolve from the calling process’s working directory. muxVideoWithAudio() recognizes output filename extensions regardless of case. WebM output, including .WEBM and .WeBm, converts audio to Opus while copying the video stream. These are rendering internals. Their result and error conventions differ by operation: browser and capture orchestration throws, FFmpeg wrappers generally return result objects, and teardown helpers avoid masking the original failure. Browser and frame-capture diagnostics, including motion-blur reports, go to stderr. This keeps stdout available for machine-readable results such as hyperframes benchmark --json.

@hyperframes/producer

Get a finished video without assembling the pipeline yourself.

Deterministic rendering

Understand what HyperFrames controls and what the environment still affects.