Files
hyperframes/docs/packages/engine.mdx
T

147 lines
5.4 KiB
Plaintext

---
title: "@hyperframes/engine"
description: "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
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
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.
## 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.
## Remote media downloads
The engine downloads remote `https://` video, audio, image, and font sources
into the render's work directory before it uses them. Each download has these
limits, and an environment variable changes each one:
| Limit | Default | Environment variable |
| --- | --- | --- |
| Largest file | 8 GiB | `HYPERFRAMES_MAX_DOWNLOAD_BYTES` |
| Longest single attempt, however fast data arrives | 30 minutes | `HYPERFRAMES_MAX_DOWNLOAD_MS` |
| Slowest average speed over a minute | 32 KiB/s | `HYPERFRAMES_MIN_DOWNLOAD_BYTES_PER_SEC` |
| Free space left on the download volume | 512 MiB | `HYPERFRAMES_DOWNLOAD_MIN_FREE_BYTES` |
Sizes are in bytes and the time limit is in milliseconds. A speed or free-space
value of `0` turns that check off.
A download that passes one of these limits stops with an error. The time limit
applies to each attempt: a stalled or too-slow attempt that is retried starts a
new 30 minutes, while an attempt stopped by the time limit is not retried.
The free-space check counts the declared sizes of all downloads running at the
same time in this process, so parallel downloads in one render cannot fill the
volume together. Separate render processes on one host see each other's writes
only when they measure free space again, every 4 MiB received. On a shared host
that evicts workloads below a free-disk threshold, set
`HYPERFRAMES_DOWNLOAD_MIN_FREE_BYTES` above that threshold.
## 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 |
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`.
## Related topics
<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>