---
title: "@hyperframes/producer"
description: "Render a HyperFrames project from Node.js."
---

`@hyperframes/producer` owns the complete render pipeline: compile the project,
capture its frames, encode the video, and mix its audio.

Use it when rendering is part of your own Node.js service or job runner. For a
local script or terminal workflow, use [`npx hyperframes render`](/developers/cli)
instead.

```bash
npm install @hyperframes/producer
```

## Render one project

`createRenderJob()` describes the render. `executeRenderJob()` receives that
job, the project directory, and the output path.

```ts
import {
  createRenderJob,
  executeRenderJob,
} from "@hyperframes/producer";

const job = createRenderJob({
  fps: 30,
  quality: "standard",
  format: "mp4",
});

await executeRenderJob(
  job,
  "./my-hyperframes-project",
  "./renders/video.mp4",
  (currentJob, message) => {
    console.log(
      `${Math.round(currentJob.progress)}% ${message}`,
    );
  },
);
```

The entry file defaults to `index.html`. Set `entryFile` when the project has a
different entry composition.

```ts
const job = createRenderJob({
  fps: { num: 30000, den: 1001 },
  quality: "high",
  entryFile: "compositions/launch.html",
});
```

## Choose an output

| Format | Best for | Audio |
| --- | --- | --- |
| `mp4` | Default delivery and web playback | AAC |
| `webm` | Transparent video for the web | Opus |
| `mov` | Transparent ProRes 4444 for an editor | AAC |
| `gif` | Small silent previews | None |
| `png-sequence` | Lossless frames for another pipeline | AAC sidecar when needed |
| `hls` | VOD streaming from a playlist directory | AAC rendition |

HDR output is available for MP4 through `hdrMode`. Transparent formats render
in SDR because HDR and alpha are not one supported output path.

```ts
const job = createRenderJob({
  fps: 30,
  quality: "high",
  format: "mp4",
  hdrMode: "auto",
});
```

See [HDR rendering](/guides/hdr) for the source and delivery constraints.

### HLS

`format: "hls"` writes an HLS VOD stream into `outputPath`, which is a
directory: `master.m3u8`, `video.m3u8` and `video_NNNNN.ts`, plus `audio.m3u8`
and `audio_NNNNN.ts` when the composition has audio. The encode is the same
H.264 + AAC as MP4 — the packaging pass only stream-copies it into segments.

```ts
const job = createRenderJob({
  fps: 30,
  format: "hls",
  hlsSegmentSeconds: 4,
});
```

Segments are exactly `hlsSegmentSeconds` long except the last, because the
encoder GOP is locked to `round(fps × hlsSegmentSeconds)` frames so every
segment starts on a keyframe. HLS is SDR only (`hdrMode: "force-hdr"` is
rejected), refuses GPU encoding (GPU encoders ignore the keyframe lock), and is
not available in distributed rendering, Lambda, or Cloud Run.

## Inspect output validation

A matching output duration does not prove that every expected frame is present.
WebM and HLS often omit the frame count from their metadata. When no usable count
is available, the producer skips the frame-count check and continues checking
duration and requested dimensions.

Set `debug: true` in `createRenderJob()` or use `npx hyperframes render --debug`
to retain `render.log` in the render's working directory. Its
`artifact_frame_count_unavailable` debug event records the output path and
expected frame count whenever this check is skipped. Normal output stays quiet;
a custom `logger` can also collect the event through its `debug` method.

## Cancel a render

Pass an abort signal to the final argument:

```ts
const controller = new AbortController();

await executeRenderJob(
  job,
  "./my-hyperframes-project",
  "./renders/video.mp4",
  undefined,
  controller.signal,
);

// Call controller.abort() from your cancellation path.
```

An aborted render throws `RenderCancelledError`. Correctness warnings can also
block a render when `strictness: "strict"` is enabled.

## Build a render service

The package exports a Hono application and server helpers:

```ts
import { startServer } from "@hyperframes/producer";

await startServer({ port: 8080 });
```

For larger workloads, the `@hyperframes/producer/distributed` entry exposes the
three rendering activities—`plan`, `renderChunk`, and `assemble`. Your
orchestrator remains responsible for dispatch, retries, storage, and networking.

## Related topics

<CardGroup cols={2}>
  <Card title="Choose rendering infrastructure" icon="server" href="/deploy/overview">
    Decide between local, server, Temporal, AWS, or another adapter.
  </Card>
  <Card title="@hyperframes/engine" icon="gear" href="/packages/engine">
    Use the lower-level capture and encoding primitives.
  </Card>
</CardGroup>