// fallow-ignore-file code-duplication
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
statSync,
utimesSync,
writeFileSync,
} from "node:fs";
import { basename, join } from "node:path";
import { tmpdir } from "node:os";
import { spawnSync } from "node:child_process";
import {
parseVideoElements,
hasGradedCanvas,
parseImageElements,
extractAllVideoFrames,
extractVideoFramesRange,
extractionFrameCountForDuration,
createFrameLookupTable,
FrameLookupTable,
rebaseVideoToWindow,
alignClipStartToFirstOutputFrame,
resolveFrameFormat,
codecMayHaveAlpha,
decoderForCodec,
resolveVideoExtractionWindow,
resolveVideoExtractionDuration,
getFrameAtTime,
analyzeClipMediaFit,
classifyVideoExtractionError,
videoExtractionSourceLabel,
runVideoExtractionWithRetry,
VideoSourceExtractionError,
type VideoElement,
type ExtractedFrames,
type ExtractionResult,
} from "./videoFrameExtractor.js";
describe("parseVideoElements strict literal timing", () => {
it.each(["", " ", "0s", "0abc", "0px", "-1s", "Infinity", "NaN", "0x10"])(
"does not drop hand-authored data-duration=%j as an explicit zero window",
(duration) => {
expect(
parseVideoElements(
``,
),
).toHaveLength(1);
},
);
});
import {
extractFinalVideoFrameTimestamp,
extractVideoMetadata,
type VideoMetadata,
} from "../utils/ffprobe.js";
import { ffmpegStatsReader, runFfmpeg, type RunFfmpegOptions } from "../utils/runFfmpeg.js";
// Pass-through, so a test can tell whether extraction ran ffmpeg.
vi.mock("../utils/runFfmpeg.js", async (importOriginal) => {
const real = await importOriginal();
return { ...real, runFfmpeg: vi.fn(real.runFfmpeg) };
});
import { COMPLETE_SENTINEL, GC_MARKER, SCHEMA_PREFIX } from "./extractionCache.js";
import { resolveRuntimeMediaClipDuration } from "../../../core/src/runtime/media.js";
import { compileTimingAttrs, sourceTimeAt } from "@hyperframes/core";
import { RATE_RANGE } from "@hyperframes/core/audio-automation";
// ffmpeg is not preinstalled on GitHub's ubuntu-24.04 runners. The producer
// regression test at packages/producer/tests/vfr-screen-recording/ runs inside
// Dockerfile.test (which does include ffmpeg) and is the primary CI signal
// for this bug. Locally and in any CI job with ffmpeg on PATH, the tests
// below run too — they exercise the extractor in isolation against a
// synthesized VFR fixture.
const HAS_FFMPEG = spawnSync("ffmpeg", ["-version"]).status === 0;
const HAS_ZSCALE =
HAS_FFMPEG &&
/\szscale\s/.test(spawnSync("ffmpeg", ["-hide_banner", "-filters"]).stdout.toString());
const FFMPEG_ENCODERS = HAS_FFMPEG
? spawnSync("ffmpeg", ["-hide_banner", "-encoders"]).stdout.toString()
: "";
// Homebrew's ffmpeg has libsvtav1 but not libaom-av1. Either one writes an untagged AV1 stream.
const AV1_ENCODER = ["libaom-av1", "libsvtav1"].find((name) =>
new RegExp(`\\s${name}\\s`).test(FFMPEG_ENCODERS),
);
describe("resolveVideoExtractionDuration", () => {
const metadata = (
durationSeconds: number,
videoStreamDurationSeconds = durationSeconds,
): VideoMetadata => ({
durationSeconds,
videoStreamDurationSeconds,
width: 1920,
height: 1080,
fps: 30,
videoCodec: "h264",
hasAudio: false,
isVFR: false,
hasAlpha: false,
colorSpace: null,
});
const video = (overrides: Partial = {}): VideoElement => ({
id: "root-video",
src: "video.mp4",
start: 0,
end: Number.POSITIVE_INFINITY,
mediaStart: 0,
playbackRate: 1,
loop: false,
hasAudio: false,
...overrides,
});
it("caps an open 60-second root source to a two-second composition", () => {
expect(resolveVideoExtractionDuration(video(), metadata(60), 2)).toBe(2);
});
it("keeps a shorter natural source duration inside a longer composition", () => {
expect(resolveVideoExtractionDuration(video(), metadata(2), 10)).toBe(2);
});
it("falls back to container duration when stream duration is unavailable", () => {
expect(resolveVideoExtractionDuration(video(), metadata(2, 0), 10)).toBe(2);
});
it("preserves explicit bounds and loop flags while applying the timeline ceiling", () => {
const explicitLoop = video({ end: 8, loop: true });
expect(resolveVideoExtractionDuration(explicitLoop, metadata(60), 10)).toBe(8);
expect(explicitLoop.loop).toBe(true);
});
it("extracts the source span consumed by an explicit 2x timeline slot", () => {
expect(
resolveVideoExtractionWindow(
video({ end: 2, mediaStart: 1, playbackRate: 2 }),
metadata(8),
2,
),
).toMatchObject({
compositionStart: 0,
mediaStart: 1,
durationSeconds: 4,
timelineDurationSeconds: 2,
});
});
it("extracts the source span a ramped slot consumes: 2s of 1x to 3x reads 2*(3-1)/ln 3 source seconds", () => {
const rate = {
target: "rate",
points: [
{ t: 0, v: 1 },
{ t: 2, v: 3 },
],
};
expect(
resolveVideoExtractionWindow(video({ end: 2, playbackRate: rate }), metadata(8), 2),
).toMatchObject({ compositionStart: 0, mediaStart: 0, timelineDurationSeconds: 2 });
const { durationSeconds } = resolveVideoExtractionWindow(
video({ end: 2, playbackRate: rate }),
metadata(8),
2,
);
expect(durationSeconds).toBeCloseTo(3.6411, 3);
});
const RAMP = {
target: "rate",
points: [
{ t: 0, v: 1 },
{ t: 4, v: 3 },
],
};
it("starts a ramped clip that begins before the timeline at the integrated source time of the trimmed part", () => {
// geometric 1x to 3x over 4s: source(t) = 4(3^(t/4)-1)/ln 3; 1s trimmed reads 1.1508, all 4s read 7.2819
const window = resolveVideoExtractionWindow(
video({ start: -1, end: 3, playbackRate: RAMP }),
metadata(20),
3,
);
expect(window.mediaStart).toBeCloseTo(1.1508, 3);
expect(window.durationSeconds).toBeCloseTo(6.1311, 3);
});
it("rebases a ramped clip so lookup reads the same source second the untrimmed lane would", () => {
const clip = video({ start: -1, end: 3, playbackRate: RAMP });
rebaseVideoToWindow(clip, resolveVideoExtractionWindow(clip, metadata(20), 3));
// composition second 2 is 3s into the authored lane: source 4.6586
const seconds = clip.mediaStart + sourceTimeAt(clip.playbackRate ?? 1, 2 - clip.start);
expect(seconds).toBeCloseTo(4.6586, 3);
});
it("leaves media start untouched for a nested clip whose start sums to a frame boundary with float dust", () => {
// 3.3 + 1.3666666666666667 = 4.666666666666666, frame 140 at 30 fps
const clip = video({ start: 3.3 + 1.3666666666666667, end: 8, mediaStart: 1.35 });
alignClipStartToFirstOutputFrame(clip, 30);
expect(clip.mediaStart).toBe(1.35);
expect(clip.start).toBe(140 / 30);
});
it("snaps a float-noise composition start to the timeline origin so the first frame is kept", () => {
const clip = video({ start: -1, end: 8, playbackRate: 0.7 });
rebaseVideoToWindow(clip, { compositionStart: 2.2e-16, mediaStart: 0.7, durationSeconds: 5 });
expect(clip.start).toBe(0);
});
it("reports the natural timeline duration of a ramped clip through the lane", () => {
const flat = {
target: "rate",
points: [
{ t: 0, v: 2 },
{ t: 1, v: 2 },
],
};
expect(resolveVideoExtractionWindow(video({ playbackRate: flat }), metadata(4))).toMatchObject({
durationSeconds: 4,
timelineDurationSeconds: 2,
});
});
it("reports natural timeline duration after constant playback-rate retiming", () => {
expect(
resolveVideoExtractionWindow(video({ mediaStart: 1, playbackRate: 2 }), metadata(5), 10),
).toMatchObject({
compositionStart: 0,
mediaStart: 1,
durationSeconds: 4,
timelineDurationSeconds: 2,
});
});
it("trims materially negative preroll and advances the source offset", () => {
const preroll = video({ start: -60, end: 120, mediaStart: 0 });
expect(resolveVideoExtractionWindow(preroll, metadata(120), 2)).toEqual({
compositionStart: 0,
mediaStart: 60,
durationSeconds: 2,
});
expect(resolveVideoExtractionDuration(preroll, metadata(120), 2)).toBe(2);
});
it("returns an empty window for a clip entirely before composition time zero", () => {
expect(resolveVideoExtractionWindow(video({ start: -60, end: -10 }), metadata(120), 2)).toEqual(
{ compositionStart: 0, mediaStart: 60, durationSeconds: 0 },
);
});
it("preserves a short source cycle when negative preroll crosses a loop boundary", () => {
expect(
resolveVideoExtractionWindow(
video({ start: -5, end: 10, mediaStart: 0, loop: true }),
metadata(3),
2,
),
).toEqual({
compositionStart: -5,
mediaStart: 0,
durationSeconds: 3,
preserveTimelinePhase: true,
});
});
it("marks an entirely held interval for exact final-frame resolution", () => {
expect(
resolveVideoExtractionWindow(
video({ start: -5, end: 10, mediaStart: 0, loop: false }),
metadata(3),
2,
),
).toEqual({
compositionStart: -2.000001,
mediaStart: 2.999999,
durationSeconds: 0.000001,
preserveTimelineEnd: true,
ensureFinalFrame: true,
});
});
it.each([
{ loop: true, preservation: { preserveTimelinePhase: true }, label: "loop" },
{
loop: false,
preservation: { preserveTimelineEnd: true, ensureFinalFrame: true },
label: "held tail",
},
])(
"caps a finite long slot to one short source range for $label playback",
({ loop, preservation }) => {
expect(resolveVideoExtractionWindow(video({ end: 60, loop }), metadata(3), 60)).toEqual({
compositionStart: 0,
mediaStart: 0,
durationSeconds: 3,
...preservation,
});
},
);
it.each([
{ loop: true, preservation: { preserveTimelinePhase: true }, label: "loop" },
{
loop: false,
preservation: { preserveTimelineEnd: true, ensureFinalFrame: true },
label: "held tail",
},
])(
"uses the playable video-stream duration for a long-audio mux in $label playback",
({ loop, preservation }) => {
expect(resolveVideoExtractionWindow(video({ end: 60, loop }), metadata(60, 3), 60)).toEqual({
compositionStart: 0,
mediaStart: 0,
durationSeconds: 3,
...preservation,
});
},
);
it("preserves authored timing when the visible interval partially crosses a held tail", () => {
expect(
resolveVideoExtractionWindow(
video({ start: -2, end: 10, mediaStart: 0, loop: false }),
metadata(3),
2,
),
).toEqual({
compositionStart: 0,
mediaStart: 2,
durationSeconds: 1,
preserveTimelineEnd: true,
ensureFinalFrame: true,
});
});
it.each([
{ start: 0, expected: { compositionStart: 0, mediaStart: 0, durationSeconds: 3 } },
{ start: -2, expected: { compositionStart: 0, mediaStart: 2, durationSeconds: 1 } },
{ start: -5, expected: { compositionStart: 0, mediaStart: 5, durationSeconds: 0 } },
])(
"keeps an omitted-duration clip source-bounded like runtime (start=$start)",
({ start, expected }) => {
for (const loop of [false, true]) {
const parsed = parseVideoElements(
``,
)[0]!;
const planned = { ...parsed, start };
const runtimeDuration = resolveRuntimeMediaClipDuration({
isVideo: true,
sourceDuration: 3,
hostRemaining: 15 - start,
explicitDuration: null,
});
expect(runtimeDuration).toBe(3);
expect(parsed.end).toBe(Number.POSITIVE_INFINITY);
expect(resolveVideoExtractionWindow(planned, metadata(3), 15)).toEqual(expected);
}
},
);
it("bounds an entirely held long source to its final-frame sample", () => {
expect(
resolveVideoExtractionWindow(
video({ start: -600, end: 10, mediaStart: 0, loop: false }),
metadata(120),
2,
),
).toEqual({
compositionStart: -480.000001,
mediaStart: 119.999999,
durationSeconds: 0.000001,
preserveTimelineEnd: true,
ensureFinalFrame: true,
});
});
it("preserves a complete loop cycle when visibility ends exactly on a wrap boundary", () => {
expect(
resolveVideoExtractionWindow(
video({ start: -1, end: 10, mediaStart: 0, loop: true }),
metadata(3),
2,
),
).toEqual({
compositionStart: -1,
mediaStart: 0,
durationSeconds: 3,
preserveTimelinePhase: true,
});
});
it("keeps an open-ended loop source-bounded instead of inventing a longer slot", () => {
expect(resolveVideoExtractionWindow(video({ loop: true }), metadata(3), 10)).toEqual({
compositionStart: 0,
mediaStart: 0,
durationSeconds: 3,
});
});
it("never plans more extraction than the playable source range", () => {
for (const loop of [false, true]) {
for (const sourceDuration of [0.5, 3, 120]) {
for (const mediaStart of [0, sourceDuration / 3]) {
for (const start of [-600, -5, -1, 0, 2]) {
const window = resolveVideoExtractionWindow(
video({ start, end: start + 60, mediaStart, loop }),
metadata(sourceDuration),
10,
);
expect(window.durationSeconds).toBeLessThanOrEqual(sourceDuration - mediaStart);
expect(window.durationSeconds).toBeGreaterThanOrEqual(0);
}
}
}
}
});
it("rejects a media start at source EOF before planning extraction", () => {
expect(() =>
resolveVideoExtractionWindow(video({ mediaStart: 3 }), metadata(3), 10),
).toThrowError(expect.objectContaining({ kind: "media_start_out_of_range", retryable: false }));
});
it("rejects a media start at video-stream EOF even when the container continues", () => {
expect(() =>
resolveVideoExtractionWindow(video({ mediaStart: 3 }), metadata(60, 3), 10),
).toThrowError(expect.objectContaining({ kind: "media_start_out_of_range", retryable: false }));
});
it("plans a one-frame held tail when an explicit non-looping slot starts past EOF", () => {
expect(resolveVideoExtractionWindow(video({ end: 6, mediaStart: 5 }), metadata(2))).toEqual({
compositionStart: 0,
mediaStart: 1.999999,
durationSeconds: 0.000001,
preserveTimelineEnd: true,
ensureFinalFrame: true,
});
});
it("keeps the playable suffix when an explicit non-looping slot starts just inside EOF", () => {
expect(
resolveVideoExtractionWindow(video({ end: 6, mediaStart: 1.9 }), metadata(2), 6),
).toEqual({
compositionStart: 0,
mediaStart: 1.9,
durationSeconds: 0.10000000000000009,
preserveTimelineEnd: true,
ensureFinalFrame: true,
});
});
it("rejects a looping explicit slot that starts at source EOF", () => {
expect(() =>
resolveVideoExtractionWindow(video({ end: 6, mediaStart: 2, loop: true }), metadata(2), 6),
).toThrowError(expect.objectContaining({ kind: "media_start_out_of_range", retryable: false }));
});
it("rebases a loop phase when the visible window stays within one cycle", () => {
expect(
resolveVideoExtractionWindow(
video({ start: -5, end: 10, mediaStart: 0, loop: true }),
metadata(3),
0.5,
),
).toEqual({ compositionStart: 0, mediaStart: 2, durationSeconds: 0.5 });
});
it("retains legacy behavior when no timeline end is supplied", () => {
expect(resolveVideoExtractionDuration(video(), metadata(60))).toBe(60);
});
});
describe("extractionFrameCountForDuration", () => {
it("uses the same VFR ceil and CFR nearest-boundary rules as FFmpeg", () => {
expect(extractionFrameCountForDuration(0.466666, 30, true)).toBe(14);
expect(extractionFrameCountForDuration(0.466666, 30, false)).toBe(14);
expect(extractionFrameCountForDuration(0.616666, 30, true)).toBe(19);
expect(extractionFrameCountForDuration(0.616666, 30, false)).toBe(18);
});
it.each([
[0.33 - 0.03, 30, 9],
[0.29 - 0.04, 24, 6],
[0.35 - 0.05, 60, 18],
[4.03 - 3.53, 30, 15],
[4.03 - 3.78, 24, 6],
])(
"snaps floating-point integral boundaries before VFR ceil (%s seconds at %i fps)",
(duration, fps, expectedFrames) => {
expect(extractionFrameCountForDuration(duration, fps, true)).toBe(expectedFrames);
},
);
it("still ceils a genuine fractional boundary beyond floating-point noise", () => {
expect(extractionFrameCountForDuration(0.300001, 30, true)).toBe(10);
});
it("matches FFmpeg's six-digit duration parsing", () => {
expect(extractionFrameCountForDuration(0.6000009, 30, true)).toBe(18);
expect(extractionFrameCountForDuration(0.600001, 30, true)).toBe(19);
expect(extractionFrameCountForDuration(2.05, 30, false)).toBe(62);
});
it("keeps exact NTSC rationals at short CFR and VFR boundaries", () => {
expect(extractionFrameCountForDuration(0.25025, { num: 30000, den: 1001 }, false)).toBe(8);
expect(extractionFrameCountForDuration(0.125125, { num: 24000, den: 1001 }, true)).toBe(3);
expect(extractionFrameCountForDuration(0.5005, { num: 24000, den: 1001 }, true)).toBe(12);
});
it("fails closed for invalid durations and emits one frame for positive sub-frame work", () => {
expect(extractionFrameCountForDuration(Number.NaN, 30, true)).toBe(0);
expect(extractionFrameCountForDuration(1, 0, true)).toBe(0);
expect(extractionFrameCountForDuration(0, 30, true)).toBe(0);
expect(extractionFrameCountForDuration(0.001, 30, false)).toBe(1);
});
});
describe("video extraction failure taxonomy and bounded retry", () => {
it("classifies missing and transient HTTP sources without exposing retry ambiguity", () => {
expect(classifyVideoExtractionError(new Error("HTTP 404: Not Found"))).toMatchObject({
kind: "download_not_found",
retryable: false,
});
expect(classifyVideoExtractionError(new Error("HTTP 503: Service Unavailable"))).toMatchObject({
kind: "download_transient",
retryable: true,
});
});
it("retries one transient failure, cleaning partial output before the retry", async () => {
const retryDir = mkdtempSync(join(tmpdir(), "hf-extract-retry-"));
const partialPath = join(retryDir, "frame-00001.jpg");
let attempts = 0;
try {
const outcome = await runVideoExtractionWithRetry(
async () => {
attempts += 1;
if (attempts === 1) {
writeFileSync(partialPath, "partial");
throw new VideoSourceExtractionError(
"ffmpeg_timeout",
true,
"Video frame extraction timed out",
);
}
expect(existsSync(partialPath)).toBe(false);
return "frames";
},
{
maxTransientRetries: 1,
onRetry: () => {
rmSync(retryDir, { recursive: true, force: true });
mkdirSync(retryDir, { recursive: true });
},
},
);
expect(outcome).toEqual({ result: "frames", retries: 1 });
expect(attempts).toBe(2);
} finally {
rmSync(retryDir, { recursive: true, force: true });
}
});
it("does not retry deterministic or caller-aborted failures", async () => {
let deterministicAttempts = 0;
await expect(
runVideoExtractionWithRetry(async () => {
deterministicAttempts += 1;
throw new VideoSourceExtractionError(
"zero_output",
false,
"Video source produced no decodable frames",
);
}),
).rejects.toMatchObject({ kind: "zero_output", retryable: false });
expect(deterministicAttempts).toBe(1);
const controller = new AbortController();
controller.abort();
let abortedAttempts = 0;
await expect(
runVideoExtractionWithRetry(
async () => {
abortedAttempts += 1;
throw new VideoSourceExtractionError(
"download_transient",
true,
"Video source download failed transiently",
);
},
{ signal: controller.signal },
),
).rejects.toMatchObject({ kind: "cancelled", retryable: false });
expect(abortedAttempts).toBe(0);
});
it("does not retry transient extraction failures unless the caller opts in", async () => {
let attempts = 0;
await expect(
runVideoExtractionWithRetry(async () => {
attempts += 1;
throw new VideoSourceExtractionError(
"ffmpeg_timeout",
true,
"Video frame extraction timed out",
);
}),
).rejects.toMatchObject({ kind: "ffmpeg_timeout", retryable: true });
expect(attempts).toBe(1);
});
it("fails closed to zero retries for a non-finite runtime retry budget", async () => {
let attempts = 0;
await expect(
runVideoExtractionWithRetry(
async () => {
attempts += 1;
throw new VideoSourceExtractionError(
"ffmpeg_timeout",
true,
"Video frame extraction timed out",
);
},
{ maxTransientRetries: Number.NaN },
),
).rejects.toMatchObject({ kind: "ffmpeg_timeout", retryable: true });
expect(attempts).toBe(1);
});
it("names a failed clip by its project-relative file, never a host, query or absolute path", () => {
expect(videoExtractionSourceLabel("assets/clips/a.mp4", "/proj")).toBe("assets/clips/a.mp4");
expect(videoExtractionSourceLabel("/proj/assets/a.mp4?x=1", "/proj")).toBe("assets/a.mp4");
expect(videoExtractionSourceLabel("/elsewhere/private/b.mp4", "/proj")).toBe("b.mp4");
expect(videoExtractionSourceLabel("https://cdn.example/v/c%201.mp4?Signature=s", "/proj")).toBe(
"c 1.mp4",
);
expect(videoExtractionSourceLabel("HTTPS://cdn.example/v/d.mp4?Signature=s", "/proj")).toBe(
"d.mp4",
);
});
it("never prints a scheme payload, username or drive path for a source that is not a project file", () => {
expect(videoExtractionSourceLabel("file:///Users/me/private/a.mp4", "/proj")).toBe("a.mp4");
expect(videoExtractionSourceLabel("data:video/mp4;base64,AAAA", "/proj")).toBe("inline video");
expect(videoExtractionSourceLabel("blob:https://cdn.example/1f3a", "/proj")).toBe(
"inline video",
);
expect(videoExtractionSourceLabel("ftp://host.example/pub/e.mp4", "/proj")).toBe("e.mp4");
expect(videoExtractionSourceLabel("C:\\Users\\me\\private\\f.mp4", "/proj")).toBe("f.mp4");
expect(videoExtractionSourceLabel("C:\\proj\\assets\\g.mp4", "C:\\proj")).toBe("assets/g.mp4");
});
it("reports which clip failed when a source file is missing", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-extract-names-"));
try {
const result = await extractAllVideoFrames(
[
{
id: "v1",
src: "assets/missing.mp4",
start: 0,
end: 1,
mediaStart: 0,
loop: false,
hasAudio: false,
},
],
dir,
{ fps: 30, outputDir: join(dir, "out") },
);
expect(result.errors).toHaveLength(1);
expect(result.errors[0]).toMatchObject({ videoId: "v1", source: "assets/missing.mp4" });
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
// Codec-based alpha defaulting replaces tag-based detection (the
// alpha_mode/ALPHA_MODE case bug — see ffprobe.test.ts for the regression
// pin on that). The extractor uses these helpers for two decisions:
// 1. whether to force the alpha-aware decoder (libvpx-vp9 for VP9, libvpx
// for VP8)
// 2. whether to default the cached frame format to PNG (with alpha) vs JPG
// The "default to capable" trade is small file-size growth on opaque VP9
// content for correctness on alpha-having content even when the sidecar tag
// is missing or muxed with the wrong case.
describe("codec alpha capability", () => {
it("flags VP9, VP8, and ProRes as alpha-capable", () => {
expect(codecMayHaveAlpha("vp9")).toBe(true);
expect(codecMayHaveAlpha("VP9")).toBe(true);
expect(codecMayHaveAlpha("vp8")).toBe(true);
expect(codecMayHaveAlpha("prores")).toBe(true);
});
it("does not flag h264 / h265 / mpeg4 (no alpha in their bitstreams)", () => {
expect(codecMayHaveAlpha("h264")).toBe(false);
expect(codecMayHaveAlpha("h265")).toBe(false);
expect(codecMayHaveAlpha("hevc")).toBe(false);
expect(codecMayHaveAlpha("mpeg4")).toBe(false);
});
it("treats undefined / empty input as non-alpha", () => {
expect(codecMayHaveAlpha(undefined)).toBe(false);
expect(codecMayHaveAlpha("")).toBe(false);
});
it("returns the alpha-aware decoder name for VP9 and VP8", () => {
expect(decoderForCodec("vp9")).toBe("libvpx-vp9");
expect(decoderForCodec("VP9")).toBe("libvpx-vp9");
expect(decoderForCodec("vp8")).toBe("libvpx");
});
});
describe("resolveFrameFormat", () => {
function metadata(overrides: Partial = {}): VideoMetadata {
return {
durationSeconds: 1,
width: 320,
height: 180,
fps: 30,
hasAudio: false,
videoCodec: "h264",
colorSpace: {
colorTransfer: "bt709",
colorPrimaries: "bt709",
colorSpace: "bt709",
},
isVFR: false,
hasAlpha: false,
...overrides,
};
}
it("keeps opaque non-alpha sources on jpg by default", () => {
expect(resolveFrameFormat(metadata(), undefined)).toBe("jpg");
expect(resolveFrameFormat(metadata(), "auto")).toBe("jpg");
});
it("honors explicit png for opaque videos", () => {
expect(resolveFrameFormat(metadata(), "png")).toBe("png");
});
it("honors explicit jpg for opaque videos", () => {
expect(resolveFrameFormat(metadata(), "jpg")).toBe("jpg");
});
it("forces png when alpha is present or the codec can carry alpha", () => {
expect(resolveFrameFormat(metadata({ hasAlpha: true }), "jpg")).toBe("png");
expect(resolveFrameFormat(metadata({ videoCodec: "vp9" }), "jpg")).toBe("png");
});
it("keeps ProRes without an alpha plane on jpg and ProRes with one on png", () => {
expect(resolveFrameFormat(metadata({ videoCodec: "prores" }), undefined)).toBe("jpg");
expect(resolveFrameFormat(metadata({ videoCodec: "prores", hasAlpha: true }), "jpg")).toBe(
"png",
);
});
type FormatCase = Pick & {
requested: "auto" | "jpg" | "png";
};
const formatCases: FormatCase[] = ["vp9", "vp8", "h264", "prores"].flatMap((videoCodec) =>
[true, false].flatMap((hasAlpha) =>
[true, false, undefined].flatMap((alphaPlaneDecoded) =>
(["auto", "jpg", "png"] as const).map((requested) => ({
videoCodec,
hasAlpha,
alphaPlaneDecoded,
requested,
})),
),
),
);
function expectedFormat({ videoCodec, hasAlpha, alphaPlaneDecoded, requested }: FormatCase) {
const sidecar = videoCodec === "vp9" || videoCodec === "vp8";
const keepsPng = hasAlpha || (sidecar && alphaPlaneDecoded !== false);
return keepsPng || requested === "png" ? "png" : "jpg";
}
it("lets VP8/VP9 leave png only when a decode probe found no alpha plane", () => {
expect(formatCases).toHaveLength(72);
for (const { requested, ...fields } of formatCases) {
const actual = resolveFrameFormat(metadata(fields), requested);
expect(actual, JSON.stringify(fields)).toBe(expectedFormat({ requested, ...fields }));
}
expect(resolveFrameFormat(metadata({ videoCodec: "vp9", alphaPlaneDecoded: false }))).toBe(
"jpg",
);
expect(resolveFrameFormat(metadata({ videoCodec: "vp8", alphaPlaneDecoded: false }))).toBe(
"jpg",
);
});
});
describe("parseVideoElements", () => {
it("marks a graded video and image, and only those", () => {
const html = `
`;
expect(parseVideoElements(html).map(({ id, graded }) => [id, graded])).toEqual([
["g", true],
["p", undefined],
]);
expect(parseImageElements(html).map(({ id, graded }) => [id, graded])).toEqual([
["gi", true],
["pi", undefined],
]);
expect(hasGradedCanvas(html)).toBe(false);
expect(
hasGradedCanvas(``),
).toBe(true);
});
it.each([
{
label: "valueless playback-start",
attributes: 'data-playback-start data-media-start="1.5"',
expected: 1.5,
},
{
label: "empty playback-start",
attributes: 'data-playback-start="" data-media-start="1.5"',
expected: 1.5,
},
{
label: "whitespace playback-start",
attributes: 'data-playback-start=" " data-media-start="1.5"',
expected: 1.5,
},
{
label: "invalid playback-start",
attributes: 'data-playback-start="later" data-media-start="1.5"',
expected: 1.5,
},
{ label: "missing media-start", attributes: "", expected: 0 },
{ label: "invalid media-start", attributes: 'data-media-start="later"', expected: 0 },
{
label: "negative playback-start",
attributes: 'data-playback-start="-1" data-media-start="1.5"',
expected: 1.5,
},
{ label: "negative media-start", attributes: 'data-media-start="-1"', expected: 0 },
{
label: "finite playback-start",
attributes: 'data-playback-start="2.25" data-media-start="1.5"',
expected: 2.25,
},
{
label: "zero playback-start",
attributes: 'data-playback-start="0" data-media-start="1.5"',
expected: 0,
},
])("uses finite playback-start -> media-start -> 0 for $label", ({ attributes, expected }) => {
const [video] = parseVideoElements(``);
expect(video?.mediaStart).toBe(expected);
});
it("parses and normalizes constant playback rate for final rendering", () => {
const [fast, low, high, invalid] = parseVideoElements(
'' +
'' +
'' +
'',
);
expect(fast?.playbackRate).toBe(2);
expect(low?.playbackRate).toBe(RATE_RANGE.min);
expect(high?.playbackRate).toBe(RATE_RANGE.max);
expect(invalid?.playbackRate).toBe(1);
});
it("parses a rate lane from data-automation into the clip's rate", () => {
const automation = JSON.stringify({
version: 1,
lanes: [
{
target: "rate",
points: [
{ t: 0, v: 1 },
{ t: 2, v: 3 },
],
},
],
});
const [ramped] = parseVideoElements(
``,
);
expect(ramped?.playbackRate).toMatchObject({ target: "rate" });
});
it("parses videos without an id or data-start attribute", () => {
const videos = parseVideoElements('');
expect(videos).toHaveLength(1);
expect(videos[0]).toMatchObject({
id: "hf-video-0",
src: "clip.mp4",
start: 0,
end: Infinity,
mediaStart: 0,
loop: false,
hasAudio: false,
});
});
it("preserves explicit ids and derives end from data-duration", () => {
const videos = parseVideoElements(
'',
);
expect(videos).toHaveLength(1);
expect(videos[0]).toEqual({
id: "hero",
src: "clip.mp4",
start: 2,
end: 7,
mediaStart: 1.5,
playbackRate: 1,
loop: false,
hasAudio: true,
});
});
it("preserves looped timed video semantics for render frame lookup", () => {
const videos = parseVideoElements(
'',
);
expect(videos[0]).toMatchObject({
id: "hero",
start: 2,
end: 7,
loop: true,
});
});
it("resolves a relative data-start reference to another clip's end", () => {
const videos = parseVideoElements(
'' +
'',
);
const main = videos.find((v) => v.id === "main");
// intro ends at 10, so main starts at 10 and ends at 30 — not NaN.
expect(main?.start).toBe(10);
expect(main?.end).toBe(30);
});
it("still resolves relative data-start after compileTimingAttrs", () => {
const raw =
'' +
'';
const { html } = compileTimingAttrs(raw);
const main = parseVideoElements(html).find((v) => v.id === "main");
expect(main?.start).toBe(10);
expect(main?.end).toBe(30);
});
it("applies + and - offsets on a relative reference", () => {
const videos = parseVideoElements(
'' +
'' +
'',
);
expect(videos.find((v) => v.id === "gap")?.start).toBe(12);
expect(videos.find((v) => v.id === "overlap")?.start).toBe(9.5);
});
it("resolves chained references (A -> B -> C)", () => {
const videos = parseVideoElements(
'' +
'' +
'',
);
expect(videos.find((v) => v.id === "b")?.start).toBe(4);
expect(videos.find((v) => v.id === "c")?.start).toBe(7); // 4 + 3
});
it("resolves a reference to a non-video timed element (div clip)", () => {
const videos = parseVideoElements(
'' +
'',
);
expect(videos.find((v) => v.id === "clip")?.start).toBe(6);
});
it("derives a referenced clip's duration from data-end when data-duration is absent", () => {
const videos = parseVideoElements(
'' +
'',
);
// intro: start 2, end 9 -> duration 7 -> main starts at 9.
expect(videos.find((v) => v.id === "main")?.start).toBe(9);
});
it("resolves a reference inside its own composition when another composition reuses the id", () => {
const videos = parseVideoElements(
'",
);
expect(videos.find((v) => v.id === "clip")?.start).toBe(3);
});
it("falls back to 0 (never NaN) for an unknown reference target", () => {
const videos = parseVideoElements(
'',
);
const orphan = videos.find((v) => v.id === "orphan");
expect(orphan?.start).toBe(0);
expect(Number.isNaN(orphan?.start)).toBe(false);
expect(orphan?.end).toBe(5);
});
it("does not hang or NaN on a circular reference", () => {
const videos = parseVideoElements(
'' +
'',
);
for (const v of videos) {
expect(Number.isNaN(v.start)).toBe(false);
}
});
it("discovers