Skip to content

Commit 2b19b9a

Browse files
committed
feat(engine): a chunk-fed encoder and the rule for which films may use it, off by default
1 parent c14d92a commit 2b19b9a

7 files changed

Lines changed: 265 additions & 7 deletions

File tree

‎packages/engine/src/config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ export interface EngineConfig {
9090
* true. Kill switch: `HF_DE_WORKER_ENCODE=false`.
9191
*/
9292
enableDrawElementWorkerEncode: boolean;
93+
useInPageEncode: boolean;
9394
/**
9495
* INTERNAL. Set by resolveConfig when it disabled enablePageSideCompositing
9596
* solely because drawElement was on. Lets the producer's compile-time gates
@@ -306,6 +307,7 @@ export const DEFAULT_CONFIG: EngineConfig = {
306307
videoLayerPassthrough: false,
307308
useDrawElement: true,
308309
enableDrawElementWorkerEncode: true,
310+
useInPageEncode: false,
309311
// Auto-detected per host in `resolveConfig`; defaults off for the raw
310312
// DEFAULT_CONFIG (used directly by tests and worker-sizing fallbacks).
311313
lowMemoryMode: false,
@@ -360,6 +362,7 @@ const BOOLEAN_ENGINE_CONFIG_FIELDS = [
360362
"videoLayerPassthrough",
361363
"useDrawElement",
362364
"enableDrawElementWorkerEncode",
365+
"useInPageEncode",
363366
"lowMemoryMode",
364367
"enablePageSideCompositing",
365368
"enableChunkedEncode",
@@ -889,6 +892,7 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
889892
"HF_DE_WORKER_ENCODE",
890893
DEFAULT_CONFIG.enableDrawElementWorkerEncode,
891894
),
895+
useInPageEncode: envBool("HF_INPAGE_ENCODE", DEFAULT_CONFIG.useInPageEncode),
892896
lowMemoryMode: resolveLowMemoryMode(),
893897
enablePageSideCompositing: envBool(
894898
"HF_PAGE_SIDE_COMPOSITING",

‎packages/engine/src/index.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,18 @@ export {
226226
type StreamingEncoderResult,
227227
type FrameReorderBuffer,
228228
} from "./services/streamingEncoder.js";
229+
export {
230+
spawnChunkStreamingEncoder,
231+
buildChunkStreamingArgs,
232+
BT709_LIMITED,
233+
type ChunkColour,
234+
type ChunkStreamingOptions,
235+
} from "./services/chunkStreamingEncoder.js";
236+
export {
237+
resolveInPageEncode,
238+
type InPageEncodeDecision,
239+
type InPageEncodeInput,
240+
} from "./services/inPageEncodeEligibility.js";
229241

230242
// ── Media processing ───────────────────────────────────────────────────────────
231243
export {
Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
import { spawnSync } from "child_process";
2+
import { mkdtempSync, rmSync } from "fs";
3+
import { tmpdir } from "os";
4+
import { join } from "path";
5+
import { afterEach, beforeEach, describe, expect, it } from "vitest";
6+
import { getFfmpegBinary, getFfprobeBinary } from "../utils/ffmpegBinaries.js";
7+
import {
8+
buildChunkStreamingArgs,
9+
spawnChunkStreamingEncoder,
10+
BT709_LIMITED,
11+
} from "./chunkStreamingEncoder.js";
12+
13+
const fps = { num: 30, den: 1 };
14+
15+
describe("buildChunkStreamingArgs", () => {
16+
it("copies an Annex-B stream, tags it BT.709 and runs no filter", () => {
17+
const args = buildChunkStreamingArgs({ fps }, "/tmp/out.mp4");
18+
19+
expect(args.slice(0, 6)).toEqual(["-f", "h264", "-framerate", "30", "-i", "-"]);
20+
expect(args).toContain("copy");
21+
expect(args).not.toContain("-vf");
22+
expect(args[args.indexOf("-bsf:v") + 1]).toBe(
23+
"h264_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1:video_full_range_flag=0",
24+
);
25+
expect(args[args.indexOf("-color_range") + 1]).toBe("tv");
26+
expect(args.at(-1)).toBe("/tmp/out.mp4");
27+
});
28+
29+
it("writes the range the page encoder reported", () => {
30+
const args = buildChunkStreamingArgs(
31+
{ fps, colour: { ...BT709_LIMITED, fullRange: true } },
32+
"o.mp4",
33+
);
34+
35+
expect(args[args.indexOf("-bsf:v") + 1]).toContain("video_full_range_flag=1");
36+
expect(args[args.indexOf("-color_range") + 1]).toBe("pc");
37+
});
38+
});
39+
40+
describe("spawnChunkStreamingEncoder", () => {
41+
let dir = "";
42+
beforeEach(() => {
43+
dir = mkdtempSync(join(tmpdir(), "hf-chunk-enc-"));
44+
});
45+
afterEach(() => rmSync(dir, { recursive: true, force: true }));
46+
47+
it("muxes encoded chunks into an mp4 with one frame per tick and BT.709 tags", async () => {
48+
const source = spawnSync(
49+
getFfmpegBinary(),
50+
[
51+
"-hide_banner",
52+
"-loglevel",
53+
"error",
54+
"-f",
55+
"lavfi",
56+
"-i",
57+
"testsrc=d=1:r=30:s=160x90",
58+
].concat(["-c:v", "libx264", "-bf", "0", "-pix_fmt", "yuv420p", "-f", "h264", "-"]),
59+
{ maxBuffer: 64 * 1024 * 1024 },
60+
);
61+
expect(source.status).toBe(0);
62+
const stream = source.stdout;
63+
const out = join(dir, "out.mp4");
64+
65+
const encoder = spawnChunkStreamingEncoder(out, { fps });
66+
const third = Math.ceil(stream.length / 3);
67+
for (let at = 0; at < stream.length; at += third) {
68+
expect(await encoder.writeFrame(stream.subarray(at, at + third))).toBe(true);
69+
}
70+
const result = await encoder.close();
71+
72+
expect(result.success).toBe(true);
73+
const probe = spawnSync(
74+
getFfprobeBinary(),
75+
["-v", "error", "-count_frames", "-select_streams", "v:0"]
76+
.concat([
77+
"-show_entries",
78+
"stream=nb_read_frames,r_frame_rate,color_space,color_primaries,color_transfer,color_range",
79+
])
80+
.concat(["-of", "json", out]),
81+
{ encoding: "utf-8" },
82+
);
83+
const stream0 = JSON.parse(probe.stdout).streams[0];
84+
expect(stream0).toMatchObject({
85+
nb_read_frames: "30",
86+
r_frame_rate: "30/1",
87+
color_space: "bt709",
88+
color_primaries: "bt709",
89+
color_transfer: "bt709",
90+
color_range: "tv",
91+
});
92+
});
93+
});
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
import type { Fps } from "@hyperframes/core";
2+
import { fpsToFfmpegArg } from "@hyperframes/core";
3+
import type { EngineConfig } from "../config.js";
4+
import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
5+
import { spawnFfmpegStream, type StreamingEncoder } from "./streamingEncoder.js";
6+
7+
export interface ChunkColour {
8+
primaries: number;
9+
transfer: number;
10+
matrix: number;
11+
fullRange: boolean;
12+
}
13+
14+
export const BT709_LIMITED: ChunkColour = {
15+
primaries: 1,
16+
transfer: 1,
17+
matrix: 1,
18+
fullRange: false,
19+
};
20+
21+
export interface ChunkStreamingOptions {
22+
fps: Fps;
23+
colour?: ChunkColour;
24+
}
25+
26+
export function buildChunkStreamingArgs(
27+
options: ChunkStreamingOptions,
28+
outputPath: string,
29+
): string[] {
30+
const { primaries, transfer, matrix, fullRange } = options.colour ?? BT709_LIMITED;
31+
const vui = [
32+
`colour_primaries=${primaries}`,
33+
`transfer_characteristics=${transfer}`,
34+
`matrix_coefficients=${matrix}`,
35+
`video_full_range_flag=${fullRange ? 1 : 0}`,
36+
].join(":");
37+
const args = ["-f", "h264", "-framerate", fpsToFfmpegArg(options.fps), "-i", "-"];
38+
args.push("-c:v", "copy", "-bsf:v", `h264_metadata=${vui}`);
39+
args.push(
40+
...["-colorspace:v", "bt709", "-color_primaries:v", "bt709", "-color_trc:v", "bt709"],
41+
...["-color_range", fullRange ? "pc" : "tv"],
42+
...["-video_track_timescale", "90000", "-avoid_negative_ts", "make_zero"],
43+
);
44+
appendRenderProvenanceArgs(args, outputPath);
45+
args.push("-y", outputPath);
46+
return args;
47+
}
48+
49+
export function spawnChunkStreamingEncoder(
50+
outputPath: string,
51+
options: ChunkStreamingOptions,
52+
signal?: AbortSignal,
53+
config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>,
54+
): StreamingEncoder {
55+
return spawnFfmpegStream(outputPath, buildChunkStreamingArgs(options, outputPath), {
56+
signal,
57+
config,
58+
});
59+
}
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { describe, expect, it } from "vitest";
2+
import { resolveInPageEncode, type InPageEncodeInput } from "./inPageEncodeEligibility.js";
3+
4+
const ready: InPageEncodeInput = {
5+
enabled: true,
6+
captureMode: "drawelement",
7+
format: "mp4",
8+
codec: "h264",
9+
hdr: false,
10+
transparent: false,
11+
workers: 1,
12+
hls: false,
13+
videoLayer: false,
14+
encoderSupported: true,
15+
};
16+
17+
describe("resolveInPageEncode", () => {
18+
it("takes a plain h264 mp4 drawElement film", () => {
19+
expect(resolveInPageEncode(ready)).toEqual({ eligible: true });
20+
});
21+
22+
it.each([
23+
[{ enabled: false }, "disabled"],
24+
[{ captureMode: "screenshot" as const }, "capture is not drawElement"],
25+
[{ format: "webm" }, "output is not mp4"],
26+
[{ codec: "h265" }, "codec is not h264"],
27+
[{ hdr: true }, "hdr"],
28+
[{ transparent: true }, "transparent"],
29+
[{ workers: 3 }, "parallel workers"],
30+
[{ hls: true }, "hls"],
31+
[{ videoLayer: true }, "video layer passthrough"],
32+
[{ encoderSupported: false }, "page encoder unsupported"],
33+
])("leaves %j to today's path: %s", (change, reason) => {
34+
expect(resolveInPageEncode({ ...ready, ...change })).toEqual({ eligible: false, reason });
35+
});
36+
});
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
export interface InPageEncodeInput {
2+
enabled: boolean;
3+
captureMode: "drawelement" | "screenshot" | "beginframe";
4+
format: string;
5+
codec: string;
6+
hdr: boolean;
7+
transparent: boolean;
8+
workers: number;
9+
hls: boolean;
10+
videoLayer: boolean;
11+
encoderSupported: boolean;
12+
}
13+
14+
export type InPageEncodeDecision = { eligible: true } | { eligible: false; reason: string };
15+
16+
export function resolveInPageEncode(input: InPageEncodeInput): InPageEncodeDecision {
17+
const blocker = (
18+
[
19+
[!input.enabled, "disabled"],
20+
[input.captureMode !== "drawelement", "capture is not drawElement"],
21+
[input.format !== "mp4", "output is not mp4"],
22+
[input.codec !== "h264", "codec is not h264"],
23+
[input.hdr, "hdr"],
24+
[input.transparent, "transparent"],
25+
[input.workers !== 1, "parallel workers"],
26+
[input.hls, "hls"],
27+
[input.videoLayer, "video layer passthrough"],
28+
[!input.encoderSupported, "page encoder unsupported"],
29+
] as const
30+
).find(([blocked]) => blocked);
31+
return blocker ? { eligible: false, reason: blocker[1] } : { eligible: true };
32+
}

‎packages/engine/src/services/streamingEncoder.ts‎

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -515,16 +515,41 @@ export async function spawnStreamingEncoder(
515515
signal?: AbortSignal,
516516
config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>,
517517
): Promise<StreamingEncoder> {
518-
const outputDir = dirname(outputPath);
519-
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
520-
521518
let gpuEncoder: GpuEncoder = null;
522519
if (options.useGpu) {
523520
gpuEncoder = await getCachedGpuEncoder();
524521
}
525522

526523
const nvencPresets = gpuEncoder === "nvenc" ? await getCachedNvencPresets() : undefined;
527524
const args = buildStreamingArgs(options, outputPath, gpuEncoder, nvencPresets);
525+
const checksJpeg = !options.rawInputFormat && (options.imageFormat ?? "jpeg") === "jpeg";
526+
return spawnFfmpegStream(outputPath, args, {
527+
signal,
528+
config,
529+
checkFrame: checksJpeg
530+
? (frame, index) => {
531+
const error = jpegInputError(frame);
532+
if (error) throw new Error(`Invalid JPEG input at frame ${index}: ${error}`);
533+
}
534+
: undefined,
535+
});
536+
}
537+
538+
export function spawnFfmpegStream(
539+
outputPath: string,
540+
args: string[],
541+
{
542+
signal,
543+
config,
544+
checkFrame,
545+
}: {
546+
signal?: AbortSignal;
547+
config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>;
548+
checkFrame?: (frame: Buffer, index: number) => void;
549+
},
550+
): StreamingEncoder {
551+
const outputDir = dirname(outputPath);
552+
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
528553

529554
const ffmpeg: ChildProcess = spawn(getFfmpegBinary(), args, {
530555
stdio: ["pipe", "pipe", "pipe"],
@@ -638,10 +663,7 @@ export async function spawnStreamingEncoder(
638663
// so without this copy the pipe would read partially-overwritten data
639664
// and flicker.
640665
const copy = Buffer.from(buffer);
641-
if (!options.rawInputFormat && (options.imageFormat ?? "jpeg") === "jpeg") {
642-
const error = jpegInputError(copy);
643-
if (error) throw new Error(`Invalid JPEG input at frame ${inputFrameIndex}: ${error}`);
644-
}
666+
checkFrame?.(copy, inputFrameIndex);
645667
const accepted = stdin.write(copy);
646668
inputFrameIndex++;
647669
// Reset inactivity timer immediately ONLY on `accepted === true`. `true`

0 commit comments

Comments
 (0)