mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
* perf(producer): size a long video's chunks in one plan, no re-plan * docs(producer): chunk formulas name the minParallelChunks floor
418 lines
14 KiB
TypeScript
418 lines
14 KiB
TypeScript
import { afterEach, describe, expect, it } from "vitest";
|
|
import { DEFAULT_CONFIG, resolveConfig } from "@hyperframes/engine";
|
|
import {
|
|
createRenderRequest,
|
|
distributedConfigFromRequest,
|
|
parseRenderRequest,
|
|
renderConfigFromRequest,
|
|
renderRequestFromDistributedConfig,
|
|
serializeRenderRequest,
|
|
} from "./renderRequest.js";
|
|
import { InvalidConfigError } from "./services/distributed/renderConfigValidation.js";
|
|
|
|
const originalForceScreenshot = process.env.PRODUCER_FORCE_SCREENSHOT;
|
|
|
|
afterEach(() => {
|
|
if (originalForceScreenshot === undefined) delete process.env.PRODUCER_FORCE_SCREENSHOT;
|
|
else process.env.PRODUCER_FORCE_SCREENSHOT = originalForceScreenshot;
|
|
});
|
|
|
|
function request() {
|
|
return createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video.mp4",
|
|
engineConfig: { ...DEFAULT_CONFIG, protocolTimeout: 123_456 },
|
|
options: {
|
|
fps: { num: 30, den: 1 },
|
|
quality: "high",
|
|
format: "mp4",
|
|
gifLoop: 0,
|
|
workers: 3,
|
|
useGpu: true,
|
|
strictness: "best-effort",
|
|
entryFile: "compositions/main.html",
|
|
crf: 18,
|
|
videoFrameFormat: "png",
|
|
hdrMode: "force-sdr",
|
|
variables: { title: "Hello", nested: { count: 2 } },
|
|
outputResolution: "landscape-4k",
|
|
outputResolutionAspectAgnostic: true,
|
|
distributed: {
|
|
width: 1920,
|
|
height: 1080,
|
|
codec: "h264",
|
|
chunkSize: 120,
|
|
maxParallelChunks: 8,
|
|
targetChunkFrames: 1600,
|
|
minParallelChunks: 4,
|
|
cfr: true,
|
|
},
|
|
},
|
|
});
|
|
}
|
|
|
|
describe("RenderRequest", () => {
|
|
it("preserves explicit motion blur off through the distributed request round trip", () => {
|
|
const value = request();
|
|
value.options.pageMotionBlur = "off";
|
|
const config = distributedConfigFromRequest(value);
|
|
expect(config.pageMotionBlur).toBe("off");
|
|
expect(
|
|
renderRequestFromDistributedConfig({
|
|
projectDir: value.projectDir,
|
|
outputPath: value.outputPath,
|
|
config,
|
|
}).options.pageMotionBlur,
|
|
).toBe("off");
|
|
});
|
|
|
|
it("carries the delivery encoder options through every adapter", () => {
|
|
const value = request();
|
|
Object.assign(value.options, {
|
|
keyframeIntervalSeconds: 2,
|
|
maxBitrate: "8M",
|
|
bufferSize: "12M",
|
|
});
|
|
const expected = { keyframeIntervalSeconds: 2, maxBitrate: "8M", bufferSize: "12M" };
|
|
expect(renderConfigFromRequest(value)).toMatchObject(expected);
|
|
const config = distributedConfigFromRequest(value);
|
|
expect(config).toMatchObject(expected);
|
|
expect(
|
|
renderRequestFromDistributedConfig({
|
|
projectDir: value.projectDir,
|
|
outputPath: value.outputPath,
|
|
config,
|
|
}).options,
|
|
).toMatchObject(expected);
|
|
expect(() =>
|
|
parseRenderRequest({ ...value, options: { ...value.options, maxBitrate: 8 } }),
|
|
).toThrow();
|
|
expect(() =>
|
|
parseRenderRequest({ ...value, options: { ...value.options, keyframeIntervalSeconds: 0 } }),
|
|
).toThrow(/positive/);
|
|
});
|
|
|
|
it("round-trips through JSON without dropping nested options", () => {
|
|
const value = request();
|
|
expect(parseRenderRequest(serializeRenderRequest(value))).toEqual(value);
|
|
});
|
|
|
|
it("adapts the same request to local and distributed execution", () => {
|
|
const value = request();
|
|
const local = renderConfigFromRequest(value);
|
|
const distributed = distributedConfigFromRequest(value);
|
|
|
|
expect(local).toMatchObject({
|
|
fps: { num: 30, den: 1 },
|
|
quality: "high",
|
|
format: "mp4",
|
|
variables: value.options.variables,
|
|
outputResolutionAspectAgnostic: true,
|
|
producerConfig: { protocolTimeout: 123_456 },
|
|
});
|
|
expect(distributed).toMatchObject({
|
|
fps: 30,
|
|
width: 1920,
|
|
height: 1080,
|
|
format: "mp4",
|
|
chunkSize: 120,
|
|
strictness: "best-effort",
|
|
outputResolutionAspectAgnostic: true,
|
|
variables: value.options.variables,
|
|
engineConfig: { protocolTimeout: 123_456 },
|
|
});
|
|
expect(distributed).not.toHaveProperty("producerConfig");
|
|
});
|
|
|
|
it("round-trips distributed adapter fields back into the shared request", () => {
|
|
const value = request();
|
|
const distributed = distributedConfigFromRequest(value);
|
|
const reconstructed = renderRequestFromDistributedConfig({
|
|
projectDir: value.projectDir,
|
|
outputPath: value.outputPath,
|
|
config: distributed,
|
|
});
|
|
|
|
expect(reconstructed.options).toMatchObject({
|
|
fps: value.options.fps,
|
|
quality: value.options.quality,
|
|
format: value.options.format,
|
|
crf: value.options.crf,
|
|
videoFrameFormat: value.options.videoFrameFormat,
|
|
outputResolution: value.options.outputResolution,
|
|
outputResolutionAspectAgnostic: value.options.outputResolutionAspectAgnostic,
|
|
hdrMode: value.options.hdrMode,
|
|
strictness: value.options.strictness,
|
|
entryFile: value.options.entryFile,
|
|
variables: value.options.variables,
|
|
distributed: value.options.distributed,
|
|
});
|
|
});
|
|
|
|
it("snapshots environment-derived engine options once at the boundary", () => {
|
|
process.env.PRODUCER_FORCE_SCREENSHOT = "true";
|
|
const value = createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video.mp4",
|
|
options: { fps: { num: 30, den: 1 }, quality: "standard", format: "mp4" },
|
|
});
|
|
process.env.PRODUCER_FORCE_SCREENSHOT = "false";
|
|
|
|
expect(value.options.engineConfig.forceScreenshot).toBe(true);
|
|
expect(renderConfigFromRequest(value).producerConfig?.forceScreenshot).toBe(true);
|
|
});
|
|
|
|
it("accepts 25 fps for a distributed render", () => {
|
|
const value = request();
|
|
value.options.fps = { num: 25, den: 1 };
|
|
expect(distributedConfigFromRequest(value).fps).toBe(25);
|
|
});
|
|
|
|
it("rejects unsupported distributed fps before an adapter launch", () => {
|
|
const value = request();
|
|
value.options.fps = { num: 30_000, den: 1_001 };
|
|
expect(() => distributedConfigFromRequest(value)).toThrow("does not support fps");
|
|
});
|
|
|
|
it("rejects JSON-unsafe request values before serialization", () => {
|
|
const cyclic: Record<string, unknown> = {};
|
|
cyclic.self = cyclic;
|
|
for (const variables of [
|
|
{ missing: undefined },
|
|
{ callback: () => undefined },
|
|
{ identifier: 1n },
|
|
{ ratio: Number.NaN },
|
|
{ when: new Date(0) },
|
|
cyclic,
|
|
]) {
|
|
expect(() =>
|
|
createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video.mp4",
|
|
options: { fps: { num: 30, den: 1 }, quality: "standard", format: "mp4", variables },
|
|
}),
|
|
).toThrow();
|
|
}
|
|
});
|
|
|
|
it("omits absent optional options while preserving JSON validation for payloads", () => {
|
|
const value = createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video.mp4",
|
|
options: {
|
|
fps: { num: 30, den: 1 },
|
|
quality: "standard",
|
|
format: "mp4",
|
|
gifLoop: undefined,
|
|
},
|
|
});
|
|
|
|
expect(value.options).not.toHaveProperty("gifLoop");
|
|
});
|
|
|
|
it("rejects malformed optional and distributed fields", () => {
|
|
const value = request();
|
|
expect(() =>
|
|
parseRenderRequest({ ...value, options: { ...value.options, workers: "many" } }),
|
|
).toThrow("workers");
|
|
expect(() =>
|
|
parseRenderRequest({
|
|
...value,
|
|
options: { ...value.options, distributed: { ...value.options.distributed, width: "wide" } },
|
|
}),
|
|
).toThrow("distributed.width");
|
|
});
|
|
|
|
it("requires complete and valid engine config snapshots on both wire paths", () => {
|
|
const value = request();
|
|
for (const engineConfig of [
|
|
{},
|
|
{ ...value.options.engineConfig, protocolTimeout: "forever" },
|
|
{ ...value.options.engineConfig, browserGpuMode: "turbo" },
|
|
{ ...value.options.engineConfig, streamingEncodeDurationCapEnabled: "true" },
|
|
]) {
|
|
expect(() =>
|
|
parseRenderRequest({ ...value, options: { ...value.options, engineConfig } }),
|
|
).toThrow("Engine config");
|
|
}
|
|
|
|
for (const engineConfig of [
|
|
{},
|
|
{ ...value.options.engineConfig, protocolTimeout: "forever" },
|
|
{ ...value.options.engineConfig, browserGpuMode: "turbo" },
|
|
{ ...value.options.engineConfig, streamingEncodeDurationCapEnabled: "true" },
|
|
]) {
|
|
const distributed = distributedConfigFromRequest(value);
|
|
(distributed as { engineConfig: unknown }).engineConfig = engineConfig;
|
|
expect(() =>
|
|
renderRequestFromDistributedConfig({
|
|
projectDir: value.projectDir,
|
|
outputPath: value.outputPath,
|
|
config: distributed,
|
|
}),
|
|
).toThrow("Engine config");
|
|
}
|
|
});
|
|
|
|
it("accepts fractional coresPerWorker snapshots from the canonical resolver", () => {
|
|
const engineConfig = resolveConfig({ coresPerWorker: 0.5 });
|
|
const value = createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video.mp4",
|
|
engineConfig,
|
|
options: {
|
|
fps: { num: 30, den: 1 },
|
|
quality: "standard",
|
|
format: "mp4",
|
|
distributed: { width: 1920, height: 1080, cfr: true },
|
|
},
|
|
});
|
|
|
|
expect(value.options.engineConfig.coresPerWorker).toBe(0.5);
|
|
expect(parseRenderRequest(serializeRenderRequest(value))).toEqual(value);
|
|
|
|
const distributed = distributedConfigFromRequest(value);
|
|
(distributed as { engineConfig: unknown }).engineConfig = engineConfig;
|
|
expect(
|
|
renderRequestFromDistributedConfig({
|
|
projectDir: value.projectDir,
|
|
outputPath: value.outputPath,
|
|
config: distributed,
|
|
}).options.engineConfig.coresPerWorker,
|
|
).toBe(0.5);
|
|
});
|
|
|
|
it("preserves the distributed InvalidConfigError contract for engine snapshots", () => {
|
|
const value = request();
|
|
const distributed = distributedConfigFromRequest(value);
|
|
(distributed as { engineConfig: unknown }).engineConfig = {};
|
|
|
|
try {
|
|
renderRequestFromDistributedConfig({
|
|
projectDir: value.projectDir,
|
|
outputPath: value.outputPath,
|
|
config: distributed,
|
|
});
|
|
throw new Error("expected distributed validation to fail");
|
|
} catch (error) {
|
|
expect(error).toBeInstanceOf(InvalidConfigError);
|
|
expect((error as InvalidConfigError).field).toBe("config.engineConfig");
|
|
}
|
|
});
|
|
|
|
it("validates the reverse distributed adapter at the wire boundary", () => {
|
|
const distributed = distributedConfigFromRequest(request());
|
|
distributed.width = 1921;
|
|
expect(() =>
|
|
renderRequestFromDistributedConfig({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video.mp4",
|
|
config: distributed,
|
|
}),
|
|
).toThrow("must be even");
|
|
});
|
|
|
|
describe("format: hls", () => {
|
|
function hlsRequest(options: { hlsSegmentSeconds?: number } = {}) {
|
|
return createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video-hls",
|
|
engineConfig: DEFAULT_CONFIG,
|
|
options: {
|
|
fps: { num: 30, den: 1 },
|
|
quality: "standard",
|
|
format: "hls",
|
|
...options,
|
|
},
|
|
});
|
|
}
|
|
|
|
it("round-trips hls and its segment length", () => {
|
|
const value = hlsRequest({ hlsSegmentSeconds: 6 });
|
|
expect(value.options.format).toBe("hls");
|
|
expect(value.options.hlsSegmentSeconds).toBe(6);
|
|
expect(parseRenderRequest(serializeRenderRequest(value))).toEqual(value);
|
|
});
|
|
|
|
it("carries the segment length through to the local render config", () => {
|
|
expect(renderConfigFromRequest(hlsRequest({ hlsSegmentSeconds: 2 }))).toMatchObject({
|
|
format: "hls",
|
|
hlsSegmentSeconds: 2,
|
|
});
|
|
});
|
|
|
|
it("omits hlsSegmentSeconds when unset so the orchestrator default applies", () => {
|
|
expect(hlsRequest().options).not.toHaveProperty("hlsSegmentSeconds");
|
|
});
|
|
|
|
it("rejects a non-positive or fractional segment length at the wire boundary", () => {
|
|
const value = hlsRequest();
|
|
for (const hlsSegmentSeconds of [0, -4, 4.5]) {
|
|
expect(() =>
|
|
parseRenderRequest({ ...value, options: { ...value.options, hlsSegmentSeconds } }),
|
|
).toThrow("hlsSegmentSeconds must be an integer >= 1");
|
|
}
|
|
});
|
|
|
|
// v1 is in-process only. `DistributedFormat` has no "hls" member, so this
|
|
// gate is also what makes the adapter's `format:` assignment typecheck.
|
|
it("refuses to convert an hls request to a distributed config", () => {
|
|
const value = createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video-hls",
|
|
engineConfig: DEFAULT_CONFIG,
|
|
options: {
|
|
fps: { num: 30, den: 1 },
|
|
quality: "standard",
|
|
format: "hls",
|
|
distributed: { width: 1920, height: 1080 },
|
|
},
|
|
});
|
|
|
|
expect(() => distributedConfigFromRequest(value)).toThrow(
|
|
"Distributed render does not support hls",
|
|
);
|
|
});
|
|
|
|
it("still names gif in the same rejection", () => {
|
|
const value = createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video.gif",
|
|
engineConfig: DEFAULT_CONFIG,
|
|
options: {
|
|
fps: { num: 30, den: 1 },
|
|
quality: "standard",
|
|
format: "gif",
|
|
distributed: { width: 1920, height: 1080 },
|
|
},
|
|
});
|
|
|
|
expect(() => distributedConfigFromRequest(value)).toThrow(
|
|
"Distributed render does not support gif",
|
|
);
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("segmented resume flags", () => {
|
|
it("carries resumeSegments and keepSegments from the request into the render config", () => {
|
|
const req = createRenderRequest({
|
|
projectDir: "/project",
|
|
outputPath: "/output/video.mp4",
|
|
engineConfig: { ...DEFAULT_CONFIG },
|
|
options: {
|
|
fps: { num: 30, den: 1 },
|
|
quality: "high",
|
|
format: "mp4",
|
|
gifLoop: 0,
|
|
strictness: "best-effort",
|
|
resumeSegments: true,
|
|
keepSegments: true,
|
|
},
|
|
});
|
|
const config = renderConfigFromRequest(req);
|
|
expect(config.resumeSegments).toBe(true);
|
|
expect(config.keepSegments).toBe(true);
|
|
});
|
|
});
|