Skip to content

Commit 7608cba

Browse files
committed
perf(producer): cut distributed chunks by estimated capture cost, same chunk count
Auto-sized plans place chunk boundaries so each chunk carries about the same estimated capture cost (page base plus active video megapixels); chunk count, explicit chunkSize, uniform-cost compositions and the targetChunkFrames ceiling are unchanged. Frame-cost calibration samples by cost interval plus the heaviest frame, so a heavy window is always measured.
1 parent 2bff65b commit 7608cba

8 files changed

Lines changed: 386 additions & 14 deletions

File tree

‎packages/engine/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,7 @@ export {
216216
resolveVideoExtractionWindow,
217217
rebaseVideoToWindow,
218218
resolveFinalFrameExtractionWindow,
219+
resolveFrameFormat,
219220
resolveVideoExtractionDuration,
220221
resolvePlayableVideoDuration,
221222
extractionFrameCountForDuration,
Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
import { describe, expect, it } from "bun:test";
2+
import { buildWeightedChunkSlices, planFrameWeights } from "./chunkWeights.js";
3+
import {
4+
buildChunkSlices,
5+
buildPlanChunkSlices,
6+
MAX_CHUNK_SIZE,
7+
MIN_CHUNK_SIZE,
8+
resolveChunkPlan,
9+
} from "./plan.js";
10+
import type { PlanVideosJson } from "./shared.js";
11+
12+
type Slices = ReturnType<typeof buildChunkSlices>;
13+
14+
function chunkCosts(weights: Float64Array, slices: Slices) {
15+
return slices.map((slice) =>
16+
weights.slice(slice.startFrame, slice.endFrame).reduce((sum, weight) => sum + weight, 0),
17+
);
18+
}
19+
20+
function expectExactCover(slices: Slices, totalFrames: number) {
21+
expect(slices[0]?.startFrame).toBe(0);
22+
expect(slices.at(-1)?.endFrame).toBe(totalFrames);
23+
slices.forEach((slice, index) => {
24+
expect(slice.index).toBe(index);
25+
expect(slice.endFrame).toBeGreaterThan(slice.startFrame);
26+
if (index > 0) expect(slice.startFrame).toBe(slices[index - 1]?.endFrame ?? -1);
27+
});
28+
}
29+
30+
function weightsWithHeavyWindow(totalFrames: number, from: number, to: number, heavy: number) {
31+
const weights = new Float64Array(totalFrames).fill(1);
32+
weights.fill(heavy, from, to);
33+
return weights;
34+
}
35+
36+
function video(id: string, start: number, end: number, hidden?: boolean) {
37+
return { id, start, end, hidden } as PlanVideosJson["videos"][number];
38+
}
39+
40+
function extractedVideo(videoId: string, width: number, height: number, hasAlpha = false) {
41+
return {
42+
videoId,
43+
metadata: { width, height, hasAlpha, videoCodec: "h264" },
44+
} as PlanVideosJson["extracted"][number];
45+
}
46+
47+
describe("buildPlanChunkSlices", () => {
48+
it.each([
49+
[1500, 18],
50+
[660, 16],
51+
[121, 12],
52+
[50, 16],
53+
[1, 16],
54+
[54000, 256],
55+
])("uniform cost keeps the equal-frame cut (%d frames, max %d chunks)", (frames, max) => {
56+
const { chunkCount, effectiveChunkSize } = resolveChunkPlan(frames, undefined, max);
57+
const fullLengthVideo = planFrameWeights({
58+
videos: [video("v", 0, frames)],
59+
extracted: [extractedVideo("v", 1920, 1080)],
60+
totalFrames: frames,
61+
fps: 1,
62+
width: 1920,
63+
height: 1080,
64+
});
65+
for (const weights of [new Float64Array(frames).fill(0.7), fullLengthVideo]) {
66+
expect(buildPlanChunkSlices(weights, {}, chunkCount, effectiveChunkSize)).toEqual(
67+
buildChunkSlices(frames, chunkCount, effectiveChunkSize),
68+
);
69+
}
70+
});
71+
72+
it("balances a heavy window across the same number of chunks", () => {
73+
const frames = 1500;
74+
const { chunkCount, effectiveChunkSize } = resolveChunkPlan(frames, undefined, 18);
75+
const weights = weightsWithHeavyWindow(frames, 700, 783, 4);
76+
const slices = buildPlanChunkSlices(weights, {}, chunkCount, effectiveChunkSize);
77+
78+
expect(slices).toHaveLength(chunkCount);
79+
expectExactCover(slices, frames);
80+
for (const slice of slices) {
81+
expect(slice.endFrame - slice.startFrame).toBeGreaterThanOrEqual(MIN_CHUNK_SIZE);
82+
}
83+
const costs = chunkCosts(weights, slices);
84+
const mean = costs.reduce((sum, cost) => sum + cost, 0) / costs.length;
85+
expect(Math.max(...costs)).toBeLessThanOrEqual(mean * 1.15);
86+
87+
const uniformCosts = chunkCosts(
88+
weights,
89+
buildChunkSlices(frames, chunkCount, effectiveChunkSize),
90+
);
91+
expect(Math.max(...uniformCosts)).toBeGreaterThan(mean * 1.5);
92+
const heavyChunk = slices.find((slice) => slice.startFrame <= 740 && slice.endFrame > 740);
93+
expect((heavyChunk?.endFrame ?? 0) - (heavyChunk?.startFrame ?? 0)).toBeLessThan(
94+
effectiveChunkSize,
95+
);
96+
});
97+
98+
it("keeps the equal-frame cut when the caller passed a chunkSize", () => {
99+
const weights = weightsWithHeavyWindow(1500, 700, 783, 4);
100+
expect(buildPlanChunkSlices(weights, { chunkSize: 84 }, 18, 84)).toEqual(
101+
buildChunkSlices(1500, 18, 84),
102+
);
103+
});
104+
105+
it.each([
106+
[25, 16],
107+
[11, 16],
108+
[12, 1],
109+
])("stays a valid cover on tiny compositions (%d frames, max %d chunks)", (frames, max) => {
110+
const { chunkCount, effectiveChunkSize } = resolveChunkPlan(frames, undefined, max);
111+
const weights = weightsWithHeavyWindow(frames, 0, 3, 6);
112+
const slices = buildPlanChunkSlices(weights, {}, chunkCount, effectiveChunkSize);
113+
expect(slices).toHaveLength(chunkCount);
114+
expectExactCover(slices, frames);
115+
for (const slice of slices) {
116+
expect(slice.endFrame - slice.startFrame).toBeGreaterThanOrEqual(
117+
Math.floor(frames / chunkCount),
118+
);
119+
}
120+
});
121+
122+
it("keeps every chunk under MAX_CHUNK_SIZE or the equal cut, whichever is larger", () => {
123+
const frames = 9000;
124+
const weights = weightsWithHeavyWindow(frames, 0, 100, 50);
125+
const slices = buildPlanChunkSlices(weights, {}, 2, 4500);
126+
expectExactCover(slices, frames);
127+
for (const slice of slices) expect(slice.endFrame - slice.startFrame).toBeLessThanOrEqual(4500);
128+
129+
const fourChunks = buildPlanChunkSlices(
130+
weightsWithHeavyWindow(frames, 0, 100, 200),
131+
{},
132+
4,
133+
2250,
134+
);
135+
expectExactCover(fourChunks, frames);
136+
for (const slice of fourChunks) {
137+
expect(slice.endFrame - slice.startFrame).toBeLessThanOrEqual(MAX_CHUNK_SIZE);
138+
}
139+
});
140+
141+
it("keeps targetChunkFrames as a per-chunk frame ceiling", () => {
142+
const frames = 1500;
143+
const { chunkCount, effectiveChunkSize } = resolveChunkPlan(frames, undefined, 18, 120);
144+
const weights = weightsWithHeavyWindow(frames, 700, 783, 4);
145+
const slices = buildPlanChunkSlices(
146+
weights,
147+
{ targetChunkFrames: 120 },
148+
chunkCount,
149+
effectiveChunkSize,
150+
);
151+
expect(slices).toHaveLength(chunkCount);
152+
expectExactCover(slices, frames);
153+
for (const slice of slices) expect(slice.endFrame - slice.startFrame).toBeLessThanOrEqual(120);
154+
});
155+
});
156+
157+
describe("buildWeightedChunkSlices", () => {
158+
it("returns null for uniform cost so the caller keeps the equal-frame cut", () => {
159+
expect(buildWeightedChunkSlices(new Float64Array(100).fill(2), 4, 10, 3600)).toBeNull();
160+
});
161+
});
162+
163+
describe("planFrameWeights", () => {
164+
const base = { totalFrames: 100, fps: 10, width: 3840, height: 2160 };
165+
const uhd = (3840 * 2160) / 1e6;
166+
167+
it("weights active frames by video megapixels and frame format", () => {
168+
const weights = planFrameWeights({
169+
...base,
170+
videos: [video("jpg", 1, 3), video("png", 2, 4), video("hidden", 0, 10, true)],
171+
extracted: [
172+
extractedVideo("jpg", 3840, 2160),
173+
extractedVideo("png", 3840, 2160, true),
174+
extractedVideo("hidden", 3840, 2160),
175+
],
176+
});
177+
expect(weights[5]).toBeCloseTo(0.7);
178+
expect(weights[15]).toBeCloseTo(0.7 + uhd);
179+
expect(weights[25]).toBeCloseTo(0.7 + uhd + 1.5 * uhd);
180+
expect(weights[35]).toBeCloseTo(0.7 + 1.5 * uhd);
181+
expect(weights[40]).toBeCloseTo(0.7);
182+
});
183+
184+
it("caps megapixels at the composition size and clamps windows to the timeline", () => {
185+
const weights = planFrameWeights({
186+
...base,
187+
width: 1920,
188+
height: 1080,
189+
videos: [video("big", -5, 500), video("unextracted", 0, 5)],
190+
extracted: [extractedVideo("big", 3840, 2160)],
191+
});
192+
expect(weights).toHaveLength(100);
193+
expect(weights[0]).toBeCloseTo(0.7 + (1920 * 1080) / 1e6);
194+
expect(weights[99]).toBeCloseTo(0.7 + (1920 * 1080) / 1e6);
195+
});
196+
});
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
import { resolveFrameFormat } from "@hyperframes/engine";
2+
import { isUniformFrameCost } from "../render/captureCost.js";
3+
import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
4+
import type { PlanVideosJson } from "./shared.js";
5+
6+
/** Per-frame page cost, in megapixel-frames of jpg capture (measured: 0.03 s base / 0.045 s per MP). */
7+
const PAGE_BASE_WEIGHT = 0.7;
8+
/** png frames cost ~1.5x jpg per megapixel. */
9+
const PNG_WEIGHT_FACTOR = 1.5;
10+
11+
/** Estimated capture cost of every frame: page base plus each active video's pixels. */
12+
export function planFrameWeights(input: {
13+
videos: PlanVideosJson["videos"];
14+
extracted: PlanVideosJson["extracted"];
15+
totalFrames: number;
16+
fps: number;
17+
width: number;
18+
height: number;
19+
}): Float64Array {
20+
const { totalFrames, fps } = input;
21+
const delta = new Float64Array(totalFrames + 1);
22+
const outputPixels = input.width * input.height;
23+
const extractedById = new Map(input.extracted.map((entry) => [entry.videoId, entry]));
24+
for (const video of input.videos) {
25+
const entry = extractedById.get(video.id);
26+
if (!entry || video.hidden) continue;
27+
const start = Math.max(0, Math.round(video.start * fps));
28+
const end = Math.min(totalFrames, Math.round(video.end * fps));
29+
if (!(end > start)) continue;
30+
const { width, height } = entry.metadata;
31+
const factor = resolveFrameFormat(entry.metadata) === "png" ? PNG_WEIGHT_FACTOR : 1;
32+
const weight = (Math.min(width * height, outputPixels) / 1e6) * factor;
33+
delta[start] = delta[start]! + weight;
34+
delta[end] = delta[end]! - weight;
35+
}
36+
const weights = new Float64Array(totalFrames);
37+
let active = 0;
38+
for (let frame = 0; frame < totalFrames; frame++) {
39+
active += delta[frame]!;
40+
weights[frame] = PAGE_BASE_WEIGHT + active;
41+
}
42+
return weights;
43+
}
44+
45+
/**
46+
* Cut `[0, weights.length)` into `chunkCount` ranges of ~equal summed weight, each within
47+
* `[minFrames, maxFrames]` where the frame count allows. `null` when the cost is uniform.
48+
*/
49+
export function buildWeightedChunkSlices(
50+
weights: Float64Array,
51+
chunkCount: number,
52+
minFrames: number,
53+
maxFrames: number,
54+
): ChunkSliceJson[] | null {
55+
if (isUniformFrameCost(weights)) return null;
56+
const totalFrames = weights.length;
57+
const total = weights.reduce((sum, weight) => sum + weight, 0);
58+
const minSize = Math.max(1, Math.min(minFrames, Math.floor(totalFrames / chunkCount)));
59+
const maxSize = Math.max(maxFrames, Math.ceil(totalFrames / chunkCount));
60+
const slices: ChunkSliceJson[] = [];
61+
let startFrame = 0;
62+
let frame = 0;
63+
let costBefore = 0;
64+
for (let index = 0; index < chunkCount - 1; index++) {
65+
const target = ((index + 1) * total) / chunkCount;
66+
// Advance while the boundary after `frame` lands nearer the target than the one before it.
67+
while (frame < totalFrames && costBefore + weights[frame]! / 2 < target) {
68+
costBefore += weights[frame++]!;
69+
}
70+
const remaining = chunkCount - index - 1;
71+
const low = Math.max(startFrame + minSize, totalFrames - remaining * maxSize);
72+
const high = Math.min(startFrame + maxSize, totalFrames - remaining * minSize);
73+
const endFrame = Math.min(high, Math.max(low, frame));
74+
slices.push({ index, startFrame, endFrame });
75+
startFrame = endFrame;
76+
}
77+
slices.push({ index: chunkCount - 1, startFrame, endFrame: totalFrames });
78+
return slices;
79+
}

‎packages/producer/src/services/distributed/plan.ts‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ import {
6262
} from "../renderOrchestrator.js";
6363
import { closeFileServerSafely } from "../fileServer.js";
6464
import { measurePlanSecondsPerFrame } from "./planFrameCost.js";
65+
import { buildWeightedChunkSlices, planFrameWeights } from "./chunkWeights.js";
6566
import { runAudioStage } from "../render/stages/audioStage.js";
6667
import { runCompileStage } from "../render/stages/compileStage.js";
6768
import {
@@ -431,6 +432,8 @@ export const DEFAULT_MAX_PARALLEL_CHUNKS = 16;
431432
* outweighs the parallelism gain on tiny renders.
432433
*/
433434
export const MIN_CHUNK_SIZE = 10;
435+
/** Largest `chunkSize`; `validateDistributedRenderConfig` enforces it, and cost-weighted chunks stay under it. */
436+
export const MAX_CHUNK_SIZE = 3600;
434437
/** Most chunks one render may plan; `validateDistributedRenderConfig` enforces it on `maxParallelChunks`. */
435438
export const MAX_PARALLEL_CHUNKS_CEILING = 256;
436439
// 0.11 s per megapixel-frame (~0.23 s per 1080p frame) was measured on one simple 1080p fixture on a
@@ -837,6 +840,28 @@ export function buildChunkSlices(
837840
return slices;
838841
}
839842

843+
/**
844+
* The plan's chunk cut: auto-sized plans re-cut the same chunk count by estimated capture cost;
845+
* an explicit `chunkSize` or uniform cost keeps {@link buildChunkSlices}. `targetChunkFrames` stays a frame ceiling.
846+
*/
847+
export function buildPlanChunkSlices(
848+
frameWeights: Float64Array,
849+
config: Pick<DistributedRenderConfig, "chunkSize" | "targetChunkFrames">,
850+
chunkCount: number,
851+
effectiveChunkSize: number,
852+
): ChunkSliceJson[] {
853+
const weighted =
854+
config.chunkSize === undefined
855+
? buildWeightedChunkSlices(
856+
frameWeights,
857+
chunkCount,
858+
MIN_CHUNK_SIZE,
859+
Math.min(config.targetChunkFrames ?? MAX_CHUNK_SIZE, MAX_CHUNK_SIZE),
860+
)
861+
: null;
862+
return weighted ?? buildChunkSlices(frameWeights.length, chunkCount, effectiveChunkSize);
863+
}
864+
840865
/**
841866
* Hash the deterministic-font bundle that ships inside `@hyperframes/producer`.
842867
* The compiled HTML already inlines per-family `@font-face` data URIs, so the
@@ -1526,6 +1551,14 @@ export async function buildLocalExecutionPlan(
15261551
const digests: PlanFileDigests = options.digests ?? new Map();
15271552
const separateAudio = plansSeparateAudio(config, options);
15281553
const chunksCarryAudio = !separateAudio && carriesChunkAudio(config, options);
1554+
const frameWeights = planFrameWeights({
1555+
videos: planVideosJson.videos,
1556+
extracted: planVideosJson.extracted,
1557+
totalFrames,
1558+
fps: config.fps,
1559+
width,
1560+
height,
1561+
});
15291562
stageStarted = Date.now();
15301563
const [audioOutcome, overlapOutcome, frameCostOutcome] = await Promise.allSettled([
15311564
separateAudio
@@ -1549,6 +1582,7 @@ export async function buildLocalExecutionPlan(
15491582
html: compiled.html,
15501583
planVideos: planVideosJson,
15511584
totalFrames,
1585+
frameWeights,
15521586
fps: config.fps,
15531587
width,
15541588
height,
@@ -1580,7 +1614,7 @@ export async function buildLocalExecutionPlan(
15801614
maxParallel,
15811615
config.targetChunkFrames,
15821616
);
1583-
const chunks = buildChunkSlices(totalFrames, chunkCount, effectiveChunkSize);
1617+
const chunks = buildPlanChunkSlices(frameWeights, config, chunkCount, effectiveChunkSize);
15841618
const audioResult = audioOutcome.value;
15851619
if (audioResult?.audioError) {
15861620
applyDistributedAudioWarningPolicy(job, audioResult.audioError, audioResult.audioFailures, log);

‎packages/producer/src/services/distributed/planFrameCost.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ export async function measurePlanSecondsPerFrame(input: {
3737
html: string;
3838
planVideos: PlanVideosJson;
3939
totalFrames: number;
40+
/** Estimated capture cost per frame; calibration samples by cost interval. */
41+
frameWeights: Float64Array;
4042
fps: number;
4143
width: number;
4244
height: number;
@@ -49,7 +51,7 @@ export async function measurePlanSecondsPerFrame(input: {
4951
}): Promise<number> {
5052
const { planDir, workDir, planVideos, fps, log } = input;
5153
const fpsRatio = { num: fps, den: 1 };
52-
const sampled = selectCaptureCalibrationFrames(input.totalFrames);
54+
const sampled = selectCaptureCalibrationFrames(input.totalFrames, input.frameWeights);
5355
const extracted = [
5456
...rebuildExtractedFramesFromPlanDir(
5557
planDir,
@@ -91,7 +93,13 @@ export async function measurePlanSecondsPerFrame(input: {
9193
createCaptureCalibrationConfig(input.cfg),
9294
);
9395
await initializeSession(session);
94-
const { estimate } = await measureCaptureCostFromSession(session, input.totalFrames, fps, log);
96+
const { estimate } = await measureCaptureCostFromSession(
97+
session,
98+
input.totalFrames,
99+
fps,
100+
log,
101+
sampled,
102+
);
95103
return (estimate.p95Ms ?? 0) / 1000;
96104
} finally {
97105
if (session) await closeCaptureSession(session).catch(() => {});

0 commit comments

Comments
 (0)