Files
hyperframes/packages/engine/src/utils/ffprobe.test.ts
T
Miguel Ángel 2af37ac0c3 fix(engine): read a video's length from its packets when headers state none (#7233)
* fix(engine): read a video's length from its packets when its headers state none

* fix(engine): ignore the cut first line of a long packet scan and count N/A as a frame

* chore(engine): trim the packet scan comments and put its doc back on the function

* style(engine): format the packet duration test
2026-11-05 11:53:45 +00:00

2417 lines
86 KiB
TypeScript

// fallow-ignore-file code-duplication
import { EventEmitter } from "events";
import { spawnSync } from "child_process";
import { mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
import { tmpdir } from "os";
import { basename, join, resolve } from "path";
import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
import {
extractMediaMetadata,
extractPngMetadataFromBuffer,
formatFfmpegSeconds,
parseFrameRate,
} from "./ffprobe.js";
function crc32(buf: Buffer): number {
let crc = 0xffffffff;
for (let i = 0; i < buf.length; i++) {
crc ^= buf[i] ?? 0;
for (let bit = 0; bit < 8; bit++) {
const mask = -(crc & 1);
crc = (crc >>> 1) ^ (0xedb88320 & mask);
}
}
return (crc ^ 0xffffffff) >>> 0;
}
function pngChunk(type: string, data: number[]): Buffer {
const chunkData = Buffer.from(data);
const header = Buffer.alloc(8);
header.writeUInt32BE(chunkData.length, 0);
header.write(type, 4, 4, "ascii");
const crc = Buffer.alloc(4);
crc.writeUInt32BE(crc32(Buffer.concat([Buffer.from(type, "ascii"), chunkData])), 0);
return Buffer.concat([header, chunkData, crc]);
}
function buildPngWithChunks(chunks: Buffer[]): Buffer {
return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), ...chunks]);
}
function buildMinimalPng(options?: {
cIcpAfterIdat?: boolean;
invalidCrc?: boolean;
longCicp?: boolean;
}) {
const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
const cicpData = options?.longCicp ? [9, 16, 0, 1, 255] : [9, 16, 0, 1];
let cicp = pngChunk("cICP", cicpData);
if (options?.invalidCrc) {
cicp = Buffer.from(cicp);
cicp[cicp.length - 1] ^= 0xff;
}
const idat = pngChunk(
"IDAT",
[0x78, 0x9c, 0x63, 0x60, 0x60, 0x60, 0x00, 0x00, 0x00, 0x04, 0x00, 0x01],
);
const iend = pngChunk("IEND", []);
return options?.cIcpAfterIdat
? buildPngWithChunks([ihdr, idat, cicp, iend])
: buildPngWithChunks([ihdr, cicp, idat, iend]);
}
describe("extractMediaMetadata", () => {
it("reads HDR PNG cICP metadata when ffprobe color fields are absent", async () => {
const fixturePath = resolve(
__dirname,
"../../../producer/tests/hdr-regression/src/hdr-photo-pq.png",
);
const metadata = await extractMediaMetadata(fixturePath);
expect(metadata.colorSpace).toEqual({
colorPrimaries: "bt2020",
colorTransfer: "smpte2084",
colorSpace: "gbr",
});
});
});
describe("a phone clip's display size", () => {
afterEach(() => {
vi.resetModules();
});
async function probed(stream: Record<string, unknown>) {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "hevc",
width: 1920,
height: 1080,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
...stream,
},
],
format: { duration: "3" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: mocked, displaySize } = await import("./ffprobe.js");
const dir = mkdtempSync(`${tmpdir()}/hf-turned-`);
try {
writeFileSync(`${dir}/clip.mov`, "");
return displaySize(await mocked(`${dir}/clip.mov`));
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
it("is portrait for an iPhone clip stored landscape with a -90 display matrix", async () => {
const shown = await probed({ side_data_list: [{ rotation: -90 }] });
expect(shown).toEqual({ width: 1080, height: 1920 });
});
it("reads an older muxer's rotate tag, and keeps a half turn's size", async () => {
expect(await probed({ tags: { rotate: "270" } })).toEqual({ width: 1080, height: 1920 });
expect(await probed({ side_data_list: [{ rotation: 180 }] })).toEqual({
width: 1920,
height: 1080,
});
});
it("widens anamorphic pixels, then turns, as Chrome lays the element out", async () => {
const shown = await probed({ sample_aspect_ratio: "4:3", side_data_list: [{ rotation: 90 }] });
expect(shown).toEqual({ width: 1080, height: 2560 });
});
});
describe("extractMediaMetadata nb_frames duration cross-check", () => {
afterEach(() => {
vi.resetModules();
});
it("never reads a non-PNG video's bytes looking for PNG colour metadata", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "h264",
width: 16,
height: 16,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
},
],
format: { duration: "1" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
// Bytes that carry PNG cICP, reported by ffprobe as an untagged H.264 stream.
const dir = mkdtempSync(`${tmpdir()}/hf-not-png-`);
const path = `${dir}/clip.mp4`;
writeFileSync(path, buildMinimalPng());
const meta = await mocked(path);
rmSync(dir, { recursive: true, force: true });
expect(meta.colorSpace).toBeNull();
});
it("uses nb_frames to bound video duration when stream duration is absent and audio is longer", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "h264",
width: 1920,
height: 1080,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
nb_frames: "150",
},
{ codec_type: "audio", codec_name: "aac" },
],
format: { duration: "10" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
const meta = await mocked("/tmp/stock-clip-long-audio.mp4");
expect(meta.durationSeconds).toBe(10);
expect(meta.videoStreamDurationSeconds).toBe(5);
expect(meta.frames).toBe(150);
});
it("falls back to container duration when nb_frames is absent", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "h264",
width: 1280,
height: 720,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
},
{ codec_type: "audio", codec_name: "aac" },
],
format: { duration: "10" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
const meta = await mocked("/tmp/no-nb-frames.mp4");
expect(meta.videoStreamDurationSeconds).toBe(10);
expect(meta.frames).toBeUndefined();
});
it("keeps container duration when nb_frames-derived duration is within 10%", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "h264",
width: 1280,
height: 720,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
nb_frames: "285",
},
],
format: { duration: "10" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
const meta = await mocked("/tmp/close-duration.mp4");
// 285 / 30 = 9.5s, within 10% of container (10s), so keep container
expect(meta.videoStreamDurationSeconds).toBe(10);
});
it("prefers stream duration over nb_frames when both are present", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "h264",
width: 1280,
height: 720,
duration: "5",
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
nb_frames: "300",
},
],
format: { duration: "10" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: mocked } = await import("./ffprobe.js");
const meta = await mocked("/tmp/stream-duration-present.mp4");
// stream duration (5s) takes precedence, nb_frames (300 / 30 = 10s) ignored
expect(meta.videoStreamDurationSeconds).toBe(5);
});
});
describe("extractPngMetadataFromBuffer", () => {
it("accepts a valid cICP chunk before IDAT", () => {
const metadata = extractPngMetadataFromBuffer(buildMinimalPng());
expect(metadata?.colorSpace).toEqual({
colorPrimaries: "bt2020",
colorTransfer: "smpte2084",
colorSpace: "gbr",
});
});
it("rejects cICP chunks after IDAT", () => {
const metadata = extractPngMetadataFromBuffer(buildMinimalPng({ cIcpAfterIdat: true }));
expect(metadata).toEqual({
width: 1,
height: 1,
colorSpace: null,
});
});
it("rejects cICP chunks with invalid CRC", () => {
expect(extractPngMetadataFromBuffer(buildMinimalPng({ invalidCrc: true }))).toBeNull();
});
it("rejects cICP chunks whose payload is not exactly four bytes", () => {
const metadata = extractPngMetadataFromBuffer(buildMinimalPng({ longCicp: true }));
expect(metadata).toEqual({
width: 1,
height: 1,
colorSpace: null,
});
});
it("continues to parse the checked-in HDR PNG fixture", () => {
const fixture = readFileSync(
resolve(__dirname, "../../../producer/tests/hdr-regression/src/hdr-photo-pq.png"),
);
expect(extractPngMetadataFromBuffer(fixture)?.colorSpace?.colorTransfer).toBe("smpte2084");
});
it("keeps metadata fallback independent from full PNG integrity validation", () => {
const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
expect(extractPngMetadataFromBuffer(buildPngWithChunks([ihdr]))).toMatchObject({
width: 1,
height: 1,
});
});
});
describe("probeMediaProfile", () => {
afterEach(() => {
vi.resetModules();
vi.doUnmock("child_process");
});
it("classifies still, moving, audio-only, and mixed streams from probe data", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video", codec_name: "png" }],
format: { format_name: "png_pipe" },
}),
},
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video", codec_name: "h264" }],
format: { format_name: "mov,mp4,m4a,3gp,3g2,mj2" },
}),
},
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "audio", codec_name: "mp3" }],
format: { format_name: "mp3" },
}),
},
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video" }, { codec_type: "audio", codec_name: "opus" }],
format: { format_name: "matroska,webm" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { probeMediaProfile } = await import("./ffprobe.js");
const validPngPath = resolve(
__dirname,
"../../../producer/tests/hdr-regression/src/hdr-photo-pq.png",
);
await expect(probeMediaProfile(validPngPath)).resolves.toEqual({
hasVideoStream: true,
hasAudioStream: false,
visualKind: "still",
});
await expect(probeMediaProfile("/tmp/extensionless-video")).resolves.toEqual({
hasVideoStream: true,
hasAudioStream: false,
visualKind: "moving",
});
await expect(probeMediaProfile("/tmp/extensionless-audio")).resolves.toEqual({
hasVideoStream: false,
hasAudioStream: true,
visualKind: "none",
});
await expect(probeMediaProfile("/tmp/mixed-av")).resolves.toEqual({
hasVideoStream: true,
hasAudioStream: true,
visualKind: "moving",
});
});
it("does not treat attached cover art in an audio container as an image asset", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{ codec_type: "video", disposition: { attached_pic: 1 } },
{ codec_type: "audio", codec_name: "mp3" },
],
format: { format_name: "mp3" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { probeMediaProfile } = await import("./ffprobe.js");
await expect(probeMediaProfile("/tmp/audio-with-cover")).resolves.toMatchObject({
hasAudioStream: true,
visualKind: "none",
});
});
it("deduplicates probes within one cancellation scope without sharing across scopes", async () => {
const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-media-probe-cache-"));
const fixturePath = resolve(fixtureDir, "asset");
writeFileSync(fixturePath, "cache identity only");
const outcome = {
kind: "exit" as const,
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video", codec_name: "h264" }],
format: { format_name: "mov,mp4,m4a,3gp,3g2,mj2" },
}),
};
const { spawn, calls } = createSpawnSpy([outcome, outcome]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { probeMediaProfile } = await import("./ffprobe.js");
const firstSignal = new AbortController().signal;
const secondSignal = new AbortController().signal;
try {
await Promise.all([
probeMediaProfile(fixturePath, { signal: firstSignal }),
probeMediaProfile(fixturePath, { signal: firstSignal }),
]);
expect(calls).toHaveLength(1);
await probeMediaProfile(fixturePath, { signal: secondSignal });
expect(calls).toHaveLength(2);
} finally {
rmSync(fixtureDir, { recursive: true, force: true });
}
});
it("bounds the process-scoped probe cache", async () => {
// Cache identity is derived from stat, so synthesise it instead of writing
// 129 real files: the eviction rule is in-memory, and on a contended
// Windows runner the file churn alone pushed this past the test timeout.
const paths = Array.from({ length: 129 }, (_, index) => `/probe-lru/asset-${index}`);
const outcome = {
kind: "exit" as const,
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "audio", codec_name: "aac" }],
format: { format_name: "aac" },
}),
};
const { spawn, calls } = createSpawnSpy([outcome]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
vi.doMock("fs", async () => {
const actual = await vi.importActual<typeof import("fs")>("fs");
const statSync = (filePath: string) => ({
dev: 1n,
ino: BigInt(paths.indexOf(filePath)),
size: 1n,
mtimeNs: 0n,
ctimeNs: 0n,
});
return { ...actual, statSync };
});
try {
const { probeMediaProfile } = await import("./ffprobe.js");
const [first, second, ...rest] = paths;
for (const filePath of paths.slice(0, 128)) await probeMediaProfile(filePath);
// A hit refreshes the entry, so the 129th insert evicts `second`, not `first`.
await probeMediaProfile(first!);
await probeMediaProfile(rest.at(-1)!);
expect(calls).toHaveLength(129);
await probeMediaProfile(first!);
expect(calls).toHaveLength(129);
await probeMediaProfile(second!);
expect(calls).toHaveLength(130);
} finally {
vi.doUnmock("fs");
}
});
it("classifies extensionless AVIF from its ISO-BMFF brand instead of the generic mov demuxer", async () => {
const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-avif-profile-"));
const fixturePath = resolve(fixtureDir, "asset");
const ftyp = Buffer.alloc(24);
ftyp.writeUInt32BE(24, 0);
ftyp.write("ftyp", 4, 4, "ascii");
ftyp.write("avif", 8, 4, "ascii");
ftyp.writeUInt32BE(0, 12);
ftyp.write("mif1", 16, 4, "ascii");
ftyp.write("avif", 20, 4, "ascii");
writeFileSync(fixturePath, ftyp);
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video", codec_name: "av1" }],
format: { format_name: "mov,mp4,m4a,3gp,3g2,mj2" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { probeMediaProfile } = await import("./ffprobe.js");
try {
await expect(probeMediaProfile(fixturePath)).resolves.toMatchObject({
hasVideoStream: true,
hasAudioStream: false,
visualKind: "still",
});
} finally {
rmSync(fixtureDir, { recursive: true, force: true });
}
});
it("uses any non-attached video stream when cover art precedes moving video", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{ codec_type: "video", disposition: { attached_pic: 1 } },
{ codec_type: "video", codec_name: "h264" },
{ codec_type: "audio", codec_name: "mp3" },
],
format: { format_name: "mov,mp4,m4a,3gp,3g2,mj2" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { probeMediaProfile } = await import("./ffprobe.js");
await expect(probeMediaProfile("/tmp/video-with-cover")).resolves.toMatchObject({
visualKind: "moving",
});
});
it.skipIf(spawnSync("ffprobe", ["-version"]).status !== 0)(
"rejects an IHDR-only truncated PNG even when ffprobe accepts png_pipe",
async () => {
vi.resetModules();
vi.doUnmock("child_process");
const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-truncated-png-profile-"));
const fixturePath = resolve(fixtureDir, "asset");
const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
writeFileSync(fixturePath, buildPngWithChunks([ihdr]));
const { probeMediaProfile } = await import("./ffprobe.js");
try {
await expect(probeMediaProfile(fixturePath)).rejects.toThrow();
} finally {
rmSync(fixtureDir, { recursive: true, force: true });
}
},
);
it("does not turn an aborted PNG probe into a successful metadata fallback", async () => {
type KillableFakeProc = FakeProc & { kill: (signal?: NodeJS.Signals) => boolean };
const spawn = () => {
const proc = new EventEmitter() as KillableFakeProc;
proc.stdout = new EventEmitter();
proc.stderr = new EventEmitter();
proc.kill = vi.fn(() => {
process.nextTick(() => proc.emit("close", null, "SIGTERM"));
return true;
});
process.nextTick(() => proc.emit("spawn"));
return proc;
};
const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-aborted-png-profile-"));
const fixturePath = resolve(fixtureDir, "asset");
writeFileSync(fixturePath, buildMinimalPng());
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { probeMediaProfile } = await import("./ffprobe.js");
const controller = new AbortController();
try {
const pending = probeMediaProfile(fixturePath, { signal: controller.signal });
controller.abort(new Error("render cancelled"));
await expect(pending).rejects.toThrow("render cancelled");
} finally {
rmSync(fixtureDir, { recursive: true, force: true });
}
});
});
interface SpawnCall {
command: string;
args: readonly string[];
}
interface FakeProc extends EventEmitter {
stdout: EventEmitter;
stderr: EventEmitter;
}
type SpawnOutcome =
| { kind: "missing" }
| { kind: "error"; message: string; code?: string }
| {
kind: "exit";
code: number;
stdout?: string;
stderr?: string;
/** Emit stdout as these exact byte chunks, to exercise a multi-byte
* character split across a pipe-chunk boundary. */
stdoutChunks?: Buffer[];
};
const NO_DECODED_FRAMES: SpawnOutcome = { kind: "exit", code: 0, stdout: "" };
const metadataProbes = (calls: SpawnCall[]) => calls.filter((c) => c.args.includes("-show_format"));
function createSpawnSpy(outcomes: SpawnOutcome[]): {
spawn: (command: string, args: readonly string[]) => FakeProc;
calls: SpawnCall[];
} {
const calls: SpawnCall[] = [];
let invocation = 0;
const spawn = (command: string, args: readonly string[]): FakeProc => {
calls.push({ command, args });
const outcome = outcomes[invocation] ?? outcomes[outcomes.length - 1];
invocation += 1;
const proc = new EventEmitter() as FakeProc;
proc.stdout = new EventEmitter();
proc.stderr = new EventEmitter();
process.nextTick(() => {
if (!outcome) return;
if (outcome.kind === "missing") {
const err = new Error("spawn ffprobe ENOENT") as NodeJS.ErrnoException;
err.code = "ENOENT";
proc.emit("error", err);
return;
}
if (outcome.kind === "error") {
const err = new Error(outcome.message) as NodeJS.ErrnoException;
if (outcome.code) err.code = outcome.code;
proc.emit("error", err);
return;
}
if (outcome.stdoutChunks) {
for (const chunk of outcome.stdoutChunks) proc.stdout.emit("data", chunk);
} else if (outcome.stdout) proc.stdout.emit("data", Buffer.from(outcome.stdout));
if (outcome.stderr) proc.stderr.emit("data", Buffer.from(outcome.stderr));
proc.emit("close", outcome.code);
});
return proc;
};
return { spawn, calls };
}
describe("media metadata cache invalidation", () => {
afterEach(() => {
vi.resetModules();
vi.doUnmock("child_process");
});
it("refreshes video metadata after an in-place file change", async () => {
const dir = mkdtempSync(resolve(tmpdir(), "hf-video-metadata-change-"));
const file = resolve(dir, "video.mp4");
writeFileSync(file, "original file");
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{ codec_type: "video", width: 32, height: 24, avg_frame_rate: "10/1", duration: "1" },
],
format: { duration: "1" },
}),
},
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{ codec_type: "video", width: 64, height: 48, avg_frame_rate: "24/1", duration: "2" },
],
format: { duration: "2" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata } = await import("./ffprobe.js");
try {
expect(await extractMediaMetadata(file)).toMatchObject({ width: 32, durationSeconds: 1 });
writeFileSync(file, "updated file with different dimensions");
const refreshed = await extractMediaMetadata(file);
expect(refreshed).toMatchObject({ width: 64, height: 48, fps: 24, durationSeconds: 2 });
expect(await extractMediaMetadata(file)).toBe(refreshed);
expect(calls).toHaveLength(2);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("refreshes audio metadata after an atomic same-size file replacement", async () => {
const dir = mkdtempSync(resolve(tmpdir(), "hf-audio-metadata-change-"));
const file = resolve(dir, "audio.wav");
const replacement = resolve(dir, "replacement.wav");
writeFileSync(file, "first");
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{ codec_type: "audio", codec_name: "pcm_s16le", sample_rate: "22050", channels: 1 },
],
format: { duration: "1" },
}),
},
NO_DECODED_FRAMES,
NO_DECODED_FRAMES,
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{ codec_type: "audio", codec_name: "pcm_s16le", sample_rate: "44100", channels: 2 },
],
format: { duration: "2" },
}),
},
NO_DECODED_FRAMES,
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
try {
expect(await extractAudioMetadata(file)).toMatchObject({
durationSeconds: 1,
sampleRate: 22050,
});
writeFileSync(replacement, "other");
renameSync(replacement, file);
const refreshed = await extractAudioMetadata(file);
expect(refreshed).toMatchObject({ durationSeconds: 2, sampleRate: 44100, channels: 2 });
expect(await extractAudioMetadata(file)).toBe(refreshed);
expect(metadataProbes(calls)).toHaveLength(2);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it.each([false, true])(
"refreshes final-frame timestamps in signal scope %s",
async (useSignal) => {
const dir = mkdtempSync(resolve(tmpdir(), "hf-final-frame-change-"));
const file = resolve(dir, "video.mp4");
writeFileSync(file, "original file");
const { spawn, calls } = createSpawnSpy([
{ kind: "exit", code: 0, stdout: "1.900000\n" },
{ kind: "exit", code: 0, stdout: "1.950000\n" },
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
const metadata = { videoStreamDurationSeconds: 2, videoStreamStartSeconds: 0 };
const signal = useSignal ? new AbortController().signal : undefined;
try {
expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.9);
writeFileSync(file, "updated file with a different frame rate");
expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.95);
expect(await extractFinalVideoFrameTimestamp(file, metadata, signal)).toBe(1.95);
expect(calls).toHaveLength(2);
} finally {
rmSync(dir, { recursive: true, force: true });
}
},
);
it("does not return successful cached metadata after the file disappears", async () => {
const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-removed-"));
const file = resolve(dir, "video.mp4");
writeFileSync(file, "original file");
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video", width: 32, height: 24 }],
format: { duration: "1" },
}),
},
{ kind: "exit", code: 1, stderr: "input missing" },
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata } = await import("./ffprobe.js");
try {
await extractMediaMetadata(file);
rmSync(file);
await expect(extractMediaMetadata(file)).rejects.toThrow(/input missing/);
expect(calls).toHaveLength(2);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("does not retain completed metadata when file identity is unavailable", async () => {
const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-no-identity-"));
const file = resolve(dir, "missing.wav");
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "audio", codec_name: "mp3" }],
format: { duration: "1" },
}),
},
NO_DECODED_FRAMES,
NO_DECODED_FRAMES,
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "audio", codec_name: "mp3" }],
format: { duration: "2" },
}),
},
NO_DECODED_FRAMES,
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
try {
expect(await extractAudioMetadata(file)).toMatchObject({ durationSeconds: 1 });
expect(await extractAudioMetadata(file)).toMatchObject({ durationSeconds: 2 });
expect(metadataProbes(calls)).toHaveLength(2);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("keeps the replacement probe cached when an older probe fails", async () => {
const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-probe-race-"));
const file = resolve(dir, "video.mp4");
writeFileSync(file, "original file");
const factory = createSpawnSpy([]);
const processes: FakeProc[] = [];
vi.resetModules();
vi.doMock("child_process", () => ({
spawn: (command: string, args: readonly string[]) => {
const proc = factory.spawn(command, args);
processes.push(proc);
return proc;
},
}));
const { extractMediaMetadata } = await import("./ffprobe.js");
try {
const failed = expect(extractMediaMetadata(file)).rejects.toThrow(/code 1/);
writeFileSync(file, "updated file with different dimensions");
const replacement = extractMediaMetadata(file);
processes[0]?.emit("close", 1);
await failed;
const shared = extractMediaMetadata(file);
expect(factory.calls).toHaveLength(2);
processes[1]?.stdout.emit(
"data",
Buffer.from(
JSON.stringify({
streams: [{ codec_type: "video", width: 64, height: 48 }],
format: { duration: "2" },
}),
),
);
processes[1]?.emit("close", 0);
const [first, second] = await Promise.all([replacement, shared]);
expect(second).toBe(first);
expect(first).toMatchObject({ width: 64, durationSeconds: 2 });
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("still shares an unchanged file probe between concurrent callers", async () => {
const dir = mkdtempSync(resolve(tmpdir(), "hf-metadata-shared-"));
const file = resolve(dir, "video.mp4");
writeFileSync(file, "unchanged file");
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video", width: 32, height: 24 }],
format: { duration: "1" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata } = await import("./ffprobe.js");
try {
const [first, second] = await Promise.all([
extractMediaMetadata(file),
extractMediaMetadata(file),
]);
expect(second).toBe(first);
expect(calls).toHaveLength(1);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
describe("ffprobe missing-binary fallback", () => {
const originalFfprobePath = process.env.HYPERFRAMES_FFPROBE_PATH;
const originalPath = process.env.PATH;
function hidePathBinaries(): void {
process.env.PATH = "";
}
afterEach(() => {
vi.resetModules();
vi.doUnmock("child_process");
if (originalFfprobePath === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
else process.env.HYPERFRAMES_FFPROBE_PATH = originalFfprobePath;
if (originalPath === undefined) delete process.env.PATH;
else process.env.PATH = originalPath;
});
it("spawns the configured absolute FFprobe path when HYPERFRAMES_FFPROBE_PATH is set", async () => {
process.env.HYPERFRAMES_FFPROBE_PATH = "/tools/ffprobe.exe";
const successfulStderr = "recoverable diagnostic on a successful probe";
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "audio", codec_name: "aac", sample_rate: "48000", channels: 2 }],
format: { duration: "1.25", bit_rate: "128000" },
}),
stderr: successfulStderr,
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
const meta = await extractAudioMetadata("/tmp/uses-configured-ffprobe.wav");
expect(meta.durationSeconds).toBe(1.25);
expect(JSON.stringify(meta)).not.toContain(successfulStderr);
expect(calls[0]?.command).toBe(resolve("/tools/ffprobe.exe"));
expect(calls[0]?.args.slice(0, 2)).toEqual(["-v", "error"]);
});
it("does not accept an incomplete PNG through the missing-binary fallback", async () => {
const fixtureDir = mkdtempSync(resolve(tmpdir(), "hf-truncated-png-fallback-"));
const fixturePath = resolve(fixtureDir, "asset");
const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
writeFileSync(fixturePath, buildPngWithChunks([ihdr]));
const { spawn } = createSpawnSpy([{ kind: "missing" }]);
hidePathBinaries();
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { probeMediaProfile } = await import("./ffprobe.js");
try {
await expect(probeMediaProfile(fixturePath)).rejects.toThrow(/ffprobe/i);
} finally {
rmSync(fixtureDir, { recursive: true, force: true });
}
});
// The container always reports 1.25s; each case varies what the decode probe finds.
// `spawns` says whether the probe ran (no-frames also runs the full-scan fallback).
it.each([
{
name: "non-AAC codec, decoded duration well beyond the container summary",
codec: "flac",
sampleRate: "48000",
lastFrame: { best_effort_timestamp_time: "3.9", nb_samples: 4800 },
expected: 4.0, // 3.9 + 4800/48000
spawns: 2,
},
{
name: "decoded duration within probe-precision margin of the summary — kept as-is",
codec: "aac",
sampleRate: "48000",
// 1.2 + 3840/48000 = 1.28, only 0.03s over the 1.25s summary — under
// the margin, so the summary (edit-list-corrected) duration wins.
lastFrame: { best_effort_timestamp_time: "1.2", nb_samples: 3840 },
expected: 1.25,
spawns: 2,
},
{
name: "no decodable frames — keeps the container duration",
codec: "opus",
sampleRate: "48000",
lastFrame: undefined,
expected: 1.25,
// An empty tail read falls back to a full scan, which also finds
// nothing (the mock's last outcome — the empty stdout — repeats).
spawns: 3,
},
{
name: "zero sample rate — skips the decode probe entirely",
codec: "aac",
sampleRate: "0",
// Would have won on any other row; the probe is never spawned to see it.
lastFrame: { best_effort_timestamp_time: "10", nb_samples: 999_999 },
expected: 1.25,
spawns: 1,
},
])(
"derives audio duration for $name",
async ({ codec, sampleRate, lastFrame, expected, spawns }) => {
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{ codec_type: "audio", codec_name: codec, sample_rate: sampleRate, channels: 2 },
],
format: { duration: "1.25", bit_rate: "128000" },
}),
},
{
kind: "exit",
code: 0,
stdout: lastFrame
? `${lastFrame.best_effort_timestamp_time},${lastFrame.nb_samples}\n`
: "",
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
const meta = await extractAudioMetadata(`/tmp/${codec}-${sampleRate}.audio`);
expect(meta.durationSeconds).toBeCloseTo(expected, 6);
expect(calls).toHaveLength(spawns);
},
);
// A bad seek index can make the tail read find nothing past a real final frame.
it("falls back to a full decode when the tail-seeked read finds no frames", async () => {
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "audio", codec_name: "opus", sample_rate: "48000", channels: 2 }],
format: { duration: "1.25" },
}),
},
{ kind: "exit", code: 0, stdout: "" }, // tail-seeked read: nothing found
{ kind: "exit", code: 0, stdout: "1.4,4800\n" }, // full-scan fallback: real frame
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
const meta = await extractAudioMetadata("/tmp/tail-seek-miss.opus");
expect(meta.durationSeconds).toBeCloseTo(1.5, 6); // 1.4 + 4800/48000, well past the margin
expect(calls).toHaveLength(3);
expect(calls[1]?.args).toContain("-read_intervals");
expect(calls[2]?.args).not.toContain("-read_intervals");
});
// An abort is the caller's own intent, so the decode probe must surface it
// rather than swallow it the way it swallows a genuine probe failure. The
// signal is aborted only once the decode probe has spawned — aborting up
// front trips the container probe instead, leaving this path untested.
it("propagates an abort raised during the decode probe", async () => {
const controller = new AbortController();
const { spawn: baseSpawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "audio", codec_name: "opus", sample_rate: "48000", channels: 2 }],
format: { duration: "1.25" },
}),
},
{ kind: "exit", code: 0, stdout: "9,960\n" },
]);
const spawn = (command: string, args: readonly string[]) => {
if (calls.length === 1) controller.abort();
return baseSpawn(command, args);
};
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
await expect(
extractAudioMetadata("/tmp/aborted.audio", { signal: controller.signal }),
).rejects.toThrow();
expect(calls).toHaveLength(2);
});
it("extractMediaMetadata falls back to PNG cICP metadata when ffprobe is missing", async () => {
const { spawn, calls } = createSpawnSpy([{ kind: "missing" }]);
hidePathBinaries();
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
const fixture = resolve(
__dirname,
"../../../producer/tests/hdr-regression/src/hdr-photo-pq.png",
);
const meta = await extractMediaMetadataMocked(fixture);
expect(calls.length).toBe(1);
expect(basename(calls[0]?.command ?? "")).toMatch(/^ffprobe(?:\.exe)?$/);
expect(meta.videoCodec).toBe("png");
expect(meta.durationSeconds).toBe(0);
expect(meta.fps).toBe(0);
expect(meta.hasAudio).toBe(false);
expect(meta.isVFR).toBe(false);
expect(meta.hasAlpha).toBe(false);
expect(meta.colorSpace?.colorTransfer).toBe("smpte2084");
expect(meta.colorSpace?.colorPrimaries).toBe("bt2020");
});
it("extractMediaMetadata detects VP9 alpha_mode streams", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "vp9",
width: 320,
height: 180,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
pix_fmt: "yuv420p",
tags: { alpha_mode: "1" },
},
],
format: { duration: "1.5" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
const meta = await extractMediaMetadataMocked("/tmp/alpha.webm");
expect(meta.videoCodec).toBe("vp9");
expect(meta.hasAlpha).toBe(true);
});
it("normalizes omitted video color components to empty strings", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "h264",
width: 64,
height: 64,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
pix_fmt: "yuv420p",
color_space: "bt709",
},
],
format: { duration: "1" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
const metadata = await extractMediaMetadataMocked("/tmp/partial-color.mp4");
expect(metadata.colorSpace).toEqual({
colorPrimaries: "",
colorTransfer: "",
colorSpace: "bt709",
});
});
// Regression: newer libavformat builds (and the output of `hyperframes
// remove-background` itself) write the VP9-alpha sidecar tag as
// `ALPHA_MODE` (uppercase). The lowercase-only check classified those
// files as having no alpha, the producer extracted them as JPGs, and
// the injected <img> overlays were fully opaque rectangles that hid
// every static element below them on the z-stack. The bug was silent —
// studio preview rendered correctly via native <video> playback while
// production renders covered headlines and captions with the avatar.
it("extractMediaMetadata detects ALPHA_MODE (uppercase) streams from newer ffmpeg builds", async () => {
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "vp9",
width: 320,
height: 180,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
pix_fmt: "yuv420p",
tags: { ALPHA_MODE: "1" },
},
],
format: { duration: "1.5" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
const meta = await extractMediaMetadataMocked("/tmp/alpha-uppercase.webm");
expect(meta.videoCodec).toBe("vp9");
expect(meta.hasAlpha).toBe(true);
});
it("leaves alphaPlaneDecoded absent when the untagged VP9 decode probe fails", async () => {
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "vp9",
width: 320,
height: 180,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
pix_fmt: "yuv420p",
},
],
format: { duration: "1.5" },
}),
},
{ kind: "exit", code: 1, stderr: "decoder failed" },
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
const meta = await extractMediaMetadataMocked("/tmp/probe-fails.webm");
expect(calls[1]?.args).toEqual(expect.arrayContaining(["-c:v", "libvpx-vp9"]));
expect(meta.hasAlpha).toBe(false);
expect("alphaPlaneDecoded" in meta).toBe(false);
});
it("extractMediaMetadata rethrows ffprobe-missing error for non-image files without fallback", async () => {
const { spawn } = createSpawnSpy([{ kind: "missing" }]);
hidePathBinaries();
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
await expect(extractMediaMetadataMocked("/tmp/no-such-video.mp4")).rejects.toThrow(/ffprobe/);
});
it("surfaces bounded ffprobe stderr for invalid media", async () => {
const leadingNoise = "x".repeat(10_000);
const diagnostic = "Invalid data found when processing input";
const inputPath = "/tmp/render/My Secret Video.mp4";
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 1,
stderr: `${leadingNoise}${inputPath}: ${diagnostic}`,
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
let thrown: unknown;
try {
await extractAudioMetadata(inputPath);
} catch (error) {
thrown = error;
}
expect(String(thrown)).toContain(diagnostic);
expect(String(thrown)).toContain("[input]");
expect(String(thrown)).not.toContain(inputPath);
expect(String(thrown)).not.toContain("My Secret Video.mp4");
expect(String(thrown).length).toBeLessThan(4_500);
expect(calls[0]?.args.slice(0, 2)).toEqual(["-v", "error"]);
expect(calls[0]?.args.at(-1)).toBe(inputPath);
});
it("redacts an input path fragment when the stderr tail starts inside its basename", async () => {
const diagnostic = "Invalid data found when processing input";
const inputPath = "/tmp/render/Confidential Client Preview.mp4";
const retainedPathFragment = "Client Preview.mp4";
const diagnosticPrefix = `: ${diagnostic} `;
const remainingBytes =
8 * 1024 - Buffer.byteLength(retainedPathFragment) - Buffer.byteLength(diagnosticPrefix);
const multibyteCount = Math.floor(remainingBytes / Buffer.byteLength("€"));
const trailingAscii = "x".repeat(remainingBytes - multibyteCount * Buffer.byteLength("€"));
const stderr = `${inputPath}${diagnosticPrefix}${"€".repeat(multibyteCount)}${trailingAscii}`;
const { spawn } = createSpawnSpy([{ kind: "exit", code: 1, stderr }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
let thrown: unknown;
try {
await extractAudioMetadata(inputPath);
} catch (error) {
thrown = error;
}
expect(String(thrown)).toContain(diagnostic);
expect(String(thrown)).toContain("[input]");
expect(String(thrown)).not.toContain(retainedPathFragment);
expect(String(thrown)).not.toContain("Client Preview.mp4");
});
it("extractAudioMetadata surfaces a ffprobe-missing error verbatim", async () => {
const { spawn, calls } = createSpawnSpy([{ kind: "missing" }]);
hidePathBinaries();
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
await expect(extractAudioMetadata("/tmp/no-such-audio.wav")).rejects.toThrow(
/ffprobe not found/,
);
expect(calls.length).toBe(1);
expect(basename(calls[0]?.command ?? "")).toMatch(/^ffprobe(?:\.exe)?$/);
});
it("analyzeKeyframeIntervals flags a single-keyframe video as problematic, not healthy", async () => {
// A single-GOP file (one keyframe at t=0) is the worst case this check exists to catch.
// Regression for #3460, where fewer than 2 keyframes short-circuited to isProblematic:false.
// Real `csv=p=0` output has a trailing comma per row; parseFloat must tolerate it.
const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "0.000000,\n" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { analyzeKeyframeIntervals } = await import("./ffprobe.js");
await expect(
analyzeKeyframeIntervals("/tmp/single-gop.mp4", {
videoStreamDurationSeconds: 6.5,
videoStreamStartSeconds: 0,
}),
).resolves.toEqual({
avgIntervalSeconds: 6.5,
maxIntervalSeconds: 6.5,
keyframeCount: 1,
isProblematic: true,
});
});
it("analyzeKeyframeIntervals leaves a single keyframe exactly at the 2s threshold healthy", async () => {
// isProblematic compares with a strict `>`, so exactly 2s must stay healthy.
const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "0.000000\n" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { analyzeKeyframeIntervals } = await import("./ffprobe.js");
await expect(
analyzeKeyframeIntervals("/tmp/exactly-two-seconds.mp4", {
videoStreamDurationSeconds: 2,
videoStreamStartSeconds: 0,
}),
).resolves.toEqual({
avgIntervalSeconds: 2,
maxIntervalSeconds: 2,
keyframeCount: 1,
isProblematic: false,
});
});
it("analyzeKeyframeIntervals normalizes an absolute keyframe pts against a nonzero stream start", async () => {
// ffprobe's pts_time is absolute, not relative to stream start. A clip with
// start_time=5 and a keyframe at absolute pts 5.0 is still single-GOP end-to-end,
// so it must stay flagged, not cleared by subtracting duration from the raw pts.
const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "5.000000\n" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { analyzeKeyframeIntervals } = await import("./ffprobe.js");
await expect(
analyzeKeyframeIntervals("/tmp/nonzero-start-single-gop.mp4", {
videoStreamDurationSeconds: 3,
videoStreamStartSeconds: 5,
}),
).resolves.toEqual({
avgIntervalSeconds: 3,
maxIntervalSeconds: 3,
keyframeCount: 1,
isProblematic: true,
});
});
it("analyzeKeyframeIntervals leaves a short single-keyframe video healthy", async () => {
// The single-GOP span is measured off the duration the caller passes in, so
// a 1s video muxed with 10s of audio has to be probed with its video
// stream's duration; the container's would overstate the span and warn.
const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "0.000000\n" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { analyzeKeyframeIntervals } = await import("./ffprobe.js");
await expect(
analyzeKeyframeIntervals("/tmp/short-video-long-audio.mp4", {
videoStreamDurationSeconds: 1,
videoStreamStartSeconds: 0,
}),
).resolves.toEqual({
avgIntervalSeconds: 1,
maxIntervalSeconds: 1,
keyframeCount: 1,
isProblematic: false,
});
});
it("analyzeKeyframeIntervals treats a single keyframe with an unknown (NaN) duration as healthy, not NaN", async () => {
// ffprobe reports "N/A" for duration on some containers, which parses to
// NaN upstream in extractMediaMetadata. Without a finite-duration guard,
// NaN propagates through Math.max unchanged into the returned interval.
const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "0.000000\n" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { analyzeKeyframeIntervals } = await import("./ffprobe.js");
await expect(
analyzeKeyframeIntervals("/tmp/unknown-duration.mp4", {
videoStreamDurationSeconds: NaN,
videoStreamStartSeconds: 0,
}),
).resolves.toEqual({
avgIntervalSeconds: 0,
maxIntervalSeconds: 0,
keyframeCount: 1,
isProblematic: false,
});
});
it("analyzeKeyframeIntervals reports a zero-keyframe video as healthy, ignoring the duration", async () => {
const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { analyzeKeyframeIntervals } = await import("./ffprobe.js");
await expect(
analyzeKeyframeIntervals("/tmp/no-keyframes.mp4", {
videoStreamDurationSeconds: 6.5,
videoStreamStartSeconds: 0,
}),
).resolves.toEqual({
avgIntervalSeconds: 0,
maxIntervalSeconds: 0,
keyframeCount: 0,
isProblematic: false,
});
});
it("analyzeKeyframeIntervals surfaces a ffprobe-missing error verbatim", async () => {
const { spawn, calls } = createSpawnSpy([{ kind: "missing" }]);
hidePathBinaries();
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { analyzeKeyframeIntervals } = await import("./ffprobe.js");
await expect(
analyzeKeyframeIntervals("/tmp/no-such-video.mp4", {
videoStreamDurationSeconds: 10,
videoStreamStartSeconds: 0,
}),
).rejects.toThrow(/ffprobe not found/);
expect(calls.length).toBe(1);
expect(basename(calls[0]?.command ?? "")).toMatch(/^ffprobe(?:\.exe)?$/);
});
it("ffprobe-missing error message includes install hint", async () => {
const { spawn } = createSpawnSpy([{ kind: "missing" }]);
hidePathBinaries();
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
await expect(extractAudioMetadata("/tmp/example.mp3")).rejects.toThrow(/install FFmpeg/i);
});
});
describe("ffprobe option separator", () => {
afterEach(() => {
vi.resetModules();
vi.doUnmock("child_process");
});
it("places -- before the file path so paths starting with - are not parsed as options", async () => {
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "h264",
width: 320,
height: 180,
r_frame_rate: "30/1",
avg_frame_rate: "30/1",
},
],
format: { duration: "1.5" },
}),
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata } = await import("./ffprobe.js");
const filePath = "/tmp/-dangerous-name.mp4";
await extractMediaMetadata(filePath);
const args = calls[0]?.args ?? [];
const filePathIndex = args.indexOf(filePath);
expect(filePathIndex).toBeGreaterThan(0);
expect(args[filePathIndex - 1]).toBe("--");
});
it("uses -- for audio and keyframe probes too", async () => {
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "audio",
codec_name: "aac",
sample_rate: "48000",
channels: 2,
},
],
format: { duration: "1.25" },
}),
},
// The decode-based duration probe also runs, so its argv (including its
// own `--`) is covered here too.
{ kind: "exit", code: 0, stdout: "1.2,3840\n" },
{ kind: "exit", code: 0, stdout: "0.000\n1.000\n" },
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata, analyzeKeyframeIntervals } = await import("./ffprobe.js");
await extractAudioMetadata("/tmp/-audio.wav");
await analyzeKeyframeIntervals("/tmp/-video.mp4", {
videoStreamDurationSeconds: 10,
videoStreamStartSeconds: 0,
});
// Per call, not a flattened count. A total of 3 is satisfied by one call
// emitting three `--` and two emitting none — i.e. it cannot fail for
// misplacement, which is the shape of bug this exists to catch.
expect(calls.map((call) => (call.args ?? []).slice(-2))).toEqual([
["--", "/tmp/-audio.wav"],
["--", "/tmp/-audio.wav"],
["--", "/tmp/-video.mp4"],
]);
});
});
describe("parseFrameRate", () => {
// Direct against the exported function. The previous table drove this
// through extractMediaMetadata behind a spawn mock, which cost a
// vi.resetModules() plus a dynamic re-import of core's 238-file barrel per
// row (74.9 ms vs 0.094 ms) — and 4 of its 7 rows produced identical values
// against the pre-fix implementation, so it could not fail for the bugs it
// was written to catch.
it.each([
["30/1", 30],
["30000/1001", 29.97],
["24000/1001", 23.98],
["60", 60],
["25.5", 25.5],
])("parses %s as %s", (input, expected) => {
expect(parseFrameRate(input)).toBe(expected);
});
it.each([
["30/", 0],
["30/0", 0],
["0/0", 0],
["abc/def", 0],
["", 0],
[undefined, 0],
])("returns 0 for unusable input %s", (input, expected) => {
expect(parseFrameRate(input)).toBe(expected);
});
// Finite operands, infinite quotient — the operand-only guard missed these.
it.each(["1e308/1e-10", "2/1e-320"])("returns 0 for overflowing quotient %s", (input) => {
expect(parseFrameRate(input)).toBe(0);
});
// Negatives were truthy, so `meta.fps || 30` did not rescue them and
// buildEncoderArgs emitted `-r -30`.
it.each(["-30/1", "30/-1", "-60"])("returns 0 for negative rate %s", (input) => {
expect(parseFrameRate(input)).toBe(0);
});
// Fell through to a bare parseFloat that stops at trailing garbage. The
// rational operands had the same defect after the plain path was fixed.
it.each(["30/1/2", "60fps", "60fps/1", "60/1fps", "30garbage/1garbage", "/", "/1", "30/"])(
"returns 0 for malformed input %s",
(input) => {
expect(parseFrameRate(input)).toBe(0);
},
);
// raw * 100 overflows for a finite-but-huge rate, so the rounded value was
// Infinity even though the pre-round guard passed.
it.each(["1e307", "1e307/1", "1e308/0.5"])("returns 0 when rounding overflows: %s", (input) => {
expect(parseFrameRate(input)).toBe(0);
});
// 2dp rounding collapsed these to 0, and the caller's `|| 30` then
// re-encoded a 300-second timelapse as a ~1/30-second clip.
it.each([
["1/300", 0.01],
["1/1000", 0.01],
["1/200", 0.01],
])("floors sub-0.005 rate %s to %s rather than 0", (input, expected) => {
expect(parseFrameRate(input)).toBe(expected);
});
});
describe("extractPngMetadataFromBuffer cICP ordering", () => {
it("does not emit color space until IHDR provides width and height", () => {
const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
const cicp = pngChunk("cICP", [9, 16, 0, 1]);
const idat = pngChunk("IDAT", [0x78, 0x9c, 0x03, 0x00, 0x00, 0x00, 0x00, 0x01]);
const iend = pngChunk("IEND", []);
// cICP before IHDR is invalid PNG ordering; make sure we don't return
// zero-sized metadata in that case.
const malformed = buildPngWithChunks([cicp, ihdr, idat, iend]);
expect(extractPngMetadataFromBuffer(malformed)).toEqual({
width: 1,
height: 1,
colorSpace: {
colorPrimaries: "bt2020",
colorTransfer: "smpte2084",
colorSpace: "gbr",
},
});
// Without any IHDR, a cICP alone should not produce a result.
const onlyCicp = buildPngWithChunks([cicp, iend]);
expect(extractPngMetadataFromBuffer(onlyCicp)).toBeNull();
});
});
describe("PNG chunk walk — integrity of the fallback itself", () => {
const IHDR_4K = [0, 0, 0x0f, 0, 0, 0, 0x08, 0x70, 16, 2, 0, 0, 0];
const CICP_PQ = [9, 16, 0, 1];
// Regression: the walk used to continue past cICP to IEND, which made
// whole-file integrity a precondition for returning anything. A damaged
// trailing chunk in an otherwise-good HDR PNG nulled the whole result, and
// extractMediaMetadata then re-throws the ffprobe error it had swallowed
// rather than using the fallback it just computed.
it("returns metadata even when a chunk AFTER cICP is corrupt", () => {
const bad = pngChunk("tEXt", [65, 66]);
bad[bad.length - 1] ^= 0xff; // break the CRC
const png = buildPngWithChunks([
pngChunk("IHDR", IHDR_4K),
pngChunk("cICP", CICP_PQ),
pngChunk("IDAT", [0x78, 0x9c, 0x63, 0x00, 0x00, 0x00, 0x02, 0x00, 0x01]),
bad,
pngChunk("IEND", []),
]);
expect(extractPngMetadataFromBuffer(png)).toEqual({
width: 3840,
height: 2160,
colorSpace: { colorPrimaries: "bt2020", colorTransfer: "smpte2084", colorSpace: "gbr" },
});
});
it("survives outright truncation after cICP", () => {
const png = buildPngWithChunks([pngChunk("IHDR", IHDR_4K), pngChunk("cICP", CICP_PQ)]);
const truncated = Buffer.concat([png, Buffer.from([0, 0, 0x7f, 0xff, 73, 68, 65, 84])]);
expect(extractPngMetadataFromBuffer(truncated)?.width).toBe(3840);
});
// Regression: IHDR had no first-chunk anchor, so a later one overwrote the
// real dimensions and the producer laid out a 1-pixel image.
it("ignores a second IHDR", () => {
const png = buildPngWithChunks([
pngChunk("IHDR", IHDR_4K),
pngChunk("cICP", CICP_PQ),
pngChunk("IDAT", [0x78, 0x9c, 0x63, 0x00, 0x00, 0x00, 0x02, 0x00, 0x01]),
pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]),
pngChunk("IEND", []),
]);
const meta = extractPngMetadataFromBuffer(png);
expect(meta?.width).toBe(3840);
expect(meta?.height).toBe(2160);
});
// A truncated 8-byte IHDR used to be accepted, reading height out of the
// CRC bytes; the spec length is 13.
it("rejects a short IHDR rather than reading garbage dimensions", () => {
const png = buildPngWithChunks([
pngChunk("IHDR", [0, 0, 0, 7, 0, 0, 0, 9]),
pngChunk("cICP", CICP_PQ),
pngChunk("IEND", []),
]);
expect(extractPngMetadataFromBuffer(png)).toBeNull();
});
it("still rejects a PNG whose IHDR or cICP itself is corrupt", () => {
const badIhdr = pngChunk("IHDR", IHDR_4K);
badIhdr[badIhdr.length - 1] ^= 0xff;
expect(
extractPngMetadataFromBuffer(buildPngWithChunks([badIhdr, pngChunk("IEND", [])])),
).toBeNull();
});
});
describe("crc32 works on every runtime the package declares", () => {
afterEach(() => {
vi.resetModules();
vi.doUnmock("node:zlib");
});
/** Load ffprobe.ts as it would evaluate on Node 22.0/22.1. */
async function loadWithoutNativeCrc32() {
const actual = await vi.importActual<typeof import("node:zlib")>("node:zlib");
vi.resetModules();
// zlib.crc32 landed in 22.2.0, but engine and cli both declare
// `"node": ">=22"` behind a major-only gate. A NAMED import of a missing
// export throws at module evaluation, so ffprobe.ts would fail to load
// entirely on those runtimes — before any PNG is touched.
vi.doMock("node:zlib", () => ({ ...actual, crc32: undefined }));
return import("./ffprobe.js");
}
it("parses an HDR PNG identically with the native crc32 unavailable", async () => {
const png = buildPngWithChunks([
pngChunk("IHDR", [0, 0, 0x0f, 0, 0, 0, 0x08, 0x70, 16, 2, 0, 0, 0]),
pngChunk("cICP", [9, 16, 0, 1]),
pngChunk("IEND", []),
]);
const withNative = extractPngMetadataFromBuffer(png);
expect(withNative?.colorSpace?.colorTransfer).toBe("smpte2084");
const fresh = await loadWithoutNativeCrc32();
expect(fresh.extractPngMetadataFromBuffer(png)).toEqual(withNative);
});
it("rejects a corrupt chunk on the fallback path too", async () => {
const bad = pngChunk("IHDR", [0, 0, 0x0f, 0, 0, 0, 0x08, 0x70, 16, 2, 0, 0, 0]);
bad[bad.length - 1] ^= 0xff;
const png = buildPngWithChunks([bad, pngChunk("IEND", [])]);
const fresh = await loadWithoutNativeCrc32();
expect(fresh.extractPngMetadataFromBuffer(png)).toBeNull();
});
});
describe("audio duration decode probe never fails the call and needs no profile allowlist", () => {
afterEach(() => {
vi.resetModules();
vi.doUnmock("child_process");
});
const aacStream = (profile?: string) =>
JSON.stringify({
streams: [
{ codec_type: "audio", codec_name: "aac", sample_rate: "44100", channels: 2, profile },
],
format: { duration: "600", bit_rate: "128000" },
});
async function probe(outcomes: SpawnOutcome[], file: string) {
const { spawn, calls } = createSpawnSpy(outcomes);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
return { meta: await extractAudioMetadata(file), calls };
}
// Regression: the old refinement had no try/catch, so its failure rejected a
// call whose duration was already correct. htmlCompiler catches that as
// "no audio stream", returns 0, and the render ships silent.
it("keeps the container duration when the decode probe fails", async () => {
const { meta, calls } = await probe(
[
{ kind: "exit", code: 0, stdout: aacStream() },
{ kind: "exit", code: 1, stdout: "", stderr: "ffprobe exploded" },
],
"/tmp/decode-probe-fails.m4a",
);
expect(meta.durationSeconds).toBe(600);
// The tail-seeked attempt fails, so the full-scan fallback also runs (and
// also fails, via the mock's repeated last outcome) before giving up.
expect(calls).toHaveLength(3);
});
it("keeps the container duration when the decode probe returns junk", async () => {
const { meta, calls } = await probe(
[
{ kind: "exit", code: 0, stdout: aacStream() },
{ kind: "exit", code: 0, stdout: "not json at all" },
],
"/tmp/decode-probe-junk.m4a",
);
expect(meta.durationSeconds).toBe(600);
expect(calls).toHaveLength(3);
});
// The old refinement needed a profile allowlist because it guessed a fixed
// samples-per-frame value (right for AAC-LC, wrong for HE-AAC/LD/ELD/etc).
// Decoding the real last frame's own sample count has no such assumption,
// so every profile goes through the same path with no special-casing.
it.each(["LC", "HE-AAC", "HE-AACv2", "LD", "ELD", "Main", "", "SomethingNew"])(
"corrects duration for AAC profile %s, with no allowlist",
async (profile) => {
const { meta, calls } = await probe(
[
{ kind: "exit", code: 0, stdout: aacStream(profile) },
{ kind: "exit", code: 0, stdout: "603.9,4410\n" },
],
`/tmp/aac-${profile || "none"}.m4a`,
);
expect(meta.durationSeconds).toBeCloseTo(604, 5); // 603.9 + 4410/44100
expect(calls).toHaveLength(2);
},
);
const audioProbe = (stream: object, format: object) =>
JSON.stringify({
streams: [{ codec_type: "audio", codec_name: "aac", sample_rate: "44100", ...stream }],
format: { duration: "600", ...format },
});
const readInterval = (calls: SpawnCall[]) =>
calls[1]?.args[calls[1].args.indexOf("-read_intervals") + 1];
it.each([
["the stream", { start_time: "1.4" }, {}],
["the format, when the stream has none", {}, { start_time: "1.4" }],
])("measures the decoded end from the start time of %s", async (_, stream, format) => {
const { meta, calls } = await probe(
[
{ kind: "exit", code: 0, stdout: audioProbe(stream, format) },
{ kind: "exit", code: 0, stdout: "601.3,4410\n" },
],
`/tmp/start-offset-${Object.keys(format).length}.ts`,
);
expect(meta.durationSeconds).toBe(600); // 601.3 + 0.1 - 1.4 is within the margin
expect(readInterval(calls)).toBe("600.4%+2147483647");
});
it.each([
["trusts a shorter decode for raw ADTS", "aac", 10],
["keeps the container for an MP4, whose edit list may trim", "mov,mp4,m4a,3gp,3g2,mj2", 600],
])("%s", async (_, formatName, expected) => {
const { meta } = await probe(
[
{ kind: "exit", code: 0, stdout: audioProbe({}, { format_name: formatName }) },
{ kind: "exit", code: 0, stdout: "9.9,4410\n" },
],
`/tmp/shorter-decode-${formatName.length}.aac`,
);
expect(meta.durationSeconds).toBeCloseTo(expected, 5);
});
it("reads the last frame of a decode listing longer than the stdout cap", async () => {
const rows = Array.from({ length: 10000 }, (_, i) => `${(i / 100).toFixed(2)},4410`);
const { meta } = await probe(
[
{ kind: "exit", code: 0, stdout: aacStream() },
{ kind: "exit", code: 0, stdout: `${rows.join("\n")}\n603.9,4410\n` },
],
"/tmp/long-decode-listing.m4a",
);
expect(meta.durationSeconds).toBeCloseTo(604, 5);
});
});
// honest.mp4 is FLAC-in-MP4; lying.mp4 is the same bytes with the mvhd/tkhd/mdhd
// durations halved, every audio frame intact.
const HAS_FFPROBE = spawnSync("ffprobe", ["-version"]).status === 0;
describe.skipIf(!HAS_FFPROBE)(
"extractAudioMetadata recovers a real lying container's true duration",
() => {
const honestPath = resolve(__dirname, "__fixtures__/lying-container/honest.mp4");
const lyingPath = resolve(__dirname, "__fixtures__/lying-container/lying.mp4");
it("recovers the true duration from a FLAC-in-MP4 file whose container atoms were patched to lie", async () => {
const { extractAudioMetadata } = await import("./ffprobe.js");
const trueMeta = await extractAudioMetadata(honestPath);
expect(trueMeta.audioCodec).toBe("flac");
expect(trueMeta.durationSeconds).toBeGreaterThan(3.9);
const lyingMeta = await extractAudioMetadata(lyingPath);
// Recovers the real duration — not the halved container summary.
expect(lyingMeta.durationSeconds).toBeCloseTo(trueMeta.durationSeconds, 1);
});
// ffprobe reads an open interval's end from uninitialised heap; glibc's MALLOC_PERTURB_
// makes that garbage deterministic on Linux, as Windows' heap does at random.
it("decodes the tail in one pass when ffprobe's heap is dirty", async () => {
const real = await vi.importActual<typeof import("child_process")>("child_process");
const probes: string[][] = [];
vi.resetModules();
vi.doMock("child_process", () => ({
...real,
spawn: (command: string, args: string[], options: object) => {
probes.push(args);
return real.spawn(command, args, options);
},
}));
const previous = process.env.MALLOC_PERTURB_;
process.env.MALLOC_PERTURB_ = "1";
try {
const { extractAudioMetadata } = await import("./ffprobe.js");
expect((await extractAudioMetadata(lyingPath)).durationSeconds).toBeCloseTo(4, 3);
// The container probe, then the tail decode; a third call is the full-scan fallback.
expect(probes).toHaveLength(2);
} finally {
if (previous === undefined) delete process.env.MALLOC_PERTURB_;
else process.env.MALLOC_PERTURB_ = previous;
vi.doUnmock("child_process");
vi.resetModules();
}
});
// 2 s of AAC in MPEG-TS starting at 1.4 s: last frame 3.448 + 1024/16000 - 1.4.
it("does not add an MPEG-TS start time to the duration", async () => {
const { extractAudioMetadata } = await import("./ffprobe.js");
const path = resolve(__dirname, "__fixtures__/lying-container/start-offset.mpegts");
expect((await extractAudioMetadata(path)).durationSeconds).toBeCloseTo(2.112, 3);
});
// 2 s silence + 1 s noise as raw ADTS; ffprobe 8.1 estimates about 9.1 s from the quiet opening.
it("corrects a raw ADTS duration that the container overclaims", async () => {
const { extractAudioMetadata } = await import("./ffprobe.js");
const path = resolve(__dirname, "__fixtures__/lying-container/overclaim.aac");
expect((await extractAudioMetadata(path)).durationSeconds).toBeCloseTo(3.072, 3);
});
},
);
describe("final video frame timestamp probes", () => {
afterEach(() => {
vi.resetModules();
vi.doUnmock("child_process");
});
it("normalizes absolute frame PTS by the selected video stream start", async () => {
const { spawn, calls } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "video",
codec_name: "h264",
width: 64,
height: 64,
duration: "3",
start_time: "5",
r_frame_rate: "1/1",
avg_frame_rate: "1/1",
},
],
format: { duration: "8" },
}),
},
{ kind: "exit", code: 0, stdout: "5.000000,\n6.000000\n7.000000\n" },
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractFinalVideoFrameTimestamp, extractMediaMetadata } = await import("./ffprobe.js");
const metadata = await extractMediaMetadata("/tmp/nonzero-start.mp4");
expect(metadata.videoStreamDurationSeconds).toBe(3);
expect(metadata.videoStreamStartSeconds).toBe(5);
await expect(extractFinalVideoFrameTimestamp("/tmp/nonzero-start.mp4", metadata)).resolves.toBe(
2,
);
const intervalIndex = calls[1]?.args.indexOf("-read_intervals") ?? -1;
expect(calls[1]?.args[intervalIndex + 1]).toBe("7%8");
});
it("falls back to a bounded-output full scan when a transport cannot interval-seek", async () => {
const { spawn, calls } = createSpawnSpy([
{ kind: "exit", code: 0, stdout: "" },
{ kind: "exit", code: 0, stdout: "-2.000000,\n-1.000000\n0.000000\n" },
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
await expect(
extractFinalVideoFrameTimestamp("/tmp/unindexed-negative-base.ts", {
videoStreamDurationSeconds: 3,
videoStreamStartSeconds: -2,
}),
).resolves.toBe(2);
const intervalIndex = calls[0]?.args.indexOf("-read_intervals") ?? -1;
expect(calls[0]?.args[intervalIndex + 1]).toBe("0%1");
expect(calls[1]?.args).not.toContain("-read_intervals");
});
it("does not share a caller-cancellable probe across render consumers", async () => {
type KillableFakeProc = FakeProc & { kill: (signal?: NodeJS.Signals) => boolean };
const processes: KillableFakeProc[] = [];
const spawn = () => {
const proc = new EventEmitter() as KillableFakeProc;
proc.stdout = new EventEmitter();
proc.stderr = new EventEmitter();
proc.kill = vi.fn(() => {
process.nextTick(() => proc.emit("close", null, "SIGTERM"));
return true;
});
processes.push(proc);
process.nextTick(() => proc.emit("spawn"));
return proc;
};
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
const metadata = { videoStreamDurationSeconds: 3, videoStreamStartSeconds: 0 };
const firstController = new AbortController();
const secondController = new AbortController();
const first = extractFinalVideoFrameTimestamp(
"/tmp/shared-source.mp4",
metadata,
firstController.signal,
);
const second = extractFinalVideoFrameTimestamp(
"/tmp/shared-source.mp4",
metadata,
secondController.signal,
);
expect(processes).toHaveLength(2);
firstController.abort();
await expect(first).rejects.toThrow(/ffprobe abort/);
expect(processes[0]?.kill).toHaveBeenCalledWith("SIGTERM");
expect(processes[1]?.kill).not.toHaveBeenCalled();
processes[1]?.stdout.emit("data", Buffer.from("2.000000\n"));
processes[1]?.emit("close", 0, null);
await expect(second).resolves.toBe(2);
expect(secondController.signal.aborted).toBe(false);
});
it("deduplicates the interval and fallback chain within one cancellation scope", async () => {
const { spawn, calls } = createSpawnSpy([
{ kind: "exit", code: 0, stdout: "" },
{ kind: "exit", code: 0, stdout: "-2.000000\n-1.000000\n0.000000\n" },
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
const metadata = { videoStreamDurationSeconds: 3, videoStreamStartSeconds: -2 };
const signal = new AbortController().signal;
await expect(
Promise.all([
extractFinalVideoFrameTimestamp("/tmp/repeated-held-tail.ts", metadata, signal),
extractFinalVideoFrameTimestamp("/tmp/repeated-held-tail.ts", metadata, signal),
]),
).resolves.toEqual([2, 2]);
expect(calls).toHaveLength(2);
expect(calls[0]?.args).toContain("-read_intervals");
expect(calls[1]?.args).not.toContain("-read_intervals");
});
it("still deduplicates cancellation-independent probes", async () => {
const { spawn, calls } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "2.000000\n" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractFinalVideoFrameTimestamp } = await import("./ffprobe.js");
const metadata = { videoStreamDurationSeconds: 3, videoStreamStartSeconds: 0 };
await Promise.all([
extractFinalVideoFrameTimestamp("/tmp/shared-source.mp4", metadata),
extractFinalVideoFrameTimestamp("/tmp/shared-source.mp4", metadata),
]);
expect(calls).toHaveLength(1);
});
});
describe("runFfprobe process and stream handling", () => {
afterEach(() => {
vi.resetModules();
vi.doUnmock("child_process");
});
// Regression: `--` protects "-intro.mp4" but not a path of exactly "-",
// which ffprobe rewrites to fd: AFTER option parsing and then reads stdin.
// With stdin left as an unwritten pipe the probe hung for the full 30s
// deadline and failed with an empty diagnostic.
it("rejects a filePath of '-' immediately instead of hanging on stdin", async () => {
const { spawn, calls } = createSpawnSpy([{ kind: "exit", code: 0, stdout: "{}" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata } = await import("./ffprobe.js");
await expect(extractMediaMetadata("-")).rejects.toThrow(/stdin is not a supported input path/);
expect(calls).toHaveLength(0);
});
it("never leaves the child's stdin as a writable pipe", async () => {
const stdios: unknown[] = [];
const spawn = (_c: string, _a: readonly string[], opts?: { stdio?: unknown }) => {
stdios.push(opts?.stdio);
const proc = new EventEmitter() as FakeProc;
proc.stdout = new EventEmitter();
proc.stderr = new EventEmitter();
process.nextTick(() => {
proc.stdout.emit(
"data",
Buffer.from(
JSON.stringify({
streams: [{ codec_type: "video", codec_name: "h264", width: 2, height: 2 }],
format: { duration: "1" },
}),
),
);
proc.emit("close", 0);
});
return proc;
};
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata } = await import("./ffprobe.js");
await extractMediaMetadata("/tmp/stdio-shape.mp4");
expect(stdios[0]).toEqual(["ignore", "pipe", "pipe"]);
});
// NOTE on the StringDecoder change: a per-chunk toString() corrupts a
// multi-byte character split across a pipe boundary into U+FFFD, but
// U+FFFD is valid JSON string content, so JSON.parse still succeeds and
// extractMediaMetadata's public surface returns nothing that exposes the
// mangled tag value. There is no assertion here that fails on the old
// implementation, so rather than ship a test that cannot fail, the
// corruption is stated in the commit and this covers the bound instead.
it("refuses to parse stdout that exceeds the size bound", async () => {
const huge = "x".repeat(8_000_001);
const { spawn } = createSpawnSpy([{ kind: "exit", code: 0, stdout: huge }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata } = await import("./ffprobe.js");
await expect(extractMediaMetadata("/tmp/unbounded-output.mov")).rejects.toThrow(
/exceeded 8000000 characters/,
);
});
});
describe.skipIf(!HAS_FFPROBE)("VP8/VP9 decoded alpha plane probe on real files", () => {
let dir: string;
const encode = (name: string, args: string[]): string => {
const out = join(dir, name);
const res = spawnSync("ffmpeg", [
"-v",
"error",
"-f",
"lavfi",
"-i",
"color=c=red@0.5:s=64x64:d=1,format=rgba",
...args,
"-y",
out,
]);
expect(res.status).toBe(0);
return out;
};
let alpha: string;
let alphaVp8: string;
let opaqueVp9: string;
let opaqueVp8: string;
let mpeg4: string;
beforeAll(() => {
dir = mkdtempSync(join(tmpdir(), "hf-decoded-alpha-"));
alpha = encode("alpha.webm", ["-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p"]);
// libvpx refuses transparency with its default alt-ref frames.
alphaVp8 = encode("alpha-vp8.webm", [
"-c:v",
"libvpx",
"-auto-alt-ref",
"0",
"-pix_fmt",
"yuva420p",
]);
opaqueVp9 = encode("opaque-vp9.webm", ["-c:v", "libvpx-vp9", "-pix_fmt", "yuv420p"]);
opaqueVp8 = encode("opaque-vp8.webm", ["-c:v", "libvpx", "-pix_fmt", "yuv420p"]);
mpeg4 = encode("opaque.mp4", ["-c:v", "mpeg4", "-pix_fmt", "yuv420p"]);
});
afterAll(() => rmSync(dir, { recursive: true, force: true }));
it("probeDecodedAlphaPlane sees the alpha plane only in the alpha stream", async () => {
const { probeDecodedAlphaPlane } = await import("./ffprobe.js");
expect(await probeDecodedAlphaPlane(alpha, "libvpx-vp9")).toBe(true);
expect(await probeDecodedAlphaPlane(alphaVp8, "libvpx")).toBe(true);
expect(await probeDecodedAlphaPlane(opaqueVp9, "libvpx-vp9")).toBe(false);
expect(await probeDecodedAlphaPlane(opaqueVp8, "libvpx")).toBe(false);
expect(await probeDecodedAlphaPlane(join(dir, "missing.webm"), "libvpx-vp9")).toBeUndefined();
});
it("extractMediaMetadata records alphaPlaneDecoded=false only for untagged VP8/VP9", async () => {
const { extractMediaMetadata } = await import("./ffprobe.js");
const vp9 = await extractMediaMetadata(opaqueVp9);
expect(vp9).toMatchObject({ videoCodec: "vp9", hasAlpha: false, alphaPlaneDecoded: false });
const vp8 = await extractMediaMetadata(opaqueVp8);
expect(vp8).toMatchObject({ videoCodec: "vp8", hasAlpha: false, alphaPlaneDecoded: false });
// Tagged alpha is already decided by hasAlpha, so it is not probed.
const tagged = await extractMediaMetadata(alpha);
expect(tagged.hasAlpha).toBe(true);
expect("alphaPlaneDecoded" in tagged).toBe(false);
const other = await extractMediaMetadata(mpeg4);
expect(other.videoCodec).toBe("mpeg4");
expect("alphaPlaneDecoded" in other).toBe(false);
});
});
describe("formatFfmpegSeconds", () => {
it("never writes an exponent, which ffmpeg and ffprobe reject", () => {
expect(formatFfmpegSeconds(8.881784197001252e-16)).toBe("0");
expect(formatFfmpegSeconds(-8.881784197001252e-16)).toBe("0");
expect(formatFfmpegSeconds(1.5e-7)).toBe("0");
});
it("keeps ordinary times exactly as String() writes them", () => {
expect(formatFfmpegSeconds(1.35)).toBe("1.35");
expect(formatFfmpegSeconds(4.666666666666667)).toBe("4.666666666666667");
expect(formatFfmpegSeconds(0)).toBe("0");
});
});
describe("the audio tail probe's read interval", () => {
it("starts at a plain decimal when the duration is a hair over one second", async () => {
const probe = {
kind: "exit" as const,
code: 0,
stdout: JSON.stringify({
streams: [
{
codec_type: "audio",
codec_name: "aac",
sample_rate: "48000",
channels: 2,
start_time: "0.000000",
duration: "1.000001",
},
],
format: {
format_name: "mov,mp4,m4a,3gp,3g2,mj2",
start_time: "0.000000",
duration: "1.000001",
},
}),
};
const { spawn, calls } = createSpawnSpy([probe, { kind: "exit", code: 0, stdout: "" }]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractAudioMetadata } = await import("./ffprobe.js");
await extractAudioMetadata("/probe-tail/asset.m4a");
const intervals = calls.flatMap((call) => {
const at = call.args.indexOf("-read_intervals");
return at === -1 ? [] : [call.args[at + 1]!];
});
expect(intervals.length).toBeGreaterThan(0);
for (const interval of intervals) expect(interval.split("%")[0]).toMatch(/^\d+(\.\d+)?$/);
});
});
describe("a video whose headers state no duration", () => {
it("is measured from its packets, so a recorder's WebM or Matroska is not refused", async () => {
const dir = mkdtempSync(resolve(tmpdir(), "hf-no-duration-"));
const file = resolve(dir, "recording.mkv");
writeFileSync(file, "x");
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video", width: 32, height: 24, avg_frame_rate: "10/1" }],
format: {},
}),
},
{
kind: "exit",
code: 0,
stdout: "0.000000,0.100000\n2.800000,0.100000\n2.700000,0.100000\n",
},
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: mocked, resolvePlayableVideoDuration } =
await import("./ffprobe.js");
try {
const metadata = await mocked(file);
expect(resolvePlayableVideoDuration(metadata)).toBeCloseTo(2.9);
} finally {
rmSync(dir, { recursive: true, force: true });
vi.resetModules();
vi.doUnmock("child_process");
}
});
it("ignores the half line a long film's output is cut at, and counts a packet with no stated duration as one frame", async () => {
const file = resolve(mkdtempSync(resolve(tmpdir(), "hf-no-duration-long-")), "long.mkv");
writeFileSync(file, "x");
const packets = (n: number) =>
Array.from({ length: n }, (_, i) => `${(i / 30).toFixed(6)},N/A`).join("\n") + "\n";
// The cut must land just after a decimal point, so its leftover digits read as a huge time.
let frames = 5000;
while (packets(frames).at(-(64 * 1024) - 1) !== ".") frames++;
const { spawn } = createSpawnSpy([
{
kind: "exit",
code: 0,
stdout: JSON.stringify({
streams: [{ codec_type: "video", width: 32, height: 24, avg_frame_rate: "30/1" }],
format: {},
}),
},
{ kind: "exit", code: 0, stdout: packets(frames) },
]);
vi.resetModules();
vi.doMock("child_process", () => ({ spawn }));
const { extractMediaMetadata: mocked, resolvePlayableVideoDuration } =
await import("./ffprobe.js");
try {
expect(resolvePlayableVideoDuration(await mocked(file))).toBeCloseTo(frames / 30, 1);
} finally {
vi.resetModules();
vi.doUnmock("child_process");
}
});
});