mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* feat(engine): decouple transparent background from png capture format PNG capture used to imply a cleared page background. A new CaptureOptions.transparentBackground lets lossless opaque PNG capture (4:4:4 MP4 output) keep the page background. Absent, it still follows format === "png", so alpha output and motion blur are unchanged. Opaque PNG skips drawElement, whose verification and worker-encode paths are JPEG-only. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(engine): add 4:4:4 chroma option to getEncoderPreset getEncoderPreset takes an optional chromaSubsampling ("420" by default). "444" returns yuv444p for SDR MP4, so libx264 encodes the High 4:4:4 Predictive profile and odd sizes need no even padding. WebM, MOV and HDR presets ignore it. The ChromaSubsampling type is exported for the producer. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(producer): chromaSubsampling render option with lossless png capture RenderConfig.chromaSubsampling ("420" by default) opts an SDR MP4 render into 4:4:4. "444" encodes libx264 yuv444p and captures every frame as opaque PNG: Chrome's quality-100 JPEG is already 4:2:0 on beginFrame and screenshot capture, and drawElement can fall back to screenshot mid-render, so PNG is the only capture that keeps the colour. drawElement is turned off for these renders. The probe and main capture options share resolveCaptureSurface, so they cannot disagree on format, quality or background. Formats other than mp4, GPU encoding and HDR output are rejected before any work starts, auto-detected HDR sources fail before capture, and distributed requests refuse 444. The default render is unchanged. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(producer,studio-server): accept chromaSubsampling on render routes The shared parseEncoderOptions validates chromaSubsampling and answers 400 for "444" with a non-mp4 format, gpu, or force-hdr, so a request that would come back 4:2:0 never starts a render. The Studio render route, both Studio adapters and the producer HTTP server forward it. The producer server also refuses "444" with outputDynamicRange "hdr", which parseEncoderOptions cannot see. No Studio UI control; the option is route-level like crf and hdrMode. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(cli): add --chroma-subsampling flag `hyperframes render --chroma-subsampling 444` opts an SDR MP4 render into full-resolution chroma (yuv444p with lossless PNG capture). The default stays 420. The plan rejects 444 with a non-mp4 format, --gpu or --hdr before anything renders, with a usage error that names the conflicting flag. The value reaches the local render request and, only when it is 444, the Docker argv, so default Docker invocations are unchanged. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: document 4:4:4 chroma subsampling Add a "4:4:4 masters" section to the rendering guide: when to use --chroma-subsampling 444, why it captures PNG, the measured chroma gain (large for text and UI, none for footage and gradients), its limits, and a player compatibility table to be filled in from testing. Document the flag in the CLI reference, the built-in rendering docs and the hyperframes-cli skill reference (with the regenerated skills manifest), and the chromaSubsampling option in the producer docs. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: add 4:4:4 player compatibility results Fill the 4:4:4 compatibility table from testing H.264 High 4:4:4 Predictive output. Chrome 155, Edge 155, VLC 3.0, Safari on iOS 26.6 and Safari 26.6 on macOS play it, and so does AVFoundation on macOS 26.6, the framework QuickTime Player plays through. Firefox 157 on Windows and both Windows media players do not. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: note the measured render cost of 4:4:4 output Replace the vague "slower capture" note with measured numbers: a text and UI composition rendered in about twice the default time, full-frame footage in about three and a half times, because PNG encoding cost grows with image detail. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(producer): reject chromaSubsampling 444 in distributed render config Distributed configs have no chroma field and validateDistributedRenderConfig ignored unknown keys, so a JS caller passing chromaSubsampling: "444" to the Lambda or Cloud Run SDK got a 4:2:0 file with no error. Reject it, and make the rendering guide say so precisely. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(producer): check a 444 render reaches the encoder as yuv444p Every helper had tests, but nothing checked the orchestrator passes chromaSubsampling through, so dropping it from the encoder preset or capture surface would turn 444 renders back into 4:2:0 with all tests green. Render a small fixture with "444" and with the default and check pix_fmt with ffprobe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(producer): move the 444 drawElement gate into a helper Keeps runCompileStage under the fallow complexity threshold. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: keep comment share at or below the merge-base comment-ratchet failed on 11 files this PR touched. Keep the 4:4:4 rationale once in chromaSubsampling.ts, move the distributed-render reason into its error message, and cut the rest. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(producer): check a 444 render captures full-resolution chroma The encoder check alone passes when chromaSubsampling is dropped from the capture surface: frames are captured as JPEG and encoded yuv444p with 4:2:0 colour. Put a red/blue edge at an odd x, inside a 4:2:0 chroma pair, and require the two pixels to differ in Cb. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(producer): trim the chromaSubsampling.ts header to the package comment share Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix: finish switching to capturesAlpha from #6262 The merge that adopted main's transparent / capturesAlpha left these files uncommitted, so resolveCaptureSurface still returned transparentBackground. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(engine): use transparent / capturesAlpha from #6262 main added CaptureOptions.transparent and capturesAlpha (#6262), which do what this PR's transparentBackground did. Use them, keep the PNG check in drawElementWorkerEncodeEligible, and re-pin test-classification.mjs and the skills manifest against current main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(producer): cut the 4:4:4 comment blocks to one to three lines The reasoning lives in the PR description with the measurements. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor: reconcile 4:4:4 chroma with latest main Keep main's video-layer capture overrides, template entry resolution, ProRes profile parsing and blur-differential tests alongside the chroma option, and fold the encoder sub-parsers into one loop. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: keep main's compile-stage tests and regenerate the skills manifest Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
584 lines
20 KiB
TypeScript
584 lines
20 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import {
|
|
buildDockerRunArgs,
|
|
resolveDockerPlatform,
|
|
type DockerRenderOptions,
|
|
} from "./dockerRunArgs.js";
|
|
|
|
const BASE: DockerRenderOptions = {
|
|
fps: { num: 30, den: 1 },
|
|
quality: "standard",
|
|
format: "mp4",
|
|
gpu: false,
|
|
browserGpu: false,
|
|
hdrMode: "auto",
|
|
crf: undefined,
|
|
videoBitrate: undefined,
|
|
quiet: false,
|
|
};
|
|
|
|
const FIXED_INPUT = {
|
|
imageTag: "hyperframes-renderer:0.0.0-test",
|
|
projectDir: "/abs/proj",
|
|
outputDir: "/abs/out",
|
|
outputFilename: "out.mp4",
|
|
// Pin platform in tests so snapshots are arch-independent (otherwise they
|
|
// flip between linux/amd64 and linux/arm64 depending on the host running
|
|
// the test).
|
|
platform: "linux/amd64",
|
|
};
|
|
|
|
describe("buildDockerRunArgs", () => {
|
|
it("preserves an explicit page motion blur override inside Docker", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, pageMotionBlur: "off" },
|
|
});
|
|
expect(
|
|
args.slice(args.indexOf("--page-motion-blur"), args.indexOf("--page-motion-blur") + 2),
|
|
).toEqual(["--page-motion-blur", "off"]);
|
|
expect(buildDockerRunArgs({ ...FIXED_INPUT, options: BASE })).not.toContain(
|
|
"--page-motion-blur",
|
|
);
|
|
});
|
|
it("matches snapshot for the default render", () => {
|
|
expect(buildDockerRunArgs({ ...FIXED_INPUT, options: BASE })).toMatchInlineSnapshot(`
|
|
[
|
|
"run",
|
|
"--rm",
|
|
"--platform",
|
|
"linux/amd64",
|
|
"--shm-size=2g",
|
|
"-v",
|
|
"/abs/proj:/project:ro",
|
|
"-v",
|
|
"/abs/out:/output",
|
|
"hyperframes-renderer:0.0.0-test",
|
|
"/project",
|
|
"--output",
|
|
"/output/out.mp4",
|
|
"--fps",
|
|
"30",
|
|
"--quality",
|
|
"standard",
|
|
"--format",
|
|
"mp4",
|
|
"--no-browser-gpu",
|
|
]
|
|
`);
|
|
});
|
|
|
|
it("tells the container its output reaches a terminal only when the host's stdout is one", () => {
|
|
const flags = (hostStdoutIsTty?: boolean) =>
|
|
buildDockerRunArgs({ ...FIXED_INPUT, hostStdoutIsTty, options: BASE }).slice(0, 4);
|
|
expect(flags(true)).toEqual(["run", "--rm", "-e", "HYPERFRAMES_STDOUT_IS_TTY=1"]);
|
|
expect(flags(false)).toEqual(["run", "--rm", "--platform", "linux/amd64"]);
|
|
expect(flags(undefined)).toEqual(["run", "--rm", "--platform", "linux/amd64"]);
|
|
});
|
|
|
|
it("forwards --chroma-subsampling only for 4:4:4, keeping the default argv unchanged", () => {
|
|
const args = (chromaSubsampling?: "420" | "444") =>
|
|
buildDockerRunArgs({ ...FIXED_INPUT, options: { ...BASE, chromaSubsampling } });
|
|
const at = args("444").indexOf("--chroma-subsampling");
|
|
expect(at).toBeGreaterThan(-1);
|
|
expect(args("444")[at + 1]).toBe("444");
|
|
expect(args("420")).toEqual(args(undefined));
|
|
expect(args("420")).not.toContain("--chroma-subsampling");
|
|
});
|
|
|
|
it("omits --workers when auto sizing should happen inside the container", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(args).not.toContain("--workers");
|
|
});
|
|
|
|
it("matches snapshot when every renderer flag is enabled", () => {
|
|
expect(
|
|
buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: {
|
|
...BASE,
|
|
gpu: true,
|
|
hdrMode: "force-hdr",
|
|
crf: 18,
|
|
videoBitrate: undefined,
|
|
quiet: true,
|
|
},
|
|
}),
|
|
).toMatchInlineSnapshot(`
|
|
[
|
|
"run",
|
|
"--rm",
|
|
"--platform",
|
|
"linux/amd64",
|
|
"--shm-size=2g",
|
|
"--gpus",
|
|
"all",
|
|
"-v",
|
|
"/abs/proj:/project:ro",
|
|
"-v",
|
|
"/abs/out:/output",
|
|
"hyperframes-renderer:0.0.0-test",
|
|
"/project",
|
|
"--output",
|
|
"/output/out.mp4",
|
|
"--fps",
|
|
"30",
|
|
"--quality",
|
|
"standard",
|
|
"--format",
|
|
"mp4",
|
|
"--crf",
|
|
"18",
|
|
"--quiet",
|
|
"--gpu",
|
|
"--no-browser-gpu",
|
|
"--hdr",
|
|
]
|
|
`);
|
|
});
|
|
|
|
// Regression for the original PR feedback: --hdr was silently dropped from
|
|
// the docker arg array. Keep this assertion explicit (in addition to the
|
|
// snapshot above) so the failure message points directly at the flag.
|
|
it("forwards --hdr to the container when hdrMode is force-hdr", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, hdrMode: "force-hdr" },
|
|
});
|
|
expect(args).toContain("--hdr");
|
|
expect(args).not.toContain("--sdr");
|
|
});
|
|
|
|
it("forwards --sdr to the container when hdrMode is force-sdr", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, hdrMode: "force-sdr" },
|
|
});
|
|
expect(args).toContain("--sdr");
|
|
expect(args).not.toContain("--hdr");
|
|
});
|
|
|
|
it("omits --hdr and --sdr when hdrMode is auto", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(args).not.toContain("--hdr");
|
|
expect(args).not.toContain("--sdr");
|
|
});
|
|
|
|
it("requests host GPU passthrough only when gpu is enabled", () => {
|
|
const off = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(off).not.toContain("--gpus");
|
|
expect(off).not.toContain("--gpu");
|
|
|
|
const on = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, gpu: true },
|
|
});
|
|
// `--gpus all` is a docker run flag (host passthrough); `--gpu` is the
|
|
// hyperframes CLI flag forwarded into the container — both must be set.
|
|
expect(on).toContain("--gpus");
|
|
expect(on).toContain("all");
|
|
expect(on).toContain("--gpu");
|
|
});
|
|
|
|
it("forces software browser capture inside Docker", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(args).toContain("--no-browser-gpu");
|
|
});
|
|
|
|
it("forwards every renderer-shaped option (regression tripwire for silent drops)", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: {
|
|
fps: { num: 60, den: 1 },
|
|
quality: "high",
|
|
format: "webm",
|
|
workers: 8,
|
|
gpu: true,
|
|
browserGpu: false,
|
|
hdrMode: "force-hdr",
|
|
crf: 16,
|
|
vp9CpuUsed: 2,
|
|
videoBitrate: undefined,
|
|
videoFrameFormat: "png",
|
|
quiet: true,
|
|
debug: true,
|
|
bestEffort: false,
|
|
entryFile: "compositions/intro.html",
|
|
experimentalFastCapture: true,
|
|
},
|
|
});
|
|
// Each value must reach the container exactly once. If a future option
|
|
// is added but only wired through to renderLocal, this test forces the
|
|
// author to update buildDockerRunArgs (and add a check here) too.
|
|
expect(args).toContain("60");
|
|
expect(args).toContain("high");
|
|
expect(args).toContain("webm");
|
|
expect(args).toContain("8");
|
|
expect(args).toContain("--crf");
|
|
expect(args).toContain("16");
|
|
expect(args).toContain("--vp9-cpu-used");
|
|
expect(args).toContain("2");
|
|
expect(args).toContain("--video-frame-format");
|
|
expect(args).toContain("png");
|
|
expect(args).toContain("--quiet");
|
|
expect(args).toContain("--debug");
|
|
expect(args).toContain("--no-best-effort");
|
|
expect(args).toContain("--gpu");
|
|
expect(args).toContain("--no-browser-gpu");
|
|
expect(args).toContain("--hdr");
|
|
expect(args).toContain("--composition");
|
|
expect(args).toContain("compositions/intro.html");
|
|
expect(args).toContain("--experimental-fast-capture");
|
|
});
|
|
|
|
it("forwards only an explicit strict-readiness opt-in", () => {
|
|
const compatible = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, bestEffort: true },
|
|
});
|
|
expect(compatible).not.toContain("--best-effort");
|
|
expect(compatible).not.toContain("--no-best-effort");
|
|
|
|
const strict = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, bestEffort: false },
|
|
});
|
|
expect(strict).toContain("--no-best-effort");
|
|
});
|
|
|
|
it("forwards --experimental-fast-capture only when enabled", () => {
|
|
const on = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, experimentalFastCapture: true },
|
|
});
|
|
expect(on).toContain("--experimental-fast-capture");
|
|
|
|
const off = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, experimentalFastCapture: false },
|
|
});
|
|
expect(off).not.toContain("--experimental-fast-capture");
|
|
|
|
const absent = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(absent).not.toContain("--experimental-fast-capture");
|
|
});
|
|
|
|
it("forwards --format png-sequence to the container", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
outputFilename: "frames",
|
|
options: { ...BASE, format: "png-sequence" },
|
|
});
|
|
const formatIdx = args.indexOf("--format");
|
|
expect(formatIdx).toBeGreaterThanOrEqual(0);
|
|
expect(args[formatIdx + 1]).toBe("png-sequence");
|
|
});
|
|
|
|
it("forwards --format hls and --hls-segment-seconds to the container", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
outputFilename: "stream",
|
|
options: { ...BASE, format: "hls", hlsSegmentSeconds: 6 },
|
|
});
|
|
const formatIdx = args.indexOf("--format");
|
|
const segmentIdx = args.indexOf("--hls-segment-seconds");
|
|
expect(args[formatIdx + 1]).toBe("hls");
|
|
expect(args[segmentIdx + 1]).toBe("6");
|
|
});
|
|
|
|
it("omits --hls-segment-seconds for other formats", () => {
|
|
expect(buildDockerRunArgs({ ...FIXED_INPUT, options: BASE })).not.toContain(
|
|
"--hls-segment-seconds",
|
|
);
|
|
});
|
|
|
|
it("forwards --format gif and --gif-loop to the container", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
outputFilename: "demo.gif",
|
|
options: { ...BASE, format: "gif", gifLoop: 0 },
|
|
});
|
|
const formatIdx = args.indexOf("--format");
|
|
const loopIdx = args.indexOf("--gif-loop");
|
|
expect(formatIdx).toBeGreaterThanOrEqual(0);
|
|
expect(args[formatIdx + 1]).toBe("gif");
|
|
expect(loopIdx).toBeGreaterThanOrEqual(0);
|
|
expect(args[loopIdx + 1]).toBe("0");
|
|
});
|
|
|
|
it("forwards the delivery options to the container only when set", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, keyframeIntervalSeconds: 2, maxBitrate: "8M", bufferSize: "12M" },
|
|
});
|
|
const after = (flag: string) => args[args.indexOf(flag) + 1];
|
|
expect(after("--keyframe-interval")).toBe("2");
|
|
expect(after("--max-bitrate")).toBe("8M");
|
|
expect(after("--buffer-size")).toBe("12M");
|
|
const plain = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(plain).not.toContain("--max-bitrate");
|
|
expect(plain).not.toContain("--keyframe-interval");
|
|
});
|
|
|
|
it("forwards --video-bitrate to the container when set", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, videoBitrate: "10M" },
|
|
});
|
|
expect(args).toContain("--video-bitrate");
|
|
expect(args).toContain("10M");
|
|
expect(args).not.toContain("--crf");
|
|
});
|
|
|
|
it("forwards --video-frame-format to the container when set to png", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, videoFrameFormat: "png" },
|
|
});
|
|
expect(args).toContain("--video-frame-format");
|
|
expect(args).toContain("png");
|
|
});
|
|
|
|
it("omits --video-frame-format when it is auto or unset", () => {
|
|
expect(buildDockerRunArgs({ ...FIXED_INPUT, options: BASE })).not.toContain(
|
|
"--video-frame-format",
|
|
);
|
|
expect(
|
|
buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, videoFrameFormat: "auto" },
|
|
}),
|
|
).not.toContain("--video-frame-format");
|
|
});
|
|
|
|
it("forwards --variables JSON to the container when set", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, variables: { title: "Hello", n: 3 } },
|
|
});
|
|
const idx = args.indexOf("--variables");
|
|
expect(idx).toBeGreaterThan(-1);
|
|
expect(args[idx + 1]).toBe('{"title":"Hello","n":3}');
|
|
});
|
|
|
|
it("omits --variables when none provided", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(args).not.toContain("--variables");
|
|
});
|
|
|
|
it("omits --variables when payload is empty", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, variables: {} },
|
|
});
|
|
expect(args).not.toContain("--variables");
|
|
});
|
|
|
|
it("forwards --composition to the container when entryFile is set", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, entryFile: "compositions/intro.html" },
|
|
});
|
|
const idx = args.indexOf("--composition");
|
|
expect(idx).toBeGreaterThan(-1);
|
|
expect(args[idx + 1]).toBe("compositions/intro.html");
|
|
});
|
|
|
|
it("omits --composition when entryFile is not set", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(args).not.toContain("--composition");
|
|
});
|
|
|
|
it("forwards --browser-timeout in seconds when pageNavigationTimeoutMs is set", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, pageNavigationTimeoutMs: 180_000 },
|
|
});
|
|
const idx = args.indexOf("--browser-timeout");
|
|
expect(idx).toBeGreaterThan(-1);
|
|
// CLI flag takes seconds; engine takes ms — the docker bridge converts
|
|
// back to seconds so the in-container CLI re-parses it consistently.
|
|
expect(args[idx + 1]).toBe("180");
|
|
});
|
|
|
|
it("omits --browser-timeout when pageNavigationTimeoutMs is not set", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(args).not.toContain("--browser-timeout");
|
|
});
|
|
|
|
it("forwards protocol and player-ready timeouts without unit conversion", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: {
|
|
...BASE,
|
|
protocolTimeoutMs: 240_000,
|
|
playerReadyTimeoutMs: 90_000,
|
|
},
|
|
});
|
|
|
|
expect(args).toContain("--protocol-timeout");
|
|
expect(args[args.indexOf("--protocol-timeout") + 1]).toBe("240000");
|
|
expect(args).toContain("--player-ready-timeout");
|
|
expect(args[args.indexOf("--player-ready-timeout") + 1]).toBe("90000");
|
|
});
|
|
|
|
it("forwards rational --fps verbatim (NTSC 30000/1001)", () => {
|
|
// Regression for the fps fraction-syntax feature: the rational form must
|
|
// survive the host → container hop as a single `30000/1001` argument so
|
|
// the in-container CLI re-parses it as exact NTSC, not 29.97 decimal.
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, fps: { num: 30000, den: 1001 } },
|
|
});
|
|
const fpsIdx = args.indexOf("--fps");
|
|
expect(fpsIdx).toBeGreaterThanOrEqual(0);
|
|
expect(args[fpsIdx + 1]).toBe("30000/1001");
|
|
});
|
|
|
|
it("forwards integer --fps as a bare integer string", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, fps: { num: 60, den: 1 } },
|
|
});
|
|
const fpsIdx = args.indexOf("--fps");
|
|
expect(fpsIdx).toBeGreaterThanOrEqual(0);
|
|
expect(args[fpsIdx + 1]).toBe("60");
|
|
});
|
|
|
|
it("forwards --resolution to the container when outputResolution is set", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, outputResolution: "landscape-4k" },
|
|
});
|
|
const idx = args.indexOf("--resolution");
|
|
expect(idx).toBeGreaterThan(-1);
|
|
expect(args[idx + 1]).toBe("landscape-4k");
|
|
});
|
|
|
|
it("forwards the RAW aspect-agnostic alias `1080p` verbatim (does not pre-normalize to `landscape`)", () => {
|
|
// Miga R2 important note on PR #2529: Docker correctness now depends on
|
|
// forwarding the raw alias string, not the canonical preset — the
|
|
// in-container CLI re-runs `normalizeResolutionFlag` +
|
|
// `isAspectAgnosticResolutionAlias` so aspect-agnostic aliases keep
|
|
// their orientation-adaptive behavior. A future refactor that
|
|
// silently substitutes the normalized preset here would restore the
|
|
// portrait-only Docker failure this test pins against.
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, outputResolution: "1080p" },
|
|
});
|
|
const idx = args.indexOf("--resolution");
|
|
expect(idx).toBeGreaterThan(-1);
|
|
expect(args[idx + 1]).toBe("1080p");
|
|
// Belt-and-braces: the normalized preset name must NOT slip in as a
|
|
// second value that would confuse citty parsing on the container side.
|
|
expect(args).not.toContain("landscape");
|
|
});
|
|
|
|
it("omits --resolution when outputResolution is not set", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(args).not.toContain("--resolution");
|
|
});
|
|
|
|
it("forwards --no-page-side-compositing when pageSideCompositing is false", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, pageSideCompositing: false },
|
|
});
|
|
expect(args).toContain("--no-page-side-compositing");
|
|
});
|
|
|
|
it("keeps Docker debug artifacts under the mounted output directory", () => {
|
|
const args = buildDockerRunArgs({
|
|
...FIXED_INPUT,
|
|
options: { ...BASE, debug: true },
|
|
});
|
|
const envIdx = args.indexOf("PRODUCER_RENDERS_DIR=/output/renders");
|
|
const imageIdx = args.indexOf(FIXED_INPUT.imageTag);
|
|
expect(envIdx).toBeGreaterThan(-1);
|
|
expect(envIdx).toBeLessThan(imageIdx);
|
|
expect(args).toContain("--debug");
|
|
});
|
|
|
|
it("omits --no-page-side-compositing when pageSideCompositing is not explicitly false", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
expect(args).not.toContain("--no-page-side-compositing");
|
|
});
|
|
|
|
// Regression for #1193: an arm64 host (Apple Silicon) was being pinned to
|
|
// linux/amd64, which forced qemu emulation of chrome-headless-shell and
|
|
// produced either navigation timeouts or chrome SEGVs. Each host arch must
|
|
// land in its native --platform value.
|
|
it("emits linux/arm64 when host platform is arm64", () => {
|
|
const args = buildDockerRunArgs({
|
|
imageTag: "hyperframes-renderer:0.0.0-test",
|
|
projectDir: "/abs/proj",
|
|
outputDir: "/abs/out",
|
|
outputFilename: "out.mp4",
|
|
platform: "linux/arm64",
|
|
options: BASE,
|
|
});
|
|
const idx = args.indexOf("--platform");
|
|
expect(idx).toBeGreaterThanOrEqual(0);
|
|
expect(args[idx + 1]).toBe("linux/arm64");
|
|
});
|
|
|
|
it("emits linux/amd64 when platform is explicitly amd64", () => {
|
|
const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
|
|
const idx = args.indexOf("--platform");
|
|
expect(idx).toBeGreaterThanOrEqual(0);
|
|
expect(args[idx + 1]).toBe("linux/amd64");
|
|
});
|
|
});
|
|
|
|
describe("resolveDockerPlatform", () => {
|
|
it("maps arm64 hosts to linux/arm64", () => {
|
|
expect(resolveDockerPlatform("arm64", {})).toBe("linux/arm64");
|
|
});
|
|
|
|
it("maps x64 hosts to linux/amd64", () => {
|
|
expect(resolveDockerPlatform("x64", {})).toBe("linux/amd64");
|
|
});
|
|
|
|
it("treats unknown architectures as linux/amd64 (safe default)", () => {
|
|
expect(resolveDockerPlatform("riscv64", {})).toBe("linux/amd64");
|
|
});
|
|
|
|
// Regression guard: the production call site is `resolveDockerPlatform()`
|
|
// with no args. If a refactor drops either default parameter, every other
|
|
// arch-mapping test would still pass — this one fails loudly.
|
|
it("uses process.arch and process.env when called with no arguments", () => {
|
|
const result = resolveDockerPlatform();
|
|
// Must equal the explicit-arg form (env override notwithstanding, which
|
|
// wouldn't be set in the test runner unless deliberately stubbed).
|
|
const expected = process.env.HYPERFRAMES_DOCKER_PLATFORM
|
|
? process.env.HYPERFRAMES_DOCKER_PLATFORM
|
|
: resolveDockerPlatform(process.arch, {});
|
|
expect(result).toBe(expected);
|
|
});
|
|
|
|
it("honors HYPERFRAMES_DOCKER_PLATFORM override on an arm64 host (Rosetta-Node / parity-regen escape hatch)", () => {
|
|
expect(resolveDockerPlatform("arm64", { HYPERFRAMES_DOCKER_PLATFORM: "linux/amd64" })).toBe(
|
|
"linux/amd64",
|
|
);
|
|
});
|
|
|
|
it("honors HYPERFRAMES_DOCKER_PLATFORM override on an amd64 host", () => {
|
|
expect(resolveDockerPlatform("x64", { HYPERFRAMES_DOCKER_PLATFORM: "linux/arm64" })).toBe(
|
|
"linux/arm64",
|
|
);
|
|
});
|
|
|
|
it("trims whitespace from HYPERFRAMES_DOCKER_PLATFORM and ignores empty override", () => {
|
|
expect(resolveDockerPlatform("arm64", { HYPERFRAMES_DOCKER_PLATFORM: " linux/amd64 " })).toBe(
|
|
"linux/amd64",
|
|
);
|
|
// Empty/whitespace-only override falls back to arch detection — important
|
|
// for shells where `export FOO=""` would otherwise pin platform to "".
|
|
expect(resolveDockerPlatform("arm64", { HYPERFRAMES_DOCKER_PLATFORM: "" })).toBe("linux/arm64");
|
|
expect(resolveDockerPlatform("arm64", { HYPERFRAMES_DOCKER_PLATFORM: " " })).toBe(
|
|
"linux/arm64",
|
|
);
|
|
});
|
|
});
|