Skip to content

Write HTML. Render video. Built for agents.

feat(cloud): 4K renders work for transparent MOV and WebM (#6045)

Miguel Ángel25126bca6ced
diff --git a/docs/deploy/cloud.mdx b/docs/deploy/cloud.mdx
index e0e93cb735..94d26d5c59 100644
--- a/docs/deploy/cloud.mdx
+++ b/docs/deploy/cloud.mdx
@@ -54,7 +54,7 @@ hyperframes cloud render --resolution 4k
```
<Warning>
- 4K is billed at 1.5× and supports MP4 only. WebM and MOV use the alpha-capable path, which does not support 4K supersampling.
+ 4K is billed at 1.5×.
</Warning>
## Check what will upload
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index 6377777684..1b142ce652 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -1833,7 +1833,7 @@ Render parameters mirror local `hyperframes render` where they overlap:
| `--fps` | `30` | Integer, 1–240 |
| `--quality` | `standard` | `draft`, `standard`, or `high` |
| `--format` | `mp4` | `mp4`, `webm`, or `mov` |
-| `--resolution` | `1080p` | `1080p` or `4k`. 4k bills at 1.5× and cannot combine with `webm` or `mov`. |
+| `--resolution` | `1080p` | `1080p` or `4k`. 4k bills at 1.5×. |
| `--aspect-ratio` | auto | `16:9`, `9:16`, or `1:1`. Auto-detected from a local project's `data-width` and `data-height`, so you rarely need it. The renderer cannot reshape a composition — a value that disagrees with the authored ratio is an error. With `--asset-id` or `--url` the server defaults to `16:9`. |
| `--composition` / `-c` | `index.html` | Entry HTML file inside the zip |
| `--variables` | — | Inline JSON overriding `data-composition-variables` |
diff --git a/packages/cli/src/commands/cloud/render.test.ts b/packages/cli/src/commands/cloud/render.test.ts
index 52eb0cb561..dfc42e4474 100644
--- a/packages/cli/src/commands/cloud/render.test.ts
+++ b/packages/cli/src/commands/cloud/render.test.ts
@@ -9,7 +9,6 @@ import {
assertArchiveFits,
resolveAspectRatioForSubmit,
validateDryRunSource,
- validateResolutionFormatCombo,
type ProjectInputSource,
} from "./render.js";
import { CliRuntimeError } from "../../utils/commandResult.js";
@@ -36,19 +35,6 @@ function writeComposition(width: number, height: number): string {
return dir;
}
-describe("validateResolutionFormatCombo", () => {
- it("rejects 4k + webm and 4k + mov", () => {
- expect(() => validateResolutionFormatCombo("4k", "webm")).toThrow(CliRuntimeError);
- expect(() => validateResolutionFormatCombo("4k", "mov")).toThrow(CliRuntimeError);
- });
-
- it("allows 4k + mp4 and 1080p + any format", () => {
- expect(() => validateResolutionFormatCombo("4k", "mp4")).not.toThrow();
- expect(() => validateResolutionFormatCombo("1080p", "webm")).not.toThrow();
- expect(() => validateResolutionFormatCombo(undefined, undefined)).not.toThrow();
- });
-});
-
describe("validateDryRunSource", () => {
it("accepts a local directory and rejects already-uploaded sources", () => {
expect(() => validateDryRunSource({ kind: "dir", dir: "." }, true)).not.toThrow();
diff --git a/packages/cli/src/commands/cloud/render.ts b/packages/cli/src/commands/cloud/render.ts
index 9b0e96b64d..a43dce0803 100644
--- a/packages/cli/src/commands/cloud/render.ts
+++ b/packages/cli/src/commands/cloud/render.ts
@@ -234,10 +234,6 @@ export default defineCommand({
});
validateDryRunSource(project, args["dry-run"] ?? false);
- // 4k supersampling runs through the alpha-incompatible screenshot path;
- // reject the combination client-side instead of failing mid-render.
- validateResolutionFormatCombo(resolution, format);
-
// Aspect ratio is derived from the composition's authored dimensions: for
// a local dir we parse the entry HTML and auto-detect, so the user rarely
// needs --aspect-ratio at all. When they DO pass it, we validate it
@@ -498,25 +494,6 @@ export function resolveAspectRatioForSubmit(
return detection.kind === "matched" ? detection.aspectRatio : undefined;
}
-/**
- * 4k output is produced by supersampling through the screenshot capture path,
- * which doesn't support an alpha channel. webm/mov carry alpha, so the
- * combination can't be satisfied — reject it before upload.
- */
-export function validateResolutionFormatCombo(
- resolution: "1080p" | "4k" | undefined,
- format: "mp4" | "webm" | "mov" | undefined,
-): void {
- if (resolution === "4k" && (format === "webm" || format === "mov")) {
- errorBox(
- "Unsupported combination",
- `--resolution 4k cannot be combined with --format ${format}.`,
- "The alpha (webm/mov) capture path doesn't support 4k supersampling. Render 4k as mp4, or render alpha at composition resolution.",
- );
- failCommand();
- }
-}
-
const ASPECT_FALLBACK_HINT =
"server will default aspect_ratio to 16:9. Pass --aspect-ratio to override.";
diff --git a/packages/producer/src/server.test.ts b/packages/producer/src/server.test.ts
index 942853c231..e20a86778c 100644
--- a/packages/producer/src/server.test.ts
+++ b/packages/producer/src/server.test.ts
@@ -160,15 +160,16 @@ describe("prepareRenderBody — validation", () => {
expect((result as { error: string }).error).toContain("must be a string preset");
});
- it("rejects outputResolution combined with an alpha format (webm/mov)", async () => {
+ it("accepts outputResolution with an alpha format (webm/mov)", async () => {
for (const format of ["webm", "mov"]) {
const result = await prepareRenderBody({
outputResolution: "4k",
format,
html: "<html></html>",
});
- expect(result).toHaveProperty("error");
- expect((result as { error: string }).error).toContain("can't supersample");
+ expect(result).toHaveProperty("prepared");
+ const { input } = (result as { prepared: { input: Record<string, unknown> } }).prepared;
+ expect(input.outputResolution).toBe("landscape-4k");
}
});
diff --git a/packages/producer/src/server.ts b/packages/producer/src/server.ts
index b56f3fa24c..1a7ad26d95 100644
--- a/packages/producer/src/server.ts
+++ b/packages/producer/src/server.ts
@@ -376,10 +376,7 @@ function validateRenderOverrides(body: Record<string, unknown>): string | undefi
/**
* Validate an explicitly-supplied `outputResolution`. Rejects (a) non-string
* values, which parseRenderOverrides would otherwise silently coerce to
- * `undefined`; (b) unknown presets; and (c) the alpha-format combination —
- * outputResolution drives deviceScaleFactor supersampling, which the webm/mov
- * capture path can't apply (resolveDeviceScaleFactor throws mid-render), so we
- * reject it here for a clean 400 regardless of which caller sent it.
+ * `undefined`; and (b) unknown presets.
*/
function validateOutputResolutionOverride(body: Record<string, unknown>): string | undefined {
if (body.outputResolution === undefined) return undefined;
@@ -390,9 +387,6 @@ function validateOutputResolutionOverride(body: Record<string, unknown>): string
if (body.outputResolution.trim().length > 0 && normalized === undefined) {
return `Invalid outputResolution "${body.outputResolution}". Must be one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k (aliases: 1080p, 4k, …).`;
}
- if (normalized !== undefined && (body.format === "webm" || body.format === "mov")) {
- return `outputResolution is not supported with format "${body.format}": the alpha (webm/mov) capture path can't supersample. Use format "mp4", or omit outputResolution to render at the composition's native dimensions.`;
- }
return undefined;
}
diff --git a/packages/producer/src/services/distributed/renderChunk.test.ts b/packages/producer/src/services/distributed/renderChunk.test.ts
index 1e22cb10f2..0883fdb1c1 100644
--- a/packages/producer/src/services/distributed/renderChunk.test.ts
+++ b/packages/producer/src/services/distributed/renderChunk.test.ts
@@ -792,6 +792,70 @@ describe("renderChunk() — a video whose frames cannot be extracted", () => {
}, 120_000);
});
+describe("renderChunk() — an alpha format at a larger output resolution", () => {
+ it("supersamples a transparent composition and keeps its alpha", async () => {
+ if (!hasChrome) {
+ console.warn(
+ "[renderChunk.test] skipping alpha supersample test — chrome-headless-shell not available",
+ );
+ return;
+ }
+ const projectDir = join(runRoot, "project-alpha-supersample");
+ mkdirSync(projectDir, { recursive: true });
+ writeFileSync(
+ join(projectDir, "index.html"),
+ `<!doctype html><html><body style="margin:0;background:transparent">
+ <div data-composition-id="root" data-no-timeline data-width="320" data-height="180" data-duration="0.1">
+ <div style="position:absolute;left:80px;top:45px;width:160px;height:90px;background:#3a7"></div>
+ </div></body></html>`,
+ "utf-8",
+ );
+ const planDir = join(runRoot, "plan-alpha-supersample");
+ await planV2(
+ projectDir,
+ {
+ fps: 30,
+ width: 320,
+ height: 180,
+ format: "mov",
+ chunkSize: 30,
+ outputResolution: "landscape",
+ },
+ planDir,
+ );
+ const chunkDir = join(runRoot, "chunk0-alpha-supersample");
+ materializePlanV2Target(planDir, { role: "chunk", chunkIndex: 0 }, chunkDir);
+ const out = join(runRoot, "chunk0-alpha-supersample.mov");
+ try {
+ await renderChunk(chunkDir, 0, out);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ if (!HOST_CHROME_FAILURE_PATTERNS.test(message)) throw err;
+ console.warn(
+ "[renderChunk.test] skipping alpha supersample test — host Chrome stack can't render:",
+ message.slice(0, 240),
+ );
+ return;
+ }
+ const probe = spawnSync("ffprobe", [
+ ...["-v", "error", "-select_streams", "v:0"],
+ ...["-show_entries", "stream=width,height,pix_fmt", "-of", "csv=p=0", "--", out],
+ ]);
+ expect(probe.stdout.toString().trim()).toMatch(/^1920,1080,yuva/);
+ const frame = spawnSync(
+ "ffmpeg",
+ [
+ ...["-v", "error", "-i", out, "-frames:v", "1"],
+ ...["-vf", "format=rgba", "-f", "rawvideo", "-"],
+ ],
+ { maxBuffer: 1920 * 1080 * 4 },
+ ).stdout;
+ const alphaAt = (x: number, y: number) => frame[(y * 1920 + x) * 4 + 3];
+ expect(alphaAt(10, 10)).toBe(0);
+ expect(alphaAt(960, 540)).toBe(255);
+ }, 120_000);
+});
+
describe("renderChunk() — frameRange", () => {
// A box sliding across the frame, so every frame differs and a misplaced,
// dropped or repeated frame changes the assembled output.