Skip to content

Commit aae32e4

Browse files
perf(producer): cut distributed chunks by estimated capture cost (#6295)
* 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. * fix(producer): hold cost-weighted chunks to the worker time limit's frame cap The weighted cut could grow a chunk up to MAX_CHUNK_SIZE frames, past the per-chunk frame count resolveMaxParallelChunks sized against the worker time limit. The cut now takes the same cap, from one shared helper, and keeps the equal-frame size as its floor. * fix(producer): keep the chunk-cut doc comment under 120 characters * perf(producer): drop the calibration sampler change from the cost-weighted cut The cut no longer touches how capture cost is measured; that keeps the producer bundle within its size budget and the change to the chunk boundaries alone. * perf(producer): compute the chunk frame cap inline to keep the bundle small
1 parent 6b424e0 commit aae32e4

5 files changed

Lines changed: 358 additions & 7 deletions

File tree

‎packages/engine/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,6 +218,7 @@ export {
218218
resolveVideoExtractionWindow,
219219
rebaseVideoToWindow,
220220
resolveFinalFrameExtractionWindow,
221+
resolveFrameFormat,
221222
resolveVideoExtractionDuration,
222223
resolvePlayableVideoDuration,
223224
extractionFrameCountForDuration,
Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
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+
197+
it("holds every chunk to the worker time limit's frame cap", () => {
198+
const frames = 1500;
199+
const { chunkCount, effectiveChunkSize } = resolveChunkPlan(frames, undefined, 18);
200+
const weights = weightsWithHeavyWindow(frames, 700, 783, 4);
201+
const capped = buildPlanChunkSlices(weights, {}, chunkCount, effectiveChunkSize, 90);
202+
expectExactCover(capped, frames);
203+
for (const slice of capped) expect(slice.endFrame - slice.startFrame).toBeLessThanOrEqual(90);
204+
205+
const uncapped = buildPlanChunkSlices(weights, {}, chunkCount, effectiveChunkSize);
206+
expect(Math.max(...uncapped.map((s) => s.endFrame - s.startFrame))).toBeGreaterThan(90);
207+
});
208+
});
Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
import { resolveFrameFormat } from "@hyperframes/engine";
2+
import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
3+
import type { PlanVideosJson } from "./shared.js";
4+
5+
/** Per-frame page cost, in megapixel-frames of jpg capture (measured: 0.03 s base / 0.045 s per MP). */
6+
const PAGE_BASE_WEIGHT = 0.7;
7+
/** png frames cost ~1.5x jpg per megapixel. */
8+
const PNG_WEIGHT_FACTOR = 1.5;
9+
10+
/** Costs whose max/min stay within 5% count as uniform. */
11+
function isUniformFrameCost(weights: Float64Array): boolean {
12+
let lightest = Infinity;
13+
let heaviest = 0;
14+
for (const weight of weights) {
15+
lightest = Math.min(lightest, weight);
16+
heaviest = Math.max(heaviest, weight);
17+
}
18+
return heaviest <= lightest * 1.05;
19+
}
20+
21+
/** Estimated capture cost of every frame: page base plus each active video's pixels. */
22+
export function planFrameWeights(input: {
23+
videos: PlanVideosJson["videos"];
24+
extracted: PlanVideosJson["extracted"];
25+
totalFrames: number;
26+
fps: number;
27+
width: number;
28+
height: number;
29+
}): Float64Array {
30+
const { totalFrames, fps } = input;
31+
const delta = new Float64Array(totalFrames + 1);
32+
const outputPixels = input.width * input.height;
33+
const extractedById = new Map(input.extracted.map((entry) => [entry.videoId, entry]));
34+
for (const video of input.videos) {
35+
const entry = extractedById.get(video.id);
36+
if (!entry || video.hidden) continue;
37+
const start = Math.max(0, Math.round(video.start * fps));
38+
const end = Math.min(totalFrames, Math.round(video.end * fps));
39+
if (!(end > start)) continue;
40+
const { width, height } = entry.metadata;
41+
const factor = resolveFrameFormat(entry.metadata) === "png" ? PNG_WEIGHT_FACTOR : 1;
42+
const weight = (Math.min(width * height, outputPixels) / 1e6) * factor;
43+
delta[start] = delta[start]! + weight;
44+
delta[end] = delta[end]! - weight;
45+
}
46+
const weights = new Float64Array(totalFrames);
47+
let active = 0;
48+
for (let frame = 0; frame < totalFrames; frame++) {
49+
active += delta[frame]!;
50+
weights[frame] = PAGE_BASE_WEIGHT + active;
51+
}
52+
return weights;
53+
}
54+
55+
/**
56+
* Cut `[0, weights.length)` into `chunkCount` ranges of ~equal summed weight, each within
57+
* `[minFrames, maxFrames]` where the frame count allows. `null` when the cost is uniform.
58+
*/
59+
export function buildWeightedChunkSlices(
60+
weights: Float64Array,
61+
chunkCount: number,
62+
minFrames: number,
63+
maxFrames: number,
64+
): ChunkSliceJson[] | null {
65+
if (isUniformFrameCost(weights)) return null;
66+
const totalFrames = weights.length;
67+
const total = weights.reduce((sum, weight) => sum + weight, 0);
68+
const minSize = Math.max(1, Math.min(minFrames, Math.floor(totalFrames / chunkCount)));
69+
const maxSize = Math.max(maxFrames, Math.ceil(totalFrames / chunkCount));
70+
const slices: ChunkSliceJson[] = [];
71+
let startFrame = 0;
72+
let frame = 0;
73+
let costBefore = 0;
74+
for (let index = 0; index < chunkCount - 1; index++) {
75+
const target = ((index + 1) * total) / chunkCount;
76+
// Advance while the boundary after `frame` lands nearer the target than the one before it.
77+
while (frame < totalFrames && costBefore + weights[frame]! / 2 < target) {
78+
costBefore += weights[frame++]!;
79+
}
80+
const remaining = chunkCount - index - 1;
81+
const low = Math.max(startFrame + minSize, totalFrames - remaining * maxSize);
82+
const high = Math.min(startFrame + maxSize, totalFrames - remaining * minSize);
83+
const endFrame = Math.min(high, Math.max(low, frame));
84+
slices.push({ index, startFrame, endFrame });
85+
startFrame = endFrame;
86+
}
87+
slices.push({ index: chunkCount - 1, startFrame, endFrame: totalFrames });
88+
return slices;
89+
}

0 commit comments

Comments
 (0)