> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @hyperframes/engine

> Low-level, seekable frame capture and encoding primitives.

`@hyperframes/engine` is the low-level layer beneath the
[Producer](/packages/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.

```bash theme={null}
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.

```ts theme={null}
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.

<CardGroup cols={2}>
  <Card title="@hyperframes/producer" icon="video" href="/packages/producer">
    Get a finished video without assembling the pipeline yourself.
  </Card>

  <Card title="Deterministic rendering" icon="repeat" href="/concepts/determinism">
    Understand what HyperFrames controls and what the environment still affects.
  </Card>
</CardGroup>