From 794ebeb89f35e082c9fa7a4633fcb07a882434bd Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 9 Jun 2026 13:13:06 -0700
Subject: [PATCH] chore(ci): add fast-capture video validation workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Renders a video composition baseline-vs-fast on a native amd64 Linux runner and
asserts the fast (drawElementImage) output matches via PSNR — validating the
BeginFrame paint path captures video, which couldn't be checked locally
(macOS has no BeginFrame; Docker-on-rosetta hung).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .fallowrc.jsonc                               |  1 +
 .github/workflows/fast-video-validation.yml   | 49 ++++++++++++
 .../producer/scripts/validate-fast-video.ts   | 77 +++++++++++++++++++
 3 files changed, 127 insertions(+)
 create mode 100644 .github/workflows/fast-video-validation.yml
 create mode 100644 packages/producer/scripts/validate-fast-video.ts

diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc
index 878728bcb2..033bcea4b1 100644
--- a/.fallowrc.jsonc
+++ b/.fallowrc.jsonc
@@ -14,6 +14,7 @@
     "packages/producer/src/runtime-conformance.ts",
     "packages/producer/src/benchmark.ts",
     "packages/producer/scripts/generate-font-data.ts",
+    "packages/producer/scripts/validate-fast-video.ts",
     "packages/cli/scripts/generate-font-data.ts",
     "packages/engine/scripts/test-fitTextFontSize-browser.ts",
     "packages/aws-lambda/scripts/*.ts",
diff --git a/.github/workflows/fast-video-validation.yml b/.github/workflows/fast-video-validation.yml
new file mode 100644
index 0000000000..3516a60114
--- /dev/null
+++ b/.github/workflows/fast-video-validation.yml
@@ -0,0 +1,49 @@
+# Validates the experimental fast-capture (drawElementImage) VIDEO path on a
+# native amd64 Linux runner — where chrome-headless-shell's per-frame BeginFrame
+# drives a real paint each frame, so drawElementImage's snapshot is fresh and
+# video captures correctly. This is the one part of the feature that could not be
+# validated locally (macOS has no BeginFrame; Docker-on-rosetta hung).
+# See docs/fast-capture-limitations.md (Limitation 2).
+#
+# Manual trigger: Actions → "Fast-capture video validation" → Run workflow.
+name: Fast-capture video validation
+
+on:
+  workflow_dispatch:
+    inputs:
+      composition:
+        description: Test composition to render (must contain <video>)
+        default: sub-composition-video
+      min_psnr:
+        description: Min fast-vs-baseline PSNR (dB) to pass
+        default: "25"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Build test Docker image (cached)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
+        with:
+          context: .
+          file: Dockerfile.test
+          load: true
+          tags: hyperframes-producer:test
+          cache-from: type=gha,scope=regression-test-image
+          cache-to: type=gha,mode=max,scope=regression-test-image
+
+      - name: Validate fast-capture video (drawElement + BeginFrame)
+        run: |
+          docker run --rm \
+            --security-opt seccomp=unconfined \
+            --shm-size=4g \
+            -e PRODUCER_VALIDATE_COMP='${{ inputs.composition }}' \
+            -e PRODUCER_VALIDATE_MIN_PSNR='${{ inputs.min_psnr }}' \
+            --workdir /app/packages/producer \
+            --entrypoint bunx \
+            hyperframes-producer:test tsx scripts/validate-fast-video.ts
diff --git a/packages/producer/scripts/validate-fast-video.ts b/packages/producer/scripts/validate-fast-video.ts
new file mode 100644
index 0000000000..78db16f8e9
--- /dev/null
+++ b/packages/producer/scripts/validate-fast-video.ts
@@ -0,0 +1,77 @@
+/**
+ * Validate the fast-capture (drawElementImage) VIDEO path on real Linux.
+ *
+ * drawElementImage draws a snapshot taken at the paint event; capturing video
+ * needs a fresh per-frame paint. On Linux headless-shell that paint comes from
+ * the per-frame HeadlessExperimental.beginFrame — so video should capture
+ * correctly there (see docs/fast-capture-limitations.md, Limitation 2). This
+ * could not be validated under Docker-on-rosetta (renders hung); this script is
+ * meant to run on a native amd64 Linux runner inside Dockerfile.test.
+ *
+ * Renders a video composition twice — baseline (screenshot) and fast
+ * (drawElement) — and asserts the fast output matches the baseline (PSNR above
+ * threshold), proving the video was captured and not dropped to black.
+ *
+ *   PRODUCER_VALIDATE_COMP=sub-composition-video \
+ *   bunx tsx scripts/validate-fast-video.ts
+ *
+ * Exit 0 = fast video matches baseline; exit 1 = regression (black/stale video).
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createRenderJob, executeRenderJob } from "../src/index.js";
+
+const COMP = process.env.PRODUCER_VALIDATE_COMP ?? "sub-composition-video";
+const MIN_PSNR = Number.parseFloat(process.env.PRODUCER_VALIDATE_MIN_PSNR ?? "25");
+const work = mkdtempSync(join(tmpdir(), "fastvideo-"));
+
+process.env.PRODUCER_ENABLE_BROWSER_POOL = "false";
+
+async function render(mode: "baseline" | "fast", out: string): Promise<void> {
+  process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE = mode === "fast" ? "true" : "false";
+  const job = createRenderJob({
+    fps: 30,
+    quality: "high",
+    format: "mp4",
+    workers: 1,
+    useGpu: false,
+    hdrMode: "force-sdr",
+  });
+  await executeRenderJob(job, resolve("tests", COMP, "src"), out);
+}
+
+function psnr(a: string, b: string): number {
+  const out = execFileSync(
+    "bash",
+    ["-c", `ffmpeg -y -i "${a}" -i "${b}" -lavfi psnr -f null - 2>&1`],
+    { encoding: "utf8" },
+  );
+  const m = out.match(/average:(\S+)/);
+  if (!m) throw new Error(`ffmpeg psnr produced no average:\n${out}`);
+  return m[1] === "inf" ? Number.POSITIVE_INFINITY : Number.parseFloat(m[1]);
+}
+
+async function main(): Promise<void> {
+  const baseline = join(work, "baseline.mp4");
+  const fast = join(work, "fast.mp4");
+  console.log(`[validate-fast-video] comp=${COMP} minPsnr=${MIN_PSNR}`);
+  await render("baseline", baseline);
+  await render("fast", fast);
+  const db = psnr(baseline, fast);
+  console.log(`[validate-fast-video] fast-vs-baseline PSNR = ${db} dB`);
+  if (db < MIN_PSNR) {
+    console.error(
+      `[validate-fast-video] FAIL — ${db} dB < ${MIN_PSNR} dB. Fast capture dropped video ` +
+        `(stale/black snapshot). The Linux BeginFrame paint path is not capturing video.`,
+    );
+    process.exit(1);
+  }
+  console.log("[validate-fast-video] PASS — fast video matches baseline.");
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});