Skip to content

Commit eec3c51

Browse files
perf(producer): multi-worker mp4 renders start encoding while frames are still being captured (#5952)
* perf(producer): multi-worker mp4 renders start encoding while frames are still being captured On the multi-worker disk capture path the encoder used to start only after every worker had finished. It now starts with capture and is fed frame 0, 1, 2... in order as each frame file lands, with the same encoder arguments, so the output is byte-identical and the encode left after capture is shorter. Off for drawElement capture (a failed self-check discards every frame) and for png/gif/webm/mov/HDR/GPU/chunked/HLS output. If the overlapped encode fails, the frames are encoded after capture exactly as before. * perf(producer): encode during capture only when a core is spare for the encoder With every core busy capturing, the encoder only slowed capture down, so the overlap now runs only when the render uses fewer workers than the CPU count worker sizing sees. Also pins the reviewed producer test-lane source hash and drops an added comment line. * refactor(producer): shorter comments on the encode-while-capturing helpers
1 parent d67e81c commit eec3c51

10 files changed

Lines changed: 382 additions & 61 deletions

File tree

‎packages/engine/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,7 @@ export {
295295
type WorkerResult,
296296
type WorkerSizing,
297297
type WorkerSizingBound,
298+
type LandedFrame,
298299
type ParallelProgress,
299300
} from "./services/parallelCoordinator.js";
300301

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

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,14 @@ export interface ParallelProgress {
8888
workerProgress: Map<number, number>;
8989
/** Latest lifecycle transition; absent on ordinary completed-frame updates. */
9090
latestWorkerPhase?: ParallelWorkerPhaseDiagnostic;
91+
/** Disk capture only: the frame file this update finished writing, readable from now on. */
92+
landedFrame?: LandedFrame;
93+
}
94+
95+
/** A captured frame file: `index` is its file index (`frame_<index>`), `path` where it was written. */
96+
export interface LandedFrame {
97+
index: number;
98+
path: string;
9199
}
92100

93101
export type ParallelWorkerPhase =
@@ -552,7 +560,9 @@ async function captureFrameRange(
552560
task: WorkerTask,
553561
captureOptions: CaptureOptions,
554562
signal: AbortSignal | undefined,
555-
onFrameCaptured: ((workerId: number, frameIndex: number) => void) | undefined,
563+
onFrameCaptured:
564+
| ((workerId: number, frameIndex: number, landedFrame?: LandedFrame) => void)
565+
| undefined,
556566
onFrameBuffer:
557567
| ((frameIndex: number, buffer: Buffer, session: CaptureSession) => Promise<void>)
558568
| undefined,
@@ -645,18 +655,20 @@ async function captureFrameRange(
645655
const time = (i * captureOptions.fps.den) / captureOptions.fps.num;
646656
const fileFrameIdx = i - outputOffset;
647657

658+
let landedFrame: LandedFrame | undefined;
648659
if (onFrameBuffer) {
649660
const { buffer } = await runCaptureOperation("frame_capture", i, () =>
650661
captureFrameToBuffer(session, fileFrameIdx, time),
651662
);
652663
await onFrameBuffer(i, buffer, session);
653664
} else {
654-
await runCaptureOperation("frame_capture", i, () =>
665+
const { path } = await runCaptureOperation("frame_capture", i, () =>
655666
captureFrame(session, fileFrameIdx, time),
656667
);
668+
landedFrame = { index: fileFrameIdx, path };
657669
}
658670
framesCaptured++;
659-
if (onFrameCaptured) onFrameCaptured(task.workerId, i);
671+
if (onFrameCaptured) onFrameCaptured(task.workerId, i, landedFrame);
660672
}
661673
return framesCaptured;
662674
}
@@ -824,7 +836,7 @@ async function executeWorkerTask(
824836
captureOptions: CaptureOptions,
825837
createBeforeCaptureHook: () => BeforeCaptureHook | null,
826838
signal?: AbortSignal,
827-
onFrameCaptured?: (workerId: number, frameIndex: number) => void,
839+
onFrameCaptured?: (workerId: number, frameIndex: number, landedFrame?: LandedFrame) => void,
828840
onFrameBuffer?: (frameIndex: number, buffer: Buffer, session: CaptureSession) => Promise<void>,
829841
config?: Partial<EngineConfig>,
830842
parallel?: boolean,
@@ -1066,7 +1078,7 @@ export async function executeParallelCapture(
10661078

10671079
for (const task of tasks) workerProgress.set(task.workerId, 0);
10681080

1069-
const onFrameCaptured = (workerId: number, _frameIndex: number) => {
1081+
const onFrameCaptured = (workerId: number, _frameIndex: number, landedFrame?: LandedFrame) => {
10701082
const current = workerProgress.get(workerId) || 0;
10711083
workerProgress.set(workerId, current + 1);
10721084

@@ -1077,6 +1089,7 @@ export async function executeParallelCapture(
10771089
capturedFrames,
10781090
activeWorkers: tasks.length,
10791091
workerProgress: new Map(workerProgress),
1092+
...(landedFrame && { landedFrame }),
10801093
});
10811094
}
10821095
};

‎packages/producer/scripts/test-classification.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ const INTEGRATION_TEST_FILES = new Set([
3737
"src/services/render/renderCancel.integration.test.ts",
3838
"src/services/render/segmentedColorGrading.integration.test.ts",
3939
"src/services/render/stages/compileStage.mediaType.test.ts",
40+
"src/services/render/stages/encodeWhileCapturing.test.ts",
4041
"src/services/render/stages/gifEncodeArgs.test.ts",
4142
"src/services/videoFrameBorderClip.test.ts",
4243
"src/utils/audioRegression.test.ts",

‎packages/producer/src/services/render/stages/captureStage.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ import {
4545
type CapturePerfSummary,
4646
type CaptureSession,
4747
type EngineConfig,
48+
type LandedFrame,
4849
captureFrame,
4950
captureFrameToBufferPipelined,
5051
verifyDiskDrawElementSamples,
@@ -118,6 +119,7 @@ export interface CaptureStageInput {
118119
* When set, `endFrame - startFrame` MUST equal `totalFrames`.
119120
*/
120121
frameRange?: { startFrame: number; endFrame: number };
122+
onFrameLanded?: (frame: LandedFrame) => void;
121123
}
122124

123125
export interface CaptureStageResult {
@@ -408,6 +410,7 @@ export async function runCaptureStage(input: CaptureStageInput): Promise<Capture
408410
if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
409411
return;
410412
}
413+
if (progress.landedFrame) input.onFrameLanded?.(progress.landedFrame);
411414
job.framesRendered = progress.capturedFrames;
412415
checkDiskProjection(progress.capturedFrames);
413416
const frameProgress = progress.capturedFrames / progress.totalFrames;

‎packages/producer/src/services/render/stages/encodeStage.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ mock.module("@hyperframes/engine", () => ({
4646
}),
4747
resolveConfig: () => resolvedEngineConfig,
4848
runFfmpeg: runFfmpegMock,
49+
spawnStreamingEncoder: mock(),
4950
}));
5051

5152
const tempDirs: string[] = [];

‎packages/producer/src/services/render/stages/encodeStage.ts‎

Lines changed: 177 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@
2626
* branch + same args.
2727
* - `Encoding failed: <err>` throws on the encoder's
2828
* `success: false`.
29+
*
30+
* `encodeWhileCapturing` runs the same mp4 encode during multi-worker disk
31+
* capture, feeding frames in order as they land, and falls back to this
32+
* stage's encode if it fails.
2933
*/
3034

3135
import {
@@ -38,6 +42,7 @@ import {
3842
statSync,
3943
writeFileSync,
4044
} from "node:fs";
45+
import { readFile } from "node:fs/promises";
4146
import { dirname, join } from "node:path";
4247
import {
4348
encodeFramesChunkedConcat,
@@ -47,16 +52,18 @@ import {
4752
MIXED_AUDIO_FILENAME,
4853
resolveConfig,
4954
runFfmpeg,
55+
spawnStreamingEncoder,
5056
type EngineConfig,
5157
type EncodeResult,
58+
type LandedFrame,
5259
} from "@hyperframes/engine";
5360
import {
5461
clearGifFramesBeforeNext,
5562
gifClearsAfterLeavingFrameInPlace,
5663
type Fps,
5764
} from "@hyperframes/core";
5865
import type { ProducerLogger } from "../../../logger.js";
59-
import { formatExportFrameName } from "../../../utils/paths.js";
66+
import { formatCaptureFrameName, formatExportFrameName } from "../../../utils/paths.js";
6067
import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
6168
import {
6269
buildGifPalettegenArgs,
@@ -108,7 +115,8 @@ export interface EncodeStageInput {
108115
enableChunkedEncode: boolean;
109116
chunkedEncodeSize: number;
110117
/** Already-resolved engine config from the orchestrator; direct callers fall back below. */
111-
engineConfig?: Pick<EngineConfig, "ffmpegEncodeTimeout" | "vp9CpuUsed">;
118+
engineConfig?: Pick<EngineConfig, "ffmpegEncodeTimeout" | "vp9CpuUsed"> &
119+
Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>;
112120
abortSignal: AbortSignal | undefined;
113121
assertNotAborted: () => void;
114122
onProgress?: ProgressCallback;
@@ -254,23 +262,183 @@ function startEncodeProgress(
254262
return (frames = total) => reportEncodeProgress(job, frames, total, onProgress, 75);
255263
}
256264

265+
function resolveEngineConfig(input: EncodeStageInput) {
266+
return input.engineConfig ?? input.job.config.producerConfig ?? resolveConfig();
267+
}
268+
269+
function videoEncoderOptions(input: EncodeStageInput, engineCfg: Pick<EngineConfig, "vp9CpuUsed">) {
270+
const { job, preset } = input;
271+
return {
272+
fps: job.config.fps,
273+
width: input.width,
274+
height: input.height,
275+
codec: preset.codec,
276+
preset: preset.preset,
277+
quality: input.effectiveQuality,
278+
bitrate: input.effectiveBitrate,
279+
pixelFormat: preset.pixelFormat,
280+
vp9CpuUsed: engineCfg.vp9CpuUsed,
281+
useGpu: job.config.useGpu,
282+
hdr: preset.hdr,
283+
// Distributed chunk renders pass these so the encoder writes closed-GOP
284+
// keyframes that survive `-f concat -c copy` at assemble time. In-process
285+
// renders leave both undefined → preserves the existing open-GOP output.
286+
lockGopForChunkConcat: input.lockGopForChunkConcat === true,
287+
gopSize: input.gopSize,
288+
};
289+
}
290+
291+
/**
292+
* Software libx264 from JPEG only: the streaming encoder then runs the disk encoder's
293+
* arguments (same bytes). Needs a core the capture workers leave free.
294+
*/
295+
export function canEncodeWhileCapturing(
296+
input: EncodeStageInput,
297+
workerCount: number,
298+
cpuCount: number,
299+
): boolean {
300+
return (
301+
workerCount > 1 &&
302+
workerCount < cpuCount &&
303+
!input.isPngSequence &&
304+
!input.isGif &&
305+
!input.enableChunkedEncode &&
306+
input.preset.codec === "h264" &&
307+
!input.preset.hdr &&
308+
input.job.config.useGpu !== true &&
309+
input.captureImageFormat === "jpeg" &&
310+
input.lockGopForChunkConcat !== true
311+
);
312+
}
313+
314+
export interface EncodeWhileCapturing {
315+
/** A worker finished writing this frame. */
316+
onFrameLanded: (frame: LandedFrame) => void;
317+
/** Capture succeeded and every frame is in `framesDir`: encode the rest. */
318+
finish: () => Promise<EncodeStageResult>;
319+
/** Capture failed: stop the encoder and wait for it to exit. */
320+
abort: () => Promise<void>;
321+
/** Frames handed to the encoder so far. */
322+
readonly framesFed: number;
323+
}
324+
325+
/** The merge renames a worker's frame into `framesDir` at any moment; rename is atomic, so it is at one of the two. */
326+
async function readLandedFrame(workerPath: string | undefined, mergedPath: string) {
327+
if (workerPath !== undefined) {
328+
try {
329+
return await readFile(workerPath);
330+
} catch (error) {
331+
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
332+
}
333+
}
334+
return readFile(mergedPath);
335+
}
336+
337+
/**
338+
* Feeds frames 0, 1, 2… to the encoder as each lands; capture never waits on it.
339+
* On failure `finish` re-runs `runEncodeStage` on the same frames.
340+
*/
341+
export function encodeWhileCapturing(
342+
input: EncodeStageInput,
343+
totalFrames: number,
344+
): EncodeWhileCapturing {
345+
const engineCfg = resolveEngineConfig(input);
346+
const stop = new AbortController();
347+
const signal = input.abortSignal
348+
? AbortSignal.any([input.abortSignal, stop.signal])
349+
: stop.signal;
350+
const landed = new Map<number, string>();
351+
let captureDone = false;
352+
let framesFed = 0;
353+
let wake: (() => void) | null = null;
354+
const nudge = () => {
355+
wake?.();
356+
wake = null;
357+
};
358+
signal.addEventListener("abort", nudge, { once: true });
359+
let reportFed = null as ((frames?: number) => void) | null;
360+
361+
const encoder = spawnStreamingEncoder(
362+
input.videoOnlyPath,
363+
{ ...videoEncoderOptions(input, engineCfg), imageFormat: "jpeg" },
364+
signal,
365+
engineCfg,
366+
);
367+
const fed: Promise<unknown> = (async () => {
368+
const stream = await encoder;
369+
for (let next = 0; next < totalFrames; next++) {
370+
while (!landed.has(next) && !captureDone && !signal.aborted) {
371+
await new Promise<void>((resolve) => (wake = resolve));
372+
}
373+
if (signal.aborted) return;
374+
const mergedPath = join(input.framesDir, formatCaptureFrameName(next, "jpg"));
375+
const frame = await readLandedFrame(landed.get(next), mergedPath);
376+
landed.delete(next);
377+
if (!(await stream.writeFrame(frame))) {
378+
throw new Error(stream.getExitError() ?? "encoder exited before the last frame");
379+
}
380+
framesFed++;
381+
reportFed?.(framesFed);
382+
}
383+
})().then(
384+
() => undefined,
385+
(error: unknown) => error ?? new Error("encode failed"),
386+
);
387+
const closeEncoder = async () => (await encoder.catch(() => null))?.close();
388+
389+
return {
390+
onFrameLanded: (frame) => {
391+
landed.set(frame.index, frame.path);
392+
nudge();
393+
},
394+
finish: async () => {
395+
const start = Date.now();
396+
captureDone = true;
397+
input.log.info("[Render] Encoded frames while capturing", {
398+
framesFed,
399+
totalFrames,
400+
});
401+
const encoded = startEncodeProgress(input.job, "Encoding video", input.onProgress);
402+
reportFed = encoded;
403+
nudge();
404+
const failure = await fed;
405+
const result = await closeEncoder();
406+
input.assertNotAborted();
407+
if (failure === undefined && result?.success) {
408+
encoded();
409+
return { encodeMs: Date.now() - start };
410+
}
411+
input.log.warn(
412+
"[Render] Encoding while capturing failed; encoding the frames after capture",
413+
{
414+
error: String(failure ?? result?.error),
415+
},
416+
);
417+
return runEncodeStage(input);
418+
},
419+
abort: async () => {
420+
stop.abort();
421+
await fed;
422+
await closeEncoder();
423+
},
424+
get framesFed() {
425+
return framesFed;
426+
},
427+
};
428+
}
429+
257430
export async function runEncodeStage(input: EncodeStageInput): Promise<EncodeStageResult> {
258431
const {
259432
job,
260433
log,
261434
outputPath,
262435
framesDir,
263436
videoOnlyPath,
264-
width,
265-
height,
266437
needsAlpha,
267438
hasAudio,
268439
audioOutputPath,
269440
isPngSequence,
270441
isGif,
271-
preset,
272-
effectiveQuality,
273-
effectiveBitrate,
274442
enableChunkedEncode,
275443
chunkedEncodeSize,
276444
abortSignal,
@@ -313,7 +481,7 @@ export async function runEncodeStage(input: EncodeStageInput): Promise<EncodeSta
313481
return { encodeMs: Date.now() - stage5Start };
314482
}
315483

316-
const engineCfg = input.engineConfig ?? job.config.producerConfig ?? resolveConfig();
484+
const engineCfg = resolveEngineConfig(input);
317485

318486
if (isGif) {
319487
// ── Stage 5 (gif): two-pass palette encode ───────────────────────
@@ -357,24 +525,7 @@ export async function runEncodeStage(input: EncodeStageInput): Promise<EncodeSta
357525

358526
const frameExt = frameFileExtension(input.captureImageFormat);
359527
const framePattern = `frame_%06d.${frameExt}`;
360-
const encoderOpts = {
361-
fps: job.config.fps,
362-
width,
363-
height,
364-
codec: preset.codec,
365-
preset: preset.preset,
366-
quality: effectiveQuality,
367-
bitrate: effectiveBitrate,
368-
pixelFormat: preset.pixelFormat,
369-
vp9CpuUsed: engineCfg.vp9CpuUsed,
370-
useGpu: job.config.useGpu,
371-
hdr: preset.hdr,
372-
// Distributed chunk renders pass these so the encoder writes closed-GOP
373-
// keyframes that survive `-f concat -c copy` at assemble time. In-process
374-
// renders leave both undefined → preserves the existing open-GOP output.
375-
lockGopForChunkConcat: input.lockGopForChunkConcat === true,
376-
gopSize: input.gopSize,
377-
};
528+
const encoderOpts = videoEncoderOptions(input, engineCfg);
378529
const encodeResult = enableChunkedEncode
379530
? await encodeFramesChunkedConcat(
380531
framesDir,

0 commit comments

Comments
 (0)