mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
* feat(engine): encoders cap peak bitrate and place keyframes on a set interval * style(engine): shorten the rate-cap comment * style(engine): drop the doc lines the comment ratchet flagged * feat(producer): mp4 renders honour a keyframe interval and a peak bitrate cap on every encoder path * style(producer): shorten the delivery encoder file headers * style(producer): drop a comment line from the segment manifest * style(producer): shorten the integration test header * test: delivery encoder tests follow the ffprobe argv contract and run in the integration lane * feat: the render request, server and Lambda plan carry the keyframe interval and peak bitrate cap * fix(studio): the Studio render route passes the keyframe interval and bitrate cap to the encoder * chore(studio-server): drop a comment the helper's name already says * feat(cli): render and lambda render take --keyframe-interval, --max-bitrate and --buffer-size
720 lines
26 KiB
TypeScript
720 lines
26 KiB
TypeScript
// fallow-ignore-file unused-type code-duplication complexity
|
||
/**
|
||
* Streaming Encoder Service
|
||
*
|
||
* Pipes frame screenshot buffers directly to FFmpeg's stdin via `-f image2pipe`
|
||
* instead of writing them to disk and reading them back in a separate encode
|
||
* stage. Inspired by Remotion's approach to browser-based video rendering.
|
||
*
|
||
* Two building blocks:
|
||
* 1. Frame reorder buffer – ensures out-of-order parallel workers feed
|
||
* frames to FFmpeg stdin in sequential order.
|
||
* 2. Streaming FFmpeg encoder – spawns FFmpeg with `-f image2pipe` and
|
||
* exposes an async `writeFrame(buffer)` + `close()` API.
|
||
*/
|
||
|
||
import { jpegInputError } from "../utils/jpegInput.js";
|
||
import { spawn, type ChildProcess } from "child_process";
|
||
import { once } from "events";
|
||
import { trackChildProcess } from "../utils/processTracker.js";
|
||
import {
|
||
ManagedChildProcess,
|
||
type ManagedProcessTerminationReason,
|
||
} from "../utils/managedChildProcess.js";
|
||
import { existsSync, mkdirSync, statSync } from "fs";
|
||
import { dirname } from "path";
|
||
|
||
import {
|
||
type GpuEncoder,
|
||
getCachedGpuEncoder,
|
||
getGpuEncoderName,
|
||
buildVideoToolboxRateControlArgs,
|
||
mapPresetForGpuEncoder,
|
||
} from "../utils/gpuEncoder.js";
|
||
import {
|
||
ffmpegStatsReader,
|
||
formatFfmpegError,
|
||
isExternalFfmpegInterruption,
|
||
} from "../utils/runFfmpeg.js";
|
||
import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
|
||
import { getHdrEncoderColorParams, hdrFrameTagsFilter } from "../utils/hdr.js";
|
||
import { withEvenDimensionPad } from "../utils/evenDimensions.js";
|
||
import {
|
||
SDR_CAPTURE_TO_BT709_FILTER,
|
||
SDR_RGB_TO_TAGGED_BT709_FILTER,
|
||
} from "../utils/sdrCaptureColor.js";
|
||
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
|
||
import { fpsToFfmpegArg, fpsToNumber, type Fps } from "@hyperframes/core";
|
||
import { appendVp9CpuUsedArg } from "./vp9Options.js";
|
||
import { appendSoftwareEncoderThreadsArg } from "./softwareEncoderThreads.js";
|
||
import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
|
||
|
||
import {
|
||
appendLockedGopArgs,
|
||
appendRateCapArgs,
|
||
lockedGopCodecParams,
|
||
resolveLockedGopSize,
|
||
} from "./chunkEncoder.js";
|
||
|
||
// Re-export EncoderOptions so callers can reference the type via this module.
|
||
export type { EncoderOptions } from "./chunkEncoder.types.js";
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// 1. Frame reorder buffer — ordered async barrier
|
||
// ---------------------------------------------------------------------------
|
||
//
|
||
// Parallel workers produce frames out of order; FFmpeg's stdin expects them in
|
||
// strict sequential order. Each worker calls `waitForFrame(n)` to block until
|
||
// its turn, writes, then calls `advanceTo(n + 1)` to release the next waiter.
|
||
//
|
||
// `pending` holds an array per frame index (not a single resolver) so that
|
||
// `waitForAllDone` can coexist with the writer still waiting on the final
|
||
// frame without one clobbering the other.
|
||
|
||
export interface FrameReorderBuffer {
|
||
waitForFrame: (frame: number) => Promise<void>;
|
||
advanceTo: (frame: number) => void;
|
||
waitForAllDone: () => Promise<void>;
|
||
/**
|
||
* Reject every parked and future waiter with `err`. Required by the
|
||
* interleaved parallel drain: when one worker fails (e.g. drawElement
|
||
* self-verification), its frames will never be written — peers parked in
|
||
* waitForFrame would otherwise deadlock the whole capture (the worker pool
|
||
* awaits ALL workers before surfacing the failure).
|
||
*/
|
||
abort: (err: Error) => void;
|
||
}
|
||
|
||
export function createFrameReorderBuffer(startFrame: number, endFrame: number): FrameReorderBuffer {
|
||
let cursor = startFrame;
|
||
let aborted: Error | null = null;
|
||
const pending = new Map<number, Array<{ resolve: () => void; reject: (e: Error) => void }>>();
|
||
|
||
const enqueueAt = (frame: number, resolve: () => void, reject: (e: Error) => void): void => {
|
||
const list = pending.get(frame);
|
||
if (list === undefined) {
|
||
pending.set(frame, [{ resolve, reject }]);
|
||
} else {
|
||
list.push({ resolve, reject });
|
||
}
|
||
};
|
||
|
||
const flushAt = (frame: number): void => {
|
||
const list = pending.get(frame);
|
||
if (list === undefined) return;
|
||
pending.delete(frame);
|
||
for (const waiter of list) waiter.resolve();
|
||
};
|
||
|
||
const waitForFrame = (frame: number): Promise<void> =>
|
||
new Promise<void>((resolve, reject) => {
|
||
if (aborted) {
|
||
reject(aborted);
|
||
return;
|
||
}
|
||
if (frame === cursor) {
|
||
resolve();
|
||
return;
|
||
}
|
||
enqueueAt(frame, resolve, reject);
|
||
});
|
||
|
||
const advanceTo = (frame: number): void => {
|
||
cursor = frame;
|
||
flushAt(frame);
|
||
};
|
||
|
||
const waitForAllDone = (): Promise<void> =>
|
||
new Promise<void>((resolve, reject) => {
|
||
if (aborted) {
|
||
reject(aborted);
|
||
return;
|
||
}
|
||
if (cursor >= endFrame) {
|
||
resolve();
|
||
return;
|
||
}
|
||
enqueueAt(endFrame, resolve, reject);
|
||
});
|
||
|
||
const abort = (err: Error): void => {
|
||
if (aborted) return;
|
||
aborted = err;
|
||
for (const [frame, list] of pending) {
|
||
pending.delete(frame);
|
||
for (const waiter of list) waiter.reject(err);
|
||
}
|
||
};
|
||
|
||
return { waitForFrame, advanceTo, waitForAllDone, abort };
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// 2. Streaming FFmpeg encoder
|
||
// ---------------------------------------------------------------------------
|
||
|
||
export interface StreamingEncoderOptions {
|
||
/** Frame rate as an exact rational; see `Fps` in @hyperframes/core. */
|
||
fps: Fps;
|
||
width: number;
|
||
height: number;
|
||
codec?: "h264" | "h265" | "vp9" | "prores";
|
||
preset?: string;
|
||
quality?: number;
|
||
bitrate?: string;
|
||
maxBitrate?: string;
|
||
bufferSize?: string;
|
||
pixelFormat?: string;
|
||
/** libvpx-vp9 -cpu-used value. Defaults to the engine VP9 setting. */
|
||
vp9CpuUsed?: number;
|
||
useGpu?: boolean;
|
||
imageFormat?: "jpeg" | "png";
|
||
hdr?: { transfer: import("../utils/hdr.js").HdrTransfer };
|
||
/** When set, use rawvideo input instead of image2pipe. For HDR PQ-encoded frames. */
|
||
rawInputFormat?: "rgb48le";
|
||
/**
|
||
* Force an IDR keyframe every `gopSize` frames. Set by the HLS format so
|
||
* `-f hls -c copy` can cut segments on exact time boundaries — the segmenter
|
||
* only splits at keyframes the encoder already emitted. Default `false`
|
||
* leaves the arg list byte-identical. libx264 / libx265 only (GPU encoders,
|
||
* VP9 and ProRes ignore it); see `EncoderOptions.lockGopForChunkConcat`.
|
||
*/
|
||
lockGopForChunkConcat?: boolean;
|
||
/** Required when `lockGopForChunkConcat` is `true`. Frames per GOP. */
|
||
gopSize?: number;
|
||
}
|
||
|
||
export interface StreamingEncoderResult {
|
||
success: boolean;
|
||
durationMs: number;
|
||
fileSize: number;
|
||
error?: string;
|
||
/** Stable machine-readable cause for failures safe to retry on a fresh host. */
|
||
failureReason?: "external_interruption";
|
||
}
|
||
|
||
export interface StreamingEncoder {
|
||
/**
|
||
* Write one frame to FFmpeg stdin, awaiting `drain` when the pipe is full
|
||
* so back-pressure propagates to the caller. Resolves `false` when FFmpeg
|
||
* is already gone. Callers must serialize calls — one in-flight writeFrame
|
||
* per encoder (the frame reorder buffer provides this ordering); concurrent
|
||
* calls would interleave frame bytes on the pipe and race the drain wait.
|
||
*/
|
||
writeFrame: (buffer: Buffer) => Promise<boolean>;
|
||
/** `onFramesEncoded` hears ffmpeg's encoded-frame count while close waits for it to finish. */
|
||
close: (onFramesEncoded?: (frames: number) => void) => Promise<StreamingEncoderResult>;
|
||
getExitStatus: () => "running" | "success" | "error";
|
||
/**
|
||
* The FFmpeg failure reason (exit code + tail of stderr), or `undefined`
|
||
* while the process is still running / exited cleanly. Lets a `writeFrame`
|
||
* that returned `false` because FFmpeg died surface WHY it died (bad args,
|
||
* unsupported codec, disk full) instead of a bare "encoder exited" message.
|
||
*/
|
||
getExitError: () => string | undefined;
|
||
/** Machine-readable cause available after FFmpeg exits unexpectedly mid-write. */
|
||
getExitFailureReason?: () => "external_interruption" | undefined;
|
||
}
|
||
|
||
/**
|
||
* Build FFmpeg args for streaming (image2pipe) input.
|
||
* Reuses the same codec/quality/GPU logic as chunkEncoder's buildEncoderArgs
|
||
* but with `-f image2pipe` instead of `-i <pattern>`.
|
||
*
|
||
* Exported so unit tests can assert on the constructed CLI without spawning
|
||
* FFmpeg — see streamingEncoder.test.ts.
|
||
*/
|
||
export function buildStreamingArgs(
|
||
options: StreamingEncoderOptions,
|
||
outputPath: string,
|
||
gpuEncoder: GpuEncoder = null,
|
||
): string[] {
|
||
const {
|
||
fps,
|
||
codec = "h264",
|
||
preset = "medium",
|
||
quality = 23,
|
||
bitrate,
|
||
pixelFormat = "yuv420p",
|
||
vp9CpuUsed,
|
||
useGpu = false,
|
||
imageFormat = "jpeg",
|
||
} = options;
|
||
|
||
// Input args: pipe from stdin
|
||
const args: string[] = [];
|
||
if (options.rawInputFormat) {
|
||
// Raw pixel input (HLG/PQ-encoded rgb48le from FFmpeg extraction).
|
||
// Tag the input with the correct color space so FFmpeg uses the right
|
||
// YUV matrix when converting rgb48le → yuv420p10le for encoding.
|
||
// Without these tags FFmpeg assumes bt709 and applies the wrong matrix.
|
||
const hdrTransfer = options.hdr?.transfer;
|
||
const inputColorTrc =
|
||
hdrTransfer === "pq" ? "smpte2084" : hdrTransfer === "hlg" ? "arib-std-b67" : undefined;
|
||
args.push(
|
||
"-f",
|
||
"rawvideo",
|
||
"-pix_fmt",
|
||
options.rawInputFormat,
|
||
"-s",
|
||
`${options.width}x${options.height}`,
|
||
"-framerate",
|
||
fpsToFfmpegArg(fps),
|
||
);
|
||
if (inputColorTrc) {
|
||
args.push(
|
||
"-color_primaries",
|
||
"bt2020",
|
||
"-color_trc",
|
||
inputColorTrc,
|
||
"-colorspace",
|
||
"bt2020nc",
|
||
);
|
||
}
|
||
args.push("-i", "-");
|
||
} else {
|
||
const inputCodec = imageFormat === "png" ? "png" : "mjpeg";
|
||
args.push(
|
||
"-f",
|
||
"image2pipe",
|
||
"-vcodec",
|
||
inputCodec,
|
||
"-framerate",
|
||
fpsToFfmpegArg(fps),
|
||
"-i",
|
||
"-",
|
||
);
|
||
}
|
||
args.push("-r", fpsToFfmpegArg(fps));
|
||
|
||
const shouldUseGpu = useGpu && gpuEncoder !== null;
|
||
appendRateCapArgs(args, options);
|
||
|
||
if (codec === "h264" || codec === "h265") {
|
||
if (shouldUseGpu) {
|
||
const encoderName = getGpuEncoderName(gpuEncoder, codec);
|
||
args.push("-c:v", encoderName);
|
||
|
||
switch (gpuEncoder) {
|
||
case "nvenc":
|
||
args.push("-preset", mapPresetForGpuEncoder("nvenc", preset));
|
||
if (bitrate) args.push("-b:v", bitrate);
|
||
else args.push("-cq", String(quality));
|
||
break;
|
||
case "videotoolbox":
|
||
args.push(
|
||
...buildVideoToolboxRateControlArgs({
|
||
bitrate,
|
||
width: options.width,
|
||
height: options.height,
|
||
fps: fpsToNumber(fps),
|
||
quality,
|
||
}),
|
||
);
|
||
break;
|
||
case "vaapi":
|
||
args.unshift("-vaapi_device", "/dev/dri/renderD128");
|
||
args.push("-vf", "format=nv12,hwupload");
|
||
if (bitrate) args.push("-b:v", bitrate);
|
||
else args.push("-qp", String(quality));
|
||
break;
|
||
case "qsv":
|
||
args.push("-preset", mapPresetForGpuEncoder("qsv", preset));
|
||
if (bitrate) args.push("-b:v", bitrate);
|
||
else args.push("-global_quality", String(quality));
|
||
break;
|
||
case "amf":
|
||
if (bitrate) args.push("-b:v", bitrate);
|
||
else args.push("-rc", "cqp", "-qp_i", String(quality), "-qp_p", String(quality));
|
||
break;
|
||
}
|
||
|
||
// Mirror SW branch: GPU h264 paths emit B-frames by default (nvenc, amf,
|
||
// qsv, vaapi) and produce the same negative-DTS freeze for downstream players.
|
||
// See chunkEncoder.buildEncoderArgs for the full explanation.
|
||
if (
|
||
codec === "h264" &&
|
||
(gpuEncoder === "nvenc" ||
|
||
gpuEncoder === "qsv" ||
|
||
gpuEncoder === "vaapi" ||
|
||
gpuEncoder === "amf")
|
||
) {
|
||
args.push("-bf", "0");
|
||
if (gpuEncoder === "qsv") {
|
||
args.push("-b_strategy", "0");
|
||
}
|
||
}
|
||
} else {
|
||
const encoderName = codec === "h264" ? "libx264" : "libx265";
|
||
args.push("-c:v", encoderName, "-preset", preset);
|
||
appendSoftwareEncoderThreadsArg(args, encoderName);
|
||
if (bitrate) args.push("-b:v", bitrate);
|
||
else args.push("-crf", String(quality));
|
||
|
||
// Same closed-GOP lock as chunkEncoder.buildEncoderArgs, so the HLS
|
||
// packager can cut `-c copy` segments on exact keyframe boundaries.
|
||
const lockedGop = resolveLockedGopSize(options);
|
||
if (lockedGop !== null) appendLockedGopArgs(args, lockedGop);
|
||
|
||
// Mirrors chunkEncoder: disable B-frames for h264 so PTS == DTS, no
|
||
// negative DTS at stream start. Without this, files freeze on the
|
||
// first frame in VS Code preview, several browsers, and some HW
|
||
// decoders. See chunkEncoder.buildEncoderArgs for the full reasoning.
|
||
// h265 also gets `-bf 0` under a locked GOP: B-frame reordering across
|
||
// a segment boundary brings the same negative-DTS hazard back at every seam.
|
||
if (codec === "h264" || lockedGop !== null) {
|
||
args.push("-bf", "0");
|
||
}
|
||
|
||
// Encoder-specific params: anti-banding + color space tagging.
|
||
// For HDR, getHdrEncoderColorParams also emits the SMPTE ST 2086
|
||
// mastering-display and CTA-861.3 MaxCLL/MaxFALL SEI messages —
|
||
// without them, players (Apple, YouTube, HDR TVs) treat the file
|
||
// as SDR BT.2020 and tone-map incorrectly.
|
||
const xParamsFlag = codec === "h264" ? "-x264-params" : "-x265-params";
|
||
const colorParams =
|
||
options.rawInputFormat && options.hdr
|
||
? getHdrEncoderColorParams(options.hdr.transfer).x265ColorParams
|
||
: "colorprim=bt709:transfer=bt709:colormatrix=bt709";
|
||
const gopParams = lockedGop !== null ? `:${lockedGopCodecParams(codec, lockedGop)}` : "";
|
||
if (preset === "ultrafast") {
|
||
args.push(xParamsFlag, `aq-mode=3:${colorParams}${gopParams}`);
|
||
} else {
|
||
args.push(xParamsFlag, `aq-mode=3:aq-strength=0.8:deblock=1,1:${colorParams}${gopParams}`);
|
||
}
|
||
}
|
||
// Apple devices require hvc1 tag for HEVC playback (default hev1 won't open in QuickTime)
|
||
if (codec === "h265") {
|
||
args.push("-tag:v", "hvc1");
|
||
}
|
||
} else if (codec === "vp9") {
|
||
args.push("-c:v", "libvpx-vp9", "-b:v", bitrate || "0", "-crf", String(quality));
|
||
args.push("-deadline", preset === "ultrafast" ? "realtime" : "good");
|
||
args.push("-row-mt", "1");
|
||
appendVp9CpuUsedArg(args, vp9CpuUsed);
|
||
if (pixelFormat === "yuva420p") {
|
||
args.push("-auto-alt-ref", "0");
|
||
args.push("-metadata:s:v:0", "alpha_mode=1");
|
||
}
|
||
} else if (codec === "prores") {
|
||
args.push("-c:v", "prores_ks", "-profile:v", preset, "-vendor", "apl0");
|
||
args.push("-vf", SDR_RGB_TO_TAGGED_BT709_FILTER);
|
||
args.push("-pix_fmt", pixelFormat);
|
||
appendRenderProvenanceArgs(args, outputPath);
|
||
return [...args, "-y", outputPath];
|
||
}
|
||
|
||
// Color space metadata.
|
||
// When rawInputFormat is set, data comes from the WebGPU HDR pipeline
|
||
// (PQ-encoded) — tag with bt2020/PQ truthfully.
|
||
// Otherwise, Chrome captures sRGB — tag as bt709.
|
||
if (codec === "h264" || codec === "h265") {
|
||
if (options.rawInputFormat && options.hdr) {
|
||
args.push(
|
||
"-colorspace:v",
|
||
"bt2020nc",
|
||
"-color_primaries:v",
|
||
"bt2020",
|
||
"-color_trc:v",
|
||
options.hdr.transfer === "pq" ? "smpte2084" : "arib-std-b67",
|
||
"-color_range",
|
||
"tv",
|
||
);
|
||
} else {
|
||
args.push(
|
||
"-colorspace:v",
|
||
"bt709",
|
||
"-color_primaries:v",
|
||
"bt709",
|
||
"-color_trc:v",
|
||
"bt709",
|
||
"-color_range",
|
||
"tv",
|
||
);
|
||
}
|
||
|
||
// Raw HDR input (from WebGPU pipeline) is already PQ-encoded and is only tagged; SDR is
|
||
// converted: raw sRGB or Chrome's BT.601 JPEG screenshots to tagged BT.709 limited range.
|
||
const frameFilter =
|
||
options.rawInputFormat && options.hdr
|
||
? hdrFrameTagsFilter(options.hdr.transfer)
|
||
: options.rawInputFormat
|
||
? SDR_RGB_TO_TAGGED_BT709_FILTER
|
||
: SDR_CAPTURE_TO_BT709_FILTER;
|
||
if (gpuEncoder === "vaapi") {
|
||
// vaapi already runs `format=nv12,hwupload`; the nv12 conversion aligns
|
||
// odd dimensions before upload, so only prepend the colour conversion.
|
||
const vfIdx = args.indexOf("-vf");
|
||
if (vfIdx !== -1) {
|
||
args[vfIdx + 1] = `${frameFilter},${args[vfIdx + 1]}`;
|
||
}
|
||
} else {
|
||
// Pad odd dimensions up to even so 4:2:0 encoders (software and
|
||
// nvenc/videotoolbox/qsv/amf) don't abort with "height not divisible by 2".
|
||
args.push(
|
||
"-vf",
|
||
withEvenDimensionPad(frameFilter, pixelFormat, options.width, options.height),
|
||
);
|
||
}
|
||
|
||
// Fixed timescale for consistent A/V timing across platforms.
|
||
args.push("-video_track_timescale", "90000");
|
||
}
|
||
|
||
if (gpuEncoder !== "vaapi") {
|
||
args.push("-pix_fmt", pixelFormat);
|
||
}
|
||
|
||
// Belt-and-suspenders against negative DTS at stream start. See chunkEncoder
|
||
// for the full explanation; same playback compatibility class.
|
||
args.push("-avoid_negative_ts", "make_zero");
|
||
|
||
appendRenderProvenanceArgs(args, outputPath);
|
||
|
||
args.push("-y", outputPath);
|
||
return args;
|
||
}
|
||
|
||
/**
|
||
* Spawn a streaming FFmpeg encoder that accepts frame buffers on stdin.
|
||
*/
|
||
export async function spawnStreamingEncoder(
|
||
outputPath: string,
|
||
options: StreamingEncoderOptions,
|
||
signal?: AbortSignal,
|
||
config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>,
|
||
): Promise<StreamingEncoder> {
|
||
const outputDir = dirname(outputPath);
|
||
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
|
||
|
||
let gpuEncoder: GpuEncoder = null;
|
||
if (options.useGpu) {
|
||
gpuEncoder = await getCachedGpuEncoder();
|
||
}
|
||
|
||
const args = buildStreamingArgs(options, outputPath, gpuEncoder);
|
||
|
||
const ffmpeg: ChildProcess = spawn(getFfmpegBinary(), args, {
|
||
stdio: ["pipe", "pipe", "pipe"],
|
||
// See runFfmpeg.ts: keeps a console window off the user's desktop on Windows.
|
||
windowsHide: true,
|
||
});
|
||
trackChildProcess(ffmpeg);
|
||
|
||
let exitStatus: "running" | "success" | "error" = "running";
|
||
let stderr = "";
|
||
let exitCode: number | null = null;
|
||
let exitSignal: NodeJS.Signals | null = null;
|
||
let terminationReason: ManagedProcessTerminationReason = "exit";
|
||
|
||
ffmpeg.stdin?.on("error", () => {});
|
||
ffmpeg.stdout?.on("error", () => {});
|
||
|
||
// Inactivity timeout: fires only when no frame has been written for
|
||
// `ffmpegStreamingTimeout` ms. A slow-but-progressing capture (e.g. a CI
|
||
// runner under load) keeps resetting the timer on each writeFrame, so total
|
||
// wall-clock render time is unbounded — only a true hang (Chrome dead,
|
||
// capture stuck, no frames arriving) trips SIGTERM. The 600s default was
|
||
// previously a total-render cap, which intermittently killed legitimate
|
||
// slow renders mid-encode (FFmpeg got SIGTERM after most frames were sent;
|
||
// libx264 printed its summary and exited 255, observable as
|
||
// "Streaming encode failed: FFmpeg exited with code 255" with audio:0kB).
|
||
const streamingTimeout = config?.ffmpegStreamingTimeout ?? DEFAULT_CONFIG.ffmpegStreamingTimeout;
|
||
let framesEncoded = 0;
|
||
let onFramesEncoded: ((frames: number) => void) | undefined;
|
||
const managed = new ManagedChildProcess(ffmpeg, {
|
||
signal,
|
||
inactivityTimeoutMs: streamingTimeout,
|
||
onStderr: ffmpegStatsReader(({ frames }) => {
|
||
if (frames === undefined) return;
|
||
framesEncoded = frames;
|
||
onFramesEncoded?.(frames);
|
||
}),
|
||
});
|
||
const exitPromise = managed.wait().then((outcome) => {
|
||
exitCode = outcome.exitCode;
|
||
exitSignal = outcome.signal;
|
||
stderr = outcome.stderr;
|
||
terminationReason = outcome.reason;
|
||
exitStatus = outcome.reason === "exit" && outcome.exitCode === 0 ? "success" : "error";
|
||
return outcome;
|
||
});
|
||
|
||
const waitForDrainOrExit = async (
|
||
stdin: NonNullable<ChildProcess["stdin"]>,
|
||
): Promise<"drain" | "exit"> => {
|
||
// Back-pressure can hit once per frame. Do not race `exitPromise.then(...)`
|
||
// here: V8 retains `.then` reaction-list entries on an unsettled promise,
|
||
// so a one-hour 30fps render under steady back-pressure can accumulate
|
||
// ~108K closures + AbortControllers. Use one-shot listeners for this write
|
||
// instead, then abort them in finally. `close` is the event that flips
|
||
// `exitStatus`; re-check after listener attachment so a close emitted
|
||
// between `stdin.write(false)` and this await cannot hang forever.
|
||
const abortController = new AbortController();
|
||
try {
|
||
const drainPromise = once(stdin, "drain", { signal: abortController.signal }).then(
|
||
() => "drain" as const,
|
||
);
|
||
const closePromise = once(ffmpeg, "close", { signal: abortController.signal }).then(
|
||
() => "exit" as const,
|
||
);
|
||
const racePromise = Promise.race([drainPromise, closePromise]).catch(async (err: unknown) => {
|
||
if (err instanceof Error && err.name === "AbortError") {
|
||
return "exit" as const;
|
||
}
|
||
// `once(stdin, "drain")` rejects with the stream's own error when
|
||
// ffmpeg's read end closes first — a bare `write EPIPE` (darwin/
|
||
// linux) or `write EOF` (win32). Rethrowing it here made that the
|
||
// render error, with ffmpeg's exit code and stderr discarded, so a
|
||
// parked write observed the same death uninformatively that an
|
||
// unparked one reports through `getExitError()`. Wait for the exit
|
||
// to settle so the caller's `ensureFrameWritten` reads the reason,
|
||
// then report the exit like the `close` race does.
|
||
await exitPromise;
|
||
return "exit" as const;
|
||
});
|
||
|
||
if (managed.isSettled || exitStatus !== "running") {
|
||
return "exit";
|
||
}
|
||
|
||
return await racePromise;
|
||
} finally {
|
||
abortController.abort();
|
||
}
|
||
};
|
||
|
||
let inputFrameIndex = 0;
|
||
const encoder: StreamingEncoder = {
|
||
writeFrame: async (buffer: Buffer): Promise<boolean> => {
|
||
const stdin = ffmpeg.stdin;
|
||
if (exitStatus !== "running") {
|
||
return false;
|
||
}
|
||
if (!stdin || stdin.destroyed) {
|
||
// The OS can close the pipe (EPIPE) before Node delivers the child
|
||
// process `close` event. Wait for the shared exit settlement so the
|
||
// caller can synchronously inspect getExitFailureReason() instead of
|
||
// losing a host-interruption signal in this narrow race.
|
||
await exitPromise;
|
||
return false;
|
||
}
|
||
// Copy the buffer before writing — Node streams hold a reference to the
|
||
// provided buffer and drain it asynchronously. The HDR path's compositor
|
||
// reuses pre-allocated transOutput/normalCanvas buffers across frames,
|
||
// so without this copy the pipe would read partially-overwritten data
|
||
// and flicker.
|
||
const copy = Buffer.from(buffer);
|
||
if (!options.rawInputFormat && (options.imageFormat ?? "jpeg") === "jpeg") {
|
||
const error = jpegInputError(copy);
|
||
if (error) throw new Error(`Invalid JPEG input at frame ${inputFrameIndex}: ${error}`);
|
||
}
|
||
const accepted = stdin.write(copy);
|
||
inputFrameIndex++;
|
||
// Reset inactivity timer immediately ONLY on `accepted === true`. `true`
|
||
// means the write went through to the kernel pipe without buffering in
|
||
// Node — proof FFmpeg is actually consuming. `false` means Node's writable
|
||
// stream had to buffer (FFmpeg hasn't drained the pipe yet); we await
|
||
// `drain` before letting callers produce the next frame, and only reset
|
||
// after drain proves consumption. We deliberately don't reset before
|
||
// drain so a hung FFmpeg with a still-producing Chrome can't keep us
|
||
// alive forever while Node's stdin buffer grows to OOM. If FFmpeg exits
|
||
// before draining, waitForDrainOrExit returns "exit", removes its
|
||
// one-shot listeners, and callers see `false` instead of hanging.
|
||
if (accepted) {
|
||
managed.markActivity();
|
||
return true;
|
||
}
|
||
|
||
const drainResult = await waitForDrainOrExit(stdin);
|
||
if (drainResult !== "drain" || exitStatus !== "running") {
|
||
return false;
|
||
}
|
||
managed.markActivity();
|
||
return true;
|
||
},
|
||
|
||
close: async (onEncoded?: (frames: number) => void): Promise<StreamingEncoderResult> => {
|
||
// INVARIANT: close() is idempotent. The renderOrchestrator HDR cleanup
|
||
// path tracks an `encoderClosed` flag and may still re-call close() in
|
||
// the outer finally if the inner cleanup raised before the flag flipped.
|
||
// Each step here must be safe to repeat:
|
||
// - stdin.end gated on !destroyed: skipped on the second call
|
||
// - exitPromise: a single shared Promise; awaiting an already-resolved
|
||
// Promise resolves immediately with the same captured exitCode
|
||
// The returned StreamingEncoderResult is therefore consistent across
|
||
// repeated calls. If you change this method, preserve idempotency or
|
||
// a regression here will silently double-close ffmpeg and produce
|
||
// harder-to-trace errors at the orchestrator layer.
|
||
if (onEncoded && exitStatus === "running") {
|
||
onFramesEncoded = onEncoded;
|
||
onEncoded(framesEncoded);
|
||
}
|
||
const stdin = ffmpeg.stdin;
|
||
if (stdin && !stdin.destroyed) {
|
||
await new Promise<void>((resolve) => {
|
||
stdin.end(() => resolve());
|
||
});
|
||
}
|
||
|
||
const outcome = await exitPromise;
|
||
const durationMs = outcome.durationMs;
|
||
|
||
if (terminationReason === "abort") {
|
||
return {
|
||
success: false,
|
||
durationMs,
|
||
fileSize: 0,
|
||
error: "Streaming encode cancelled",
|
||
};
|
||
}
|
||
|
||
if (exitCode !== 0) {
|
||
const inactivitySuffix =
|
||
terminationReason === "inactivity"
|
||
? `\nFFmpeg stopped after ${streamingTimeout} ms without consuming a frame.`
|
||
: "";
|
||
return {
|
||
success: false,
|
||
durationMs,
|
||
fileSize: 0,
|
||
error: `${formatFfmpegError(exitCode, stderr)}${inactivitySuffix}`,
|
||
failureReason: isExternalFfmpegInterruption({
|
||
exitCode,
|
||
signal: exitSignal,
|
||
stderr,
|
||
terminationReason,
|
||
})
|
||
? "external_interruption"
|
||
: undefined,
|
||
};
|
||
}
|
||
|
||
const fileSize = existsSync(outputPath) ? statSync(outputPath).size : 0;
|
||
|
||
return { success: true, durationMs, fileSize };
|
||
},
|
||
|
||
getExitStatus: () => exitStatus,
|
||
|
||
getExitError: () => {
|
||
if (exitStatus !== "error") return undefined;
|
||
return formatFfmpegError(exitCode, stderr);
|
||
},
|
||
|
||
getExitFailureReason: () => {
|
||
if (exitStatus !== "error") return undefined;
|
||
return isExternalFfmpegInterruption({
|
||
exitCode,
|
||
signal: exitSignal,
|
||
stderr,
|
||
terminationReason,
|
||
})
|
||
? "external_interruption"
|
||
: undefined;
|
||
},
|
||
};
|
||
|
||
return encoder;
|
||
}
|