Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(cloud): 4K renders work for transparent MOV and WebM (#6045)
Miguel Ángel25126bca6ced
diff --git a/docs/deploy/cloud.mdx b/docs/deploy/cloud.mdxindex 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 uploaddiff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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>): stringif (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.tsindex 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.