From dd0c163d2b719b1df97b7e9048e246525fe4711a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 5 Sep 2026 13:28:11 +0000
Subject: [PATCH] fix(render): reject unsupported ProRes rate controls

---
 docs/guides/rendering.mdx                     |  3 ++
 docs/packages/cli.mdx                         |  6 ++--
 packages/cli/src/commands/render.ts           |  9 ++++--
 packages/cli/src/commands/render/plan.test.ts | 28 +++++++++++++++++++
 packages/cli/src/commands/render/plan.ts      |  9 ++++++
 5 files changed, 49 insertions(+), 6 deletions(-)

diff --git a/docs/guides/rendering.mdx b/docs/guides/rendering.mdx
index 66da8cc742..4c23fc9a45 100644
--- a/docs/guides/rendering.mdx
+++ b/docs/guides/rendering.mdx
@@ -95,6 +95,9 @@ browser already supports the source or you are diagnosing the proxy itself.
 ## Choose quality and frame rate
 
 The default `standard` quality is the right choice for most finished work.
+MOV is an alpha-preserving editing intermediate and always uses the fixed
+ProRes 4444 profile. `--crf` and `--video-bitrate` do not map to that profile
+and are rejected for MOV; choose MP4 or WebM when you need those controls.
 
 ```bash
 # Faster review version
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index d0df2674a9..ffcae38ea7 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -857,7 +857,7 @@ The flags that come up most:
 | `--composition, -c` | `index.html`                  | Render a different composition file. Sub-compositions using `<template>` wrappers must be referenced from `index.html` via `data-composition-src`. |
 | `--format`          | `mp4`                         | `mp4`, `webm`, `mov`, `gif`, or `png-sequence`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory.                 |
 | `--fps, -f`         | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97                                                                                            |
-| `--quality, -q`     | `standard`                    | `draft`, `standard`, or `high`. Drives CRF and bitrate.                                                                                            |
+| `--quality, -q`     | `standard`                    | `draft`, `standard`, or `high`. Drives MP4/WebM encoder settings; MOV always uses the fixed alpha-preserving ProRes 4444 profile.                  |
 | `--resolution`      | the composition's size        | Supersample to a preset via Chrome's `deviceScaleFactor`. Aspect ratio must match and the scale must be a whole multiple. Not with `--hdr`. See [4K rendering](/guides/4k-rendering). |
 | `--docker`          | off                           | Render inside Docker for [deterministic output](/concepts/determinism)                                                                             |
 | `--variables`       | —                             | JSON object merged over the composition's `data-composition-variables` defaults                                                                    |
@@ -869,8 +869,8 @@ Quality and file size:
 
 | Flag                   | Default         | Description                                                                                              |
 | ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
-| `--crf`                | from `--quality`| Override encoder CRF, 0–51. Lower is better quality. Not with `--video-bitrate`.                          |
-| `--video-bitrate`      | from `--quality`| Target bitrate, e.g. `10M` or `5000k`. Not with `--crf`.                                                  |
+| `--crf`                | from `--quality`| Override MP4/WebM encoder CRF, 0–51. Lower is better quality. Not with `--video-bitrate`; rejected for MOV. |
+| `--video-bitrate`      | from `--quality`| Target MP4/WebM bitrate, e.g. `10M` or `5000k`. Not with `--crf`; rejected for MOV.                       |
 | `--vp9-cpu-used`       | encoder default | libvpx-vp9 speed/quality trade-off for WebM, -8 to 8. Env: `PRODUCER_VP9_CPU_USED`.                       |
 | `--gif-loop`           | `0`             | GIF loop count, `0` for forever. Range 0–65535, `--format gif` only.                                     |
 | `--video-frame-format` | `auto`          | How source video frames are extracted: `auto`, `jpg`, `png`. Use `png` for UI recordings, screen captures, and other colour-sensitive footage. |
diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts
index f53af70355..f902971d4d 100644
--- a/packages/cli/src/commands/render.ts
+++ b/packages/cli/src/commands/render.ts
@@ -138,7 +138,8 @@ export default defineCommand({
     quality: {
       type: "string",
       alias: "q",
-      description: "Quality: draft, standard, high",
+      description:
+        "Quality: draft, standard, high. MOV always uses the fixed alpha-preserving ProRes 4444 profile.",
       default: "standard",
     },
     skill: {
@@ -191,11 +192,13 @@ export default defineCommand({
     },
     crf: {
       type: "string",
-      description: "Override encoder CRF. Mutually exclusive with --video-bitrate.",
+      description:
+        "Override MP4/WebM encoder CRF. Mutually exclusive with --video-bitrate; unsupported for MOV.",
     },
     "video-bitrate": {
       type: "string",
-      description: "Target video bitrate such as 10M. Mutually exclusive with --crf.",
+      description:
+        "Target MP4/WebM video bitrate such as 10M. Mutually exclusive with --crf; unsupported for MOV.",
     },
     "vp9-cpu-used": {
       type: "string",
diff --git a/packages/cli/src/commands/render/plan.test.ts b/packages/cli/src/commands/render/plan.test.ts
index 7aed45f5e5..da3a058a6c 100644
--- a/packages/cli/src/commands/render/plan.test.ts
+++ b/packages/cli/src/commands/render/plan.test.ts
@@ -89,6 +89,34 @@ describe("createRenderPlan", () => {
     expect(() => createRenderPlan({ dir: projectDir, quality: "maximum" })).toThrow(CliUsageError);
   });
 
+  it.each([
+    ["--crf", { crf: "18" }],
+    ["--video-bitrate", { "video-bitrate": "78M" }],
+  ])("rejects unsupported %s rate control for ProRes MOV", (flag, encoderArgs) => {
+    expect(() => createRenderPlan({ dir: projectDir, format: "mov", ...encoderArgs })).toThrow(
+      CliUsageError,
+    );
+    expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(flag);
+    expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(
+      "fixed alpha-preserving ProRes 4444",
+    );
+  });
+
+  it("keeps MOV quality tiers on the fixed alpha-preserving profile", () => {
+    const plan = createRenderPlan({ dir: projectDir, format: "mov", quality: "high" });
+
+    expect(plan).toMatchObject({ format: "mov", quality: "high" });
+    expect(plan.crf).toBeUndefined();
+    expect(plan.videoBitrate).toBeUndefined();
+  });
+
+  it("keeps MP4 and WebM rate controls available", () => {
+    expect(createRenderPlan({ dir: projectDir, format: "mp4", crf: "18" }).crf).toBe(18);
+    expect(
+      createRenderPlan({ dir: projectDir, format: "webm", "video-bitrate": "10M" }).videoBitrate,
+    ).toBe("10M");
+  });
+
   it("rejects batch and single-render variables before execution", () => {
     expect(() =>
       createRenderPlan({ dir: projectDir, batch: "rows.json", variables: '{"name":"Ada"}' }),
diff --git a/packages/cli/src/commands/render/plan.ts b/packages/cli/src/commands/render/plan.ts
index 600a267760..52f2efb0ad 100644
--- a/packages/cli/src/commands/render/plan.ts
+++ b/packages/cli/src/commands/render/plan.ts
@@ -408,6 +408,15 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
     );
     failUsage();
   }
+  if (format === "mov" && (crf !== undefined || videoBitrate !== undefined)) {
+    const flag = crf !== undefined ? "--crf" : "--video-bitrate";
+    errorBox(
+      "Unsupported ProRes rate control",
+      `${flag} does not apply to MOV. MOV uses a fixed alpha-preserving ProRes 4444 profile.`,
+      `Remove ${flag}, or choose MP4/WebM when you need CRF or target-bitrate control.`,
+    );
+    failUsage();
+  }
 
   const quiet = args.quiet ?? false;
   const batchJson = args.json ?? false;