Files
hyperframes/packages/engine/src/services/packageHls.test.ts
T
Miguel Ángel 6a83959b0f test(engine): real-ffmpeg tests and fixture cleanup get a 30 s budget (#5368)
* test(engine): real-ffmpeg HLS tests get the 30 s budget other real-ffmpeg tests use

* test(engine): real-ffmpeg fixture cleanup gets the 30 s its setup already has
2026-10-09 23:09:10 +00:00

502 lines
17 KiB
TypeScript

import { spawnSync } from "node:child_process";
import { EventEmitter } from "node:events";
import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { getFfmpegBinary, getFfprobeBinary } from "../utils/ffmpegBinaries.js";
import {
HLS_AUDIO_PLAYLIST,
HLS_MASTER_PLAYLIST,
HLS_VIDEO_PLAYLIST,
appendLockedGopArgs,
lockedGopCodecParams,
stripAudioOnlyVariants,
} from "./chunkEncoder.js";
const HAS_FFMPEG = spawnSync(getFfmpegBinary(), ["-version"], { encoding: "utf-8" }).status === 0;
const tempDirs: string[] = [];
afterEach(() => {
for (const dir of tempDirs.splice(0)) {
rmSync(dir, { recursive: true, force: true });
}
vi.resetModules();
vi.doUnmock("child_process");
});
function makeTempDir(): string {
const dir = mkdtempSync(join(tmpdir(), "hf-package-hls-"));
tempDirs.push(dir);
return dir;
}
type FakeProc = EventEmitter & { stderr: EventEmitter; kill: ReturnType<typeof vi.fn> };
type SpawnCall = { command: string; args: readonly string[]; proc: FakeProc };
function createSpawnSpy(): {
spawn: (command: string, args: readonly string[]) => FakeProc;
calls: SpawnCall[];
} {
const calls: SpawnCall[] = [];
const spawn = (command: string, args: readonly string[]): FakeProc => {
const proc = new EventEmitter() as FakeProc;
proc.stderr = new EventEmitter();
proc.kill = vi.fn(() => true);
calls.push({ command, args, proc });
return proc;
};
return { spawn, calls };
}
async function capturePackageHlsArgs(
audioPath: string | null,
options: { segmentSeconds: number },
exitCode = 0,
stderr?: string,
): Promise<{
args: readonly string[];
outputDir: string;
result: Awaited<ReturnType<typeof import("./chunkEncoder.js").packageHls>>;
}> {
const { spawn, calls } = createSpawnSpy();
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { packageHls } = await import("./chunkEncoder.js");
const outputDir = join(makeTempDir(), "hls");
const promise = packageHls("/tmp/video-only.mp4", audioPath, outputDir, options);
const proc = calls[0]!.proc;
if (stderr !== undefined) proc.stderr.emit("data", Buffer.from(stderr));
proc.emit("exit", exitCode);
proc.emit("close", exitCode);
return { args: calls[0]!.args, outputDir, result: await promise };
}
function argValue(args: readonly string[], flag: string): string | undefined {
const index = args.indexOf(flag);
return index === -1 ? undefined : args[index + 1];
}
describe("packageHls arguments", () => {
it("stream-copies both inputs as split renditions when audio is present", async () => {
const { args } = await capturePackageHlsArgs("/tmp/audio.m4a", { segmentSeconds: 4 });
expect(args.filter((a) => a === "-i")).toHaveLength(2);
expect(args).toContain("/tmp/video-only.mp4");
expect(args).toContain("/tmp/audio.m4a");
expect(argValue(args, "-map")).toBe("0:v:0");
expect(args.slice(args.indexOf("-map") + 2)).toContain("1:a:0");
expect(argValue(args, "-var_stream_map")).toBe(
"v:0,agroup:aud,name:video a:0,agroup:aud,name:audio",
);
});
it("maps video only, with no audio group, when audioPath is null", async () => {
const { args } = await capturePackageHlsArgs(null, { segmentSeconds: 4 });
expect(args.filter((a) => a === "-i")).toHaveLength(1);
expect(argValue(args, "-var_stream_map")).toBe("v:0,name:video");
expect(args.join(" ")).not.toContain("agroup");
expect(args.join(" ")).not.toContain("1:a:0");
});
it("never re-encodes", async () => {
const { args } = await capturePackageHlsArgs("/tmp/audio.m4a", { segmentSeconds: 4 });
expect(argValue(args, "-c")).toBe("copy");
expect(args).not.toContain("-c:v");
expect(args).not.toContain("-c:a");
expect(args).not.toContain("-crf");
expect(args).not.toContain("-b:v");
});
it("requests VOD playlists with independent mpegts segments", async () => {
const { args } = await capturePackageHlsArgs("/tmp/audio.m4a", { segmentSeconds: 4 });
expect(argValue(args, "-f")).toBe("hls");
expect(argValue(args, "-hls_playlist_type")).toBe("vod");
expect(argValue(args, "-hls_flags")).toBe("independent_segments");
expect(argValue(args, "-hls_segment_type")).toBe("mpegts");
expect(argValue(args, "-master_pl_name")).toBe(HLS_MASTER_PLAYLIST);
});
it("zeroes the mpegts mux base", async () => {
const { args } = await capturePackageHlsArgs("/tmp/audio.m4a", { segmentSeconds: 4 });
expect(argValue(args, "-muxdelay")).toBe("0");
expect(argValue(args, "-muxpreload")).toBe("0");
});
it("passes segmentSeconds through to -hls_time", async () => {
const { args } = await capturePackageHlsArgs("/tmp/audio.m4a", { segmentSeconds: 6 });
expect(argValue(args, "-hls_time")).toBe("6");
});
it("writes the %v-templated playlists and segments into the output directory", async () => {
const { args, outputDir } = await capturePackageHlsArgs("/tmp/audio.m4a", {
segmentSeconds: 4,
});
expect(argValue(args, "-hls_segment_filename")).toBe(join(outputDir, "%v_%05d.ts"));
expect(args.at(-1)).toBe(join(outputDir, "%v.m3u8"));
expect(argValue(args, "-y")).toBe(join(outputDir, "%v.m3u8"));
});
it("omits the mp4-only mux args that MPEG-TS cannot carry", async () => {
const { args } = await capturePackageHlsArgs("/tmp/audio.m4a", { segmentSeconds: 4 });
expect(args).not.toContain("-movflags");
expect(args).not.toContain("-r");
expect(args).not.toContain("-avoid_negative_ts");
});
it("creates the output directory, which ffmpeg will not do itself", async () => {
const { outputDir } = await capturePackageHlsArgs(null, { segmentSeconds: 4 });
expect(existsSync(outputDir)).toBe(true);
});
it("reports the directory as the output path", async () => {
const { outputDir, result } = await capturePackageHlsArgs(null, { segmentSeconds: 4 });
expect(result).toMatchObject({ success: true, outputPath: outputDir });
});
it("surfaces an ffmpeg failure as an error string", async () => {
const { result } = await capturePackageHlsArgs(
null,
{ segmentSeconds: 4 },
1,
"Invalid data found when processing input\n",
);
expect(result.success).toBe(false);
expect(result.error).toContain("FFmpeg exited with code 1");
expect(result.error).toContain("Invalid data found");
});
it("preserves an external interruption so the job can retry on a fresh host", async () => {
const { result } = await capturePackageHlsArgs(
null,
{ segmentSeconds: 4 },
255,
"Exiting normally, received signal 15.\n",
);
expect(result).toMatchObject({ success: false, failureReason: "external_interruption" });
});
});
describe("stripAudioOnlyVariants", () => {
// Shape ffmpeg 7 writes for `v:0,agroup:aud a:0,agroup:aud`, trimmed.
const MEDIA =
'#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="group_aud",NAME="audio_1",DEFAULT=YES,URI="audio.m3u8"';
const VIDEO_VARIANT =
'#EXT-X-STREAM-INF:BANDWIDTH=49256,RESOLUTION=320x180,CODECS="avc1.42c00d,mp4a.40.2",AUDIO="group_aud"';
const AUDIO_VARIANT = '#EXT-X-STREAM-INF:BANDWIDTH=231375,CODECS="mp4a.40.2",AUDIO="group_aud"';
it("removes the audio-only variant and its URI, keeping the rendition group", () => {
const master = [
"#EXTM3U",
"#EXT-X-VERSION:3",
MEDIA,
VIDEO_VARIANT,
"video.m3u8",
"",
AUDIO_VARIANT,
"audio.m3u8",
"",
].join("\n");
expect(stripAudioOnlyVariants(master)).toBe(
["#EXTM3U", "#EXT-X-VERSION:3", MEDIA, VIDEO_VARIANT, "video.m3u8", ""].join("\n"),
);
});
it("leaves a master with only a video variant untouched", () => {
const master = ["#EXTM3U", "#EXT-X-VERSION:3", VIDEO_VARIANT, "video.m3u8", ""].join("\n");
expect(stripAudioOnlyVariants(master)).toBe(master);
});
});
describe("packageHls segmentSeconds validation", () => {
it.each([0, -4, 1.5, Number.NaN, Number.POSITIVE_INFINITY])(
"throws on segmentSeconds=%s",
async (segmentSeconds) => {
const { packageHls } = await import("./chunkEncoder.js");
await expect(
packageHls("/tmp/video.mp4", null, join(makeTempDir(), "hls"), { segmentSeconds }),
).rejects.toThrow(/positive integer segmentSeconds/);
},
);
});
describe("packageHls outputDir validation", () => {
it("rejects a directory containing % before spawning ffmpeg", async () => {
const { spawn, calls } = createSpawnSpy();
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { packageHls } = await import("./chunkEncoder.js");
const outputDir = join(makeTempDir(), "pct%20dir");
await expect(
packageHls("/tmp/video.mp4", null, outputDir, { segmentSeconds: 4 }),
).rejects.toThrow(/outputDir must not contain "%"/);
expect(calls).toHaveLength(0);
expect(existsSync(outputDir)).toBe(false);
});
});
describe.skipIf(!HAS_FFMPEG)("packageHls against real ffmpeg", { timeout: 30_000 }, () => {
const FPS = 30;
const DURATION = 4;
const SEGMENT_SECONDS = 1;
let dir: string;
beforeEach(() => {
dir = makeTempDir();
});
// `.concat` rather than a spread inside an array literal: this is an FFMPEG
// wrapper, whose trailing positional is an OUTPUT path and therefore takes no
// `--` terminator, but a verbosity-flag-then-spread array literal is
// indistinguishable from the ffPROBE wrapper shape that must have one. See
// the `SPREAD_WRAPPER` matcher in
// `producer/src/utils/ffprobeArgvContract.test.ts`, which reads raw source —
// so an example argv in a comment trips it too.
const run = (args: string[]): void => {
const argv = ["-v", "error"].concat(args);
const res = spawnSync(getFfmpegBinary(), argv, { encoding: "utf-8" });
if (res.status !== 0) throw new Error(`ffmpeg failed: ${res.stderr ?? ""}`);
};
/**
* `inputPath` is a parameter rather than the caller's last argv entry so the
* `--` terminator is the penultimate literal token, which is what
* `producer/src/utils/ffprobeArgvContract.test.ts` checks at the source level
* across the whole tree — a `join(dir, name)` call in that slot reads as two
* comma-separated entries to its parser and trips the gate.
*/
const probe = (inputPath: string, args: readonly string[]): string => {
const argv = ["-v", "error", ...args, "--", inputPath];
const res = spawnSync(getFfprobeBinary(), argv, { encoding: "utf-8" });
if (res.status !== 0) throw new Error(`ffprobe failed: ${res.stderr ?? ""}`);
return res.stdout.trim();
};
/** Same GOP lock args `buildEncoderArgs` emits for the software path. */
const lockedVideo = (): string => {
const path = join(dir, "video-only.mp4");
const gop = SEGMENT_SECONDS * FPS;
const gopArgs: string[] = [];
appendLockedGopArgs(gopArgs, gop);
gopArgs.push("-x264-params", lockedGopCodecParams("h264", gop));
run([
"-f",
"lavfi",
"-i",
`testsrc2=size=160x120:rate=${FPS}:duration=${DURATION}`,
"-c:v",
"libx264",
"-preset",
"ultrafast",
"-pix_fmt",
"yuv420p",
...gopArgs,
"-bf",
"0",
"-y",
path,
]);
return path;
};
const aacSidecar = (): string => {
const path = join(dir, "audio.m4a");
run([
"-f",
"lavfi",
"-i",
`sine=frequency=440:duration=${DURATION}`,
"-c:a",
"aac",
"-b:a",
"64k",
"-y",
path,
]);
return path;
};
const extinfs = (playlist: string): number[] =>
readFileSync(playlist, "utf-8")
.split("\n")
.filter((line) => line.startsWith("#EXTINF:"))
.map((line) => Number.parseFloat(line.slice("#EXTINF:".length)));
it("produces a VOD master with split audio and video renditions", async () => {
const { packageHls } = await import("./chunkEncoder.js");
const outputDir = join(dir, "out");
const result = await packageHls(lockedVideo(), aacSidecar(), outputDir, {
segmentSeconds: SEGMENT_SECONDS,
});
expect(result.success).toBe(true);
const master = readFileSync(join(outputDir, HLS_MASTER_PLAYLIST), "utf-8");
expect(master).toContain(HLS_VIDEO_PLAYLIST);
expect(master).toContain(HLS_AUDIO_PLAYLIST);
expect(master).toContain("#EXT-X-MEDIA:TYPE=AUDIO");
// One selectable variant: the video, with audio attached as a rendition
// group. ffmpeg also emits the audio as its own variant; that is stripped
// so a bandwidth-driven player can never pick sound without picture.
const variants = master.split("\n").filter((line) => line.startsWith("#EXT-X-STREAM-INF:"));
expect(variants).toHaveLength(1);
expect(variants[0]).toContain("RESOLUTION=");
expect(variants[0]).toContain('AUDIO="');
expect(master).toMatch(/#EXT-X-MEDIA:TYPE=AUDIO[^\n]*URI="audio\.m3u8"/);
const videoPlaylist = readFileSync(join(outputDir, HLS_VIDEO_PLAYLIST), "utf-8");
expect(videoPlaylist).toContain("#EXT-X-PLAYLIST-TYPE:VOD");
expect(videoPlaylist).toContain("#EXT-X-INDEPENDENT-SEGMENTS");
expect(videoPlaylist).toContain("#EXT-X-ENDLIST");
});
it("cuts fixed-length segments and keeps the full duration", async () => {
const { packageHls } = await import("./chunkEncoder.js");
const outputDir = join(dir, "out");
await packageHls(lockedVideo(), aacSidecar(), outputDir, {
segmentSeconds: SEGMENT_SECONDS,
});
const segments = readdirSync(outputDir).filter((f) => f.startsWith("video_"));
expect(segments).toHaveLength(Math.ceil(DURATION / SEGMENT_SECONDS));
for (const extinf of extinfs(join(outputDir, HLS_VIDEO_PLAYLIST))) {
expect(extinf).toBeCloseTo(SEGMENT_SECONDS, 3);
}
const probedDuration = Number.parseFloat(
probe(join(outputDir, HLS_VIDEO_PLAYLIST), [
"-show_entries",
"format=duration",
"-of",
"csv=p=0",
]),
);
expect(Math.abs(probedDuration - DURATION)).toBeLessThanOrEqual(1 / FPS);
});
it("starts every video segment on a keyframe", async () => {
const { packageHls } = await import("./chunkEncoder.js");
const outputDir = join(dir, "out");
await packageHls(lockedVideo(), null, outputDir, { segmentSeconds: SEGMENT_SECONDS });
const segments = readdirSync(outputDir)
.filter((f) => f.startsWith("video_"))
.sort();
expect(segments.length).toBeGreaterThan(1);
for (const segment of segments) {
const firstFrame = probe(join(outputDir, segment), [
"-select_streams",
"v",
"-show_frames",
"-show_entries",
"frame=key_frame",
"-of",
"csv=p=0",
"-read_intervals",
"%+#1",
]);
expect(firstFrame.split(",")[0]).toBe("1");
}
});
it("writes a master and no audio playlist when there is no audio", async () => {
const { packageHls } = await import("./chunkEncoder.js");
const outputDir = join(dir, "out");
const result = await packageHls(lockedVideo(), null, outputDir, {
segmentSeconds: SEGMENT_SECONDS,
});
expect(result.success).toBe(true);
expect(existsSync(join(outputDir, HLS_MASTER_PLAYLIST))).toBe(true);
expect(existsSync(join(outputDir, HLS_VIDEO_PLAYLIST))).toBe(true);
expect(existsSync(join(outputDir, HLS_AUDIO_PLAYLIST))).toBe(false);
expect(readdirSync(outputDir).filter((f) => f.startsWith("audio"))).toHaveLength(0);
});
it("starts at PTS 0 with the AAC priming packet one frame ahead of video", async () => {
const { packageHls } = await import("./chunkEncoder.js");
const AAC_FRAME_SECONDS = 1024 / 44100;
const outputDir = join(dir, "out");
await packageHls(lockedVideo(), aacSidecar(), outputDir, {
segmentSeconds: SEGMENT_SECONDS,
});
const audioPts = probe(join(outputDir, HLS_AUDIO_PLAYLIST), [
"-select_streams",
"a",
"-show_entries",
"packet=pts_time",
"-of",
"csv=p=0",
"-read_intervals",
"%+#3",
])
.split("\n")
.map((line) => Number.parseFloat(line));
const videoPts = Number.parseFloat(
probe(join(outputDir, HLS_VIDEO_PLAYLIST), [
"-select_streams",
"v",
"-show_entries",
"packet=pts_time",
"-of",
"csv=p=0",
"-read_intervals",
"%+#1",
]).split("\n")[0]!,
);
expect(audioPts[0]).toBeCloseTo(0, 3);
expect(videoPts).toBeCloseTo(AAC_FRAME_SECONDS, 3);
expect(audioPts[1]).toBeCloseTo(videoPts, 3);
});
it("cannot cut on time without the GOP lock", async () => {
const { packageHls } = await import("./chunkEncoder.js");
const unlocked = join(dir, "unlocked.mp4");
run([
"-f",
"lavfi",
"-i",
`testsrc2=size=160x120:rate=${FPS}:duration=${DURATION}`,
"-c:v",
"libx264",
"-preset",
"ultrafast",
"-pix_fmt",
"yuv420p",
"-bf",
"0",
"-y",
unlocked,
]);
const outputDir = join(dir, "out-unlocked");
await packageHls(unlocked, null, outputDir, { segmentSeconds: SEGMENT_SECONDS });
const durations = extinfs(join(outputDir, HLS_VIDEO_PLAYLIST));
expect(durations).toHaveLength(1);
expect(durations[0]).toBeCloseTo(DURATION, 3);
});
});