Files
hyperframes/docs/packages/producer.mdx
T

249 lines
9.8 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.
`chromaSubsampling: "444"` renders an SDR MP4 master with full-resolution
colour (H.264 yuv444p, lossless PNG capture). It needs the software encoder,
is rejected with `useGpu`, HDR output, other formats and distributed renders,
and many players cannot decode it. See
[4:4:4 masters](/guides/rendering#444-masters).
```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.
## Reference background
Completed jobs expose `reference_background`. In-process local render results, blocking and
streaming producer responses, and distributed plan and assembly results carry
this same additive field:
```json
{"reference_background":{"kind":"solid","rgb":[10,46,138]}}
```
The value describes the composition root and its surrounding page background at
the canonical initial film state. It is read from Chromium's computed styles
before transparent capture changes those styles, not inferred from rendered
frames or an inner panel. Distributed chunks preserve the plan's reference;
they do not choose a different reference at each chunk boundary.
| Kind | Meaning |
| --- | --- |
| `solid` | An opaque computed background, with three integer sRGB components from 0 to 255. |
| `none` | A positively established `background: none` declaration with no effective paint. |
| `unsupported_non_solid` | An effective background image or gradient. |
| `unknown` | Missing, unresolved, changing, translucent, or otherwise indeterminate background. |
A transparent computed color alone does **not** establish `none`. An undeclared
background, an authored transparent color, or an inaccessible stylesheet that
prevents proving absence remains `unknown`. Gradients and images are never
replaced with their underlying color. Consumers must preserve indeterminate
results instead of treating them as a default color or proof of a blank frame.
In-process local rendering reads from a session it already opens. The Docker CLI
wrapper does not currently return the child process's result metadata. Distributed planning
opens an inspection-only page even for a composition whose duration was
resolved statically. It does not require WebGPU, run BeginFrame liveness checks,
or reconcile media on that page. An unavailable browser or failed inspection
produces `unknown` without rejecting an otherwise valid static plan. The value
is stored in the execution-plan artifacts, not added to the hashed v2 transport
manifest, so older readers and materializers remain compatible.
## 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 });
```
A browser request (one that carries an `Origin` or `Sec-Fetch-Site` header) is accepted
only under an IP address, `localhost` or a `*.localhost` name, so a page that points its
own domain at the server cannot start renders or lint. If browsers reach the server
through a proxy name, list that name in `allowedHosts` or in the comma-separated
`PRODUCER_ALLOWED_HOSTS` variable. Requests without those headers, such as curl or
another service, are unaffected.
The server listens on `127.0.0.1` unless you pass `hostname` or set `PRODUCER_HOST`. To
listen on any other address, also set `authToken` or `PRODUCER_AUTH_TOKEN`. Every route
except `/health` then requires `Authorization: Bearer <token>`, and the server refuses to
start without one. A request's `projectDir` must resolve, symlinks included, inside
`projectsDir` (`PRODUCER_PROJECTS_DIR`, default: the working directory). Its `entryFile`
must stay inside that project, and `outputPath` must be inside `rendersDir`
(`PRODUCER_RENDERS_DIR`, default `/tmp`). `debug: true` is refused unless you set
`allowDebug` or `PRODUCER_ALLOW_DEBUG=1`. `createProducerApp` applies these path and
debug checks by default. `createRenderHandlers`, for mounting the handlers inside your own
trusted service, applies them only with `confineRequests: true`.
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.
A service that renders projects from other people should set
`PRODUCER_RESTRICT_PAGE_NETWORK=true`. The render browser can then reach only its own
project server and public IPv4 addresses: everything else it sends, from pages, frames,
workers, WebSockets and WebRTC alike, goes through a local proxy that checks every
address a name resolves to and connects to the address it checked. A refused request
fails like any other unreachable asset. Leave it unset for local renders that load
assets from your own machine or network.
The setting accepts `true`, `1`, `yes` or `on` to turn the restriction on and `false`, `0`,
`no` or `off` to leave it off, in any letter case. Any other value turns it on and logs a
warning, so a misspelled value never leaves a render service open.
With the restriction on, a video or audio URL is downloaded through the same address
checks before FFmpeg reads it. A file FFmpeg does read by URL, such as a signed storage
URL for a project's video, must be a self-contained container like MP4, WebM or WAV. A
playlist, manifest or concat list under a media file name is refused.
If your network routes a range that is not a private one, such as a cluster's pod range,
add it with `PRODUCER_NON_PUBLIC_CIDRS`, a comma-separated list like `192.160.0.0/16`. Asset
downloads and the render browser then refuse those addresses too. A malformed entry
refuses every address rather than being skipped, and logs a warning.
`hyperframes render --docker` passes both settings into its render container when they
are set in the shell that runs it. When they are not set, the container's render page can
reach anything the container's network can, including private addresses.
## 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>