@hyperframes/engine

Low-level, seekable frame capture and encoding primitives.

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

npm install @hyperframes/engine

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.

import {
  captureFrame,
  closeCaptureSession,
  createCaptureSession,
  getCompositionDuration,
  initializeSession,
} from "@hyperframes/engine";

const fps = { num: 30, den: 1 };
const session = await createCaptureSession(
  serverUrl,
  "./frames",
  {
    width: 1920,
    height: 1080,
    fps,
    format: "jpeg",
  },
);

try {
  await initializeSession(session);
  const duration = await getCompositionDuration(session);
  const totalFrames = Math.ceil(duration * 30);

  for (let frame = 0; frame < totalFrames; frame += 1) {
    const time = frame / 30;
    await captureFrame(session, frame, time);
  }
} finally {
  await closeCaptureSession(session);
}

Use captureFrameToBuffer() when the next stage needs an in-memory buffer instead of a file.

What else the package exposes

Surface	Use it for
Browser management	Launching, pooling, and releasing Chrome
Encoders	MP4, WebM, MOV, GIF, PNG-sequence, muxing, and faststart
Media extraction	Preparing source video frames and audio tracks
Parallel capture	Distributing frame ranges across workers
Diagnostics	Capture performance, media metadata, and GPU parity

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.

@hyperframes/producer

Get a finished video without assembling the pipeline yourself.

Deterministic rendering

Understand what HyperFrames controls and what the environment still affects.