// 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