Skip to content

Commit 5107e1c

Browse files
committed
Merge remote-tracking branch 'origin/main' into feat/render-telemetry-output-and-environment
2 parents 51d7282 + b64a7a3 commit 5107e1c

29 files changed

Lines changed: 605 additions & 99 deletions

‎docs/guides/rendering.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ npx hyperframes render --output final.mp4
4646
| WebM | Web delivery and transparent overlays |
4747
| GIF | Short previews in issues, pull requests, and documentation |
4848
| PNG sequence | Frame-by-frame handoff to compositing software |
49+
| HLS | VOD streaming from a playlist directory |
4950

5051
Examples:
5152

@@ -61,6 +62,9 @@ npx hyperframes render --format gif --fps 15 --output preview.gif
6162

6263
# RGBA frames in a directory
6364
npx hyperframes render --format png-sequence --output frames
65+
66+
# HLS VOD stream in a directory
67+
npx hyperframes render --format hls --output stream
6468
```
6569

6670
GIF has no audio and limited transparency. Prefer MP4 or WebM for normal playback.
@@ -94,6 +98,25 @@ View the PNG over a checkerboard or contrasting background. If it is still
9498
opaque, compare it with the composition's PNG-sequence output to check whether
9599
transparency was already missing before video encoding.
96100

101+
### HLS streaming output
102+
103+
`--format hls` writes an HLS VOD stream into the output **directory**:
104+
`master.m3u8`, `video.m3u8` and `video_NNNNN.ts`, plus `audio.m3u8` and
105+
`audio_NNNNN.ts` when the composition has audio. The video and audio encodes
106+
are identical to MP4; only the delivery container differs, and packaging is a
107+
stream copy rather than a second encode.
108+
109+
```bash
110+
npx hyperframes render --format hls --output stream
111+
npx hyperframes render --format hls --hls-segment-seconds 6 --output stream
112+
```
113+
114+
Segments are exactly `--hls-segment-seconds` long (default 4) except the last,
115+
and every segment starts on a keyframe. HLS output is SDR only, so `--hdr` is
116+
rejected, and `--gpu` is rejected because GPU encoders ignore the forced-keyframe
117+
lock that fixed-length segments depend on. Cloud rendering (`lambda`,
118+
`cloudrun`) does not offer HLS yet.
119+
97120
## Input video codecs
98121

99122
Studio, preview, `check`, and published projects normally create cached browser

‎docs/packages/cli.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -845,6 +845,9 @@ npx hyperframes render --docker --output output.mp4
845845
# Transparent, for overlays and lower thirds
846846
npx hyperframes render --format webm --output overlay.webm
847847

848+
# HLS VOD stream (output is a directory of playlists and .ts segments)
849+
npx hyperframes render --format hls --output stream
850+
848851
npx hyperframes render --output output.mp4 --fps 60 --quality high
849852
npx hyperframes render --gpu --output gpu.mp4
850853
```
@@ -855,7 +858,7 @@ The flags that come up most:
855858
| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
856859
| `--output, -o` | `renders/<name>.mp4` | Output file path |
857860
| `--composition, -c` | `index.html` | Render a different composition file. Sub-compositions using `<template>` wrappers must be referenced from `index.html` via `data-composition-src`. |
858-
| `--format` | `mp4` | `mp4`, `webm`, `mov`, `gif`, or `png-sequence`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory. |
861+
| `--format` | `mp4` | `mp4`, `webm`, `mov`, `gif`, `png-sequence`, or `hls`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory; `hls` writes a VOD playlist directory. |
859862
| `--fps, -f` | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97 |
860863
| `--quality, -q` | `looks` | `draft`, `looks` (CRF 16, default), `delivery` (= `high`), `standard`, or `high`. MOV always uses the fixed alpha-preserving ProRes 4444 profile. |
861864
| `--resolution` | the composition's size | Supersample to a preset via Chrome's `deviceScaleFactor`. Aspect ratio must match and the scale must be a whole multiple. Not with `--hdr`. See [4K rendering](/guides/4k-rendering). |
@@ -873,6 +876,7 @@ Quality and file size:
873876
| `--video-bitrate` | from `--quality`| Target MP4/WebM bitrate, e.g. `10M` or `5000k`. Not with `--crf`; rejected for MOV. |
874877
| `--vp9-cpu-used` | encoder default | libvpx-vp9 speed/quality trade-off for WebM, -8 to 8. Env: `PRODUCER_VP9_CPU_USED`. |
875878
| `--gif-loop` | `0` | GIF loop count, `0` for forever. Range 0–65535, `--format gif` only. |
879+
| `--hls-segment-seconds`| `4` | HLS target segment length in whole seconds, 1–60. `--format hls` only. Also fixes the encoder GOP so every segment starts on a keyframe. |
876880
| `--video-frame-format` | `auto` | How source video frames are extracted: `auto`, `jpg`, `png`. Use `png` for UI recordings, screen captures, and other colour-sensitive footage. |
877881
| `--hdr` | off | Force HDR even with no HDR sources. MP4 only. See [HDR rendering](/guides/hdr). |
878882
| `--sdr` | off | Force SDR even when HDR sources are detected |

‎docs/packages/producer.mdx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ const job = createRenderJob({
6363
| `mov` | Transparent ProRes 4444 for an editor | AAC |
6464
| `gif` | Small silent previews | None |
6565
| `png-sequence` | Lossless frames for another pipeline | AAC sidecar when needed |
66+
| `hls` | VOD streaming from a playlist directory | AAC rendition |
6667

6768
HDR output is available for MP4 through `hdrMode`. Transparent formats render
6869
in SDR because HDR and alpha are not one supported output path.
@@ -78,6 +79,27 @@ const job = createRenderJob({
7879

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

82+
### HLS
83+
84+
`format: "hls"` writes an HLS VOD stream into `outputPath`, which is a
85+
directory: `master.m3u8`, `video.m3u8` and `video_NNNNN.ts`, plus `audio.m3u8`
86+
and `audio_NNNNN.ts` when the composition has audio. The encode is the same
87+
H.264 + AAC as MP4 — the packaging pass only stream-copies it into segments.
88+
89+
```ts
90+
const job = createRenderJob({
91+
fps: 30,
92+
format: "hls",
93+
hlsSegmentSeconds: 4,
94+
});
95+
```
96+
97+
Segments are exactly `hlsSegmentSeconds` long except the last, because the
98+
encoder GOP is locked to `round(fps × hlsSegmentSeconds)` frames so every
99+
segment starts on a keyframe. HLS is SDR only (`hdrMode: "force-hdr"` is
100+
rejected), refuses GPU encoding (GPU encoders ignore the keyframe lock), and is
101+
not available in distributed rendering, Lambda, or Cloud Run.
102+
81103
## Cancel a render
82104

83105
Pass an abort signal to the final argument:

‎packages/cli/src/commands/render.test.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -822,6 +822,44 @@ describe("renderLocal browser GPU config", () => {
822822
expect(producerState.createdJobs[0]?.format).toBe("png-sequence");
823823
});
824824

825+
it("forwards format: hls and hlsSegmentSeconds through to createRenderJob", async () => {
826+
await renderLocal("/tmp/project", "/tmp/stream", {
827+
fps: { num: 30, den: 1 },
828+
quality: "standard",
829+
format: "hls",
830+
hlsSegmentSeconds: 6,
831+
gpu: false,
832+
browserGpuMode: "software",
833+
hdrMode: "auto",
834+
quiet: true,
835+
});
836+
837+
expect(producerState.createdJobs[0]?.format).toBe("hls");
838+
expect(producerState.createdJobs[0]?.hlsSegmentSeconds).toBe(6);
839+
});
840+
841+
// HLS refuses the VideoToolbox fallback MP4 takes: fixed-length segments need
842+
// the software encoder's forced-keyframe lock.
843+
it("fails an HLS render instead of falling back to GPU H.264", async () => {
844+
ffmpegEncoderState.encoders = " V....D h264_videotoolbox H.264 (VideoToolbox)\n";
845+
const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);
846+
847+
await expect(
848+
renderLocal("/tmp/project", "/tmp/stream", {
849+
fps: { num: 30, den: 1 },
850+
quality: "standard",
851+
format: "hls",
852+
gpu: false,
853+
browserGpuMode: "software",
854+
hdrMode: "auto",
855+
quiet: true,
856+
}),
857+
).rejects.toMatchObject({ name: "CliRuntimeError" });
858+
859+
expect(producerState.createdJobs).toHaveLength(0);
860+
expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");
861+
});
862+
825863
it("forwards format: gif and gifLoop through to createRenderJob", async () => {
826864
await renderLocal("/tmp/project", "/tmp/demo.gif", {
827865
fps: { num: 15, den: 1 },

‎packages/cli/src/commands/render.ts‎

Lines changed: 67 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,10 @@ export const examples: Example[] = [
2727
"Render PNG sequence (RGBA frames for AE/Nuke/Fusion)",
2828
"hyperframes render --format png-sequence --output frames/",
2929
],
30+
[
31+
"Render HLS VOD (master playlist + MPEG-TS segments in a directory)",
32+
"hyperframes render --format hls --output stream/",
33+
],
3034
["High quality at 60fps", "hyperframes render --fps 60 --quality high --output hd.mp4"],
3135
["Deterministic render via Docker", "hyperframes render --docker --output deterministic.mp4"],
3236
["Parallel rendering with 6 workers", "hyperframes render --workers 6 --output fast.mp4"],
@@ -116,7 +120,7 @@ import {
116120
export default defineCommand({
117121
meta: {
118122
name: "render",
119-
description: "Render a composition to MP4, WebM, MOV, GIF, or a PNG sequence",
123+
description: "Render a composition to MP4, WebM, MOV, GIF, HLS, or a PNG sequence",
120124
},
121125
args: {
122126
dir: {
@@ -166,15 +170,23 @@ export default defineCommand({
166170
format: {
167171
type: "string",
168172
description:
169-
"Output format: mp4, webm, mov, gif, png-sequence " +
173+
"Output format: mp4, webm, mov, gif, png-sequence, hls " +
170174
"(MOV/WebM render with transparency; png-sequence writes RGBA frames " +
171-
"to a directory for AE/Nuke/Fusion ingest; gif is best at 15fps for PRs/docs)",
175+
"to a directory for AE/Nuke/Fusion ingest; gif is best at 15fps for PRs/docs; " +
176+
"hls writes a VOD playlist directory — H.264/AAC, SDR only, no GPU encoding)",
172177
default: "mp4",
173178
},
174179
"gif-loop": {
175180
type: "string",
176181
description: "GIF loop count, 0 = infinite. Range: 0-65535. Only used with --format gif.",
177182
},
183+
"hls-segment-seconds": {
184+
type: "string",
185+
description:
186+
"HLS target segment length in whole seconds (default: 4). Range: 1-60. " +
187+
"Also fixes the encoder GOP at segment x fps frames so every segment " +
188+
"starts on a keyframe. Only used with --format hls.",
189+
},
178190
"video-frame-format": {
179191
type: "string",
180192
description:
@@ -432,6 +444,8 @@ export interface RenderOptions {
432444
/** Major FFmpeg/Chrome version from local preflight (telemetry only); absent on Docker renders. */
433445
ffmpegVersionMajor?: number;
434446
browserVersionMajor?: number;
447+
/** HLS target segment length in seconds; ignored unless `format` is `"hls"`. */
448+
hlsSegmentSeconds?: number;
435449
workers?: number;
436450
gpu: boolean;
437451
/**
@@ -755,6 +769,7 @@ async function renderDocker(
755769
quality: options.quality,
756770
format: options.format,
757771
gifLoop: options.gifLoop,
772+
hlsSegmentSeconds: options.hlsSegmentSeconds,
758773
workers: options.workers,
759774
gpu: options.gpu,
760775
browserGpu: options.browserGpuMode === "hardware",
@@ -830,7 +845,12 @@ async function renderDocker(
830845
// threaded back here; the summary shows render time only (never a wrong video
831846
// length). Probe the output with ffprobe if a duration figure is wanted here.
832847
runPostRenderStep("printRenderComplete", () =>
833-
printRenderComplete(outputPath, elapsed, options.quiet),
848+
printRenderComplete({
849+
outputPath,
850+
elapsedMs: elapsed,
851+
quiet: options.quiet,
852+
format: options.format,
853+
}),
834854
);
835855
runPostRenderStep("warnIfWebmAlphaDropped", () =>
836856
warnIfWebmAlphaDropped(outputPath, options.format, options.quiet),
@@ -916,7 +936,10 @@ async function executeLocalRender(
916936
process.env.PRODUCER_HEADLESS_SHELL_PATH = preflight.browser.executablePath;
917937
}
918938

919-
if (!options.gpu && options.format === "mp4" && preflight.ffmpegPath) {
939+
// HLS shares the H.264 encode path but cannot take the GPU fallback below:
940+
// its fixed-length segments need the software encoder's forced-keyframe lock.
941+
const isHls = options.format === "hls";
942+
if (!options.gpu && (options.format === "mp4" || isHls) && preflight.ffmpegPath) {
920943
let encoderMode: H264EncoderMode = "software";
921944
try {
922945
encoderMode = await detectH264EncoderModeForRender(
@@ -927,12 +950,18 @@ async function executeLocalRender(
927950
} catch (error) {
928951
if (cancellation.signal.aborted) cancellation.signal.throwIfAborted();
929952
// HDR MP4 uses HEVC; auto mode cannot resolve the codec until sources
930-
// have been inspected. Only forced SDR is definitely H.264 here.
931-
if (error instanceof H264EncoderUnavailableError && options.hdrMode === "force-sdr") {
953+
// have been inspected. Forced SDR and HLS are definitely H.264 here.
954+
if (
955+
error instanceof H264EncoderUnavailableError &&
956+
(options.hdrMode === "force-sdr" || isHls)
957+
) {
932958
errorBox(
933-
"MP4 H.264 encoder unavailable",
959+
`${isHls ? "HLS" : "MP4"} H.264 encoder unavailable`,
934960
error.message,
935-
`Install an FFmpeg build with libx264 support (${getFFmpegInstallHint()}), or render WebM instead: hyperframes render --format webm --output output.webm`,
961+
`Install an FFmpeg build with libx264 support (${getFFmpegInstallHint()})` +
962+
(isHls
963+
? "."
964+
: ", or render WebM instead: hyperframes render --format webm --output output.webm"),
936965
);
937966
failCommand();
938967
}
@@ -943,6 +972,14 @@ async function executeLocalRender(
943972
console.warn(c.warn(` Unable to probe H.264 encoder capabilities: ${detail}`));
944973
}
945974
}
975+
if (encoderMode === "gpu" && isHls) {
976+
errorBox(
977+
"HLS H.264 encoder unavailable",
978+
"FFmpeg does not include libx264, and HLS cannot fall back to VideoToolbox: fixed-length segments require the software encoder's forced-keyframe lock.",
979+
`Install an FFmpeg build with libx264 support (${getFFmpegInstallHint()}).`,
980+
);
981+
failCommand();
982+
}
946983
if (encoderMode === "gpu") {
947984
console.warn(
948985
c.warn(" FFmpeg does not include libx264; falling back to VideoToolbox H.264 encoding."),
@@ -991,6 +1028,7 @@ async function executeLocalRender(
9911028
quality: options.quality,
9921029
format: options.format,
9931030
gifLoop: options.gifLoop,
1031+
hlsSegmentSeconds: options.hlsSegmentSeconds,
9941032
workers: options.workers,
9951033
useGpu: options.gpu,
9961034
hdrMode: options.hdrMode,
@@ -1055,13 +1093,14 @@ async function executeLocalRender(
10551093
}
10561094
runPostRenderStep("trackRenderMetrics", () => trackRenderMetrics(job, elapsed, options, false));
10571095
runPostRenderStep("printRenderComplete", () =>
1058-
printRenderComplete(
1096+
printRenderComplete({
10591097
outputPath,
1060-
elapsed,
1061-
options.quiet,
1062-
job.perfSummary,
1063-
options.browserGpuMode,
1064-
),
1098+
elapsedMs: elapsed,
1099+
quiet: options.quiet,
1100+
format: options.format,
1101+
perf: job.perfSummary,
1102+
requestedGpuMode: options.browserGpuMode,
1103+
}),
10651104
);
10661105
runPostRenderStep("warnIfWebmAlphaDropped", () =>
10671106
warnIfWebmAlphaDropped(outputPath, options.format, options.quiet),
@@ -1788,7 +1827,7 @@ function readOutputFootprint(outputPath: string): { fileSize: string; isDirector
17881827
try {
17891828
const stat = statSync(outputPath);
17901829
if (!stat.isDirectory()) return { fileSize: formatBytes(stat.size), isDirectory: false };
1791-
// png-sequence output is a directory; sum contained file sizes so the
1830+
// png-sequence and hls write a directory; sum contained file sizes so the
17921831
// user sees the deliverable footprint, not the directory inode size.
17931832
let total = 0;
17941833
for (const entry of readdirSync(outputPath, { withFileTypes: true })) {
@@ -1805,25 +1844,28 @@ function readOutputFootprint(outputPath: string): { fileSize: string; isDirector
18051844
}
18061845
}
18071846

1808-
function printRenderComplete(
1809-
outputPath: string,
1810-
elapsedMs: number,
1811-
quiet: boolean,
1812-
perf?: RenderPerfSummary,
1813-
requestedGpuMode?: "auto" | "hardware" | "software",
1814-
): void {
1815-
if (quiet) return;
1847+
function printRenderComplete(input: {
1848+
outputPath: string;
1849+
elapsedMs: number;
1850+
quiet: boolean;
1851+
format: RenderFormat;
1852+
perf?: RenderPerfSummary;
1853+
requestedGpuMode?: "auto" | "hardware" | "software";
1854+
}): void {
1855+
if (input.quiet) return;
1856+
const { outputPath, elapsedMs, perf } = input;
18161857
const { fileSize, isDirectory } = readOutputFootprint(outputPath);
18171858
const detail = formatRenderSummaryDetail({
18181859
elapsedMs,
18191860
outputDurationSeconds: perf?.compositionDurationSeconds,
18201861
isDirectory,
18211862
frameCount: perf?.totalFrames,
1863+
playlistDirectory: input.format === "hls",
18221864
});
18231865
console.log("");
18241866
console.log(c.success("\u25C7") + " " + c.accent(outputPath));
18251867
console.log(" " + c.bold(fileSize) + c.dim(" \u00B7 " + detail));
1826-
if (perf) printRenderPipeline(perf, requestedGpuMode);
1868+
if (perf) printRenderPipeline(perf, input.requestedGpuMode);
18271869
}
18281870

18291871
function printRenderPipeline(

‎packages/cli/src/commands/render/execute.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ export async function executeRenderPlan(
126126
format: plan.format,
127127
gifLoop: plan.gifLoop,
128128
gifFpsCapped: plan.gifFpsCapped,
129+
hlsSegmentSeconds: plan.hlsSegmentSeconds,
129130
workers: plan.workers,
130131
gpu: plan.useGpu,
131132
browserGpuMode: plan.browserGpuMode,
@@ -311,6 +312,7 @@ async function executeBatchRender(
311312
format: plan.format,
312313
gifLoop: plan.gifLoop,
313314
gifFpsCapped: plan.gifFpsCapped,
315+
hlsSegmentSeconds: plan.hlsSegmentSeconds,
314316
workers: plan.workers,
315317
gpu: plan.useGpu,
316318
browserGpuMode: plan.browserGpuMode,

0 commit comments

Comments
 (0)