mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(engine): GPU renders use the NVENC preset names the host's ffmpeg lists * fix(engine): one ffmpeg stdout reader for encoder detection and preset listing * ci(engine): raise the engine unpacked size budget for the NVENC preset reader
1437 lines
52 KiB
TypeScript
1437 lines
52 KiB
TypeScript
// fallow-ignore-file code-duplication
|
||
/**
|
||
* buildStreamingArgs unit tests.
|
||
*
|
||
* These tests focus on the FFmpeg CLI shape rather than spawning the encoder
|
||
* — they're the cheap regression net for the HDR static-metadata bug
|
||
* (side_data=[none] in the encoded MP4) reproduced by
|
||
* packages/producer/scripts/hdr-smoke.ts. Without these assertions, future
|
||
* refactors of the x265-params string can silently strip
|
||
* master-display / max-cll and ship as SDR BT.2020 again.
|
||
*/
|
||
|
||
import { validJpeg } from "./__fixtures__/jpeg.js";
|
||
|
||
import { spawnSync } from "child_process";
|
||
import { EventEmitter } from "events";
|
||
import { mkdtempSync, rmSync } from "fs";
|
||
import { tmpdir } from "os";
|
||
import { basename, join } from "path";
|
||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||
|
||
import {
|
||
buildStreamingArgs,
|
||
createFrameReorderBuffer,
|
||
type StreamingEncoderOptions,
|
||
} from "./streamingEncoder.js";
|
||
import { DEFAULT_HDR10_MASTERING } from "../utils/hdr.js";
|
||
import { type GpuEncoder } from "../utils/gpuEncoder.js";
|
||
import {
|
||
SDR_CAPTURE_TO_BT709_FILTER,
|
||
SDR_RGB_TO_TAGGED_BT709_FILTER,
|
||
} from "../utils/sdrCaptureColor.js";
|
||
|
||
const baseHdrPq: StreamingEncoderOptions = {
|
||
fps: { num: 30, den: 1 },
|
||
width: 1920,
|
||
height: 1080,
|
||
codec: "h265",
|
||
preset: "medium",
|
||
quality: 23,
|
||
pixelFormat: "yuv420p10le",
|
||
useGpu: false,
|
||
rawInputFormat: "rgb48le",
|
||
hdr: { transfer: "pq" },
|
||
};
|
||
|
||
const baseHdrHlg: StreamingEncoderOptions = {
|
||
...baseHdrPq,
|
||
hdr: { transfer: "hlg" },
|
||
};
|
||
|
||
const baseSdr: StreamingEncoderOptions = {
|
||
fps: { num: 30, den: 1 },
|
||
width: 1920,
|
||
height: 1080,
|
||
codec: "h264",
|
||
preset: "medium",
|
||
quality: 23,
|
||
useGpu: false,
|
||
};
|
||
|
||
const baseVp9 = {
|
||
...baseSdr,
|
||
codec: "vp9" as const,
|
||
preset: "good",
|
||
quality: 18,
|
||
pixelFormat: "yuva420p",
|
||
imageFormat: "png" as const,
|
||
};
|
||
|
||
function getX265ParamsValue(args: string[]): string | undefined {
|
||
const idx = args.indexOf("-x265-params");
|
||
return idx === -1 ? undefined : args[idx + 1];
|
||
}
|
||
|
||
describe("buildStreamingArgs", () => {
|
||
describe("H.265 sample-entry tagging", () => {
|
||
const encoders: [GpuEncoder, string][] = [
|
||
[null, "libx265"],
|
||
["nvenc", "hevc_nvenc"],
|
||
["videotoolbox", "hevc_videotoolbox"],
|
||
["vaapi", "hevc_vaapi"],
|
||
["qsv", "hevc_qsv"],
|
||
["amf", "hevc_amf"],
|
||
];
|
||
|
||
function expectSingleHvc1Tag(args: string[]): void {
|
||
const tagIndex = args.indexOf("-tag:v");
|
||
expect(args.filter((arg) => arg === "-tag:v")).toHaveLength(1);
|
||
expect(args[tagIndex + 1]).toBe("hvc1");
|
||
expect(tagIndex).toBeGreaterThan(args.indexOf("-i") + 1);
|
||
expect(tagIndex + 1).toBeLessThan(args.length - 1);
|
||
}
|
||
|
||
it.each(encoders)("tags H.265 output exactly once with encoder %s", (encoder, encoderName) => {
|
||
const args = buildStreamingArgs(
|
||
{ ...baseSdr, codec: "h265", useGpu: true },
|
||
"/tmp/out.mp4",
|
||
encoder,
|
||
);
|
||
|
||
expect(args[args.indexOf("-c:v") + 1]).toBe(encoderName);
|
||
expectSingleHvc1Tag(args);
|
||
});
|
||
|
||
it("gives an NVENC build that lists only legacy presets a legacy preset, not p4", () => {
|
||
const legacy = new Set(["default", "slow", "medium", "fast", "hp", "hq"]);
|
||
const args = buildStreamingArgs(
|
||
{ ...baseSdr, codec: "h265", useGpu: true, preset: "medium" },
|
||
"/tmp/out.mp4",
|
||
"nvenc",
|
||
legacy,
|
||
);
|
||
|
||
expect(args[args.indexOf("-preset") + 1]).toBe("medium");
|
||
});
|
||
|
||
it("keeps the software tag when a detected GPU is disabled", () => {
|
||
const args = buildStreamingArgs({ ...baseSdr, codec: "h265" }, "/tmp/out.mp4", "nvenc");
|
||
|
||
expect(args[args.indexOf("-c:v") + 1]).toBe("libx265");
|
||
expectSingleHvc1Tag(args);
|
||
});
|
||
|
||
it.each([baseHdrPq, baseHdrHlg])("tags HDR $hdr.transfer VideoToolbox output", (options) => {
|
||
const args = buildStreamingArgs({ ...options, useGpu: true }, "/tmp/hdr.mp4", "videotoolbox");
|
||
|
||
expect(args[args.indexOf("-c:v") + 1]).toBe("hevc_videotoolbox");
|
||
expect(args[args.indexOf("-color_trc:v") + 1]).toBe(
|
||
options.hdr?.transfer === "pq" ? "smpte2084" : "arib-std-b67",
|
||
);
|
||
expectSingleHvc1Tag(args);
|
||
});
|
||
|
||
it.each(encoders)("does not tag H.264 output with encoder %s", (encoder) => {
|
||
const args = buildStreamingArgs({ ...baseSdr, useGpu: true }, "/tmp/out.mp4", encoder);
|
||
|
||
expect(args).not.toContain("-tag:v");
|
||
expect(args).not.toContain("hvc1");
|
||
});
|
||
|
||
it("does not tag VP9 output when a GPU is requested", () => {
|
||
const args = buildStreamingArgs({ ...baseVp9, useGpu: true }, "/tmp/out.webm", "nvenc");
|
||
|
||
expect(args[args.indexOf("-c:v") + 1]).toBe("libvpx-vp9");
|
||
expect(args).not.toContain("-tag:v");
|
||
expect(args).not.toContain("hvc1");
|
||
});
|
||
});
|
||
|
||
describe("HDR PQ (libx265)", () => {
|
||
it("emits master-display and max-cll in -x265-params", () => {
|
||
const args = buildStreamingArgs(baseHdrPq, "/tmp/out.mp4");
|
||
const x265 = getX265ParamsValue(args);
|
||
expect(x265).toBeDefined();
|
||
expect(x265).toContain(`master-display=${DEFAULT_HDR10_MASTERING.masterDisplay}`);
|
||
expect(x265).toContain(`max-cll=${DEFAULT_HDR10_MASTERING.maxCll}`);
|
||
expect(x265).toContain("colorprim=bt2020");
|
||
expect(x265).toContain("transfer=smpte2084");
|
||
expect(x265).toContain("colormatrix=bt2020nc");
|
||
});
|
||
|
||
it("tags the output stream with bt2020 / smpte2084 / tv range", () => {
|
||
const args = buildStreamingArgs(baseHdrPq, "/tmp/out.mp4");
|
||
expect(args).toContain("-colorspace:v");
|
||
expect(args[args.indexOf("-colorspace:v") + 1]).toBe("bt2020nc");
|
||
expect(args[args.indexOf("-color_primaries:v") + 1]).toBe("bt2020");
|
||
expect(args[args.indexOf("-color_trc:v") + 1]).toBe("smpte2084");
|
||
expect(args[args.indexOf("-color_range") + 1]).toBe("tv");
|
||
});
|
||
|
||
it("uses libx265 with -tag:v hvc1 for QuickTime compatibility", () => {
|
||
const args = buildStreamingArgs(baseHdrPq, "/tmp/out.mp4");
|
||
const cvIdx = args.indexOf("-c:v");
|
||
expect(cvIdx).toBeGreaterThan(-1);
|
||
expect(args[cvIdx + 1]).toBe("libx265");
|
||
expect(args).toContain("-tag:v");
|
||
expect(args[args.indexOf("-tag:v") + 1]).toBe("hvc1");
|
||
});
|
||
|
||
it("keeps the aq-mode prefix even with master-display present", () => {
|
||
const args = buildStreamingArgs(baseHdrPq, "/tmp/out.mp4");
|
||
const x265 = getX265ParamsValue(args);
|
||
expect(x265?.startsWith("aq-mode=3")).toBe(true);
|
||
});
|
||
|
||
it("uses the simpler aq-mode prefix on ultrafast preset", () => {
|
||
const args = buildStreamingArgs({ ...baseHdrPq, preset: "ultrafast" }, "/tmp/out.mp4");
|
||
const x265 = getX265ParamsValue(args);
|
||
expect(x265?.startsWith("aq-mode=3:")).toBe(true);
|
||
expect(x265).not.toContain("aq-strength");
|
||
expect(x265).toContain(`master-display=${DEFAULT_HDR10_MASTERING.masterDisplay}`);
|
||
});
|
||
});
|
||
|
||
describe("HDR HLG (libx265)", () => {
|
||
it("emits master-display, max-cll, and the HLG transfer", () => {
|
||
const args = buildStreamingArgs(baseHdrHlg, "/tmp/out.mp4");
|
||
const x265 = getX265ParamsValue(args);
|
||
expect(x265).toContain("transfer=arib-std-b67");
|
||
expect(x265).toContain(`master-display=${DEFAULT_HDR10_MASTERING.masterDisplay}`);
|
||
expect(x265).toContain(`max-cll=${DEFAULT_HDR10_MASTERING.maxCll}`);
|
||
});
|
||
|
||
it("tags the output stream with arib-std-b67", () => {
|
||
const args = buildStreamingArgs(baseHdrHlg, "/tmp/out.mp4");
|
||
expect(args[args.indexOf("-color_trc:v") + 1]).toBe("arib-std-b67");
|
||
});
|
||
});
|
||
|
||
describe("HDR raw input tagging", () => {
|
||
it("tags the rawvideo input with the matching color metadata", () => {
|
||
const args = buildStreamingArgs(baseHdrPq, "/tmp/out.mp4");
|
||
const inputColorTrcIdx = args.indexOf("-color_trc");
|
||
expect(inputColorTrcIdx).toBeGreaterThan(-1);
|
||
expect(args[inputColorTrcIdx + 1]).toBe("smpte2084");
|
||
const inputPrimariesIdx = args.indexOf("-color_primaries");
|
||
expect(inputPrimariesIdx).toBeGreaterThan(-1);
|
||
expect(args[inputPrimariesIdx + 1]).toBe("bt2020");
|
||
// Pix_fmt of the raw input must match the buffer we hand FFmpeg.
|
||
expect(args.indexOf("rgb48le")).toBeGreaterThan(-1);
|
||
});
|
||
|
||
it("does not strip the input color tags when bitrate is set instead of CRF", () => {
|
||
const args = buildStreamingArgs({ ...baseHdrPq, bitrate: "20M" }, "/tmp/out.mp4");
|
||
const x265 = getX265ParamsValue(args);
|
||
expect(x265).toContain(`master-display=${DEFAULT_HDR10_MASTERING.masterDisplay}`);
|
||
expect(args).toContain("-b:v");
|
||
expect(args[args.indexOf("-b:v") + 1]).toBe("20M");
|
||
});
|
||
});
|
||
|
||
describe("SDR fallback", () => {
|
||
it("does NOT emit HDR mastering metadata for SDR encodes", () => {
|
||
const args = buildStreamingArgs(baseSdr, "/tmp/out.mp4");
|
||
const x264 = args[args.indexOf("-x264-params") + 1];
|
||
expect(x264).toContain("colorprim=bt709");
|
||
expect(x264).toContain("transfer=bt709");
|
||
expect(x264).toContain("colormatrix=bt709");
|
||
expect(x264).not.toContain("master-display");
|
||
expect(x264).not.toContain("max-cll");
|
||
});
|
||
|
||
it("tags SDR output with bt709 and tv range", () => {
|
||
const args = buildStreamingArgs(baseSdr, "/tmp/out.mp4");
|
||
expect(args[args.indexOf("-color_trc:v") + 1]).toBe("bt709");
|
||
expect(args[args.indexOf("-color_primaries:v") + 1]).toBe("bt709");
|
||
expect(args[args.indexOf("-colorspace:v") + 1]).toBe("bt709");
|
||
expect(args[args.indexOf("-color_range") + 1]).toBe("tv");
|
||
expect(args[args.indexOf("-vf") + 1]).toBe(SDR_CAPTURE_TO_BT709_FILTER);
|
||
});
|
||
|
||
it("adds the pad after range conversion for odd SDR output dimensions", () => {
|
||
const args = buildStreamingArgs({ ...baseSdr, height: 1081 }, "/tmp/out.mp4");
|
||
expect(args[args.indexOf("-vf") + 1]).toBe(
|
||
`${SDR_CAPTURE_TO_BT709_FILTER},pad=ceil(iw/2)*2:ceil(ih/2)*2`,
|
||
);
|
||
});
|
||
|
||
it("converts ProRes to the BT.709 it is tagged with and keeps the alpha format", () => {
|
||
const args = buildStreamingArgs(
|
||
{ ...baseVp9, codec: "prores", preset: "4444", pixelFormat: "yuva444p10le" },
|
||
"/tmp/out.mov",
|
||
);
|
||
expect(args[args.indexOf("-vf") + 1]).toBe(SDR_RGB_TO_TAGGED_BT709_FILTER);
|
||
expect(args[args.indexOf("-pix_fmt") + 1]).toBe("yuva444p10le");
|
||
});
|
||
});
|
||
|
||
describe("output path", () => {
|
||
it("places the output path last after -y", () => {
|
||
const args = buildStreamingArgs(baseHdrPq, "/tmp/some-output.mp4");
|
||
expect(args[args.length - 2]).toBe("-y");
|
||
expect(args[args.length - 1]).toBe("/tmp/some-output.mp4");
|
||
});
|
||
});
|
||
|
||
describe("VP9 cpu-used", () => {
|
||
it("emits the default speed/quality tradeoff for streaming WebM", () => {
|
||
const args = buildStreamingArgs(baseVp9, "/tmp/out.webm");
|
||
|
||
expect(args[args.indexOf("-c:v") + 1]).toBe("libvpx-vp9");
|
||
expect(args[args.indexOf("-cpu-used") + 1]).toBe("4");
|
||
});
|
||
|
||
it("honors the resolved engine override for streaming WebM", () => {
|
||
const args = buildStreamingArgs({ ...baseVp9, vp9CpuUsed: 2 }, "/tmp/out.webm");
|
||
|
||
expect(args[args.indexOf("-cpu-used") + 1]).toBe("2");
|
||
});
|
||
});
|
||
|
||
describe("fps rational forwarding", () => {
|
||
// Regression for the fps fraction-syntax feature: both `-framerate`
|
||
// (input timestamping) and `-r` (output framerate) must carry the
|
||
// rational verbatim — collapsing to 29.97 decimal at this boundary
|
||
// would defeat the whole point of supporting NTSC end-to-end.
|
||
it("emits rational -framerate and -r for NTSC 30000/1001 (image2pipe)", () => {
|
||
const sdrNtsc: StreamingEncoderOptions = {
|
||
...baseSdr,
|
||
fps: { num: 30000, den: 1001 },
|
||
};
|
||
const args = buildStreamingArgs(sdrNtsc, "/tmp/ntsc.mp4");
|
||
const framerateIdx = args.indexOf("-framerate");
|
||
expect(framerateIdx).toBeGreaterThan(-1);
|
||
expect(args[framerateIdx + 1]).toBe("30000/1001");
|
||
|
||
const rIdx = args.indexOf("-r");
|
||
expect(rIdx).toBeGreaterThan(-1);
|
||
expect(args[rIdx + 1]).toBe("30000/1001");
|
||
});
|
||
|
||
it("emits rational -framerate and -r for NTSC 30000/1001 (rawvideo HDR)", () => {
|
||
const hdrNtsc: StreamingEncoderOptions = {
|
||
...baseHdrPq,
|
||
fps: { num: 30000, den: 1001 },
|
||
};
|
||
const args = buildStreamingArgs(hdrNtsc, "/tmp/ntsc-hdr.mp4");
|
||
const framerateIdx = args.indexOf("-framerate");
|
||
expect(framerateIdx).toBeGreaterThan(-1);
|
||
expect(args[framerateIdx + 1]).toBe("30000/1001");
|
||
|
||
const rIdx = args.indexOf("-r");
|
||
expect(rIdx).toBeGreaterThan(-1);
|
||
expect(args[rIdx + 1]).toBe("30000/1001");
|
||
});
|
||
|
||
it("emits bare integer -r for { num: 30, den: 1 }", () => {
|
||
const args = buildStreamingArgs(baseSdr, "/tmp/30.mp4");
|
||
const rIdx = args.indexOf("-r");
|
||
expect(rIdx).toBeGreaterThan(-1);
|
||
expect(args[rIdx + 1]).toBe("30");
|
||
});
|
||
});
|
||
|
||
describe("GPU preset mapping", () => {
|
||
const baseGpu: StreamingEncoderOptions = {
|
||
fps: { num: 30, den: 1 },
|
||
width: 1920,
|
||
height: 1080,
|
||
codec: "h264",
|
||
preset: "ultrafast",
|
||
quality: 28,
|
||
useGpu: true,
|
||
};
|
||
|
||
function presetArg(args: string[]): string | undefined {
|
||
const idx = args.indexOf("-preset");
|
||
return idx === -1 ? undefined : args[idx + 1];
|
||
}
|
||
|
||
// Regression for the streaming-encode + --gpu failure: NVENC rejects
|
||
// libx264 `ultrafast` with AVERROR(EINVAL), which previously surfaced
|
||
// as a bare "FFmpeg exited with code -22".
|
||
it("translates ultrafast to NVENC p1", () => {
|
||
const args = buildStreamingArgs(baseGpu, "/tmp/out.mp4", "nvenc");
|
||
expect(presetArg(args)).toBe("p1");
|
||
});
|
||
|
||
it("translates medium to NVENC p4", () => {
|
||
const args = buildStreamingArgs({ ...baseGpu, preset: "medium" }, "/tmp/out.mp4", "nvenc");
|
||
expect(presetArg(args)).toBe("p4");
|
||
});
|
||
|
||
it("uses a supported derived bitrate for high-quality VideoToolbox", () => {
|
||
const args = buildStreamingArgs(
|
||
{
|
||
...baseGpu,
|
||
fps: { num: 24, den: 1 },
|
||
width: 1920,
|
||
height: 1080,
|
||
preset: "slow",
|
||
quality: 15,
|
||
},
|
||
"/tmp/out.mp4",
|
||
"videotoolbox",
|
||
);
|
||
|
||
expect(args).not.toContain("-q:v");
|
||
expect(args[args.indexOf("-b:v") + 1]).toBe("12M");
|
||
expect(args[args.indexOf("-allow_sw") + 1]).toBe("1");
|
||
});
|
||
|
||
// Same mapping applies to hevc_nvenc: NVENC's preset vocabulary is
|
||
// codec-agnostic, so the helper must translate for H.265 too.
|
||
it("translates libx264 preset names to NVENC pN for h265 as well", () => {
|
||
for (const [libx264, nvencPreset] of [
|
||
["ultrafast", "p1"],
|
||
["medium", "p4"],
|
||
["veryslow", "p7"],
|
||
] as const) {
|
||
const args = buildStreamingArgs(
|
||
{ ...baseGpu, codec: "h265", preset: libx264 },
|
||
"/tmp/out.mp4",
|
||
"nvenc",
|
||
);
|
||
expect(args[args.indexOf("-c:v") + 1]).toBe("hevc_nvenc");
|
||
expect(presetArg(args)).toBe(nvencPreset);
|
||
}
|
||
});
|
||
|
||
it("rewrites QSV's unsupported ultrafast preset to veryfast", () => {
|
||
const args = buildStreamingArgs(baseGpu, "/tmp/out.mp4", "qsv");
|
||
expect(presetArg(args)).toBe("veryfast");
|
||
});
|
||
|
||
it("passes QSV-supported preset names through unchanged", () => {
|
||
const args = buildStreamingArgs({ ...baseGpu, preset: "medium" }, "/tmp/out.mp4", "qsv");
|
||
expect(presetArg(args)).toBe("medium");
|
||
});
|
||
|
||
it("uses AMD AMF encoder names and quality flags when selected", () => {
|
||
const h264Args = buildStreamingArgs(
|
||
{ ...baseGpu, preset: "medium", quality: 23 },
|
||
"/tmp/out.mp4",
|
||
"amf",
|
||
);
|
||
expect(h264Args[h264Args.indexOf("-c:v") + 1]).toBe("h264_amf");
|
||
expect(h264Args[h264Args.indexOf("-qp_i") + 1]).toBe("23");
|
||
expect(h264Args).toContain("-bf");
|
||
expect(h264Args[h264Args.indexOf("-bf") + 1]).toBe("0");
|
||
|
||
const h265Args = buildStreamingArgs(
|
||
{ ...baseGpu, codec: "h265", preset: "medium", quality: 23 },
|
||
"/tmp/out.mp4",
|
||
"amf",
|
||
);
|
||
expect(h265Args[h265Args.indexOf("-c:v") + 1]).toBe("hevc_amf");
|
||
expect(h265Args[h265Args.indexOf("-qp_i") + 1]).toBe("23");
|
||
});
|
||
|
||
// 4:2:0 HW encode aborts on odd dims just like libx264, so the pad follows the colour conversion.
|
||
it("converts to BT.709 and pads odd dimensions for non-VAAPI GPU encoding", () => {
|
||
for (const gpu of ["nvenc", "videotoolbox", "qsv", "amf"] as const) {
|
||
const args = buildStreamingArgs({ ...baseGpu, height: 1081 }, "/tmp/out.mp4", gpu);
|
||
const vfIdx = args.indexOf("-vf");
|
||
expect(args[vfIdx + 1]).toBe(
|
||
`${SDR_CAPTURE_TO_BT709_FILTER},pad=ceil(iw/2)*2:ceil(ih/2)*2`,
|
||
);
|
||
}
|
||
});
|
||
|
||
it("does not require the pad filter for even GPU output dimensions", () => {
|
||
const args = buildStreamingArgs(baseGpu, "/tmp/out.mp4", "videotoolbox");
|
||
expect(args[args.indexOf("-vf") + 1]).toBe(SDR_CAPTURE_TO_BT709_FILTER);
|
||
});
|
||
|
||
it("prepends range conversion to VAAPI chain (nv12 covers even-dim)", () => {
|
||
const args = buildStreamingArgs(baseGpu, "/tmp/out.mp4", "vaapi");
|
||
const vfIdx = args.indexOf("-vf");
|
||
expect(args[vfIdx + 1]).toBe(`${SDR_CAPTURE_TO_BT709_FILTER},format=nv12,hwupload`);
|
||
});
|
||
});
|
||
|
||
// The HLS format locks the GOP so `-f hls -c copy` can cut segments on
|
||
// exact time boundaries. Every other format must keep the old arg list.
|
||
describe("lockGopForChunkConcat", () => {
|
||
it("omits closed-GOP args by default", () => {
|
||
const args = buildStreamingArgs(baseSdr, "/tmp/out.mp4");
|
||
expect(args).not.toContain("-g");
|
||
expect(args).not.toContain("-keyint_min");
|
||
expect(args).not.toContain("-sc_threshold");
|
||
expect(args).not.toContain("-force_key_frames");
|
||
const paramIdx = args.indexOf("-x264-params");
|
||
expect(args[paramIdx + 1]).not.toContain("open-gop=0");
|
||
});
|
||
|
||
it("emits closed-GOP args and x264-params for libx264", () => {
|
||
const args = buildStreamingArgs(
|
||
{ ...baseSdr, lockGopForChunkConcat: true, gopSize: 120 },
|
||
"/tmp/out.mp4",
|
||
);
|
||
expect(args[args.indexOf("-g") + 1]).toBe("120");
|
||
expect(args[args.indexOf("-keyint_min") + 1]).toBe("120");
|
||
expect(args[args.indexOf("-sc_threshold") + 1]).toBe("0");
|
||
expect(args[args.indexOf("-force_key_frames") + 1]).toBe("expr:eq(mod(n,120),0)");
|
||
const paramIdx = args.indexOf("-x264-params");
|
||
expect(args[paramIdx + 1]).toContain("scenecut=0");
|
||
expect(args[paramIdx + 1]).toContain("open-gop=0");
|
||
expect(args[paramIdx + 1]).toContain("repeat-headers=1");
|
||
expect(args[paramIdx + 1]).toContain("aq-strength=0.8");
|
||
expect(args[args.indexOf("-bf") + 1]).toBe("0");
|
||
});
|
||
|
||
it("emits keyint in x265-params and disables B-frames for libx265", () => {
|
||
const args = buildStreamingArgs(
|
||
{
|
||
...baseSdr,
|
||
codec: "h265",
|
||
lockGopForChunkConcat: true,
|
||
gopSize: 90,
|
||
},
|
||
"/tmp/out.mp4",
|
||
);
|
||
expect(args[args.indexOf("-g") + 1]).toBe("90");
|
||
expect(getX265ParamsValue(args)).toContain("keyint=90");
|
||
expect(getX265ParamsValue(args)).toContain("min-keyint=90");
|
||
expect(args[args.indexOf("-bf") + 1]).toBe("0");
|
||
});
|
||
|
||
it("throws on a missing or invalid gopSize", () => {
|
||
for (const bad of [undefined, 0, -10, NaN, Infinity]) {
|
||
expect(() =>
|
||
buildStreamingArgs(
|
||
{ ...baseSdr, lockGopForChunkConcat: true, gopSize: bad as number | undefined },
|
||
"/tmp/out.mp4",
|
||
),
|
||
).toThrow(/lockGopForChunkConcat=true requires a positive integer gopSize/);
|
||
}
|
||
});
|
||
});
|
||
});
|
||
|
||
describe("createFrameReorderBuffer", () => {
|
||
it("fast-paths waitForFrame(cursor) without queueing", async () => {
|
||
const buf = createFrameReorderBuffer(0, 3);
|
||
await buf.waitForFrame(0);
|
||
});
|
||
|
||
it("gates out-of-order writers into cursor order", async () => {
|
||
const buf = createFrameReorderBuffer(0, 4);
|
||
const writeOrder: number[] = [];
|
||
|
||
const writer = async (frame: number) => {
|
||
await buf.waitForFrame(frame);
|
||
writeOrder.push(frame);
|
||
buf.advanceTo(frame + 1);
|
||
};
|
||
|
||
const p3 = writer(3);
|
||
const p1 = writer(1);
|
||
const p2 = writer(2);
|
||
const p0 = writer(0);
|
||
|
||
await Promise.all([p0, p1, p2, p3]);
|
||
expect(writeOrder).toEqual([0, 1, 2, 3]);
|
||
});
|
||
|
||
it("supports multiple waiters registered for the same frame", async () => {
|
||
const buf = createFrameReorderBuffer(0, 2);
|
||
const resolved: string[] = [];
|
||
|
||
const a = buf.waitForFrame(1).then(() => resolved.push("a"));
|
||
const b = buf.waitForFrame(1).then(() => resolved.push("b"));
|
||
|
||
buf.advanceTo(0);
|
||
await Promise.resolve();
|
||
expect(resolved).toEqual([]);
|
||
|
||
buf.advanceTo(1);
|
||
await Promise.all([a, b]);
|
||
expect(resolved.sort()).toEqual(["a", "b"]);
|
||
});
|
||
|
||
it("waitForAllDone resolves when cursor reaches endFrame", async () => {
|
||
const buf = createFrameReorderBuffer(0, 3);
|
||
let done = false;
|
||
const allDone = buf.waitForAllDone().then(() => {
|
||
done = true;
|
||
});
|
||
|
||
buf.advanceTo(1);
|
||
await Promise.resolve();
|
||
expect(done).toBe(false);
|
||
|
||
buf.advanceTo(3);
|
||
await allDone;
|
||
expect(done).toBe(true);
|
||
});
|
||
|
||
it("waitForAllDone fast-paths when cursor already past endFrame", async () => {
|
||
const buf = createFrameReorderBuffer(0, 3);
|
||
buf.advanceTo(5);
|
||
await buf.waitForAllDone();
|
||
});
|
||
});
|
||
|
||
interface FakeStdin extends EventEmitter {
|
||
destroyed: boolean;
|
||
end: (cb?: () => void) => void;
|
||
write: (chunk: Buffer) => boolean;
|
||
}
|
||
|
||
interface FakeProc extends EventEmitter {
|
||
stdin: FakeStdin;
|
||
stdout: EventEmitter;
|
||
stderr: EventEmitter;
|
||
kill: ReturnType<typeof vi.fn>;
|
||
}
|
||
|
||
interface SpawnCall {
|
||
command: string;
|
||
args: readonly string[];
|
||
proc: FakeProc;
|
||
}
|
||
|
||
function createFakeStdin(): FakeStdin {
|
||
const state = { destroyed: false };
|
||
const stdin = new EventEmitter() as FakeStdin;
|
||
Object.defineProperty(stdin, "destroyed", {
|
||
get: () => state.destroyed,
|
||
set: (v: boolean) => {
|
||
state.destroyed = v;
|
||
},
|
||
});
|
||
stdin.end = (cb?: () => void) => {
|
||
state.destroyed = true;
|
||
if (cb) process.nextTick(cb);
|
||
};
|
||
stdin.write = (_chunk: Buffer): boolean => !state.destroyed;
|
||
return stdin;
|
||
}
|
||
|
||
function createFakeProc(): FakeProc {
|
||
const proc = new EventEmitter() as FakeProc;
|
||
proc.stdin = createFakeStdin();
|
||
proc.stdout = new EventEmitter();
|
||
proc.stderr = new EventEmitter();
|
||
proc.kill = vi.fn();
|
||
return proc;
|
||
}
|
||
|
||
function createSpawnSpy(): {
|
||
spawn: (command: string, args: readonly string[]) => FakeProc;
|
||
calls: SpawnCall[];
|
||
} {
|
||
const calls: SpawnCall[] = [];
|
||
const spawn = (command: string, args: readonly string[]): FakeProc => {
|
||
const proc = createFakeProc();
|
||
calls.push({ command, args, proc });
|
||
return proc;
|
||
};
|
||
return { spawn, calls };
|
||
}
|
||
|
||
const baseOptions: StreamingEncoderOptions = {
|
||
fps: { num: 30, den: 1 },
|
||
width: 100,
|
||
height: 100,
|
||
codec: "h264",
|
||
useGpu: false,
|
||
};
|
||
|
||
async function resolveWithin<T>(promise: Promise<T>, ms = 100): Promise<T | "timeout"> {
|
||
let timeout: ReturnType<typeof setTimeout> | undefined;
|
||
try {
|
||
return await Promise.race([
|
||
promise,
|
||
new Promise<"timeout">((resolve) => {
|
||
timeout = setTimeout(() => resolve("timeout"), ms);
|
||
}),
|
||
]);
|
||
} finally {
|
||
if (timeout) clearTimeout(timeout);
|
||
}
|
||
}
|
||
|
||
describe("spawnStreamingEncoder lifecycle and cleanup", () => {
|
||
const originalPath = process.env.PATH;
|
||
|
||
beforeEach(() => {
|
||
process.env.PATH = "";
|
||
});
|
||
|
||
afterEach(() => {
|
||
vi.resetModules();
|
||
vi.doUnmock("child_process");
|
||
if (originalPath === undefined) delete process.env.PATH;
|
||
else process.env.PATH = originalPath;
|
||
});
|
||
|
||
it("returns a success result when ffmpeg exits cleanly after close()", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-success-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
expect(calls).toHaveLength(1);
|
||
expect(basename(calls[0]?.command ?? "")).toMatch(/^ffmpeg(?:\.exe)?$/);
|
||
|
||
const proc = calls[0]!.proc;
|
||
const closePromise = encoder.close();
|
||
process.nextTick(() => proc.emit("close", 0));
|
||
|
||
const result = await closePromise;
|
||
expect(result.success).toBe(true);
|
||
expect(result.error).toBeUndefined();
|
||
expect(result.fileSize).toBe(0); // No real ffmpeg, no file written
|
||
});
|
||
|
||
it("reports ffmpeg's encoded-frame count while close() waits, and stops at exit", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-encoded-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
const proc = calls[0]!.proc;
|
||
proc.stderr.emit("data", Buffer.from("frame= 10 fps=20 q=28.0 size=1kB time=00:00:00.33\r"));
|
||
|
||
const heard: number[] = [];
|
||
const closePromise = encoder.close((frames) => heard.push(frames));
|
||
proc.stderr.emit("data", Buffer.from("frame= 25 fps=20 q=28.0 size=2kB time=00:00:00.83\r"));
|
||
process.nextTick(() => proc.emit("close", 0));
|
||
await closePromise;
|
||
proc.stderr.emit("data", Buffer.from("frame= 30 fps=20 q=28.0 size=2kB time=00:00:01.00\r"));
|
||
|
||
expect(heard).toEqual([10, 25]);
|
||
});
|
||
|
||
it("returns a failure result (does NOT throw) when ffmpeg exits non-zero before close()", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-fail-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
proc.stderr.emit("data", Buffer.from("Encoder error\n"));
|
||
await new Promise<void>((resolve) => {
|
||
process.nextTick(() => {
|
||
proc.emit("close", 1);
|
||
resolve();
|
||
});
|
||
});
|
||
|
||
const result = await encoder.close();
|
||
expect(result.success).toBe(false);
|
||
expect(result.error).toContain("FFmpeg exited with code 1");
|
||
expect(result.error).toContain("Encoder error");
|
||
});
|
||
|
||
it("classifies ffmpeg's handled SIGTERM as an external interruption", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-interrupted-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
const proc = calls[0]!.proc;
|
||
proc.stderr.emit("data", Buffer.from("Exiting normally, received signal 15.\n"));
|
||
process.nextTick(() => proc.emit("close", 255));
|
||
|
||
const result = await encoder.close();
|
||
expect(result.success).toBe(false);
|
||
expect(result.failureReason).toBe("external_interruption");
|
||
expect(encoder.getExitFailureReason?.()).toBe("external_interruption");
|
||
});
|
||
|
||
it("getExitError surfaces the ffmpeg failure reason after a non-zero exit", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-exiterr-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
// While running, there is no exit error to report.
|
||
expect(encoder.getExitError()).toBeUndefined();
|
||
|
||
proc.stderr.emit("data", Buffer.from("Unknown encoder 'libx264'\n"));
|
||
await new Promise<void>((resolve) => {
|
||
process.nextTick(() => {
|
||
proc.emit("close", 1);
|
||
resolve();
|
||
});
|
||
});
|
||
|
||
// After a non-zero exit, the reason is available synchronously — this is
|
||
// what `ensureFrameWritten` reads to turn "encoder exited before frame 0"
|
||
// into an actionable message.
|
||
const exitError = encoder.getExitError();
|
||
expect(exitError).toContain("FFmpeg exited with code 1");
|
||
expect(exitError).toContain("Unknown encoder 'libx264'");
|
||
});
|
||
|
||
it("getExitError returns undefined after a clean exit", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-exitok-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
await new Promise<void>((resolve) => {
|
||
process.nextTick(() => {
|
||
proc.emit("close", 0);
|
||
resolve();
|
||
});
|
||
});
|
||
|
||
expect(encoder.getExitError()).toBeUndefined();
|
||
});
|
||
|
||
it("returns a failure result (does NOT throw) when ffmpeg fails to spawn (ENOENT)", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-enoent-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
await new Promise<void>((resolve) => {
|
||
process.nextTick(() => {
|
||
const err = new Error("spawn ffmpeg ENOENT") as NodeJS.ErrnoException;
|
||
err.code = "ENOENT";
|
||
proc.emit("error", err);
|
||
resolve();
|
||
});
|
||
});
|
||
|
||
const result = await encoder.close();
|
||
expect(result.success).toBe(false);
|
||
expect(result.error).toMatch(/spawn ffmpeg ENOENT/);
|
||
});
|
||
|
||
it("returns a 'cancelled' result and SIGTERMs ffmpeg when the abort signal fires", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const controller = new AbortController();
|
||
const dir = mkdtempSync(join(tmpdir(), "se-abort-"));
|
||
const encoder = await spawnStreamingEncoder(
|
||
join(dir, "out.mp4"),
|
||
baseOptions,
|
||
controller.signal,
|
||
);
|
||
|
||
const proc = calls[0]!.proc;
|
||
controller.abort();
|
||
expect(proc.kill).toHaveBeenCalledWith("SIGTERM");
|
||
|
||
process.nextTick(() => proc.emit("close", null));
|
||
const result = await encoder.close();
|
||
|
||
expect(result.success).toBe(false);
|
||
expect(result.error).toBe("Streaming encode cancelled");
|
||
});
|
||
|
||
it("close() is idempotent: a second call still resolves to a result and does not throw", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-idempotent-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
process.nextTick(() => proc.emit("close", 0));
|
||
|
||
const first = await encoder.close();
|
||
expect(first.success).toBe(true);
|
||
|
||
// Defensive cleanup in renderOrchestrator may call close() again after the
|
||
// explicit call. Verify the second call doesn't reject — it can return
|
||
// either success (cached) or a benign failure result, but must not throw.
|
||
let threw = false;
|
||
try {
|
||
const second = await encoder.close();
|
||
expect(typeof second.success).toBe("boolean");
|
||
} catch {
|
||
threw = true;
|
||
}
|
||
expect(threw).toBe(false);
|
||
});
|
||
|
||
it("rejects a malformed JPEG before writing it and reports its input frame index", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-jpeg-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
const proc = calls[0]!.proc;
|
||
const write = vi.spyOn(proc.stdin, "write");
|
||
expect(await encoder.writeFrame(validJpeg)).toBe(true);
|
||
const malformed = Buffer.from(validJpeg);
|
||
malformed[malformed.indexOf(Buffer.from([0xff, 0xdb])) + 4] = 0x20;
|
||
await expect(encoder.writeFrame(malformed)).rejects.toThrow(
|
||
"Invalid JPEG input at frame 1: invalid JPEG DQT precision 2",
|
||
);
|
||
expect(write).toHaveBeenCalledTimes(1);
|
||
process.nextTick(() => proc.emit("close", 0));
|
||
await encoder.close();
|
||
});
|
||
|
||
it.each([
|
||
{ ...baseOptions, imageFormat: "png" as const },
|
||
{ ...baseOptions, rawInputFormat: "rgb48le" as const },
|
||
])("does not apply JPEG validation to PNG or raw frames", async (options) => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-non-jpeg-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), options);
|
||
expect(await encoder.writeFrame(Buffer.from([0]))).toBe(true);
|
||
process.nextTick(() => calls[0]!.proc.emit("close", 0));
|
||
await encoder.close();
|
||
});
|
||
|
||
it("writeFrame returns false after ffmpeg has exited", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-writefail-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
expect(await encoder.writeFrame(validJpeg)).toBe(true);
|
||
|
||
const proc = calls[0]!.proc;
|
||
await new Promise<void>((resolve) => {
|
||
process.nextTick(() => {
|
||
proc.emit("close", 0);
|
||
resolve();
|
||
});
|
||
});
|
||
|
||
expect(await encoder.writeFrame(validJpeg)).toBe(false);
|
||
});
|
||
|
||
it("waits for child close when stdin dies first so the interruption reason is observable", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-epipe-before-close-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
const proc = calls[0]!.proc;
|
||
proc.stdin.destroyed = true;
|
||
|
||
const writePromise = encoder.writeFrame(validJpeg);
|
||
await expect(resolveWithin(writePromise, 10)).resolves.toBe("timeout");
|
||
|
||
proc.stderr.emit("data", Buffer.from("Exiting normally, received signal 15.\n"));
|
||
proc.emit("close", 255);
|
||
|
||
await expect(writePromise).resolves.toBe(false);
|
||
expect(encoder.getExitFailureReason?.()).toBe("external_interruption");
|
||
});
|
||
|
||
it("writeFrame waits for stdin drain when FFmpeg applies back-pressure", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-drain-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
proc.stdin.write = (_chunk: Buffer): boolean => false;
|
||
|
||
const writeResult = encoder.writeFrame(validJpeg) as unknown;
|
||
expect(writeResult).toBeInstanceOf(Promise);
|
||
|
||
const writePromise = writeResult as Promise<boolean>;
|
||
let settled = false;
|
||
void writePromise.then(() => {
|
||
settled = true;
|
||
});
|
||
|
||
await Promise.resolve();
|
||
expect(settled).toBe(false);
|
||
expect(proc.stdin.listenerCount("drain")).toBe(1);
|
||
|
||
proc.stdin.emit("drain");
|
||
|
||
await expect(writePromise).resolves.toBe(true);
|
||
expect(settled).toBe(true);
|
||
expect(proc.stdin.listenerCount("drain")).toBe(0);
|
||
|
||
process.nextTick(() => proc.emit("close", 0));
|
||
await encoder.close();
|
||
});
|
||
|
||
it("reports how long writeFrame waited for FFmpeg to drain", async () => {
|
||
vi.useFakeTimers({ toFake: ["Date"] });
|
||
try {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-drain-wait-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
const proc = calls[0]!.proc;
|
||
|
||
expect(await encoder.writeFrame(validJpeg)).toBe(true);
|
||
proc.stdin.write = (_chunk: Buffer): boolean => false;
|
||
const writePromise = encoder.writeFrame(validJpeg);
|
||
await Promise.resolve();
|
||
vi.setSystemTime(Date.now() + 40);
|
||
proc.stdin.emit("drain");
|
||
expect(await writePromise).toBe(true);
|
||
|
||
process.nextTick(() => proc.emit("close", 0));
|
||
expect((await encoder.close()).drainWaitMs).toBe(40);
|
||
} finally {
|
||
vi.useRealTimers();
|
||
}
|
||
});
|
||
|
||
it("does not accumulate process close listeners across repeated back-pressured writes", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-drain-listeners-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
const baselineCloseListeners = proc.listenerCount("close");
|
||
const baselineDrainListeners = proc.stdin.listenerCount("drain");
|
||
proc.stdin.write = (_chunk: Buffer): boolean => false;
|
||
|
||
for (let i = 0; i < 12; i++) {
|
||
const writePromise = encoder.writeFrame(validJpeg);
|
||
|
||
await Promise.resolve();
|
||
expect(proc.stdin.listenerCount("drain")).toBe(baselineDrainListeners + 1);
|
||
expect(proc.listenerCount("close")).toBe(baselineCloseListeners + 1);
|
||
|
||
proc.stdin.emit("drain");
|
||
|
||
await expect(writePromise).resolves.toBe(true);
|
||
expect(proc.stdin.listenerCount("drain")).toBe(baselineDrainListeners);
|
||
expect(proc.listenerCount("close")).toBe(baselineCloseListeners);
|
||
}
|
||
|
||
process.nextTick(() => proc.emit("close", 0));
|
||
await encoder.close();
|
||
});
|
||
|
||
it("writeFrame resolves false instead of hanging when FFmpeg exits before drain", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-drain-exit-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
proc.stdin.write = (_chunk: Buffer): boolean => false;
|
||
|
||
const writeResult = encoder.writeFrame(validJpeg) as unknown;
|
||
expect(writeResult).toBeInstanceOf(Promise);
|
||
|
||
const writePromise = writeResult as Promise<boolean>;
|
||
let settled = false;
|
||
void writePromise.then(() => {
|
||
settled = true;
|
||
});
|
||
|
||
await Promise.resolve();
|
||
expect(settled).toBe(false);
|
||
expect(proc.stdin.listenerCount("drain")).toBe(1);
|
||
|
||
proc.emit("close", 1);
|
||
|
||
await expect(writePromise).resolves.toBe(false);
|
||
expect(settled).toBe(true);
|
||
expect(proc.stdin.listenerCount("drain")).toBe(0);
|
||
|
||
const result = await encoder.close();
|
||
expect(result.success).toBe(false);
|
||
});
|
||
|
||
it("writeFrame resolves false with the exit reason readable when stdin errors while parked on drain", async () => {
|
||
// This is the field `write EPIPE`: ffmpeg dies while the writer waits for
|
||
// back-pressure to clear. Node's once(stdin,"drain") rejects with the
|
||
// stream error, which used to escape writeFrame as the render error and
|
||
// bury ffmpeg's exit code and stderr.
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-drain-epipe-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
proc.stdin.write = (_chunk: Buffer): boolean => false;
|
||
proc.stderr.emit("data", Buffer.from("x264 [error]: malformed input\n"));
|
||
|
||
const writePromise = encoder.writeFrame(validJpeg);
|
||
await Promise.resolve();
|
||
expect(proc.stdin.listenerCount("drain")).toBe(1);
|
||
|
||
// stdin errors first; the child's close lands a tick later, as it does
|
||
// in the field (the OS closes the pipe before Node delivers `close`).
|
||
proc.stdin.emit("error", Object.assign(new Error("write EPIPE"), { code: "EPIPE" }));
|
||
setTimeout(() => proc.emit("close", 1), 5);
|
||
|
||
// Resolves, never rejects — and by the time it does, the exit has settled
|
||
// so ensureFrameWritten can read the reason synchronously.
|
||
await expect(writePromise).resolves.toBe(false);
|
||
expect(encoder.getExitStatus()).toBe("error");
|
||
expect(encoder.getExitError()).toMatch(/code 1/);
|
||
expect(encoder.getExitError()).toContain("malformed input");
|
||
expect(proc.stdin.listenerCount("drain")).toBe(0);
|
||
|
||
const result = await encoder.close();
|
||
expect(result.success).toBe(false);
|
||
});
|
||
|
||
it("writeFrame resolves false when close fires after write returns false before await attaches listeners", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-drain-already-closed-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
|
||
|
||
const proc = calls[0]!.proc;
|
||
const baselineCloseListeners = proc.listenerCount("close");
|
||
proc.stdin.write = (_chunk: Buffer): boolean => {
|
||
proc.emit("close", 1);
|
||
return false;
|
||
};
|
||
|
||
const writePromise = encoder.writeFrame(validJpeg);
|
||
|
||
await expect(resolveWithin(writePromise)).resolves.toBe(false);
|
||
expect(encoder.getExitStatus()).toBe("error");
|
||
expect(proc.stdin.listenerCount("drain")).toBe(0);
|
||
expect(proc.listenerCount("close")).toBeLessThanOrEqual(baselineCloseListeners);
|
||
|
||
const result = await encoder.close();
|
||
expect(result.success).toBe(false);
|
||
});
|
||
|
||
it("close() removes the abort listener so a post-close abort does not re-kill ffmpeg", async () => {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const controller = new AbortController();
|
||
const dir = mkdtempSync(join(tmpdir(), "se-detach-"));
|
||
const encoder = await spawnStreamingEncoder(
|
||
join(dir, "out.mp4"),
|
||
baseOptions,
|
||
controller.signal,
|
||
);
|
||
|
||
const proc = calls[0]!.proc;
|
||
process.nextTick(() => proc.emit("close", 0));
|
||
await encoder.close();
|
||
|
||
expect(proc.kill).not.toHaveBeenCalled();
|
||
|
||
controller.abort();
|
||
expect(proc.kill).not.toHaveBeenCalled();
|
||
});
|
||
|
||
it("inactivity timeout fires only after a no-frame gap exceeds ffmpegStreamingTimeout", async () => {
|
||
vi.useFakeTimers();
|
||
try {
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-heartbeat-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions, undefined, {
|
||
ffmpegStreamingTimeout: 1000,
|
||
});
|
||
|
||
const proc = calls[0]!.proc;
|
||
|
||
// Frames every 900ms — under the 1000ms inactivity threshold — should
|
||
// keep resetting the timer. After 9× 900ms = 8.1s of "slow but
|
||
// progressing" capture the encoder must still be alive. The old total-
|
||
// render timeout would have fired SIGTERM at ~1000ms.
|
||
for (let i = 0; i < 9; i++) {
|
||
await encoder.writeFrame(validJpeg);
|
||
vi.advanceTimersByTime(900);
|
||
}
|
||
expect(proc.kill).not.toHaveBeenCalled();
|
||
|
||
// Now stall — no writeFrame for longer than the threshold. SIGTERM fires.
|
||
vi.advanceTimersByTime(1100);
|
||
expect(proc.kill).toHaveBeenCalledWith("SIGTERM");
|
||
} finally {
|
||
vi.useRealTimers();
|
||
}
|
||
});
|
||
|
||
it("inactivity timeout still fires when stdin is backpressured (stalled ffmpeg, live producer)", async () => {
|
||
vi.useFakeTimers();
|
||
try {
|
||
// Simulate the FFmpeg-hangs-but-Chrome-keeps-producing case: stdin.write
|
||
// always returns false (Node has to buffer because ffmpeg isn't draining
|
||
// the pipe). The heartbeat must NOT reset on those buffered writes —
|
||
// otherwise a hung ffmpeg with a steady frame producer would never
|
||
// SIGTERM and we'd grow Node's stdin buffer until OOM.
|
||
const { spawn, calls } = createSpawnSpy();
|
||
vi.resetModules();
|
||
vi.doMock("child_process", () => ({ spawn }));
|
||
|
||
const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
|
||
const dir = mkdtempSync(join(tmpdir(), "se-backpressure-"));
|
||
const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions, undefined, {
|
||
ffmpegStreamingTimeout: 1000,
|
||
});
|
||
|
||
const proc = calls[0]!.proc;
|
||
proc.stdin.write = (_chunk: Buffer) => false;
|
||
|
||
// A buffered write should remain pending and must NOT reset the timer.
|
||
// The 1000ms timer (last reset on spawn) therefore elapses while the
|
||
// caller is correctly back-pressured on the first frame.
|
||
const writePromise = encoder.writeFrame(validJpeg);
|
||
await Promise.resolve();
|
||
|
||
vi.advanceTimersByTime(1100);
|
||
expect(proc.kill).toHaveBeenCalledWith("SIGTERM");
|
||
|
||
proc.emit("close", null);
|
||
await expect(writePromise).resolves.toBe(false);
|
||
} finally {
|
||
vi.useRealTimers();
|
||
}
|
||
});
|
||
});
|
||
|
||
describe("createFrameReorderBuffer abort (interleaved parallel drain)", () => {
|
||
it("rejects parked waiters so a failed worker cannot deadlock its peers", async () => {
|
||
const buf = createFrameReorderBuffer(0, 100);
|
||
const parked = buf.waitForFrame(5);
|
||
const err = new Error("verify failed");
|
||
buf.abort(err);
|
||
await expect(parked).rejects.toThrow("verify failed");
|
||
// Future waiters reject immediately too.
|
||
await expect(buf.waitForFrame(6)).rejects.toThrow("verify failed");
|
||
await expect(buf.waitForAllDone()).rejects.toThrow("verify failed");
|
||
});
|
||
|
||
it("in-order waiters still resolve before an abort", async () => {
|
||
const buf = createFrameReorderBuffer(0, 10);
|
||
await expect(buf.waitForFrame(0)).resolves.toBeUndefined();
|
||
buf.advanceTo(1);
|
||
await expect(buf.waitForFrame(1)).resolves.toBeUndefined();
|
||
});
|
||
});
|
||
|
||
describe.skipIf(spawnSync("ffmpeg", ["-version"]).status !== 0)(
|
||
"buildStreamingArgs frame tags",
|
||
() => {
|
||
// VideoToolbox, like a libx264/libx265 given no colour options, writes only the colour its frames carry.
|
||
const streamTagsThrough = (args: string[], encoder: string[]): string => {
|
||
const dir = mkdtempSync(join(tmpdir(), "se-frame-tags-"));
|
||
try {
|
||
const out = join(dir, "out.mp4");
|
||
const vfAt = args.indexOf("-vf");
|
||
const vf = vfAt === -1 ? [] : ["-vf", args[vfAt + 1]!];
|
||
const source = ["-f", "lavfi", "-i", "color=c=0x808080:s=64x16:d=0.1"];
|
||
const encode = spawnSync("ffmpeg", [
|
||
"-y",
|
||
"-v",
|
||
"error",
|
||
...source,
|
||
...vf,
|
||
...encoder,
|
||
out,
|
||
]);
|
||
expect(encode.status).toBe(0);
|
||
const entries = "stream=color_space,color_transfer,color_primaries";
|
||
const probe = ["-v", "error", "-show_entries", entries, "-of", "csv=p=0", "--", out];
|
||
return spawnSync("ffprobe", probe).stdout.toString().trim();
|
||
} finally {
|
||
rmSync(dir, { recursive: true, force: true });
|
||
}
|
||
};
|
||
const tiny = { width: 64, height: 16 };
|
||
|
||
it.each([
|
||
["captured frames", {}],
|
||
["raw RGB frames", { rawInputFormat: "rgb48le" as const }],
|
||
])("tags BT.709 on %s, so an encoder that reads only them tags the stream", (_, extra) => {
|
||
const args = buildStreamingArgs({ ...baseSdr, ...tiny, ...extra }, "o.mp4");
|
||
|
||
expect(streamTagsThrough(args, ["-c:v", "libx264", "-preset", "ultrafast"])).toBe(
|
||
"bt709,bt709,bt709",
|
||
);
|
||
});
|
||
|
||
it.each([
|
||
[baseHdrPq, "smpte2084", null],
|
||
[baseHdrHlg, "arib-std-b67", null],
|
||
[baseHdrPq, "smpte2084", "videotoolbox"],
|
||
] as const)(
|
||
"tags raw HDR frames %#, so an encoder that reads only them tags the stream",
|
||
(base, trc, gpu) => {
|
||
const args = buildStreamingArgs({ ...base, ...tiny, useGpu: gpu !== null }, "o.mp4", gpu);
|
||
const x265 = [
|
||
"-c:v",
|
||
"libx265",
|
||
"-pix_fmt",
|
||
"yuv420p10le",
|
||
"-x265-params",
|
||
"log-level=error",
|
||
];
|
||
|
||
expect(streamTagsThrough(args, x265)).toBe(`bt2020nc,${trc},bt2020`);
|
||
},
|
||
);
|
||
},
|
||
);
|
||
|
||
describe.skipIf(spawnSync("ffmpeg", ["-version"]).status !== 0)(
|
||
"buildStreamingArgs raw SDR colour",
|
||
() => {
|
||
// ffmpeg 7 and older convert raw RGB with the BT.601 matrix unless told otherwise.
|
||
it("delivers raw sRGB frames in the BT.709 the mp4 is tagged with", () => {
|
||
const dir = mkdtempSync(join(tmpdir(), "se-raw-sdr-"));
|
||
const rgbAt = (
|
||
inputFormat: string[],
|
||
source: string,
|
||
decode: string,
|
||
x: number,
|
||
stdin?: Buffer,
|
||
): number[] => [
|
||
...spawnSync(
|
||
"ffmpeg",
|
||
[
|
||
"-v",
|
||
"error",
|
||
...inputFormat,
|
||
"-i",
|
||
source,
|
||
"-vf",
|
||
`${decode}format=rgb24,crop=1:1:${x}:8`,
|
||
"-frames:v",
|
||
"1",
|
||
"-f",
|
||
"rawvideo",
|
||
"-",
|
||
],
|
||
{ input: stdin },
|
||
).stdout,
|
||
];
|
||
try {
|
||
const frame = spawnSync("ffmpeg", [
|
||
"-v",
|
||
"error",
|
||
"-f",
|
||
"lavfi",
|
||
"-i",
|
||
"color=c=0xC83C28:s=64x16,format=rgb24,drawbox=x=31:y=0:w=33:h=16:c=0x0000FE:t=fill",
|
||
"-frames:v",
|
||
"1",
|
||
"-pix_fmt",
|
||
"rgb48le",
|
||
"-f",
|
||
"rawvideo",
|
||
"-",
|
||
]).stdout;
|
||
const out = join(dir, "out.mp4");
|
||
const args = buildStreamingArgs(
|
||
{
|
||
...baseSdr,
|
||
width: 64,
|
||
height: 16,
|
||
preset: "ultrafast",
|
||
quality: 0,
|
||
rawInputFormat: "rgb48le",
|
||
},
|
||
out,
|
||
);
|
||
expect(spawnSync("ffmpeg", args, { input: frame }).status).toBe(0);
|
||
|
||
const rawInput = ["-f", "rawvideo", "-pix_fmt", "rgb48le", "-s", "64x16"];
|
||
// x=8 is flat colour; x=32 sits one pixel inside the blue edge.
|
||
for (const x of [8, 32]) {
|
||
const source = rgbAt(rawInput, "-", "", x, frame);
|
||
const delivered = rgbAt([], out, "scale=in_color_matrix=bt709:in_range=tv,", x);
|
||
expect([source.length, delivered.length]).toEqual([3, 3]);
|
||
const worst = Math.max(...delivered.map((v, i) => Math.abs(v - source[i]!)));
|
||
expect(worst, `x=${x}: source ${source} delivered ${delivered}`).toBeLessThanOrEqual(2);
|
||
}
|
||
} finally {
|
||
rmSync(dir, { recursive: true, force: true });
|
||
}
|
||
}, 30_000);
|
||
},
|
||
);
|
||
|
||
describe("buildStreamingArgs video layer", () => {
|
||
const layer = { inputArgs: ["-ss", "0", "-i", "film.mp4", "-t", "10"], filters: ["fps=30"] };
|
||
const withLayer = { ...baseSdr, imageFormat: "png" as const, videoLayer: layer };
|
||
|
||
it("overlays the piped frames on the source video and maps the result", () => {
|
||
const args = buildStreamingArgs(withLayer, "/tmp/out.mp4");
|
||
expect(args.indexOf("-i")).toBeLessThan(args.indexOf("film.mp4"));
|
||
const graph = args[args.indexOf("-filter_complex") + 1] ?? "";
|
||
expect(graph).toMatch(
|
||
/^\[1:v\]fps=30,format=gbrp\[v\];\[0:v\]format=rgba\[o\];\[v\]\[o\]overlay=/,
|
||
);
|
||
expect(args[args.indexOf("-map") + 1]).toBe("[vout]");
|
||
expect(args).not.toContain("-vf");
|
||
});
|
||
|
||
it.each([
|
||
["JPEG frames", { imageFormat: "jpeg" as const }],
|
||
["GPU encode", { useGpu: true }],
|
||
["vp9", { codec: "vp9" as const }],
|
||
])("refuses %s", (_name, over) => {
|
||
expect(() => buildStreamingArgs({ ...withLayer, ...over }, "/tmp/out.mp4", "nvenc")).toThrow(
|
||
/videoLayer needs/,
|
||
);
|
||
});
|
||
});
|