Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
// fallow-ignore-file code-duplication
/**
* Unit tests for `services/distributed/plan.ts`.
*
* Covers:
* - Golden planDir layout produced from a tiny fixture (no browser probe
* required — the fixture declares `data-duration` so the probe stage
* short-circuits).
* - planHash determinism across two `plan()` calls on the same inputs.
* - Chunking math (`resolveChunkPlan`, `buildChunkSlices`).
*
* The "no browser probe" path is deliberate: spinning Chrome inside `bun test`
* is expensive and flaky. The chunking helpers + planDir layout are tested
* with synchronous compile-only fixtures; the BeginFrame / probe path lives
* inside the regression harness (`bun run --cwd packages/producer docker:test`).
*/
import { afterAll, beforeAll, describe, expect, it, mock } from "bun:test";
import { spawnSync } from "node:child_process";
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
applyConcreteGpuScreenshotClamp,
buildChromeArgs,
FFMPEG_PATH_ENV,
getFfmpegBinary,
getFfprobeBinary,
encodeAac,
} from "@hyperframes/engine";
import { recomputePlanHashFromPlanDir } from "../render/stages/freezePlan.js";
import { defaultLogger } from "../../logger.js";
import { RenderQualityError } from "../renderOrchestrator.js";
import { CURRENT_PLAN_PROTOCOL } from "./planProtocol.js";
import {
applyDistributedAudioWarningPolicy,
buildLocalExecutionPlan,
buildPlanAudio,
buildChunkSlices,
CHUNK_EXCEEDS_WORKER_TIMEOUT,
ChunkExceedsWorkerTimeoutError,
DEFAULT_CHUNK_SIZE,
DEFAULT_MAX_PARALLEL_CHUNKS,
chunkSizingUsesFrameCost,
estimateChunkSeconds,
MIN_CHUNK_SIZE,
plan,
resolveDistributedEngineConfig,
resolveChunkPlan,
planNeedsFrameCostMeasurement,
resolveMaxParallelChunks,
} from "./plan.js";
import { buildSyntheticRenderJob } from "./shared.js";
import { assemble } from "./assemble.js";
import { constrainAacTruePeak } from "../render/audioPadTrim.js";
function ffmpegOrThrow(args: string[]): void {
const ffmpeg = spawnSync(getFfmpegBinary(), ["-nostdin", "-loglevel", "error", ...args]);
if (ffmpeg.status !== 0) throw new Error(`ffmpeg fixture failed: ${ffmpeg.stderr?.toString()}`);
}
// Composition the tests render. `data-duration="1"` keeps the probe stage's
// `needsBrowser` gate `false` so plan() completes without launching Chrome.
const FIXTURE_HTML = `<!doctype html>
<html>
<head><meta charset="utf-8"><title>plan-test fixture</title></head>
<body>
<div data-composition-id="root" data-width="320" data-height="240" data-duration="1">
<p>plan-test fixture</p>
</div>
</body>
</html>`;
let projectDir: string;
let runRoot: string;
beforeAll(() => {
runRoot = mkdtempSync(join(tmpdir(), "hf-plan-test-"));
projectDir = join(runRoot, "project");
mkdirSync(projectDir, { recursive: true });
writeFileSync(join(projectDir, "index.html"), FIXTURE_HTML, "utf-8");
});
afterAll(() => {
rmSync(runRoot, { recursive: true, force: true });
});
describe("distributed warning policy", () => {
const createJob = (strictness: "strict" | "best-effort") =>
buildSyntheticRenderJob({
fps: { num: 30, den: 1 },
format: "mp4",
quality: "high",
hdrMode: "force-sdr",
strictness,
entryFile: "index.html",
});
it("rejects distributed audio degradation in strict mode", () => {
const job = createJob("strict");
expect(() => applyDistributedAudioWarningPolicy(job, "mix failed")).toThrow(RenderQualityError);
expect(job.warnings.map((warning) => warning.code)).toEqual(["audio_processing_failed"]);
});
it("rejects distributed audio degradation in best-effort mode", () => {
const job = createJob("best-effort");
expect(() =>
applyDistributedAudioWarningPolicy(job, "mix failed", [
{
stage: "mix",
reason: "ffmpeg_unsupported",
owner: "system",
retryable: false,
detail: "Option not found",
},
]),
).toThrow(RenderQualityError);
expect(job.warnings.map((warning) => warning.code)).toEqual(["audio_processing_failed"]);
expect(job.warnings[0]?.details).toEqual(
expect.objectContaining({
failureReasons: ["ffmpeg_unsupported"],
failureStages: ["mix"],
failureOwner: "system",
retryable: false,
}),
);
});
it("only marks a multi-cause audio failure retryable when every cause is retryable", () => {
const job = createJob("best-effort");
expect(() =>
applyDistributedAudioWarningPolicy(job, "mixed failure", [
{
stage: "download",
reason: "download_failed",
owner: "system",
retryable: true,
detail: "temporary download failure",
},
{
stage: "prepare",
reason: "invalid_media",
owner: "user",
retryable: false,
detail: "invalid media",
},
]),
).toThrow(RenderQualityError);
expect(job.warnings[0]?.details).toEqual(
expect.objectContaining({
failureOwner: "system",
retryable: false,
}),
);
});
it("does not invent ownership or retryability for legacy untyped failures", () => {
const job = createJob("best-effort");
expect(() => applyDistributedAudioWarningPolicy(job, "legacy failure")).toThrow(
RenderQualityError,
);
expect(job.warnings[0]?.details?.failureOwner).toBeUndefined();
expect(job.warnings[0]?.details?.retryable).toBeUndefined();
});
});
describe("distributed synthetic render job", () => {
it("threads render variables into the plan browser probe job", () => {
const variables = {
voiceoverSrc: "assets/voiceover.wav",
narrationDurationSeconds: 56.738,
};
const job = buildSyntheticRenderJob({
fps: { num: 30, den: 1 },
format: "mp4",
quality: "high",
hdrMode: "force-sdr",
entryFile: "index.html",
variables,
});
expect(job.config.variables).toEqual(variables);
});
it("turns the page's capture motion blur off for the plan probe (R19)", () => {
const job = buildSyntheticRenderJob({
fps: { num: 30, den: 1 },
format: "mp4",
quality: "high",
hdrMode: "force-sdr",
entryFile: "index.html",
});
expect(job.config.pageMotionBlur).toBe("off");
});
it("keeps the production software-GPU launch on BeginFrame control", () => {
const cfg = resolveDistributedEngineConfig({
fps: 30,
width: 320,
height: 240,
format: "mp4",
});
const forceScreenshot = applyConcreteGpuScreenshotClamp(
cfg.forceScreenshot,
"software",
cfg,
{},
);
const captureMode = forceScreenshot ? "screenshot" : "beginframe";
const args = buildChromeArgs({ width: 320, height: 240, captureMode, platform: "linux" }, cfg);
expect(forceScreenshot).toBe(false);
expect(args).toContain("--enable-begin-frame-control");
});
});
describe("resolveMaxParallelChunks", () => {
const MP_1080P = (1920 * 1080) / 1e6;
const THIRTY_MIN_30FPS = 54000;
const LAMBDA_LIMIT = 900;
const recordingLog = () => {
const warnings: string[] = [];
return { log: { ...defaultLogger, warn: (m: string) => warnings.push(m) }, warnings };
};
it("sizes 30 min of 1080p30 so every chunk fits the Lambda limit with margin", () => {
const { log } = recordingLog();
const maxParallel = resolveMaxParallelChunks(
{ workerTimeoutSeconds: LAMBDA_LIMIT, workerConcurrency: 8 },
THIRTY_MIN_30FPS,
MP_1080P,
log,
);
const { chunkCount, effectiveChunkSize } = resolveChunkPlan(
THIRTY_MIN_30FPS,
undefined,
maxParallel,
);
expect(chunkCount).toBeGreaterThan(DEFAULT_MAX_PARALLEL_CHUNKS);
expect(estimateChunkSeconds(effectiveChunkSize, MP_1080P)).toBeLessThanOrEqual(
LAMBDA_LIMIT * 0.75,
);
// The old fixed 16 planned chunks with no headroom left under the limit.
const old = resolveChunkPlan(THIRTY_MIN_30FPS, undefined, DEFAULT_MAX_PARALLEL_CHUNKS);
expect(estimateChunkSeconds(old.effectiveChunkSize, MP_1080P)).toBeGreaterThan(
LAMBDA_LIMIT * 0.75,
);
});
it("tells the user to raise --concurrency when the fitting chunk count exceeds it", () => {
const { log, warnings } = recordingLog();
const maxParallel = resolveMaxParallelChunks(
{ workerTimeoutSeconds: LAMBDA_LIMIT, workerConcurrency: 8 },
THIRTY_MIN_30FPS,
MP_1080P,
log,
);
expect(warnings).toHaveLength(1);
expect(warnings[0]).toContain(`--concurrency ${maxParallel}`);
});
it("goes one wave wide when concurrency allows, up to the 256 ceiling", () => {
const { log, warnings } = recordingLog();
const args = [3 * THIRTY_MIN_30FPS, MP_1080P, log] as const;
expect(
resolveMaxParallelChunks(
{ workerTimeoutSeconds: LAMBDA_LIMIT, workerConcurrency: 200 },
...args,
),
).toBe(200);
expect(
resolveMaxParallelChunks(
{ workerTimeoutSeconds: LAMBDA_LIMIT, workerConcurrency: 1000 },
...args,
),
).toBe(256);
expect(warnings).toEqual([]);
});
it("keeps short renders to few chunks so per-chunk overhead does not dominate", () => {
const { log } = recordingLog();
const worker = { workerTimeoutSeconds: LAMBDA_LIMIT, workerConcurrency: 256 };
expect(resolveMaxParallelChunks(worker, 60, MP_1080P, log)).toBe(1);
expect(resolveMaxParallelChunks(worker, 300, MP_1080P, log)).toBeLessThanOrEqual(3);
expect(resolveMaxParallelChunks(worker, 3600, MP_1080P, log)).toBeLessThan(64);
});
it("explicit maxParallelChunks wins and no worker inputs keeps the old default", () => {
const worker = { workerTimeoutSeconds: LAMBDA_LIMIT, workerConcurrency: 200 };
const args = [THIRTY_MIN_30FPS, MP_1080P] as const;
expect(resolveMaxParallelChunks({ ...worker, maxParallelChunks: 4 }, ...args)).toBe(4);
expect(resolveMaxParallelChunks({}, ...args)).toBe(DEFAULT_MAX_PARALLEL_CHUNKS);
expect(resolveMaxParallelChunks({ chunkSize: 240 }, ...args)).toBe(DEFAULT_MAX_PARALLEL_CHUNKS);
});
it("caps pinned chunking at one wave across the worker concurrency", () => {
const worker = { workerTimeoutSeconds: LAMBDA_LIMIT, workerConcurrency: 900 };
const maxParallel = resolveMaxParallelChunks({ ...worker, chunkSize: 30 }, 1800, MP_1080P);
expect(resolveChunkPlan(1800, 30, maxParallel).chunkCount).toBe(60);
const args = [THIRTY_MIN_30FPS, MP_1080P] as const;
expect(resolveMaxParallelChunks({ ...worker, targetChunkFrames: 300 }, ...args)).toBe(256);
});
it("sizes chunks from a measured frame cost so expensive frames fit the limit", () => {
// 45 s of 1080x1920 at 24 fps whose frames measured ~10.5 s each (a graded video on software GL).
const frames = 45 * 24;
const mp = (1080 * 1920) / 1e6;
const worker = { workerTimeoutSeconds: LAMBDA_LIMIT, workerConcurrency: 8 };
const { log } = recordingLog();
const priced = resolveChunkPlan(
frames,
undefined,
resolveMaxParallelChunks(worker, frames, mp),
);
expect(estimateChunkSeconds(priced.effectiveChunkSize, mp, 10.5)).toBeGreaterThan(LAMBDA_LIMIT);
const measured = resolveChunkPlan(
frames,
undefined,
resolveMaxParallelChunks(worker, frames, mp, log, 10.5),
);
expect(estimateChunkSeconds(measured.effectiveChunkSize, mp, 10.5)).toBeLessThanOrEqual(
LAMBDA_LIMIT * 0.75,
);
// A cheap measured frame keeps the per-pixel plan.
expect(resolveMaxParallelChunks(worker, frames, mp, log, 0.07)).toBe(
resolveMaxParallelChunks(worker, frames, mp, log),
);
});
it("measures frame cost only for graded media and only when sizing uses it", () => {
expect(planNeedsFrameCostMeasurement('<video data-color-grading=\'{"preset":"x"}\'>')).toBe(
true,
);
expect(planNeedsFrameCostMeasurement("<video src=a.mp4>")).toBe(false);
expect(chunkSizingUsesFrameCost({ workerTimeoutSeconds: LAMBDA_LIMIT })).toBe(true);
expect(chunkSizingUsesFrameCost({ workerTimeoutSeconds: LAMBDA_LIMIT, chunkSize: 48 })).toBe(
false,
);
expect(chunkSizingUsesFrameCost({})).toBe(false);
});
it("fails fast with a typed error when even 256 chunks cannot fit the limit", () => {
const eightHours = 8 * 60 * 60 * 30;
let caught: unknown;
try {
resolveMaxParallelChunks({ workerTimeoutSeconds: LAMBDA_LIMIT }, eightHours, MP_1080P);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(ChunkExceedsWorkerTimeoutError);
expect((caught as ChunkExceedsWorkerTimeoutError).code).toBe(CHUNK_EXCEEDS_WORKER_TIMEOUT);
expect((caught as Error).message).toContain("900 s worker time limit");
// A limit shorter than one chunk's fixed overhead can never fit.
expect(() => resolveMaxParallelChunks({ workerTimeoutSeconds: 30 }, 300, MP_1080P)).toThrow(
ChunkExceedsWorkerTimeoutError,
);
});
});
describe("resolveChunkPlan", () => {
it("returns 1 chunk when totalFrames fits in configChunkSize", () => {
const result = resolveChunkPlan(60, 240, 16);
expect(result.chunkCount).toBe(1);
expect(result.effectiveChunkSize).toBeGreaterThanOrEqual(60);
});
it("caps chunkCount at maxParallelChunks for very long renders", () => {
// 54000 frames / 240 = 225 naive chunks → must cap at 16.
const result = resolveChunkPlan(54000, 240, 16);
expect(result.chunkCount).toBe(16);
// 54000 / 16 = 3375 → chunkSize at least that big so the union covers
// all frames in 16 slices.
expect(result.effectiveChunkSize).toBeGreaterThanOrEqual(Math.ceil(54000 / 16));
});
it("naive count drives chunkCount when below cap", () => {
// 600 frames / 240 = 3 naive chunks; well below the 16 cap.
const result = resolveChunkPlan(600, 240, 16);
expect(result.chunkCount).toBe(3);
expect(result.effectiveChunkSize).toBe(240);
});
it("rejects non-positive totalFrames", () => {
expect(() => resolveChunkPlan(0, 240, 16)).toThrow();
expect(() => resolveChunkPlan(-1, 240, 16)).toThrow();
expect(() => resolveChunkPlan(Number.NaN, 240, 16)).toThrow();
});
it("rejects non-positive configChunkSize / maxParallelChunks", () => {
expect(() => resolveChunkPlan(60, 0, 16)).toThrow();
expect(() => resolveChunkPlan(60, 240, 0)).toThrow();
});
it("rejects non-integer inputs (would produce fractional endFrames)", () => {
expect(() => resolveChunkPlan(10.5, 240, 16)).toThrow(/positive integer/);
expect(() => resolveChunkPlan(60, 240.5, 16)).toThrow(/positive integer/);
expect(() => resolveChunkPlan(60, 240, 16.5)).toThrow(/positive integer/);
expect(() => resolveChunkPlan(60, 240, Number.POSITIVE_INFINITY)).toThrow(/positive integer/);
});
// ── Auto-size when configChunkSize is undefined ───────────────────────
// The auto-sizer picks `max(MIN_CHUNK_SIZE, ceil(totalFrames /
// maxParallelChunks))` whenever the caller leaves `chunkSize` undefined,
// honoring `maxParallelChunks` instead of clamping at a 240-frame default.
it("explicit chunkSize wins: 660 frames + chunkSize=240 + maxParallelChunks=16 → 3 chunks", () => {
// Regression guard for the "explicit number still works" half of the
// contract — passing 240 explicitly must not get auto-sized.
const result = resolveChunkPlan(660, 240, 16);
expect(result.chunkCount).toBe(3);
expect(result.effectiveChunkSize).toBe(240);
});
it("auto-sizes when chunkSize=undefined: 660 frames + maxParallelChunks=16 → 16 chunks", () => {
// ceil(660 / 16) = 42; max(MIN_CHUNK_SIZE=10, 42) = 42. naiveCount =
// ceil(660 / 42) = 16, which lands exactly at the cap.
const result = resolveChunkPlan(660, undefined, 16);
expect(result.chunkCount).toBe(16);
expect(result.effectiveChunkSize).toBe(42);
});
it("auto-size floor: tiny renders cap at MIN_CHUNK_SIZE rather than fragmenting infinitely", () => {
// 50 frames / 16 workers naively gives a 4-frame chunk size, which
// would produce 13 chunks of 4 frames each — per-chunk fixed overhead
// dwarfs the parallelism gain. The MIN_CHUNK_SIZE=10 floor pins
// chunkSize at 10, producing ceil(50/10) = 5 chunks instead.
const result = resolveChunkPlan(50, undefined, 16);
expect(result.chunkCount).toBe(5);
expect(result.effectiveChunkSize).toBe(MIN_CHUNK_SIZE);
});
it("tightens chunkCount so an explicit small chunkSize leaves no empty trailing slice", () => {
// 121 frames, chunkSize=10, maxParallelChunks=12: ceil(121/10)=13 naive →
// capped at 12, but effectiveChunkSize rounds up to ceil(121/12)=11. Eleven
// 11-frame chunks already cover [0,121), so a 12th would be the empty slice
// [121,121) that renderChunk rejects (framesInChunk <= 0). chunkCount must
// tighten to 11.
const result = resolveChunkPlan(121, 10, 12);
expect(result.effectiveChunkSize).toBe(11);
expect(result.chunkCount).toBe(11);
const slices = buildChunkSlices(121, result.chunkCount, result.effectiveChunkSize);
expect(slices).toHaveLength(11);
expect(slices[slices.length - 1]).toEqual({ index: 10, startFrame: 110, endFrame: 121 });
});
it("never emits an empty or inverted slice across a grid of explicit chunk sizes", () => {
for (const totalFrames of [37, 50, 121, 333, 1000, 4001]) {
for (const maxParallel of [2, 4, 12, 16, 40]) {
for (const chunkSize of [10, 11, 15, 24, 100]) {
const { chunkCount, effectiveChunkSize } = resolveChunkPlan(
totalFrames,
chunkSize,
maxParallel,
);
expect(chunkCount).toBeLessThanOrEqual(maxParallel);
const slices = buildChunkSlices(totalFrames, chunkCount, effectiveChunkSize);
let cursor = 0;
for (const s of slices) {
expect(s.startFrame).toBe(cursor); // contiguous from 0
expect(s.endFrame).toBeGreaterThan(s.startFrame); // non-empty
cursor = s.endFrame;
}
expect(cursor).toBe(totalFrames); // union is exactly [0, totalFrames)
}
}
}
});
// ── targetChunkFrames (optional per-chunk frame ceiling) ──
it("targetChunkFrames omitted is a no-op: identical to the 3-arg auto-sized result", () => {
// The default path must be byte-identical whether the 4th arg is absent or
// explicitly undefined.
for (const totalFrames of [50, 660, 1466, 54000]) {
for (const maxParallel of [8, 16, 64]) {
const base = resolveChunkPlan(totalFrames, undefined, maxParallel);
const withUndef = resolveChunkPlan(totalFrames, undefined, maxParallel, undefined);
expect(withUndef).toEqual(base);
}
}
});
it("targetChunkFrames collapses a short video to fewer chunks than the parallelism cap", () => {
// 1466 frames, target 300, cap 16: ceil(1466/300)=5 chunks (not 16), each
// ~293 frames. Fewer chunks → less per-chunk fixed overhead.
const result = resolveChunkPlan(1466, undefined, 16, 300);
expect(result.chunkCount).toBe(5);
expect(result.effectiveChunkSize).toBeLessThanOrEqual(300);
});
it("targetChunkFrames bounds a long video's per-chunk frames, adding chunks up to the cap", () => {
// 54000 frames (30 min @30fps), target 1600, cap 64: ceil(54000/1600)=34
// chunks, each <= 1600 frames so per-chunk render time stays under budget.
const result = resolveChunkPlan(54000, undefined, 64, 1600);
expect(result.chunkCount).toBe(34);
expect(result.effectiveChunkSize).toBeLessThanOrEqual(1600);
});
it("targetChunkFrames is clamped by maxParallelChunks: an extreme length stays at the cap (still over budget)", () => {
// 216000 frames (2 h), target 1600, cap 64: needs 135 chunks but clamps to
// 64; per-chunk frames then exceed the target — the genuine tier ceiling.
const result = resolveChunkPlan(216000, undefined, 64, 1600);
expect(result.chunkCount).toBe(64);
expect(result.effectiveChunkSize).toBeGreaterThan(1600);
});
it("explicit chunkSize wins over targetChunkFrames (targetChunkFrames is a no-op)", () => {
const withTarget = resolveChunkPlan(54000, 240, 64, 1600);
const chunkSizeOnly = resolveChunkPlan(54000, 240, 64);
expect(withTarget).toEqual(chunkSizeOnly);
});
it("rejects a non-positive or non-integer targetChunkFrames", () => {
expect(() => resolveChunkPlan(1466, undefined, 16, 0)).toThrow(/positive integer/);
expect(() => resolveChunkPlan(1466, undefined, 16, -100)).toThrow(/positive integer/);
expect(() => resolveChunkPlan(1466, undefined, 16, 300.5)).toThrow(/positive integer/);
});
it("never emits an empty or inverted slice across a grid of targetChunkFrames", () => {
for (const totalFrames of [37, 660, 1466, 12793, 54000]) {
for (const maxParallel of [8, 16, 64]) {
for (const target of [100, 300, 1600]) {
const { chunkCount, effectiveChunkSize } = resolveChunkPlan(
totalFrames,
undefined,
maxParallel,
target,
);
expect(chunkCount).toBeGreaterThanOrEqual(1);
expect(chunkCount).toBeLessThanOrEqual(maxParallel);
const slices = buildChunkSlices(totalFrames, chunkCount, effectiveChunkSize);
let cursor = 0;
for (const s of slices) {
expect(s.startFrame).toBe(cursor);
expect(s.endFrame).toBeGreaterThan(s.startFrame);
cursor = s.endFrame;
}
expect(cursor).toBe(totalFrames);
}
}
}
});
});
describe("plan() and page motion blur (R19)", () => {
const planCaptureMode = async (html: string, name: string) => {
const dir = join(runRoot, name);
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, "index.html"), html, "utf-8");
const planDir = join(runRoot, `${name}-plan`);
await plan(dir, { fps: 30, width: 320, height: 240, format: "mp4" }, planDir);
const meta = JSON.parse(readFileSync(join(planDir, "meta", "encoder.json"), "utf-8"));
return { captureMode: meta.captureMode ?? null, forceScreenshot: meta.forceScreenshot ?? null };
};
it("does not route a data-motion-blur composition through screenshot capture", async () => {
const blur = FIXTURE_HTML.replace(
'data-composition-id="root"',
'data-composition-id="root" data-motion-blur="on"',
);
const plain = await planCaptureMode(FIXTURE_HTML, "blur-plain");
const blurred = await planCaptureMode(blur, "blur-on");
expect(blurred).toEqual(plain);
}, 30_000);
});
describe("buildChunkSlices", () => {
it("produces consecutive non-overlapping ranges covering all frames", () => {
const slices = buildChunkSlices(700, 3, 240);
expect(slices).toHaveLength(3);
expect(slices[0]).toEqual({ index: 0, startFrame: 0, endFrame: 240 });
expect(slices[1]).toEqual({ index: 1, startFrame: 240, endFrame: 480 });
// Last chunk absorbs the remainder so endFrame === totalFrames exactly.
expect(slices[2]).toEqual({ index: 2, startFrame: 480, endFrame: 700 });
});
it("handles a single-chunk render", () => {
const slices = buildChunkSlices(50, 1, 240);
expect(slices).toHaveLength(1);
expect(slices[0]).toEqual({ index: 0, startFrame: 0, endFrame: 50 });
});
});
describe("plan() defaults", () => {
it("exports the documented chunking defaults", () => {
expect(DEFAULT_CHUNK_SIZE).toBe(240);
expect(DEFAULT_MAX_PARALLEL_CHUNKS).toBe(16);
expect(MIN_CHUNK_SIZE).toBe(10);
});
it("sizes chunks from the worker inputs the adapter passes", async () => {
const config = { fps: 30, width: 320, height: 240, format: "mp4" } as const;
const fixed = await plan(projectDir, config, join(runRoot, "plan-fixed-16"));
const sized = await plan(
projectDir,
{ ...config, workerTimeoutSeconds: 900, workerConcurrency: 8 },
join(runRoot, "plan-worker-sized"),
);
expect(fixed.chunkCount).toBe(3);
expect(sized.chunkCount).toBe(1);
}, 30_000);
it("splits graded media into more chunks from its measured frame cost", async () => {
const measuredFor: string[] = [];
mock.module("./planFrameCost.js", () => ({
measurePlanSecondsPerFrame: async (input: { html: string }) => {
measuredFor.push(input.html);
return 10;
},
}));
const graded = join(runRoot, "project-graded");
mkdirSync(graded, { recursive: true });
writeFileSync(
join(graded, "index.html"),
FIXTURE_HTML.replace("<p>", `<p data-color-grading='{"exposure":0.2}'>`),
"utf-8",
);
const config = {
fps: 30,
width: 320,
height: 240,
format: "mp4",
workerTimeoutSeconds: 900,
workerConcurrency: 8,
} as const;
const cheap = await plan(projectDir, config, join(runRoot, "plan-cheap"));
expect(measuredFor).toHaveLength(0);
const costly = await plan(graded, config, join(runRoot, "plan-graded"));
expect(measuredFor).toHaveLength(1);
expect(cheap.chunkCount).toBe(1);
// 30 frames at 10 s each split as far as the 10-frame chunk floor allows.
expect(costly.chunkCount).toBe(3);
}, 30_000);
it("rejects at plan time when no chunk can finish inside the worker limit", async () => {
await expect(
plan(
projectDir,
{ fps: 30, width: 320, height: 240, format: "mp4", workerTimeoutSeconds: 30 },
join(runRoot, "plan-too-slow"),
),
).rejects.toBeInstanceOf(ChunkExceedsWorkerTimeoutError);
}, 30_000);
});
describe("plan() — golden planDir + planHash determinism", () => {
// Each `plan()` call is reasonably expensive (compile pass parses + inlines
// the HTML), so we run it once for the layout assertions and once more for
// the determinism assertion. The 30s timeout absorbs cold-start font /
// runtime resolution variance on the CI host.
const TIMEOUT_MS = 30_000;
it(
"fails closed when an open-ended distributed video source cannot be extracted",
async () => {
const brokenProjectDir = join(runRoot, "broken-video-project");
const brokenPlanDir = join(runRoot, "broken-video-plan");
mkdirSync(brokenProjectDir, { recursive: true });
mkdirSync(brokenPlanDir, { recursive: true });
writeFileSync(
join(brokenProjectDir, "index.html"),
`<!doctype html>
<div data-composition-id="root" data-width="320" data-height="240" data-duration="1">
<video id="hero" src="missing.mp4" data-start="0"></video>
</div>`,
);
let caught: unknown;
try {
await plan(
brokenProjectDir,
{ fps: 30, width: 320, height: 240, format: "mp4", chunkSize: 240 },
brokenPlanDir,
);
} catch (err) {
caught = err;
}
expect(caught).toHaveProperty("name", "VideoExtractionStageError");
expect(caught).toHaveProperty("code", "VIDEO_SOURCE_UNRENDERABLE");
expect(caught).toHaveProperty("retryable", false);
expect(existsSync(join(brokenPlanDir, "meta", "videos.json"))).toBe(false);
},
TIMEOUT_MS,
);
it(
"maps an open-ended remote video HTTP 404 to a terminal source error",
async () => {
const brokenProjectDir = join(runRoot, "remote-404-video-project");
const brokenPlanDir = join(runRoot, "remote-404-video-plan");
mkdirSync(brokenProjectDir, { recursive: true });
mkdirSync(brokenPlanDir, { recursive: true });
writeFileSync(
join(brokenProjectDir, "index.html"),
`<!doctype html>
<div data-composition-id="root" data-width="320" data-height="240" data-duration="1">
<video id="hero" src="https://cdn.example/missing.mp4" data-start="0"></video>
</div>`,
);
const originalFetch = globalThis.fetch;
let fetchCalls = 0;
globalThis.fetch = (async () => {
fetchCalls += 1;
return new Response(null, { status: 404, statusText: "Not Found" });
}) as typeof fetch;
let caught: unknown;
try {
await plan(
brokenProjectDir,
{ fps: 30, width: 320, height: 240, format: "mp4", chunkSize: 240 },
brokenPlanDir,
);
} catch (err) {
caught = err;
} finally {
globalThis.fetch = originalFetch;
}
expect(fetchCalls).toBeGreaterThan(0);
expect(caught).toHaveProperty("name", "VideoExtractionStageError");
expect(caught).toHaveProperty("code", "VIDEO_SOURCE_UNRENDERABLE");
expect(caught).toHaveProperty("retryable", false);
expect(existsSync(join(brokenPlanDir, "meta", "videos.json"))).toBe(false);
},
TIMEOUT_MS,
);
it(
"produces the documented planDir layout",
async () => {
const planDir = join(runRoot, "plan-layout");
mkdirSync(planDir, { recursive: true });
// Pin chunkSize=240 so this fixture exercises the single-chunk path
// (totalFrames=30 → ceil(30/240)=1 chunk). The auto-sized variant
// (chunkSize=undefined) is exercised by the dedicated test below.
const result = await plan(
projectDir,
{ fps: 30, width: 320, height: 240, format: "mp4", chunkSize: 240 },
planDir,
);
// planDir directory layout
expect(existsSync(join(planDir, "plan.json"))).toBe(true);
expect(existsSync(join(planDir, "compiled", "index.html"))).toBe(true);
expect(existsSync(join(planDir, "video-frames"))).toBe(true);
// No audio in the fixture — audio.m4a must NOT exist.
expect(existsSync(join(planDir, "audio.m4a"))).toBe(false);
expect(existsSync(join(planDir, "meta", "composition.json"))).toBe(true);
expect(existsSync(join(planDir, "meta", "encoder.json"))).toBe(true);
expect(existsSync(join(planDir, "meta", "chunks.json"))).toBe(true);
// The temporary work tree must be cleaned up.
expect(existsSync(join(planDir, ".plan-work"))).toBe(false);
// ── PlanResult contract ─────────────────────────────────────────────
expect(result.planDir).toBe(planDir);
expect(result.planProtocol).toEqual(CURRENT_PLAN_PROTOCOL);
expect(result.planHash).toMatch(/^[0-9a-f]{64}$/);
expect(result.chunkCount).toBe(1);
expect(result.totalFrames).toBe(30); // 1s @ 30fps
expect(result.width).toBe(320);
expect(result.height).toBe(240);
expect(result.format).toBe("mp4");
expect(result.ffmpegVersion).toMatch(/ffmpeg/i);
expect(result.producerVersion).toMatch(/^\d+\.\d+\.\d+/);
// ── chunks.json shape ───────────────────────────────────────────────
const chunks = JSON.parse(
readFileSync(join(planDir, "meta", "chunks.json"), "utf-8"),
) as Array<{ index: number; startFrame: number; endFrame: number }>;
expect(chunks).toHaveLength(result.chunkCount);
// Slices must cover [0, totalFrames) with no gaps.
let cursor = 0;
for (const chunk of chunks) {
expect(chunk.startFrame).toBe(cursor);
cursor = chunk.endFrame;
}
expect(cursor).toBe(result.totalFrames);
// ── plan.json shape ─────────────────────────────────────────────────
const planJson = JSON.parse(readFileSync(join(planDir, "plan.json"), "utf-8")) as Record<
string,
unknown
>;
expect(planJson.planHash).toBe(result.planHash);
expect(planJson.protocol).toEqual(CURRENT_PLAN_PROTOCOL);
expect(planJson.hasAudio).toBe(false);
expect(planJson.totalFrames).toBe(result.totalFrames);
},
TIMEOUT_MS,
);
it(
"auto-sizes chunkSize end-to-end when caller omits it",
async () => {
// Integration check that the auto-sizer wired through plan() actually
// produces multi-chunk output for the same fixture that single-chunks
// when chunkSize is pinned. With totalFrames=30 and the default
// maxParallelChunks=16, the auto-sizer picks
// max(MIN_CHUNK_SIZE=10, ceil(30/16)=2) = 10 → ceil(30/10) = 3 chunks.
const planDir = join(runRoot, "plan-autosized");
mkdirSync(planDir, { recursive: true });
const result = await plan(
projectDir,
{ fps: 30, width: 320, height: 240, format: "mp4" },
planDir,
);
expect(result.chunkCount).toBe(3);
const chunks = JSON.parse(
readFileSync(join(planDir, "meta", "chunks.json"), "utf-8"),
) as Array<{ index: number; startFrame: number; endFrame: number }>;
expect(chunks).toHaveLength(3);
// Encoder gopSize must follow the auto-sized chunk so chunk-boundary
// IDR keyframes still land at frame 0 of each chunk.
const encoder = JSON.parse(
readFileSync(join(planDir, "meta", "encoder.json"), "utf-8"),
) as Record<string, unknown>;
expect(encoder.gopSize).toBe(10);
expect(encoder.chunkSize).toBe(10);
},
TIMEOUT_MS,
);
it(
"shares one byte-identical execution plan between the builder and legacy v1 wrapper",
async () => {
const planDirA = join(runRoot, "plan-determinism-a");
const planDirB = join(runRoot, "plan-determinism-b");
mkdirSync(planDirA, { recursive: true });
mkdirSync(planDirB, { recursive: true });
const config = { fps: 30 as const, width: 320, height: 240, format: "mp4" as const };
const a = await buildLocalExecutionPlan(projectDir, config, planDirA);
const b = await plan(projectDir, config, planDirB);
expect(a.executionPlanDir).toBe(planDirA);
expect(a.executionPlanHash).toBe(b.planHash);
expect(a.chunkCount).toBe(b.chunkCount);
expect(a.totalFrames).toBe(b.totalFrames);
expect(Object.keys(b)).toEqual([
"planDir",
"planProtocol",
"planHash",
"chunkCount",
"totalFrames",
"fps",
"width",
"height",
"format",
"ffmpegVersion",
"producerVersion",
]);
// Encoder JSON must be byte-identical — its bytes feed planHash, so any
// drift here would silently change the hash framing.
const encoderA = readFileSync(join(planDirA, "meta", "encoder.json"));
const encoderB = readFileSync(join(planDirB, "meta", "encoder.json"));
expect(encoderA.equals(encoderB)).toBe(true);
},
TIMEOUT_MS,
);
it(
"plan.json.planHash matches recomputePlanHashFromPlanDir(planDir) on the same disk",
async () => {
// Regression guard for a real-world bug observed on audio-bearing
// fixtures: plan() left a temporary `.plan-work/` subtree inside
// planDir while freezePlan walked it, so the hash baked into
// plan.json included artifacts the chunk worker would never see.
// The chunk worker's `recomputePlanHashFromPlanDir` walk then
// returned a different hash, tripping PLAN_HASH_MISMATCH at the
// first chunk invocation.
//
// This test verifies that the hash plan() writes matches the hash
// recomputed from the on-disk planDir contents — i.e. the chunk
// worker's view. Holds for any plan, audio or not.
const planDir = join(runRoot, "plan-hash-recompute");
mkdirSync(planDir, { recursive: true });
const result = await plan(
projectDir,
{ fps: 30, width: 320, height: 240, format: "mp4" },
planDir,
);
const recomputed = recomputePlanHashFromPlanDir(planDir);
expect(recomputed).toBe(result.planHash);
const planJson = JSON.parse(readFileSync(join(planDir, "plan.json"), "utf-8")) as {
planHash: string;
protocol?: unknown;
};
expect(planJson.planHash).toBe(result.planHash);
expect(planJson.protocol).toEqual(CURRENT_PLAN_PROTOCOL);
delete planJson.protocol;
writeFileSync(join(planDir, "plan.json"), `${JSON.stringify(planJson, null, 2)}\n`, "utf-8");
expect(recomputePlanHashFromPlanDir(planDir)).toBe(result.planHash);
planJson.protocol = CURRENT_PLAN_PROTOCOL;
writeFileSync(join(planDir, "plan.json"), `${JSON.stringify(planJson, null, 2)}\n`, "utf-8");
expect(recomputePlanHashFromPlanDir(planDir)).toBe(result.planHash);
},
TIMEOUT_MS,
);
// Audio-bearing variant of the planHash recompute test. The pre-fix bug
// surfaced because `runAudioStage` downloads/mixes source audio into
// `<planDir>/.plan-work/`, and `freezePlan` walked that subtree before
// plan.ts cleaned it up. A composition without `<audio>` short-circuits
// the audio stage and never materialises `.plan-work/downloads/`, so
// the no-audio test above would pass even on the broken code. This
// variant generates a 1s silent wav via `ffmpeg`, references it from
// the composition, and runs plan() — exercising the audio-mix path
// that produced the original bug.
const HAS_FFMPEG = spawnSync(getFfmpegBinary(), ["-version"]).status === 0;
it.skipIf(!HAS_FFMPEG)(
"plan.json.planHash matches recompute on an audio-bearing composition",
async () => {
const audioProjectDir = join(runRoot, "project-with-audio");
mkdirSync(audioProjectDir, { recursive: true });
// Generate a 1s mono silent wav. PCM keeps the file tiny without
// pulling in an audio asset fixture.
const audioPath = join(audioProjectDir, "silence.wav");
ffmpegOrThrow([
"-f",
"lavfi",
"-i",
"anullsrc=channel_layout=mono:sample_rate=44100",
"-t",
"1",
"-c:a",
"pcm_s16le",
audioPath,
]);
writeFileSync(
join(audioProjectDir, "index.html"),
`<!doctype html>
<html><head><meta charset="utf-8"></head><body>
<div data-composition-id="root" data-width="320" data-height="240" data-duration="1">
<audio data-composition-audio src="silence.wav"></audio>
<p>audio-bearing fixture</p>
</div>
</body></html>`,
"utf-8",
);
const planDir = join(runRoot, "plan-hash-recompute-audio");
mkdirSync(planDir, { recursive: true });
const result = await plan(
audioProjectDir,
{ fps: 30, width: 320, height: 240, format: "mp4" },
planDir,
);
const recomputed = recomputePlanHashFromPlanDir(planDir);
// This assertion fails on the pre-fix code: freezePlan saw
// `.plan-work/downloads/` (or whatever the audio stage leaves
// behind) inside planDir, baked it into plan.json's planHash,
// and then plan.ts rm'd it — so recompute walks a different
// file set than freezePlan did.
expect(recomputed).toBe(result.planHash);
// Verify the audio stage actually fired (otherwise the test
// pins the wrong path — the same false-pass mode as the
// no-audio variant above).
expect(existsSync(join(planDir, "audio.m4a"))).toBe(true);
},
TIMEOUT_MS,
);
it.skipIf(!HAS_FFMPEG)(
"plans a video-bearing project to the same planHash from different plan folders",
async () => {
const videoProjectDir = join(runRoot, "project-with-video");
mkdirSync(videoProjectDir, { recursive: true });
ffmpegOrThrow([
"-f",
"lavfi",
"-i",
"testsrc=size=320x240:rate=30:duration=1",
"-pix_fmt",
"yuv420p",
"-c:v",
"libx264",
join(videoProjectDir, "clip.mp4"),
]);
writeFileSync(
join(videoProjectDir, "index.html"),
`<!doctype html>
<div data-composition-id="root" data-width="320" data-height="240" data-duration="1">
<video id="clip" src="clip.mp4" data-start="0" muted></video>
</div>`,
"utf-8",
);
const config = { fps: 30 as const, width: 320, height: 240, format: "mp4" as const };
const dirA = join(runRoot, "plan-video-a");
const dirB = join(runRoot, "nested", "plan-video-b");
for (const dir of [dirA, dirB]) mkdirSync(dir, { recursive: true });
const a = await plan(videoProjectDir, config, dirA);
const b = await plan(videoProjectDir, config, dirB);
expect(a.planHash).toBe(b.planHash);
const videosJson = (dir: string) => readFileSync(join(dir, "meta", "videos.json"), "utf-8");
expect(videosJson(dirB)).toBe(videosJson(dirA));
expect(JSON.parse(videosJson(dirA)).extracted[0].srcPath).toBe("compiled/clip.mp4");
},
TIMEOUT_MS,
);
});
describe.skipIf(spawnSync(getFfmpegBinary(), ["-version"]).status !== 0)(
"stitched mp4 plans",
() => {
function audioProject(name: string, amplitude = 0.99, duration = 1): string {
const dir = join(runRoot, name);
mkdirSync(dir, { recursive: true });
const tone = spawnSync(getFfmpegBinary(), [
"-nostdin",
"-v",
"error",
"-f",
"lavfi",
"-i",
`aevalsrc=${amplitude}*sin(2*PI*440*t):s=48000:d=0.6`,
"-c:a",
"pcm_s16le",
join(dir, "tone.wav"),
]);
if (tone.status !== 0) throw new Error(`ffmpeg tone failed: ${tone.stderr}`);
writeFileSync(
join(dir, "index.html"),
`<!doctype html><html><head><meta charset="utf-8"></head><body>
<div data-composition-id="root" data-width="320" data-height="240" data-duration="${duration}">
<audio data-composition-audio src="tone.wav"></audio>
</div></body></html>`,
);
return dir;
}
it("fits the audio length and peak and records the layout only for mp4 without cfr", async () => {
const project = audioProject("project-stitch");
const config = { fps: 30, width: 320, height: 240, format: "mp4" } as const;
const stitched = join(runRoot, "plan-stitch");
await buildLocalExecutionPlan(project, config, stitched, { chunksCarryAudio: true });
const encoder = JSON.parse(readFileSync(join(stitched, "meta", "encoder.json"), "utf-8"));
expect(encoder.chunksCarryAudio).toBe(true);
const probe = spawnSync(
getFfprobeBinary(),
[
"-v",
"error",
"-show_entries",
"format=duration",
"-of",
"csv=p=0",
join(stitched, "audio.m4a"),
],
{ encoding: "utf-8" },
);
expect(Math.abs(Number(probe.stdout) - 1)).toBeLessThan(0.001);
const volume = spawnSync(
getFfmpegBinary(),
["-nostdin", "-i", join(stitched, "audio.m4a"), "-af", "volumedetect", "-f", "null", "-"],
{ encoding: "utf-8" },
);
expect(Number(/max_volume: (-?[\d.]+) dB/.exec(volume.stderr)?.[1])).toBeLessThan(-1);
const withCfr = join(runRoot, "plan-stitch-cfr");
await buildLocalExecutionPlan(project, { ...config, cfr: true }, withCfr, {
chunksCarryAudio: true,
});
const cfrEncoder = JSON.parse(readFileSync(join(withCfr, "meta", "encoder.json"), "utf-8"));
expect(cfrEncoder.chunksCarryAudio).toBeUndefined();
}, 60_000);
it("leaves the audio to buildPlanAudio, which makes the track the plan would", async () => {
// A hot tone, so the true-peak hold re-encodes as well.
const project = audioProject("project-separate-audio");
const config = { fps: 30, width: 320, height: 240, format: "mp4" } as const;
const carried = join(runRoot, "plan-carried-audio");
await buildLocalExecutionPlan(project, config, carried, { chunksCarryAudio: true });
const separate = join(runRoot, "plan-separate-audio");
await buildLocalExecutionPlan(project, config, separate, {
chunksCarryAudio: true,
deferAudio: true,
});
const encoder = JSON.parse(readFileSync(join(separate, "meta", "encoder.json"), "utf-8"));
expect([encoder.chunksCarryAudio, encoder.separateAudio]).toEqual([undefined, true]);
expect(existsSync(join(separate, "audio.m4a"))).toBe(false);
const work = join(runRoot, "separate-audio-work");
mkdirSync(work, { recursive: true });
const audio = join(work, "audio.m4a");
expect(await buildPlanAudio(project, config, work, audio)).toEqual({ hasAudio: true });
expect(readFileSync(audio).equals(readFileSync(join(carried, "audio.m4a")))).toBe(true);
const withCfr = join(runRoot, "plan-separate-audio-cfr");
await buildLocalExecutionPlan(project, { ...config, cfr: true }, withCfr, {
deferAudio: true,
});
const cfrEncoder = JSON.parse(readFileSync(join(withCfr, "meta", "encoder.json"), "utf-8"));
expect(cfrEncoder.separateAudio).toBeUndefined();
expect(existsSync(join(withCfr, "audio.m4a"))).toBe(true);
}, 60_000);
it("leaves webm and mov audio to buildPlanAudio too; png-sequence keeps its own", async () => {
const project = audioProject("project-separate-audio-formats");
const config = { fps: 30, width: 320, height: 240 } as const;
for (const [format, separate] of [
["webm", true],
["mov", true],
["png-sequence", false],
] as const) {
const dir = join(runRoot, `plan-separate-audio-${format}`);
await buildLocalExecutionPlan(project, { ...config, format }, dir, { deferAudio: true });
const encoder = JSON.parse(readFileSync(join(dir, "meta", "encoder.json"), "utf-8"));
expect({ format, separate: encoder.separateAudio === true }).toEqual({ format, separate });
expect({ format, mixed: existsSync(join(dir, "audio.m4a")) }).toEqual({
format,
mixed: !separate,
});
}
}, 60_000);
it("gives buildPlanAudio the sound of a video whose src the scene script sets", async () => {
const project = join(runRoot, "project-script-src");
mkdirSync(project, { recursive: true });
const clip = spawnSync(getFfmpegBinary(), [
"-nostdin",
"-v",
"error",
"-f",
"lavfi",
"-i",
"testsrc=s=320x240:r=30:d=1",
"-f",
"lavfi",
"-i",
"sine=frequency=440:sample_rate=48000:d=1",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
"-c:a",
"aac",
"-shortest",
join(project, "clip.mp4"),
]);
if (clip.status !== 0) throw new Error(`ffmpeg clip failed: ${clip.stderr}`);
writeFileSync(
join(project, "index.html"),
`<!doctype html><html><head><meta charset="utf-8"></head><body>
<div data-composition-id="root" data-width="320" data-height="240" data-duration="1" data-no-timeline>
<video id="v" data-has-audio="true" data-start="0" data-duration="1" playsinline></video>
</div>
<script>document.getElementById("v").src = "clip.mp4";</script></body></html>`,
);
const config = { fps: 30, width: 320, height: 240, format: "mp4" } as const;
const carried = join(runRoot, "plan-script-src");
await buildLocalExecutionPlan(project, config, carried, { chunksCarryAudio: true });
const work = join(runRoot, "script-src-work");
mkdirSync(work, { recursive: true });
const audio = join(work, "audio.m4a");
expect(await buildPlanAudio(project, config, work, audio)).toEqual({ hasAudio: true });
expect(readFileSync(audio).equals(readFileSync(join(carried, "audio.m4a")))).toBe(true);
}, 60_000);
it("keeps assembled loudness within 0.1 LUFS of the frame-fitted float delivery", async () => {
const project = audioProject("project-loudness-delivery", 0.3, 3.01);
ffmpegOrThrow([
"-f",
"lavfi",
"-i",
"anoisesrc=seed=2:amplitude=0.8:sample_rate=48000:duration=3.01",
"-af",
"pan=stereo|c0=c0|c1=c0",
"-c:a",
"pcm_f32le",
"-y",
join(project, "tone.wav"),
]);
const video = join(runRoot, "loudness-video.mp4");
ffmpegOrThrow([
"-f",
"lavfi",
"-i",
"color=black:size=320x240:rate=30",
"-frames:v",
"91",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
"-y",
video,
]);
const config = { fps: 30, width: 320, height: 240, format: "mp4", chunkSize: 1000 } as const;
const planDir = join(runRoot, "plan-loudness-delivery");
const planned = await buildLocalExecutionPlan(project, config, planDir);
expect(planned.totalFrames).toBe(91);
expect(planned.chunkCount).toBe(1);
const delivered = join(runRoot, "loudness-delivered.mp4");
await assemble(planDir, [video], join(planDir, "audio.m4a"), delivered);
const reference = join(runRoot, "loudness-reference.m4a");
const encoded = await encodeAac(join(project, "tone.wav"), reference, 91 / 30, {
timeout: 30_000,
filter: "apad,atrim=0:3.033333",
});
expect(encoded.success, encoded.stderr).toBe(true);
const held = await constrainAacTruePeak({
audioPath: reference,
sourcePath: join(project, "tone.wav"),
targetDurationSeconds: 91 / 30,
});
expect(held.success, held.error).toBe(true);
const measure = (path: string) => {
const result = spawnSync(
getFfmpegBinary(),
["-nostdin", "-i", path, "-vn", "-af", "ebur128=peak=true", "-f", "null", "-"],
{ encoding: "utf-8" },
);
expect(result.status, result.stderr).toBe(0);
const integrated = [...result.stderr.matchAll(/^\s*I:\s*([+-]?[\d.]+) LUFS$/gm)].at(
-1,
)?.[1];
const peak = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?[\d.]+) dBFS$/gm)].at(-1)?.[1];
if (integrated === undefined || peak === undefined)
throw new Error(`Missing loudness summary: ${result.stderr}`);
return { integratedTenths: Math.round(Number(integrated) * 10), peak: Number(peak) };
};
const actual = measure(delivered);
const expected = measure(reference);
expect(actual.peak).toBeLessThanOrEqual(-1);
// FFmpeg reports tenths of a LUFS. Compare those integer units without binary subtraction drift.
expect(Math.abs(actual.integratedTenths - expected.integratedTenths)).toBeLessThanOrEqual(1);
}, 60_000);
it.each([false, true])(
"encodes the audio once, at the frames' exact length (chunks carry audio: %s)",
async (chunksCarryAudio) => {
// 1.01 s at 30 fps is 31 frames: 49,600 samples, 48.4375 AAC frames of 1,024.
const project = audioProject(`project-one-encode-${chunksCarryAudio}`, 0.3, 1.01);
const shimDir = join(runRoot, `ffmpeg-shim-${chunksCarryAudio}`);
mkdirSync(shimDir, { recursive: true });
const shim = join(shimDir, "ffmpeg");
const calls = join(shimDir, "calls.txt");
writeFileSync(
shim,
`#!/bin/sh\necho "$*" >> "${calls}"\nexec "${getFfmpegBinary()}" "$@"\n`,
);
chmodSync(shim, 0o755);
const planDir = join(runRoot, `plan-one-encode-${chunksCarryAudio}`);
const previous = process.env[FFMPEG_PATH_ENV];
process.env[FFMPEG_PATH_ENV] = shim;
try {
await buildLocalExecutionPlan(
project,
{ fps: 30, width: 320, height: 240, format: "mp4" },
planDir,
{ chunksCarryAudio },
);
} finally {
if (previous === undefined) delete process.env[FFMPEG_PATH_ENV];
else process.env[FFMPEG_PATH_ENV] = previous;
}
const aacEncodes = readFileSync(calls, "utf-8")
.split("\n")
.filter((line) => / aac -b:a /.test(line));
expect(aacEncodes).toHaveLength(1);
const planAudio = join(planDir, "audio.m4a");
const shown = spawnSync(
getFfprobeBinary(),
[
"-v",
"error",
"-select_streams",
"a:0",
"-show_entries",
"stream=duration_ts",
"-of",
"csv=p=0",
"--",
planAudio,
],
{ encoding: "utf-8" },
);
// The edit list counts in ms, so 49,600 samples (1.0333 s) show as 1.033 s.
expect(Math.abs(Number(shown.stdout) - 49_600)).toBeLessThan(48);
},
60_000,
);
},
);
describe("plan() — codec knob", () => {
const TIMEOUT_MS = 30_000;
it(
"defaults `codec` to h264 (libx264-software) for mp4",
async () => {
const planDir = join(runRoot, "plan-codec-default");
mkdirSync(planDir, { recursive: true });
await plan(projectDir, { fps: 30, width: 320, height: 240, format: "mp4" }, planDir);
const encoder = JSON.parse(
readFileSync(join(planDir, "meta", "encoder.json"), "utf-8"),
) as Record<string, unknown>;
expect(encoder.encoder).toBe("libx264-software");
expect(encoder.pixelFormat).toBe("yuv420p");
expect(encoder).not.toHaveProperty("vp9CpuUsed");
},
TIMEOUT_MS,
);
it(
'maps `codec: "h265"` to libx265-software for mp4',
async () => {
const planDir = join(runRoot, "plan-codec-h265");
mkdirSync(planDir, { recursive: true });
await plan(
projectDir,
{ fps: 30, width: 320, height: 240, format: "mp4", codec: "h265" },
planDir,
);
const encoder = JSON.parse(
readFileSync(join(planDir, "meta", "encoder.json"), "utf-8"),
) as Record<string, unknown>;
expect(encoder.encoder).toBe("libx265-software");
// SDR 8-bit yuv420p, same as h264 — distributed mode is SDR-only and
// 10-bit / HDR pixelFormat selection is not exposed on this surface.
expect(encoder.pixelFormat).toBe("yuv420p");
},
TIMEOUT_MS,
);
it("rejects `codec` with format other than mp4", async () => {
const planDir = join(runRoot, "plan-codec-bad-format");
mkdirSync(planDir, { recursive: true });
let caught: unknown;
try {
await plan(
projectDir,
// @ts-expect-error — runtime check is the test's purpose.
{ fps: 30, width: 320, height: 240, format: "mov", codec: "h265" },
planDir,
);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(Error);
expect((caught as Error).message).toMatch(/codec.*only valid for format="mp4"/);
});
it("rejects unknown codec strings for format=mp4 (no silent fall-through to h264)", async () => {
const planDir = join(runRoot, "plan-codec-unknown");
mkdirSync(planDir, { recursive: true });
let caught: unknown;
try {
await plan(
projectDir,
// @ts-expect-error — runtime check is the test's purpose. Catches
// typos ("H265") and future codec additions ("av1") that a JS
// caller building config from JSON might pass.
{ fps: 30, width: 320, height: 240, format: "mp4", codec: "h266" },
planDir,
);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(Error);
expect((caught as Error).message).toMatch(/codec must be "h264" or "h265"/);
});
});
describe("plan() motion blur intent", () => {
it("freezes explicit off into the plan identity while omission preserves the old plan", async () => {
const base = { fps: 30 as const, width: 320, height: 240, format: "mp4" as const };
const ordinaryDir = join(runRoot, "motion-blur-omitted");
const offDir = join(runRoot, "motion-blur-off");
mkdirSync(ordinaryDir, { recursive: true });
mkdirSync(offDir, { recursive: true });
const ordinary = await plan(projectDir, base, ordinaryDir);
const off = await plan(projectDir, { ...base, pageMotionBlur: "off" }, offDir);
const encoder = (dir: string) =>
JSON.parse(readFileSync(join(dir, "meta", "encoder.json"), "utf-8"));
expect(encoder(ordinaryDir)).not.toHaveProperty("pageMotionBlur");
expect(encoder(offDir).pageMotionBlur).toBe("off");
expect(off.planHash).not.toBe(ordinary.planHash);
}, 30_000);
});
describe("plan() — variables", () => {
const TIMEOUT_MS = 30_000;
it(
"snapshots variables into meta/encoder.json so chunk workers see the controller's set",
async () => {
const planDir = join(runRoot, "plan-variables-snapshot");
mkdirSync(planDir, { recursive: true });
const variables = { title: "Hello", accent: "#ff0000" };
await plan(
projectDir,
{ fps: 30, width: 320, height: 240, format: "mp4", variables },
planDir,
);
const encoder = JSON.parse(
readFileSync(join(planDir, "meta", "encoder.json"), "utf-8"),
) as Record<string, unknown>;
expect(encoder.variables).toEqual(variables);
},
TIMEOUT_MS,
);
it(
"omits the variables key from canonical encoder.json when the caller passes no variables",
async () => {
// Backwards compat: a no-variables plan must hash identically to
// pre-Phase-9 plans. Since the canonical encoder.json strips
// `undefined` values, the key must not appear at all.
const planDir = join(runRoot, "plan-variables-absent");
mkdirSync(planDir, { recursive: true });
await plan(projectDir, { fps: 30, width: 320, height: 240, format: "mp4" }, planDir);
const encoderRaw = readFileSync(join(planDir, "meta", "encoder.json"), "utf-8");
expect(encoderRaw).not.toContain("variables");
},
TIMEOUT_MS,
);
it(
"produces a DIFFERENT planHash when variables differ",
async () => {
// Variables fold into planHash via meta/encoder.json bytes. Two plans
// with different variables must produce different hashes — chunked
// output depends on the injected values, and the byte-identical-
// retry contract has to bind to the controller's choice.
const planDirA = join(runRoot, "plan-variables-different-a");
const planDirB = join(runRoot, "plan-variables-different-b");
mkdirSync(planDirA, { recursive: true });
mkdirSync(planDirB, { recursive: true });
const base = { fps: 30 as const, width: 320, height: 240, format: "mp4" as const };
const a = await plan(projectDir, { ...base, variables: { title: "Alice" } }, planDirA);
const b = await plan(projectDir, { ...base, variables: { title: "Bob" } }, planDirB);
expect(a.planHash).not.toBe(b.planHash);
},
TIMEOUT_MS,
);
it(
"produces the SAME planHash for two plans with the same variables",
async () => {
// Canonical-JSON sorts object keys, so the same variables (regardless
// of insertion order on the caller side) must round-trip to the
// same encoder.json bytes and therefore the same planHash.
const planDirA = join(runRoot, "plan-variables-same-a");
const planDirB = join(runRoot, "plan-variables-same-b");
mkdirSync(planDirA, { recursive: true });
mkdirSync(planDirB, { recursive: true });
const base = { fps: 30 as const, width: 320, height: 240, format: "mp4" as const };
const a = await plan(
projectDir,
{ ...base, variables: { title: "Alice", accent: "#ff0000" } },
planDirA,
);
const b = await plan(
projectDir,
// Same values, opposite insertion order.
{ ...base, variables: { accent: "#ff0000", title: "Alice" } },
planDirB,
);
expect(a.planHash).toBe(b.planHash);
},
TIMEOUT_MS,
);
it(
"no-variables plan hashes identically to itself (backwards-compat baseline)",
async () => {
// Pin the no-variables path so adding the new field doesn't silently
// change the hash for callers who never opt in. Re-runs the
// determinism check from the golden block, scoped to the variables
// surface so a future refactor here trips a focused failure.
const planDirA = join(runRoot, "plan-no-variables-determinism-a");
const planDirB = join(runRoot, "plan-no-variables-determinism-b");
mkdirSync(planDirA, { recursive: true });
mkdirSync(planDirB, { recursive: true });
const config = { fps: 30 as const, width: 320, height: 240, format: "mp4" as const };
const a = await plan(projectDir, config, planDirA);
const b = await plan(projectDir, config, planDirB);
expect(a.planHash).toBe(b.planHash);
},
TIMEOUT_MS,
);
});
describe("plan() — webm format (distributed VP9)", () => {
const TIMEOUT_MS = 30_000;
it(
'maps `format: "webm"` to libvpx-vp9-software + yuva420p',
async () => {
// Pins the plan-time encoder choice for webm: libvpx-vp9-software
// with yuva420p so the format's alpha-channel contract round-trips
// through chunked rendering.
const planDir = join(runRoot, "plan-webm-vp9");
mkdirSync(planDir, { recursive: true });
const result = await plan(
projectDir,
{ fps: 30, width: 320, height: 240, format: "webm" },
planDir,
);
expect(result.format).toBe("webm");
const encoder = JSON.parse(
readFileSync(join(planDir, "meta", "encoder.json"), "utf-8"),
) as Record<string, unknown>;
expect(encoder.encoder).toBe("libvpx-vp9-software");
expect(encoder.pixelFormat).toBe("yuva420p");
// Closed-GOP must be on so concat-copy at assemble time works.
// gopSize equals the chunkSize so every chunk's first frame is a
// keyframe with no alt-ref references reaching back across seams.
expect(encoder.closedGop).toBe(true);
expect(encoder.gopSize).toBe(encoder.chunkSize);
expect(encoder.vp9CpuUsed).toBe(4);
},
TIMEOUT_MS,
);
it(
"locks the resolved VP9 cpu-used value into encoder metadata",
async () => {
const planDir = join(runRoot, "plan-webm-vp9-cpu-used");
mkdirSync(planDir, { recursive: true });
await plan(
projectDir,
{
fps: 30,
width: 320,
height: 240,
format: "webm",
producerConfig: { vp9CpuUsed: 2 },
},
planDir,
);
const encoder = JSON.parse(
readFileSync(join(planDir, "meta", "encoder.json"), "utf-8"),
) as Record<string, unknown>;
expect(encoder.vp9CpuUsed).toBe(2);
},
TIMEOUT_MS,
);
it("rejects `codec` with format=webm", async () => {
// webm is always libvpx-vp9 — same shape as mov (always ProRes 4444).
// A JS caller building config from JSON who passes `codec: "vp8"` or
// `codec: "av1"` must hit a typed error, not silently encode VP9.
const planDir = join(runRoot, "plan-webm-bad-codec");
mkdirSync(planDir, { recursive: true });
let caught: unknown;
try {
await plan(
projectDir,
// @ts-expect-error — runtime check is the test's purpose.
{ fps: 30, width: 320, height: 240, format: "webm", codec: "vp8" },
planDir,
);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(Error);
expect((caught as Error).message).toMatch(/codec.*only valid for format="mp4"/);
});
});