mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* feat(engine): decouple transparent background from png capture format PNG capture used to imply a cleared page background. A new CaptureOptions.transparentBackground lets lossless opaque PNG capture (4:4:4 MP4 output) keep the page background. Absent, it still follows format === "png", so alpha output and motion blur are unchanged. Opaque PNG skips drawElement, whose verification and worker-encode paths are JPEG-only. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(engine): add 4:4:4 chroma option to getEncoderPreset getEncoderPreset takes an optional chromaSubsampling ("420" by default). "444" returns yuv444p for SDR MP4, so libx264 encodes the High 4:4:4 Predictive profile and odd sizes need no even padding. WebM, MOV and HDR presets ignore it. The ChromaSubsampling type is exported for the producer. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(producer): chromaSubsampling render option with lossless png capture RenderConfig.chromaSubsampling ("420" by default) opts an SDR MP4 render into 4:4:4. "444" encodes libx264 yuv444p and captures every frame as opaque PNG: Chrome's quality-100 JPEG is already 4:2:0 on beginFrame and screenshot capture, and drawElement can fall back to screenshot mid-render, so PNG is the only capture that keeps the colour. drawElement is turned off for these renders. The probe and main capture options share resolveCaptureSurface, so they cannot disagree on format, quality or background. Formats other than mp4, GPU encoding and HDR output are rejected before any work starts, auto-detected HDR sources fail before capture, and distributed requests refuse 444. The default render is unchanged. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(producer,studio-server): accept chromaSubsampling on render routes The shared parseEncoderOptions validates chromaSubsampling and answers 400 for "444" with a non-mp4 format, gpu, or force-hdr, so a request that would come back 4:2:0 never starts a render. The Studio render route, both Studio adapters and the producer HTTP server forward it. The producer server also refuses "444" with outputDynamicRange "hdr", which parseEncoderOptions cannot see. No Studio UI control; the option is route-level like crf and hdrMode. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(cli): add --chroma-subsampling flag `hyperframes render --chroma-subsampling 444` opts an SDR MP4 render into full-resolution chroma (yuv444p with lossless PNG capture). The default stays 420. The plan rejects 444 with a non-mp4 format, --gpu or --hdr before anything renders, with a usage error that names the conflicting flag. The value reaches the local render request and, only when it is 444, the Docker argv, so default Docker invocations are unchanged. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: document 4:4:4 chroma subsampling Add a "4:4:4 masters" section to the rendering guide: when to use --chroma-subsampling 444, why it captures PNG, the measured chroma gain (large for text and UI, none for footage and gradients), its limits, and a player compatibility table to be filled in from testing. Document the flag in the CLI reference, the built-in rendering docs and the hyperframes-cli skill reference (with the regenerated skills manifest), and the chromaSubsampling option in the producer docs. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: add 4:4:4 player compatibility results Fill the 4:4:4 compatibility table from testing H.264 High 4:4:4 Predictive output. Chrome 155, Edge 155, VLC 3.0, Safari on iOS 26.6 and Safari 26.6 on macOS play it, and so does AVFoundation on macOS 26.6, the framework QuickTime Player plays through. Firefox 157 on Windows and both Windows media players do not. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: note the measured render cost of 4:4:4 output Replace the vague "slower capture" note with measured numbers: a text and UI composition rendered in about twice the default time, full-frame footage in about three and a half times, because PNG encoding cost grows with image detail. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(producer): reject chromaSubsampling 444 in distributed render config Distributed configs have no chroma field and validateDistributedRenderConfig ignored unknown keys, so a JS caller passing chromaSubsampling: "444" to the Lambda or Cloud Run SDK got a 4:2:0 file with no error. Reject it, and make the rendering guide say so precisely. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(producer): check a 444 render reaches the encoder as yuv444p Every helper had tests, but nothing checked the orchestrator passes chromaSubsampling through, so dropping it from the encoder preset or capture surface would turn 444 renders back into 4:2:0 with all tests green. Render a small fixture with "444" and with the default and check pix_fmt with ffprobe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(producer): move the 444 drawElement gate into a helper Keeps runCompileStage under the fallow complexity threshold. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: keep comment share at or below the merge-base comment-ratchet failed on 11 files this PR touched. Keep the 4:4:4 rationale once in chromaSubsampling.ts, move the distributed-render reason into its error message, and cut the rest. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(producer): check a 444 render captures full-resolution chroma The encoder check alone passes when chromaSubsampling is dropped from the capture surface: frames are captured as JPEG and encoded yuv444p with 4:2:0 colour. Put a red/blue edge at an odd x, inside a 4:2:0 chroma pair, and require the two pixels to differ in Cb. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(producer): trim the chromaSubsampling.ts header to the package comment share Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix: finish switching to capturesAlpha from #6262 The merge that adopted main's transparent / capturesAlpha left these files uncommitted, so resolveCaptureSurface still returned transparentBackground. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(engine): use transparent / capturesAlpha from #6262 main added CaptureOptions.transparent and capturesAlpha (#6262), which do what this PR's transparentBackground did. Use them, keep the PNG check in drawElementWorkerEncodeEligible, and re-pin test-classification.mjs and the skills manifest against current main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(producer): cut the 4:4:4 comment blocks to one to three lines The reasoning lives in the PR description with the measurements. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor: reconcile 4:4:4 chroma with latest main Keep main's video-layer capture overrides, template entry resolution, ProRes profile parsing and blur-differential tests alongside the chroma option, and fold the encoder sub-parsers into one loop. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: keep main's compile-stage tests and regenerate the skills manifest Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
205 lines
6.9 KiB
Plaintext
205 lines
6.9 KiB
Plaintext
---
|
||
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 });
|
||
```
|
||
|
||
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>
|