Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
// fallow-ignore-file code-duplication complexity
/**
* Unit tests for `services/distributed/renderChunk.ts`.
*
* The byte-identical-retry contract is the load-bearing
* test here: rendering the same `(planDir, chunkIndex)` twice must produce
* a byte-identical output file. Without this, Temporal/Step-Functions
* retries can't safely overwrite a partial chunk — and the entire
* fan-out activity has to fall back to "renderer doesn't retry".
*
* The test:
* 1. Spins a fresh planDir via `plan()` (cheap: the fixture sets
* `data-duration` so the probe stage never launches a browser).
* 2. Renders chunk 0 into two distinct temp paths via `renderChunk()`.
* 3. Asserts file bytes match exactly.
*
* Skipped (with a clear log message) when Chrome-headless-shell isn't
* available on the host — CI runs the real check inside `Dockerfile.test`.
*/
import { afterAll, beforeAll, describe, expect, it } from "bun:test";
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import {
copyFileSync,
cpSync,
createReadStream,
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
statSync,
writeFileSync,
} from "node:fs";
import { createServer } from "node:http";
import type { AddressInfo } from "node:net";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
type CaptureOptions,
extractVideoFramesRange,
VideoSourceExtractionError,
} from "@hyperframes/engine";
import { HOST_CHROME_FAILURE_PATTERNS } from "./__test_utils__/hostChromeFailures.js";
import { defaultLogger } from "../../logger.js";
import { RenderQualityError } from "../renderOrchestrator.js";
import { assemble } from "./assemble.js";
import { plan } from "./plan.js";
import { materializePlanV2Target, planV2, readPlanV2Manifest } from "./planV2.js";
import { resolvePlanAudioPath } from "./shared.js";
import {
CHUNK_INDEX_OUT_OF_RANGE,
distributedCaptureSessionDependencies,
extractDeferredVideoFramesForChunk,
MISSING_PLAN_ARTIFACT,
MISSING_RUNTIME_ENV_SNAPSHOT,
PLAN_HASH_MISMATCH,
renderChunk,
RenderChunkValidationError,
resolveChunkCaptureWorkers,
resolveLockedVp9CpuUsed,
resolvePresetForLockedEncoder,
} from "./renderChunk.js";
// Tiny fixture: 5 frames at 30fps. Captures finish in a few seconds on the
// CI host, and 5 frames is enough to stress the chunk-boundary IDR + GOP
// encoder args without grinding the test suite.
const FIXTURE_HTML = `<!doctype html>
<html>
<head><meta charset="utf-8"><title>renderChunk fixture</title></head>
<body style="margin:0;background:#000;color:#fff;font:32px sans-serif">
<div data-composition-id="root" data-no-timeline data-width="160" data-height="120" data-duration="0.16667">
<p style="padding:1rem">chunk fixture</p>
</div>
</body>
</html>`;
/** Serves one file with Range support and counts the bytes it sent. */
async function serveFileByRange(path: string) {
const size = statSync(path).size;
const served = { bytes: 0, requests: 0 };
const server = createServer((req, res) => {
served.requests++;
const match = /bytes=(\d+)-(\d*)/.exec(req.headers.range ?? "");
const start = match ? Number(match[1]) : 0;
const end = match?.[2] ? Number(match[2]) : size - 1;
res.writeHead(match ? 206 : 200, {
"Accept-Ranges": "bytes",
"Content-Length": end - start + 1,
...(match ? { "Content-Range": `bytes ${start}-${end}/${size}` } : {}),
});
const body = createReadStream(path, { start, end, highWaterMark: 16 * 1024 });
body.on("data", (chunk) => (served.bytes += chunk.length));
body.pipe(res);
res.on("close", () => body.destroy());
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
const url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/video.mp4`;
return { url, size, served, close: () => server.close() };
}
let runRoot: string;
let projectDir: string;
let planDir: string;
let hasChrome = false;
beforeAll(async () => {
runRoot = mkdtempSync(join(tmpdir(), "hf-renderchunk-test-"));
projectDir = join(runRoot, "project");
mkdirSync(projectDir, { recursive: true });
writeFileSync(join(projectDir, "index.html"), FIXTURE_HTML, "utf-8");
// Smoke-test whether chrome-headless-shell on this host can actually
// render a frame. Many dev/CI hosts ship a chrome-headless-shell whose
// GL stack can't initialize (`gl_factory.cc` errors out on
// `--use-gl=swiftshader`), which makes the BeginFrame capture loop
// hang for the full protocolTimeout. Detect that up front and soft-skip
// the byte-identical test; the Docker harness is where the determinism
// contract is exercised.
try {
const { createCaptureSession, initializeSession, closeCaptureSession } =
await import("@hyperframes/engine");
const { createFileServer } = await import("../fileServer.js");
const smokeDir = join(runRoot, "smoke");
mkdirSync(join(smokeDir, "compiled"), { recursive: true });
writeFileSync(join(smokeDir, "compiled", "index.html"), FIXTURE_HTML, "utf-8");
const fs = await createFileServer({
projectDir: join(smokeDir, "compiled"),
compiledDir: join(smokeDir, "compiled"),
port: 0,
});
try {
const framesDir = join(smokeDir, "frames");
mkdirSync(framesDir, { recursive: true });
const session = await createCaptureSession(
fs.url,
framesDir,
{
width: 160,
height: 120,
fps: { num: 30, den: 1 },
format: "jpeg",
quality: 80,
},
null,
{ browserGpuMode: "software" } as Parameters<typeof createCaptureSession>[4],
);
try {
// Wrap initializeSession in a short timeout — beginFrame failures
// hang for protocolTimeout (5 min) by default.
const initPromise = initializeSession(session);
const timeoutPromise = new Promise<never>((_, reject) =>
setTimeout(() => reject(new Error("smoke init timed out")), 15_000),
);
await Promise.race([initPromise, timeoutPromise]);
hasChrome = true;
} finally {
await closeCaptureSession(session).catch(() => {});
}
} finally {
fs.close();
}
} catch (err) {
console.warn(
"[renderChunk.test] chrome-headless-shell smoke test failed — byte-identical retry test will soft-skip. ",
"Diagnostic:",
(err instanceof Error ? err.message : String(err)).slice(0, 240),
);
hasChrome = false;
}
if (!hasChrome) return;
// Plan once for all chunk tests. The planDir is sufficiently small that
// re-creating it per test would just slow things down.
//
// Format is `png-sequence` (not `mp4`) so the chunk capture path runs in
// screenshot mode rather than BeginFrame. Most chrome-headless-shell
// builds (including the one this dev box ships) can render in
// screenshot mode without GL initialization, while BeginFrame requires
// a working SwiftShader + Vulkan stack that some hosts lack. The
// byte-identical-retry contract is the same in either capture
// mode, so the test still pins the determinism axis — and the Docker
// harness exercises both modes against a full chrome-headless-shell
// build inside `Dockerfile.test`.
planDir = join(runRoot, "plan");
mkdirSync(planDir, { recursive: true });
await plan(projectDir, { fps: 30, width: 160, height: 120, format: "png-sequence" }, planDir);
}, 30_000);
afterAll(() => {
rmSync(runRoot, { recursive: true, force: true });
});
describe("renderChunk()", () => {
// 60s ceiling absorbs Chrome cold-start + 5-frame capture + ffmpeg encode
// on slower CI workers.
const TIMEOUT_MS = 60_000;
it(
"produces a byte-identical chunk on a second invocation (byte-identical-retry contract)",
async () => {
if (!hasChrome) {
// Soft skip — Docker harness covers the real assertion.
console.warn(
"[renderChunk.test] skipping byte-identical retry test — chrome-headless-shell not available on this host",
);
return;
}
// chrome-headless-shell on some hosts cannot navigate to `chrome://gpu`
// (the URL returns an empty HTML document, and Puppeteer surfaces the
// network probe as `net::ERR_FAILED`). The byte-identical assertion
// needs a real renderChunk pass, which requires `assertSwiftShader`
// to succeed. On hosts where that probe is unsupported, we soft-skip
// and rely on the Docker harness — the same code path is exercised
// there against an image where chrome://gpu works.
const outA = join(runRoot, "chunk-a");
const outB = join(runRoot, "chunk-b");
let a, b;
try {
a = await renderChunk(planDir, 0, outA);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (HOST_CHROME_FAILURE_PATTERNS.test(message)) {
console.warn(
"[renderChunk.test] skipping byte-identical retry test — host Chrome stack can't render. ",
"Docker harness covers the determinism contract. Diagnostic:",
message.slice(0, 240),
);
return;
}
throw err;
}
b = await renderChunk(planDir, 0, outB);
// png-sequence chunks produce a directory of frames, not a single file.
expect(a.outputKind).toBe("frame-dir");
expect(b.outputKind).toBe("frame-dir");
expect(a.framesEncoded).toBeGreaterThan(0);
expect(b.framesEncoded).toBe(a.framesEncoded);
// The sha256 fingerprint must match (byte-identical-retry contract).
// For frame-dir output the fingerprint hashes the sorted list of
// `(name, sha256)` pairs, so two byte-identical chunks have the same
// fingerprint without us having to compare each PNG separately.
expect(a.sha256).toBe(b.sha256);
// Stage perf split: the timers must be populated and bounded by the
// chunk's total wall time (they partition `durationMs` alongside
// validation/file-server/hash overhead).
expect(a.planHashMs).toBeGreaterThanOrEqual(0);
expect(a.sessionBootMs).toBeGreaterThanOrEqual(0);
expect(a.captureStageMs).toBeGreaterThan(0);
expect(a.encodeStageMs).toBeGreaterThanOrEqual(0);
expect(a.workers).toBeGreaterThanOrEqual(1);
expect(["beginframe", "screenshot", "drawelement"]).toContain(a.captureMode);
expect(b.captureMode).toBe(a.captureMode);
expect(a.captureStageMs + a.encodeStageMs).toBeLessThanOrEqual(a.durationMs);
const perf = JSON.parse(readFileSync(a.perfPath, "utf-8"));
expect(perf.captureMode).toBe(a.captureMode);
for (const key of [
"planHashMs",
"sessionBootMs",
"captureStageMs",
"encodeStageMs",
"workers",
]) {
expect(typeof perf[key]).toBe("number");
}
},
TIMEOUT_MS,
);
it(
"rejects an out-of-range chunkIndex with CHUNK_INDEX_OUT_OF_RANGE",
async () => {
if (!hasChrome) return;
const out = join(runRoot, "chunk-oob");
let caught: unknown;
try {
// OOB validation runs BEFORE Chrome init, so this works regardless
// of chrome://gpu support on the host.
await renderChunk(planDir, 999, out);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(RenderChunkValidationError);
expect((caught as RenderChunkValidationError).code).toBe(CHUNK_INDEX_OUT_OF_RANGE);
expect((caught as Error).message).toContain("out of range");
},
TIMEOUT_MS,
);
it(
"rejects a planDir missing plan.json with MISSING_PLAN_ARTIFACT",
async () => {
const emptyDir = join(runRoot, "empty-plan-dir");
mkdirSync(emptyDir, { recursive: true });
const out = join(runRoot, "chunk-empty");
let caught: unknown;
try {
await renderChunk(emptyDir, 0, out);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(RenderChunkValidationError);
expect((caught as RenderChunkValidationError).code).toBe(MISSING_PLAN_ARTIFACT);
expect((caught as Error).message).toContain("planDir is missing");
},
TIMEOUT_MS,
);
it(
"rejects a planDir with a tampered planHash (PLAN_HASH_MISMATCH)",
async () => {
if (!hasChrome) return;
// Clone the existing valid planDir, then corrupt its planHash by
// editing plan.json so the on-disk fingerprint no longer matches
// the stored value.
const corruptedDir = mkdtempSync(join(runRoot, "plan-corrupted-"));
const { cpSync } = await import("node:fs");
cpSync(planDir, corruptedDir, { recursive: true });
const planJsonPath = join(corruptedDir, "plan.json");
const planJson = JSON.parse(readFileSync(planJsonPath, "utf-8")) as Record<string, unknown>;
planJson.planHash = "0".repeat(64);
writeFileSync(planJsonPath, JSON.stringify(planJson, null, 2), "utf-8");
const out = join(runRoot, "chunk-tampered");
let caught: unknown;
try {
await renderChunk(corruptedDir, 0, out);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(RenderChunkValidationError);
expect((caught as RenderChunkValidationError).code).toBe(PLAN_HASH_MISMATCH);
expect((caught as Error).message).toMatch(/fingerprint|planHash/i);
},
TIMEOUT_MS,
);
it(
"rejects a planDir whose encoder.json is missing runtimeEnv",
async () => {
if (!hasChrome) return;
const noEnvDir = mkdtempSync(join(runRoot, "plan-no-env-"));
const { cpSync } = await import("node:fs");
cpSync(planDir, noEnvDir, { recursive: true });
const encoderJsonPath = join(noEnvDir, "meta", "encoder.json");
const encoder = JSON.parse(readFileSync(encoderJsonPath, "utf-8")) as Record<string, unknown>;
delete encoder.runtimeEnv;
writeFileSync(encoderJsonPath, JSON.stringify(encoder), "utf-8");
const out = join(runRoot, "chunk-no-env");
let caught: unknown;
try {
await renderChunk(noEnvDir, 0, out);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(RenderChunkValidationError);
// Tampering the encoder.json also breaks planHash, so either code
// is acceptable — both indicate a planDir the worker correctly
// refused to render. The missing-runtimeEnv path fires when the
// encoder JSON happens to remain hash-valid (e.g. controller bug),
// the hash-mismatch path fires when it doesn't.
const code = (caught as RenderChunkValidationError).code;
expect([MISSING_RUNTIME_ENV_SNAPSHOT, PLAN_HASH_MISMATCH]).toContain(code);
},
TIMEOUT_MS,
);
});
describe("renderChunk() — variables threading", () => {
// 60s ceiling absorbs Chrome cold-start + 5-frame capture + ffmpeg encode
// on slower CI workers.
const TIMEOUT_MS = 60_000;
// Fixture whose pixels depend on `window.__hfVariables.color`. Read the
// variables on `DOMContentLoaded` and write the color onto a fullscreen
// element. Two plans with different `variables.color` MUST produce
// different chunk fingerprints — proves the controller's snapshotted
// variables reach the chunk worker's page.
const VARIABLES_FIXTURE_HTML = `<!doctype html>
<html data-composition-variables='{"color":"string"}'>
<head><meta charset="utf-8"><title>renderChunk variables fixture</title></head>
<body style="margin:0">
<div data-composition-id="root" data-no-timeline data-width="160" data-height="120" data-duration="0.16667">
<div id="paint" style="width:160px;height:120px;background:#000"></div>
</div>
<script>
(function () {
var v = (window.__hfVariables && window.__hfVariables.color) || "#000";
var el = document.getElementById("paint");
if (el) el.style.background = v;
})();
</script>
</body>
</html>`;
it(
"chunks rendered with different variables produce different output fingerprints",
async () => {
if (!hasChrome) {
// Soft skip — Docker harness covers the real assertion.
console.warn(
"[renderChunk.test] skipping variables-threading test — chrome-headless-shell not available on this host",
);
return;
}
const variablesProjectDir = join(runRoot, "project-variables");
mkdirSync(variablesProjectDir, { recursive: true });
writeFileSync(join(variablesProjectDir, "index.html"), VARIABLES_FIXTURE_HTML, "utf-8");
const planDirRed = join(runRoot, "plan-variables-red");
const planDirBlue = join(runRoot, "plan-variables-blue");
mkdirSync(planDirRed, { recursive: true });
mkdirSync(planDirBlue, { recursive: true });
const baseConfig = {
fps: 30 as const,
width: 160,
height: 120,
format: "png-sequence" as const,
};
await plan(
variablesProjectDir,
{ ...baseConfig, variables: { color: "#ff0000" } },
planDirRed,
);
await plan(
variablesProjectDir,
{ ...baseConfig, variables: { color: "#0000ff" } },
planDirBlue,
);
const outRed = join(runRoot, "chunk-variables-red");
const outBlue = join(runRoot, "chunk-variables-blue");
let red, blue;
try {
red = await renderChunk(planDirRed, 0, outRed);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (HOST_CHROME_FAILURE_PATTERNS.test(message)) {
console.warn(
"[renderChunk.test] skipping variables-threading test — host Chrome stack can't render. ",
"Docker harness covers the contract. Diagnostic:",
message.slice(0, 240),
);
return;
}
throw err;
}
blue = await renderChunk(planDirBlue, 0, outBlue);
expect(red.outputKind).toBe("frame-dir");
expect(blue.outputKind).toBe("frame-dir");
// Different variables.color → different rendered pixels → different
// fingerprint. The byte-identical-retry contract from the dedicated
// test above is what gives this assertion teeth: if variables
// weren't actually reaching the page, both chunks would hash the
// same #000 fallback.
expect(red.sha256).not.toBe(blue.sha256);
},
TIMEOUT_MS,
);
});
describe("renderChunk() — requiresWebGpu wiring", () => {
const TIMEOUT_MS = 60_000;
it(
"passes requiresWebGpu into the real CaptureOptions renderChunk() builds",
async () => {
if (!hasChrome) {
console.warn(
"[renderChunk.test] skipping requiresWebGpu wiring test — chrome-headless-shell not available on this host",
);
return;
}
const declaringDir = join(runRoot, "project-webgpu-declaring");
mkdirSync(declaringDir, { recursive: true });
writeFileSync(
join(declaringDir, "index.html"),
FIXTURE_HTML.replace(
'data-composition-id="root"',
'data-composition-id="root" data-requires-webgpu',
),
"utf-8",
);
const declaringPlanDir = join(runRoot, "plan-webgpu-declaring");
mkdirSync(declaringPlanDir, { recursive: true });
await plan(
declaringDir,
{ fps: 30, width: 160, height: 120, format: "png-sequence" },
declaringPlanDir,
);
// Spy on the real dependency seam renderChunk() calls through — this
// observes the actual CaptureOptions object it builds, not a proxy
// for it, so a regression to the wiring line fails this directly.
const original = distributedCaptureSessionDependencies.createCaptureSession;
let capturedOptions: CaptureOptions | undefined;
distributedCaptureSessionDependencies.createCaptureSession = ((...args) => {
capturedOptions = args[2];
return original(...args);
}) as typeof original;
const out = join(runRoot, "chunk-webgpu-declaring");
try {
try {
await renderChunk(declaringPlanDir, 0, out);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (!HOST_CHROME_FAILURE_PATTERNS.test(message)) throw err;
console.warn(
"[renderChunk.test] skipping requiresWebGpu wiring test — host Chrome stack can't render. Diagnostic:",
message.slice(0, 240),
);
return;
}
} finally {
distributedCaptureSessionDependencies.createCaptureSession = original;
}
expect(capturedOptions?.requiresWebGpu).toBe(true);
},
TIMEOUT_MS,
);
});
describe("renderChunk() — script failure", () => {
it("fails the chunk, as a local render fails, when the timeline script never loads", async () => {
if (!hasChrome) {
console.warn(
"[renderChunk.test] skipping script-failure test — chrome-headless-shell not available on this host",
);
return;
}
const failingDir = join(runRoot, "project-missing-script");
mkdirSync(failingDir, { recursive: true });
writeFileSync(
join(failingDir, "index.html"),
FIXTURE_HTML.replace(" data-no-timeline", "").replace(
"</body>",
'<script src="missing-timeline.js"></script>\n</body>',
),
"utf-8",
);
const failingPlanDir = join(runRoot, "plan-missing-script");
mkdirSync(failingPlanDir, { recursive: true });
await plan(
failingDir,
{ fps: 30, width: 160, height: 120, format: "png-sequence" },
failingPlanDir,
);
const error = await renderChunk(failingPlanDir, 0, join(runRoot, "chunk-missing-script")).then(
() => null,
(err: unknown) => err,
);
if (error instanceof Error && HOST_CHROME_FAILURE_PATTERNS.test(error.message)) {
console.warn(
"[renderChunk.test] skipping script-failure test — host Chrome stack can't render. Diagnostic:",
error.message.slice(0, 240),
);
return;
}
expect(error).toBeInstanceOf(RenderQualityError);
expect((error as Error).message).toContain("sub_timeline_script_failure");
}, 60_000);
});
describe("renderChunk() — a video the chunk does not show", () => {
it("renders the same without the video's file, with no media warning", async () => {
if (!hasChrome) {
console.warn(
"[renderChunk.test] skipping unshown-video test — chrome-headless-shell not available on this host",
);
return;
}
const videoDir = join(runRoot, "project-two-videos");
mkdirSync(videoDir, { recursive: true });
for (const [name, seconds] of [
["short.mp4", 2],
["long.mp4", 3],
] as const) {
const synth = spawnSync("ffmpeg", [
"-v",
"error",
"-y",
"-f",
"lavfi",
"-i",
`testsrc2=s=64x36:r=30:d=${seconds}`,
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
join(videoDir, name),
]);
if (synth.status !== 0) throw new Error(synth.stderr.toString());
}
writeFileSync(
join(videoDir, "index.html"),
// Clips over a second long, so the planner defers them to the chunks.
FIXTURE_HTML.replace('data-duration="0.16667"', 'data-duration="2.4"').replace(
"</div>",
'<video id="short" src="short.mp4" muted data-start="0" data-duration="1.2" style="position:absolute;left:0;top:0;width:64px"></video>' +
'<video id="long" src="long.mp4" muted data-start="0" data-duration="2.4" style="position:absolute;right:0;bottom:0;width:64px"></video></div>',
),
"utf-8",
);
const v2Dir = join(runRoot, "plan-two-videos");
await planV2(
videoDir,
{ fps: 30, width: 160, height: 120, format: "png-sequence", chunkSize: 36 },
v2Dir,
);
const manifest = readPlanV2Manifest(v2Dir);
expect(manifest.artifacts.find((a) => a.path === "compiled/short.mp4")?.chunks).toEqual([0]);
const without = join(runRoot, "chunk1-without-short");
const withShort = join(runRoot, "chunk1-with-short");
materializePlanV2Target(v2Dir, { role: "chunk", chunkIndex: 1 }, without);
cpSync(without, withShort, { recursive: true });
copyFileSync(join(videoDir, "short.mp4"), join(withShort, "compiled", "short.mp4"));
const warnings: unknown[] = [];
const skipped: (readonly string[] | undefined)[] = [];
const originalWarn = defaultLogger.warn;
const originalCreate = distributedCaptureSessionDependencies.createCaptureSession;
defaultLogger.warn = (message, meta) => {
warnings.push(meta);
originalWarn(message, meta);
};
distributedCaptureSessionDependencies.createCaptureSession = ((...args) => {
skipped.push(args[2].skipReadinessVideoIds);
return originalCreate(...args);
}) as typeof originalCreate;
let a, b;
try {
a = await renderChunk(without, 1, join(runRoot, "chunk1-out-without"));
b = await renderChunk(withShort, 1, join(runRoot, "chunk1-out-with"));
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (!HOST_CHROME_FAILURE_PATTERNS.test(message)) throw err;
console.warn(
"[renderChunk.test] skipping unshown-video test — host Chrome stack can't render. Diagnostic:",
message.slice(0, 240),
);
return;
} finally {
defaultLogger.warn = originalWarn;
distributedCaptureSessionDependencies.createCaptureSession = originalCreate;
}
expect(JSON.stringify(warnings)).not.toContain("media_load_failed");
// Only the unshown video is skipped; the shown one keeps today's readiness wait.
expect(new Set(skipped.map(String))).toEqual(new Set(["short"]));
expect(a.sha256).toBe(b.sha256);
// The shown video read by URL instead of from the plan renders the same chunk.
const server = await serveFileByRange(join(videoDir, "long.mp4"));
const viaUrl = join(runRoot, "chunk1-long-by-url");
try {
materializePlanV2Target(v2Dir, { role: "chunk", chunkIndex: 1 }, viaUrl, {
remoteSources: { "compiled/long.mp4": server.url },
});
expect(existsSync(join(viaUrl, "compiled", "long.mp4"))).toBe(false);
const byUrl = await renderChunk(viaUrl, 1, join(runRoot, "chunk1-out-by-url"));
expect(server.served.requests).toBeGreaterThan(0);
expect(byUrl.sha256).toBe(a.sha256);
} finally {
server.close();
}
}, 120_000);
});
describe("renderChunk() — a video shown smaller than its source", () => {
it("measures the box each video is drawn in before extracting its frames", async () => {
if (!hasChrome) {
console.warn(
"[renderChunk.test] skipping shown-size test — chrome-headless-shell not available",
);
return;
}
const projectDir = join(runRoot, "project-shown-size");
mkdirSync(projectDir, { recursive: true });
const synth = spawnSync("ffmpeg", [
...["-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=s=128x72:r=30:d=2"],
...["-c:v", "libx264", "-pix_fmt", "yuv420p", join(projectDir, "clip.mp4")],
]);
if (synth.status !== 0) throw new Error(synth.stderr.toString());
writeFileSync(
join(projectDir, "index.html"),
// Clips over a second long, so the planner defers them to the chunks.
FIXTURE_HTML.replace('data-duration="0.16667"', 'data-duration="1.2"').replace(
"</div>",
'<video id="pip" src="clip.mp4" muted data-start="0" data-duration="1.2" style="position:absolute;right:0;bottom:0;width:32px;height:18px"></video>' +
'<video id="full" src="clip.mp4" muted data-start="0" data-duration="1.2" style="position:absolute;left:0;top:0;width:128px;height:72px"></video></div>',
),
"utf-8",
);
const planDir = join(runRoot, "plan-shown-size");
await planV2(
projectDir,
{ fps: 30, width: 160, height: 120, format: "png-sequence", chunkSize: 36 },
planDir,
);
const chunkDir = join(runRoot, "chunk0-shown-size");
materializePlanV2Target(planDir, { role: "chunk", chunkIndex: 0 }, chunkDir);
let result;
try {
result = await renderChunk(chunkDir, 0, join(runRoot, "chunk0-shown-size-out"));
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (!HOST_CHROME_FAILURE_PATTERNS.test(message)) throw err;
console.warn(
"[renderChunk.test] skipping shown-size test — host Chrome stack can't render:",
message.slice(0, 240),
);
return;
}
expect(JSON.parse(readFileSync(result.perfPath, "utf-8")).videoShownBoxes).toEqual({
pip: { width: 32, height: 18 },
full: { width: 128, height: 72 },
});
}, 120_000);
});
describe("renderChunk() — a video whose frames cannot be extracted", () => {
it("fails with the extraction's own error while the capture browsers start", async () => {
if (!hasChrome) {
console.warn(
"[renderChunk.test] skipping extraction-failure test — chrome-headless-shell not available",
);
return;
}
const projectDir = join(runRoot, "project-extract-fail");
mkdirSync(projectDir, { recursive: true });
const synth = spawnSync("ffmpeg", [
...["-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=s=128x72:r=30:d=2"],
...["-c:v", "libx264", "-pix_fmt", "yuv420p", join(projectDir, "clip.mp4")],
]);
if (synth.status !== 0) throw new Error(synth.stderr.toString());
writeFileSync(
join(projectDir, "index.html"),
// A clip over a second long, so the planner defers it to the chunks.
FIXTURE_HTML.replace('data-duration="0.16667"', 'data-duration="1.2"').replace(
"</div>",
'<video id="clip" src="clip.mp4" muted data-start="0" data-duration="1.2" style="width:128px;height:72px"></video></div>',
),
"utf-8",
);
const planDir = join(runRoot, "plan-extract-fail");
await planV2(
projectDir,
{ fps: 30, width: 160, height: 120, format: "png-sequence", chunkSize: 36 },
planDir,
);
const chunkDir = join(runRoot, "chunk0-extract-fail");
// The clip is read by URL, as cloud chunks read it, from a port nothing listens on.
materializePlanV2Target(planDir, { role: "chunk", chunkIndex: 0 }, chunkDir, {
remoteSources: { "compiled/clip.mp4": "http://127.0.0.1:1/clip.mp4" },
});
let caught: unknown;
try {
await renderChunk(chunkDir, 0, join(runRoot, "chunk0-extract-fail-out"));
} catch (error) {
caught = error;
}
const message = caught instanceof Error ? caught.message : String(caught);
if (HOST_CHROME_FAILURE_PATTERNS.test(message)) {
console.warn(
"[renderChunk.test] skipping extraction-failure test — host Chrome stack can't render:",
message.slice(0, 240),
);
return;
}
// The extraction's own error, not the capture stage that waited on it.
expect(caught).toBeInstanceOf(VideoSourceExtractionError);
}, 120_000);
});
describe("renderChunk() — an alpha format at a larger output resolution", () => {
it("supersamples a transparent composition and keeps its alpha", async () => {
if (!hasChrome) {
console.warn(
"[renderChunk.test] skipping alpha supersample test — chrome-headless-shell not available",
);
return;
}
const projectDir = join(runRoot, "project-alpha-supersample");
mkdirSync(projectDir, { recursive: true });
writeFileSync(
join(projectDir, "index.html"),
`<!doctype html><html><body style="margin:0;background:transparent">
<div data-composition-id="root" data-no-timeline data-width="320" data-height="180" data-duration="0.1">
<div style="position:absolute;left:80px;top:45px;width:160px;height:90px;background:#3a7"></div>
</div></body></html>`,
"utf-8",
);
const planDir = join(runRoot, "plan-alpha-supersample");
await planV2(
projectDir,
{
fps: 30,
width: 320,
height: 180,
format: "mov",
chunkSize: 30,
outputResolution: "landscape",
},
planDir,
);
const chunkDir = join(runRoot, "chunk0-alpha-supersample");
materializePlanV2Target(planDir, { role: "chunk", chunkIndex: 0 }, chunkDir);
const out = join(runRoot, "chunk0-alpha-supersample.mov");
try {
await renderChunk(chunkDir, 0, out);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (!HOST_CHROME_FAILURE_PATTERNS.test(message)) throw err;
console.warn(
"[renderChunk.test] skipping alpha supersample test — host Chrome stack can't render:",
message.slice(0, 240),
);
return;
}
const probe = spawnSync("ffprobe", [
...["-v", "error", "-select_streams", "v:0"],
...["-show_entries", "stream=width,height,pix_fmt", "-of", "csv=p=0", "--", out],
]);
expect(probe.stdout.toString().trim()).toMatch(/^1920,1080,yuva/);
const frame = spawnSync(
"ffmpeg",
[
...["-v", "error", "-i", out, "-frames:v", "1"],
...["-vf", "format=rgba", "-f", "rawvideo", "-"],
],
{ maxBuffer: 1920 * 1080 * 4 },
).stdout;
const alphaAt = (x: number, y: number) => frame[(y * 1920 + x) * 4 + 3];
expect(alphaAt(10, 10)).toBe(0);
expect(alphaAt(960, 540)).toBe(255);
}, 120_000);
});
describe("renderChunk() — frameRange", () => {
// A box sliding across the frame, so every frame differs and a misplaced,
// dropped or repeated frame changes the assembled output.
const ANIMATED_HTML = (duration: number, audio: boolean) => `<!doctype html>
<html>
<head><meta charset="utf-8"><style>
@keyframes slide { from { transform: translateX(0px); } to { transform: translateX(120px); } }
#box { position:absolute; top:40px; width:40px; height:40px; background:#f97316;
animation: slide ${duration}s linear forwards; }
</style></head>
<body style="margin:0;background:#0f172a">
<div data-composition-id="root" data-no-timeline data-width="160" data-height="120" data-duration="${duration}">
<div id="box"></div>
${audio ? '<audio data-composition-audio src="tone.wav"></audio>' : ""}
</div>
</body>
</html>`;
function run(cmd: string, args: string[]): string {
const result = spawnSync(cmd, args, { maxBuffer: 1 << 28, encoding: "latin1" });
if (result.status !== 0) throw new Error(`${cmd} ${args.join(" ")}: ${result.stderr}`);
return result.stdout;
}
// Decoded video frame hashes in presentation order.
const frameHashes = (path: string) =>
run("ffmpeg", ["-nostdin", "-v", "error", "-i", path, "-map", "0:v", "-f", "framemd5", "-"])
.split("\n")
.filter((line) => line && !line.startsWith("#"))
.map((line) => line.split(",").at(-1)!.trim());
const pcm = (path: string) =>
run("ffmpeg", ["-nostdin", "-v", "error", "-i", path, "-map", "0:a", "-f", "s16le", "-"]);
const videoPts = (path: string) =>
run("ffprobe", [
...["-v", "error", "-select_streams", "v:0", "-show_entries", "packet=pts_time"],
...["-of", "csv=p=0", "--", path],
])
.split("\n")
.filter(Boolean)
.map((line) => Number.parseFloat(line))
.sort((x, y) => x - y);
const sha = (path: string) => createHash("sha256").update(readFileSync(path)).digest("hex");
const minPsnr = (a: string, b: string) => {
const log = spawnSync(
"ffmpeg",
[
...["-nostdin", "-i", a, "-i", b, "-lavfi"],
// Pair frames by index, not timestamp: webm's millisecond timestamps round differently.
"[0:v]setpts=N/(30*TB)[a];[1:v]setpts=N/(30*TB)[b];[a][b]psnr=stats_file=-",
...["-f", "null", "-"],
],
{ maxBuffer: 1 << 28, encoding: "latin1" },
).stdout;
const values = [...log.matchAll(/psnr_avg:(\S+)/g)].map((m) => Number(m[1]));
return Math.min(...values.map((v) => (Number.isFinite(v) ? v : 100)));
};
async function renderOrSkip<T>(label: string, render: () => Promise<T>): Promise<T | null> {
try {
return await render();
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (!HOST_CHROME_FAILURE_PATTERNS.test(message)) throw err;
console.warn(
`[renderChunk.test] skipping ${label} — host Chrome stack can't render. Diagnostic:`,
message.slice(0, 240),
);
return null;
}
}
it("renders png-sequence halves that assemble into the whole chunk's frames", async () => {
if (!hasChrome) return;
const dir = join(runRoot, "frame-range-png");
const project = join(dir, "project");
mkdirSync(project, { recursive: true });
writeFileSync(join(project, "index.html"), ANIMATED_HTML(0.3, false), "utf-8");
const planPng = join(dir, "plan");
await plan(project, { fps: 30, width: 160, height: 120, format: "png-sequence" }, planPng);
const [slice] = JSON.parse(readFileSync(join(planPng, "meta", "chunks.json"), "utf-8"));
expect(slice).toMatchObject({ startFrame: 0, endFrame: 9 });
const whole = await renderOrSkip("png frameRange test", () =>
renderChunk(planPng, 0, join(dir, "whole")),
);
if (whole === null) return;
const full = await renderChunk(planPng, 0, join(dir, "full"), {
frameRange: { startFrame: 0, endFrame: 9 },
});
const first = await renderChunk(planPng, 0, join(dir, "part-a"), {
frameRange: { startFrame: 0, endFrame: 4 },
});
const second = await renderChunk(planPng, 0, join(dir, "part-b"), {
frameRange: { startFrame: 4, endFrame: 9 },
});
// The whole slice as an explicit range is today's output, byte for byte.
expect(whole.frameRange).toEqual({ startFrame: 0, endFrame: 9 });
expect(full.sha256).toBe(whole.sha256);
expect([first.framesEncoded, second.framesEncoded]).toEqual([4, 5]);
expect(second.frameRange).toEqual({ startFrame: 4, endFrame: 9 });
expect(JSON.parse(readFileSync(second.perfPath, "utf-8"))).toMatchObject({
startFrame: 4,
endFrame: 9,
framesEncoded: 5,
});
const fromWhole = join(dir, "out-whole");
const fromParts = join(dir, "out-parts");
await assemble(planPng, [whole.outputPath], null, fromWhole);
const result = await assemble(
planPng,
[[first.outputPath, second.outputPath]],
null,
fromParts,
);
expect(result.framesEncoded).toBe(9);
const names = readdirSync(fromWhole).sort();
expect(readdirSync(fromParts).sort()).toEqual(names);
for (const name of names) {
expect(readFileSync(join(fromParts, name)).equals(readFileSync(join(fromWhole, name)))).toBe(
true,
);
}
// The animation moves, so equal frames above are not equal by accident.
expect(new Set(names.map((name) => sha(join(fromWhole, name)))).size).toBe(names.length);
}, 120_000);
// Two chunks of 9 frames; chunk 0 also renders as [0, 4) + [4, 9).
it.each([
["mp4, chunks carrying audio (stitched)", "mp4", true],
["mp4, audio muxed at assemble (joined)", "mp4", false],
["webm (joined)", "webm", false],
] as const)(
"%s: halves assemble seamlessly into the whole chunk's frames and audio",
async (label, format, chunksCarryAudio) => {
if (!hasChrome) return;
const dir = join(
runRoot,
`frame-range-${format}-${chunksCarryAudio ? "stitched" : "joined"}`,
);
const project = join(dir, "project");
mkdirSync(project, { recursive: true });
run("ffmpeg", [
...["-nostdin", "-v", "error", "-y", "-f", "lavfi"],
...["-i", "aevalsrc=0.3*sin(2*PI*440*t):s=48000:d=0.6", "-c:a", "pcm_s16le"],
join(project, "tone.wav"),
]);
writeFileSync(join(project, "index.html"), ANIMATED_HTML(0.6, true), "utf-8");
const planEnc = join(dir, "plan");
await plan(
project,
{ fps: 30, width: 160, height: 120, format, chunkSize: 9 },
planEnc,
chunksCarryAudio ? { chunksCarryAudio: true } : {},
);
expect(JSON.parse(readFileSync(join(planEnc, "meta", "chunks.json"), "utf-8"))).toHaveLength(
2,
);
const out = (name: string) => join(dir, `${name}.${format}`);
const whole0 = await renderOrSkip(label, () => renderChunk(planEnc, 0, out("whole-0")));
if (whole0 === null) return;
const whole1 = await renderChunk(planEnc, 1, out("whole-1"));
const first = await renderChunk(planEnc, 0, out("part-0a"), {
frameRange: { startFrame: 0, endFrame: 4 },
});
const second = await renderChunk(planEnc, 0, out("part-0b"), {
frameRange: { startFrame: 4, endFrame: 9 },
});
expect([first.framesEncoded, second.framesEncoded]).toEqual([4, 5]);
// Each part starts on its own keyframe, as a chunk does.
for (const part of [first, second]) {
const keyframes = run("ffprobe", [
...["-v", "error", "-select_streams", "v:0", "-show_entries", "packet=flags"],
...["-of", "csv=p=0", "--", part.outputPath],
]);
expect(keyframes.trim().split("\n")[0]).toStartWith("K");
}
const audio = chunksCarryAudio ? null : resolvePlanAudioPath(planEnc);
expect(chunksCarryAudio || audio !== null).toBe(true);
const fromWhole = out("from-whole");
const fromParts = out("from-parts");
await assemble(planEnc, [whole0.outputPath, whole1.outputPath], audio, fromWhole);
await assemble(
planEnc,
[[first.outputPath, second.outputPath], whole1.outputPath],
audio,
fromParts,
);
// Same frame count, and exactly the parts' own frames in order: nothing
// dropped, repeated or reordered at the seams.
const partFrames = [first, second, whole1].flatMap((r) => frameHashes(r.outputPath));
expect(frameHashes(fromParts)).toEqual(partFrames);
expect(frameHashes(fromParts)).toHaveLength(18);
expect(frameHashes(fromWhole)).toHaveLength(18);
// Frames keep their slot on the timeline: mp4 timestamps are exact; webm's
// millisecond timebase truncates at every join, part seams as chunk seams.
if (format === "mp4") expect(videoPts(fromParts)).toEqual(videoPts(fromWhole));
videoPts(fromParts).forEach((pts, i) => expect(Math.abs(pts - i / 30)).toBeLessThan(0.002));
// The parts are separate encodes, so compare their pixels to the whole's.
expect(minPsnr(fromParts, fromWhole)).toBeGreaterThan(35);
expect(pcm(fromParts) === pcm(fromWhole)).toBe(true);
},
180_000,
);
});
describe("resolvePresetForLockedEncoder", () => {
// Tiny fast tests for the codec-override helper. No Chrome, no ffmpeg —
// exists so a refactor that moves the override (e.g. into
// `getEncoderPreset` itself) gets caught here before the heavyweight
// Docker fixture is even run.
it("flips codec from h264 to h265 when encoder is libx265-software", () => {
const base = { preset: "medium", quality: 18, codec: "h264" as const, pixelFormat: "yuv420p" };
const out = resolvePresetForLockedEncoder(base, "libx265-software");
expect(out.codec).toBe("h265");
expect(out.preset).toBe("medium");
expect(out.quality).toBe(18);
expect(out.pixelFormat).toBe("yuv420p");
});
it("leaves the preset unchanged for libx264-software", () => {
const base = { preset: "medium", quality: 18, codec: "h264" as const, pixelFormat: "yuv420p" };
const out = resolvePresetForLockedEncoder(base, "libx264-software");
expect(out).toBe(base);
});
it("leaves the preset unchanged for prores-software", () => {
const base = {
preset: "4444",
quality: 18,
codec: "prores" as const,
pixelFormat: "yuva444p10le",
};
const out = resolvePresetForLockedEncoder(base, "prores-software");
expect(out).toBe(base);
});
it("leaves the preset unchanged for png-sequence", () => {
const base = { preset: "medium", quality: 18, codec: "h264" as const, pixelFormat: "yuv420p" };
const out = resolvePresetForLockedEncoder(base, "png-sequence");
expect(out).toBe(base);
});
});
describe("resolveChunkCaptureWorkers", () => {
it("keeps the machine-wide sizing when the runtime sets no budget", () => {
expect(resolveChunkCaptureWorkers(121, 3, undefined)).toBe(3);
});
it("raises a chunk to the runtime's budget", () => {
expect(resolveChunkCaptureWorkers(121, 3, 5)).toBe(5);
});
it("gives each browser at least 20 frames", () => {
expect(resolveChunkCaptureWorkers(121, 3, 8)).toBe(6);
expect(resolveChunkCaptureWorkers(99, 3, 5)).toBe(4);
});
it("never lowers the machine-wide sizing", () => {
expect(resolveChunkCaptureWorkers(121, 3, 1)).toBe(3);
expect(resolveChunkCaptureWorkers(30, 2, 5)).toBe(2);
});
});
describe("resolveLockedVp9CpuUsed", () => {
it("uses the locked value for new VP9 planDirs", () => {
expect(resolveLockedVp9CpuUsed({ encoder: "libvpx-vp9-software", vp9CpuUsed: 4 })).toBe(4);
});
it("preserves legacy distributed VP9 replay behavior when the field is absent", () => {
expect(resolveLockedVp9CpuUsed({ encoder: "libvpx-vp9-software" })).toBe(2);
});
it("returns undefined for non-VP9 planDirs", () => {
expect(resolveLockedVp9CpuUsed({ encoder: "libx264-software" })).toBeUndefined();
});
});
describe("extractDeferredVideoFramesForChunk", () => {
const frameSpan = (start: number, end: number) =>
Array.from({ length: end - start }, (_, i) => start + i);
const root = mkdtempSync(join(tmpdir(), "hf-deferred-chunk-"));
const planDir = join(root, "plan");
const range = {
sourcePath: "video-sources/0.mp4",
startTime: 1.5,
durationSeconds: 2.5,
format: "jpg" as const,
};
const metadata = {
durationSeconds: 4,
videoStreamDurationSeconds: 4,
videoStreamStartSeconds: 0,
width: 64,
height: 36,
fps: 30,
videoCodec: "h264",
hasAudio: false,
isVFR: false,
hasAlpha: false,
colorSpace: null,
};
const planVideos = (loop: boolean) => ({
videos: [
{ id: "clip", src: "clip.mp4", start: 0, end: 4, mediaStart: 1.5, loop, hasAudio: false },
],
extracted: [
{
videoId: "clip",
srcPath: "/planner/clip.mp4",
framePattern: "frame_%05d.jpg",
fps: 30,
totalFrames: 75,
metadata,
deferredRange: range,
},
],
});
beforeAll(() => {
mkdirSync(join(planDir, "video-sources"), { recursive: true });
const synth = spawnSync("ffmpeg", [
"-v",
"error",
"-y",
"-f",
"lavfi",
"-i",
"testsrc2=s=64x36:r=30:d=4",
"-c:v",
"libx264",
"-g",
"60",
"-pix_fmt",
"yuv420p",
join(planDir, range.sourcePath),
]);
if (synth.status !== 0) throw new Error(synth.stderr.toString());
});
afterAll(() => {
rmSync(root, { recursive: true, force: true });
});
it("extracts exactly the frames the chunk shows, identical to the planner's", async () => {
const full = await extractVideoFramesRange(
join(planDir, range.sourcePath),
"clip",
range.startTime,
range.durationSeconds,
{ fps: 30, outputDir: join(root, "full"), format: "jpg" },
);
const [chunk] = await extractDeferredVideoFramesForChunk({
planDir,
planVideos: planVideos(false),
frames: frameSpan(30, 45),
fps: { num: 30, den: 1 },
outputRoot: join(root, "chunk-1"),
cfg: {},
});
expect([...chunk!.framePaths.keys()]).toEqual(Array.from({ length: 15 }, (_, i) => 30 + i));
for (const [index, path] of chunk!.framePaths) {
expect(readFileSync(path).equals(readFileSync(full.framePaths.get(index)!))).toBe(true);
}
});
it("extracts a video's frames at the size it is shown in when given its box", async () => {
const [chunk] = await extractDeferredVideoFramesForChunk({
planDir,
planVideos: planVideos(false),
frames: frameSpan(30, 32),
fps: { num: 30, den: 1 },
outputRoot: join(root, "chunk-shown"),
cfg: {},
shownBoxes: new Map([["clip", { width: 16, height: 9 }]]),
});
const [frame] = chunk!.framePaths.values();
const size = spawnSync("ffprobe", [
"-v",
"error",
"-show_entries",
"stream=width,height",
"-of",
"csv=p=0",
"--",
frame!,
]);
expect(size.stdout.toString().trim()).toBe("16,10");
});
// Lossless keeps the file large next to what one seek reads.
const big = join(root, "big.mp4");
const synthBig = () => {
if (existsSync(big)) return;
const synth = spawnSync("ffmpeg", [
...["-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=s=640x360:r=30:d=120"],
...["-c:v", "libx264", "-preset", "ultrafast", "-qp", "0", "-g", "30", big],
]);
if (synth.status !== 0) throw new Error(synth.stderr.toString());
};
const bigVideos = () => {
const videos = planVideos(false);
const bigRange = {
...range,
sourcePath: "compiled/big.mp4",
startTime: 0,
durationSeconds: 120,
};
videos.videos[0] = { ...videos.videos[0]!, end: 120, mediaStart: 0 };
videos.extracted[0] = { ...videos.extracted[0]!, totalFrames: 3600, deferredRange: bigRange };
return videos;
};
const extract = (outputRoot: string, remoteSources?: Record<string, string>) =>
extractDeferredVideoFramesForChunk({
planDir: root,
planVideos: bigVideos(),
frames: frameSpan(1800, 1815),
fps: { num: 30, den: 1 },
outputRoot,
cfg: {},
remoteSources,
});
it("reads a source by URL in byte ranges and extracts the same frames", async () => {
synthBig();
mkdirSync(join(root, "compiled"), { recursive: true });
copyFileSync(big, join(root, "compiled", "big.mp4"));
const server = await serveFileByRange(big);
const logged: unknown[] = [];
const originalInfo = defaultLogger.info;
defaultLogger.info = (message, meta) => void logged.push({ message, ...meta });
try {
const [local] = await extract(join(root, "big-local"));
rmSync(join(root, "compiled", "big.mp4"));
const [remote] = await extract(join(root, "big-remote"), {
"compiled/big.mp4": `${server.url}?X-Amz-Signature=secret`,
});
expect(logged).toEqual([
{
message: "[renderChunk] reading video by URL",
path: "compiled/big.mp4",
url: server.url,
},
]);
expect([...remote!.framePaths.keys()]).toEqual([...local!.framePaths.keys()]);
for (const [index, path] of remote!.framePaths) {
expect(readFileSync(path).equals(readFileSync(local!.framePaths.get(index)!))).toBe(true);
}
// What it sends past the seek is socket buffering (a few MB), not the file.
expect(server.served.bytes).toBeLessThan(server.size / 3);
} finally {
defaultLogger.info = originalInfo;
server.close();
}
}, 60_000);
it("never surfaces a signed URL's query when ffmpeg fails", async () => {
synthBig();
// Echoes its arguments (long enough that the diagnostic's tail cut can land inside the URL),
// then ends on the URL the way a real read failure does.
const failingFfmpeg = join(root, "failing-ffmpeg");
writeFileSync(
failingFfmpeg,
'#!/bin/sh\necho "cannot read: $*" >&2\n' +
'for a in "$@"; do case $a in http*) echo "$a: Server returned 403 Forbidden" >&2;; esac; done\n' +
"exit 1\n",
{ mode: 0o755 },
);
const server = await serveFileByRange(big);
const originalFfmpeg = process.env.HYPERFRAMES_FFMPEG_PATH;
process.env.HYPERFRAMES_FFMPEG_PATH = failingFfmpeg;
try {
const url = `${server.url}?X-Amz-Signature=supersecret`;
const error = await extract(join(root, "big-failed"), { "compiled/big.mp4": url }).catch(
(caught: unknown) => caught,
);
expect(error).toBeInstanceOf(Error);
const { message, stack } = error as Error;
const text = JSON.stringify({ ...(error as object), message, stack });
expect(text).toContain("/video.mp4?…");
expect(text).not.toContain("supersecret");
} finally {
if (originalFfmpeg === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH;
else process.env.HYPERFRAMES_FFMPEG_PATH = originalFfmpeg;
server.close();
}
}, 60_000);
it("refuses a URL for a file no deferred video reads", async () => {
await expect(
extractDeferredVideoFramesForChunk({
planDir,
planVideos: planVideos(false),
frames: frameSpan(0, 5),
fps: { num: 30, den: 1 },
outputRoot: join(root, "chunk-stray-url"),
cfg: {},
remoteSources: { "compiled/other.mp4": "http://127.0.0.1:1/other.mp4" },
}),
).rejects.toMatchObject({ code: MISSING_PLAN_ARTIFACT });
});
it("extracts nothing for a chunk past the clip, and holds no frames", async () => {
const [chunk] = await extractDeferredVideoFramesForChunk({
planDir,
planVideos: { ...planVideos(false), videos: [{ ...planVideos(false).videos[0]!, end: 1 }] },
frames: frameSpan(60, 90),
fps: { num: 30, den: 1 },
outputRoot: join(root, "chunk-2"),
cfg: {},
});
expect(chunk!.framePaths.size).toBe(0);
});
it("wraps a looping clip back to its first frames", async () => {
const [chunk] = await extractDeferredVideoFramesForChunk({
planDir,
planVideos: planVideos(true),
frames: frameSpan(70, 80),
fps: { num: 30, den: 1 },
outputRoot: join(root, "chunk-3"),
cfg: {},
});
expect([...chunk!.framePaths.keys()].sort((a, b) => a - b)).toEqual([
0, 1, 2, 3, 4, 70, 71, 72, 73, 74,
]);
expect(readdirSync(join(root, "chunk-3", "clip"))).toHaveLength(10);
});
it("fails closed when the plan lacks the source", async () => {
const missing = { ...planVideos(false) };
missing.extracted = [
{ ...missing.extracted[0]!, deferredRange: { ...range, sourcePath: "video-sources/9.mp4" } },
];
let caught: unknown;
try {
await extractDeferredVideoFramesForChunk({
planDir,
planVideos: missing,
frames: frameSpan(0, 5),
fps: { num: 30, den: 1 },
outputRoot: join(root, "chunk-missing"),
cfg: {},
});
} catch (error) {
caught = error;
}
expect(caught).toBeInstanceOf(RenderChunkValidationError);
expect((caught as RenderChunkValidationError).code).toBe(MISSING_PLAN_ARTIFACT);
});
});