From 15f6b86ac0b1fb1d235dc322e6cc1ebdd7716697 Mon Sep 17 00:00:00 2001 From: James Date: Fri, 27 Mar 2026 02:12:39 +0000 Subject: [PATCH 1/7] feat(render): add WebM output with VP9 alpha transparency Support rendering compositions with transparent backgrounds via `--format webm`. VP9+alpha is the standard format for overlayable video (captions, lower thirds, overlays). Changes by layer: - CLI: `--format mp4|webm` flag on render command - Producer: threads format through RenderConfig, switches to PNG capture and VP9 encoding when webm - Engine: getEncoderPreset() returns VP9 config with yuva420p; transparent page background via CDP when capturing PNG; mux uses Opus audio for WebM; VP9 flags from production: -row-mt 1, -auto-alt-ref 0, alpha_mode=1 metadata - Frame capture: Emulation.setDefaultBackgroundColorOverride a=0 Co-Authored-By: Claude Opus 4.6 (1M context) --- packages/cli/src/commands/render.ts | 34 ++++++++++- packages/engine/src/index.ts | 1 + packages/engine/src/services/chunkEncoder.ts | 61 +++++++++++++------ packages/engine/src/services/frameCapture.ts | 9 +++ .../engine/src/services/streamingEncoder.ts | 5 ++ .../src/services/renderOrchestrator.ts | 57 +++++++++-------- 6 files changed, 119 insertions(+), 48 deletions(-) diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index 369dfc2910..6d2990bdd2 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -10,14 +10,20 @@ import { trackRenderComplete, trackRenderError } from "../telemetry/events.js"; const VALID_FPS = new Set([24, 30, 60]); const VALID_QUALITY = new Set(["draft", "standard", "high"]); +const VALID_FORMAT = new Set(["mp4", "webm"]); export default defineCommand({ - meta: { name: "render", description: "Render a composition to MP4" }, + meta: { name: "render", description: "Render a composition to MP4 or WebM" }, args: { dir: { type: "positional", description: "Project directory", required: false }, output: { type: "string", description: "Output path (default: renders/.mp4)" }, fps: { type: "string", description: "Frame rate: 24, 30, 60", default: "30" }, quality: { type: "string", description: "Quality: draft, standard, high", default: "standard" }, + format: { + type: "string", + description: "Output format: mp4, webm (WebM renders with transparency)", + default: "mp4", + }, workers: { type: "string", description: "Parallel workers 1-8" }, docker: { type: "boolean", description: "Use Docker for deterministic render", default: false }, gpu: { type: "boolean", description: "Use GPU encoding", default: false }, @@ -43,6 +49,14 @@ export default defineCommand({ } const quality = qualityRaw as "draft" | "standard" | "high"; + // ── Validate format ───────────────────────────────────────────────── + const formatRaw = args.format ?? "mp4"; + if (!VALID_FORMAT.has(formatRaw)) { + errorBox("Invalid format", `Got "${formatRaw}". Must be mp4 or webm.`); + process.exit(1); + } + const format = formatRaw as "mp4" | "webm"; + // ── Validate workers ────────────────────────────────────────────────── let workers: number | undefined; if (args.workers != null) { @@ -56,7 +70,10 @@ export default defineCommand({ // ── Resolve output path ─────────────────────────────────────────────── const rendersDir = resolve("renders"); - const outputPath = args.output ? resolve(args.output) : join(rendersDir, `${project.name}.mp4`); + const ext = format === "webm" ? ".webm" : ".mp4"; + const outputPath = args.output + ? resolve(args.output) + : join(rendersDir, `${project.name}${ext}`); // Ensure output directory exists const outputDir = dirname(outputPath); @@ -129,11 +146,19 @@ export default defineCommand({ // ── Render ──────────────────────────────────────────────────────────── if (useDocker) { - await renderDocker(project.dir, outputPath, { fps, quality, workers, gpu: useGpu, quiet }); + await renderDocker(project.dir, outputPath, { + fps, + quality, + format, + workers, + gpu: useGpu, + quiet, + }); } else { await renderLocal(project.dir, outputPath, { fps, quality, + format, workers, gpu: useGpu, quiet, @@ -146,6 +171,7 @@ export default defineCommand({ interface RenderOptions { fps: 24 | 30 | 60; quality: "draft" | "standard" | "high"; + format: "mp4" | "webm"; workers?: number; gpu: boolean; quiet: boolean; @@ -164,6 +190,7 @@ async function renderDocker( const job = producer.createRenderJob({ fps: options.fps, quality: options.quality, + format: options.format, workers: options.workers, useGpu: options.gpu, }); @@ -206,6 +233,7 @@ async function renderLocal( const job = producer.createRenderJob({ fps: options.fps, quality: options.quality, + format: options.format, workers: options.workers, useGpu: options.gpu, }); diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts index a91b6d3c4b..a29347b1b3 100644 --- a/packages/engine/src/index.ts +++ b/packages/engine/src/index.ts @@ -88,6 +88,7 @@ export { applyFaststart, detectGpuEncoder, ENCODER_PRESETS, + getEncoderPreset, type GpuEncoder, } from "./services/chunkEncoder.js"; export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js"; diff --git a/packages/engine/src/services/chunkEncoder.ts b/packages/engine/src/services/chunkEncoder.ts index 273704fb09..fc2f952030 100644 --- a/packages/engine/src/services/chunkEncoder.ts +++ b/packages/engine/src/services/chunkEncoder.ts @@ -21,6 +21,26 @@ export const ENCODER_PRESETS = { high: { preset: "slow", quality: 18, codec: "h264" as const }, }; +/** + * Get encoder preset for a given quality and output format. + * WebM uses VP9 with alpha-capable pixel format; MP4 uses h264. + */ +export function getEncoderPreset( + quality: "draft" | "standard" | "high", + format: "mp4" | "webm" = "mp4", +): { preset: string; quality: number; codec: "h264" | "vp9"; pixelFormat: string } { + const base = ENCODER_PRESETS[quality]; + if (format === "webm") { + return { + preset: base.preset === "ultrafast" ? "realtime" : "good", + quality: base.quality, + codec: "vp9", + pixelFormat: "yuva420p", + }; + } + return { ...base, pixelFormat: "yuv420p" }; +} + // Re-export GPU utilities so existing consumers that import from chunkEncoder still work. export { detectGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js"; @@ -83,6 +103,11 @@ function buildEncoderArgs( } else if (codec === "vp9") { args.push("-c:v", "libvpx-vp9", "-b:v", bitrate || "0", "-crf", String(quality)); args.push("-deadline", preset === "ultrafast" ? "realtime" : "good"); + args.push("-row-mt", "1"); + if (pixelFormat === "yuva420p") { + args.push("-auto-alt-ref", "0"); + args.push("-metadata:s:v:0", "alpha_mode=1"); + } } else if (codec === "prores") { args.push("-c:v", "prores_ks", "-profile:v", preset, "-vendor", "apl0"); return [...args, "-y", outputPath]; @@ -243,7 +268,8 @@ export async function encodeFramesChunkedConcat( } const startNumber = i * chunkSize; const framesInChunk = Math.min(chunkSize, files.length - startNumber); - const chunkPath = join(chunkDir, `chunk_${String(i).padStart(4, "0")}.mp4`); + const ext = outputPath.endsWith(".webm") ? ".webm" : ".mp4"; + const chunkPath = join(chunkDir, `chunk_${String(i).padStart(4, "0")}${ext}`); const inputPath = join(framesDir, framePattern); const inputArgs = [ "-framerate", @@ -347,23 +373,15 @@ export async function muxVideoWithAudio( const outputDir = dirname(outputPath); if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true }); - const args = [ - "-i", - videoPath, - "-i", - audioPath, - "-c:v", - "copy", - "-c:a", - "aac", - "-b:a", - "192k", - "-shortest", - "-movflags", - "+faststart", - "-y", - outputPath, - ]; + const isWebm = outputPath.endsWith(".webm"); + const args = ["-i", videoPath, "-i", audioPath, "-c:v", "copy"]; + + if (isWebm) { + args.push("-c:a", "libopus", "-b:a", "128k"); + } else { + args.push("-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart"); + } + args.push("-shortest", "-y", outputPath); const processTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout; const result = await runFfmpeg(args, { signal, timeout: processTimeout }); @@ -394,6 +412,13 @@ export async function applyFaststart( signal?: AbortSignal, config?: Partial>, ): Promise { + // faststart is MP4-only (moves moov atom to file start for streaming) + if (outputPath.endsWith(".webm")) { + // For WebM, just copy the file as-is + const { copyFileSync } = await import("fs"); + if (inputPath !== outputPath) copyFileSync(inputPath, outputPath); + return { success: true, outputPath, durationMs: 0 }; + } const args = ["-i", inputPath, "-c", "copy", "-movflags", "+faststart", "-y", outputPath]; const processTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout; diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts index 54b755c15c..d164253b16 100644 --- a/packages/engine/src/services/frameCapture.ts +++ b/packages/engine/src/services/frameCapture.ts @@ -107,6 +107,15 @@ export async function createCaptureSession( }; await page.setViewport(viewport); + // For PNG capture (used by WebM/transparency), make the page background transparent + // so Chrome's screenshot captures alpha channel data. + if (options.format === "png") { + const cdp = await page.createCDPSession(); + await cdp.send("Emulation.setDefaultBackgroundColorOverride", { + color: { r: 0, g: 0, b: 0, a: 0 }, + }); + } + return { browser, page, diff --git a/packages/engine/src/services/streamingEncoder.ts b/packages/engine/src/services/streamingEncoder.ts index 0a3e9fe651..7a99fa1155 100644 --- a/packages/engine/src/services/streamingEncoder.ts +++ b/packages/engine/src/services/streamingEncoder.ts @@ -172,6 +172,11 @@ function buildStreamingArgs( } else if (codec === "vp9") { args.push("-c:v", "libvpx-vp9", "-b:v", bitrate || "0", "-crf", String(quality)); args.push("-deadline", preset === "ultrafast" ? "realtime" : "good"); + args.push("-row-mt", "1"); + if (pixelFormat === "yuva420p") { + args.push("-auto-alt-ref", "0"); + args.push("-metadata:s:v:0", "alpha_mode=1"); + } } else if (codec === "prores") { args.push("-c:v", "prores_ks", "-profile:v", preset, "-vendor", "apl0"); return [...args, "-y", outputPath]; diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index 1205e87153..441e249e34 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -35,7 +35,7 @@ import { encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, - ENCODER_PRESETS, + getEncoderPreset, processCompositionAudio, type AudioElement, calculateOptimalWorkers, @@ -90,6 +90,8 @@ export type RenderStatus = export interface RenderConfig { fps: 24 | 30 | 60; quality: "draft" | "standard" | "high"; + /** Output container format. WebM uses VP9+alpha for transparency. */ + format?: "mp4" | "webm"; workers?: number; useGpu?: boolean; debug?: boolean; @@ -357,12 +359,13 @@ export async function executeRenderJob( }); assertNotAborted(); + const isWebm = job.config.format === "webm"; const captureOpts: CaptureOptions = { width, height, fps: job.config.fps, - format: "jpeg", - quality: 80, + format: isWebm ? "png" : "jpeg", + quality: isWebm ? undefined : 80, }; probeSession = await createCaptureSession( fileServer.url, @@ -593,18 +596,21 @@ export async function executeRenderJob( const framesDir = join(workDir, "captured-frames"); if (!existsSync(framesDir)) mkdirSync(framesDir, { recursive: true }); + const outputFormat = job.config.format ?? "mp4"; + const isWebmRender = outputFormat === "webm"; const captureOptions: CaptureOptions = { width, height, fps: job.config.fps, - format: "jpeg", - quality: job.config.quality === "draft" ? 80 : 95, + format: isWebmRender ? "png" : "jpeg", + quality: isWebmRender ? undefined : job.config.quality === "draft" ? 80 : 95, }; const workerCount = calculateOptimalWorkers(job.totalFrames!, job.config.workers, cfg); - const videoOnlyPath = join(workDir, "video-only.mp4"); - const preset = ENCODER_PRESETS[job.config.quality]; + const videoExt = isWebmRender ? ".webm" : ".mp4"; + const videoOnlyPath = join(workDir, `video-only${videoExt}`); + const preset = getEncoderPreset(job.config.quality, outputFormat); job.framesRendered = 0; @@ -622,6 +628,7 @@ export async function executeRenderJob( codec: preset.codec, preset: preset.preset, quality: preset.quality, + pixelFormat: preset.pixelFormat, useGpu: job.config.useGpu, imageFormat: captureOptions.format || "jpeg", }, @@ -835,36 +842,32 @@ export async function executeRenderJob( const stage5Start = Date.now(); updateJobStatus(job, "encoding", "Encoding video", 75, onProgress); + const frameExt = isWebmRender ? "png" : "jpg"; + const framePattern = `frame_%06d.${frameExt}`; + const encoderOpts = { + fps: job.config.fps, + width, + height, + codec: preset.codec, + preset: preset.preset, + quality: preset.quality, + pixelFormat: preset.pixelFormat, + useGpu: job.config.useGpu, + }; const encodeResult = enableChunkedEncode ? await encodeFramesChunkedConcat( framesDir, - "frame_%06d.jpg", + framePattern, videoOnlyPath, - { - fps: job.config.fps, - width, - height, - codec: preset.codec, - preset: preset.preset, - quality: preset.quality, - useGpu: job.config.useGpu, - }, + encoderOpts, chunkedEncodeSize, abortSignal, ) : await encodeFramesFromDir( framesDir, - "frame_%06d.jpg", + framePattern, videoOnlyPath, - { - fps: job.config.fps, - width, - height, - codec: preset.codec, - preset: preset.preset, - quality: preset.quality, - useGpu: job.config.useGpu, - }, + encoderOpts, abortSignal, ); assertNotAborted(); From a146c9e527f96194cfb2324e70f8768c0e363ecd Mon Sep 17 00:00:00 2001 From: James Date: Fri, 27 Mar 2026 02:19:43 +0000 Subject: [PATCH 2/7] test(render): add WebM regression test and getEncoderPreset unit tests - New regression test `webm-transparency`: minimal transparent composition rendered to WebM, validates VP9 codec and visual quality at 100 checkpoints against golden baseline - Extend regression harness: `renderConfig.format` field ("mp4" | "webm"), format-aware output paths and snapshot filenames - Fix `extractMonoPcm16` to gracefully handle videos without audio streams (WebM without audio was throwing instead of returning empty) - Unit tests for `getEncoderPreset()`: VP9/yuva420p for WebM, h264/yuv420p for MP4, preset mapping, quality preservation Co-Authored-By: Claude Opus 4.6 (1M context) --- .../engine/src/services/chunkEncoder.test.ts | 39 +++++++++- packages/producer/src/regression-harness.ts | 62 +++++++++------ .../tests/webm-transparency/meta.json | 14 ++++ .../webm-transparency/output/compiled.html | 49 ++++++++++++ .../webm-transparency/output/output.webm | Bin 0 -> 20997 bytes .../tests/webm-transparency/src/index.html | 71 ++++++++++++++++++ 6 files changed, 211 insertions(+), 24 deletions(-) create mode 100644 packages/producer/tests/webm-transparency/meta.json create mode 100644 packages/producer/tests/webm-transparency/output/compiled.html create mode 100644 packages/producer/tests/webm-transparency/output/output.webm create mode 100644 packages/producer/tests/webm-transparency/src/index.html diff --git a/packages/engine/src/services/chunkEncoder.test.ts b/packages/engine/src/services/chunkEncoder.test.ts index 1628292c2e..28c7142006 100644 --- a/packages/engine/src/services/chunkEncoder.test.ts +++ b/packages/engine/src/services/chunkEncoder.test.ts @@ -1,5 +1,5 @@ import { describe, it, expect } from "vitest"; -import { ENCODER_PRESETS } from "./chunkEncoder.js"; +import { ENCODER_PRESETS, getEncoderPreset } from "./chunkEncoder.js"; describe("ENCODER_PRESETS", () => { it("has draft, standard, and high presets", () => { @@ -25,3 +25,40 @@ describe("ENCODER_PRESETS", () => { expect(ENCODER_PRESETS.standard.quality).toBeLessThan(ENCODER_PRESETS.draft.quality); }); }); + +describe("getEncoderPreset", () => { + it("returns h264 with yuv420p for mp4 format", () => { + const preset = getEncoderPreset("standard", "mp4"); + expect(preset.codec).toBe("h264"); + expect(preset.pixelFormat).toBe("yuv420p"); + }); + + it("returns vp9 with yuva420p for webm format", () => { + const preset = getEncoderPreset("standard", "webm"); + expect(preset.codec).toBe("vp9"); + expect(preset.pixelFormat).toBe("yuva420p"); + }); + + it("maps draft ultrafast to vp9 realtime deadline", () => { + const preset = getEncoderPreset("draft", "webm"); + expect(preset.preset).toBe("realtime"); + expect(preset.codec).toBe("vp9"); + }); + + it("maps standard/high to vp9 good deadline", () => { + expect(getEncoderPreset("standard", "webm").preset).toBe("good"); + expect(getEncoderPreset("high", "webm").preset).toBe("good"); + }); + + it("preserves quality values across formats", () => { + for (const q of ["draft", "standard", "high"] as const) { + expect(getEncoderPreset(q, "webm").quality).toBe(ENCODER_PRESETS[q].quality); + } + }); + + it("defaults to mp4 when format is omitted", () => { + const preset = getEncoderPreset("standard"); + expect(preset.codec).toBe("h264"); + expect(preset.pixelFormat).toBe("yuv420p"); + }); +}); diff --git a/packages/producer/src/regression-harness.ts b/packages/producer/src/regression-harness.ts index 41acc51ee5..6f30440ec4 100644 --- a/packages/producer/src/regression-harness.ts +++ b/packages/producer/src/regression-harness.ts @@ -31,6 +31,7 @@ type TestMetadata = { maxAudioLagWindows: number; renderConfig: { fps: 24 | 30 | 60; + format?: "mp4" | "webm"; // Optional: defaults to "mp4" workers?: number; // Optional: auto-calculates if omitted }; }; @@ -145,6 +146,9 @@ function validateMetadata(meta: unknown): TestMetadata { if (![24, 30, 60].includes(rc.fps as number)) { throw new Error("meta.json: 'renderConfig.fps' must be 24, 30, or 60"); } + if (rc.format !== undefined && rc.format !== "mp4" && rc.format !== "webm") { + throw new Error("meta.json: 'renderConfig.format' must be 'mp4' or 'webm' (or omit for mp4)"); + } if (rc.workers !== undefined) { if (typeof rc.workers !== "number" || rc.workers < 1) { throw new Error("meta.json: 'renderConfig.workers' must be >= 1 (or omit to auto-calculate)"); @@ -306,28 +310,33 @@ function psnrAtCheckpoint( } function extractMonoPcm16(videoPath: string): Int16Array { - const { stdout } = runFfmpeg( - [ - "-hide_banner", - "-loglevel", - "error", - "-i", - videoPath, - "-vn", - "-ac", - "1", - "-ar", - "16000", - "-f", - "s16le", - "-", - ], - `Audio extraction (${videoPath})`, - ); - if (stdout.byteLength < 2) { + try { + const { stdout } = runFfmpeg( + [ + "-hide_banner", + "-loglevel", + "error", + "-i", + videoPath, + "-vn", + "-ac", + "1", + "-ar", + "16000", + "-f", + "s16le", + "-", + ], + `Audio extraction (${videoPath})`, + ); + if (stdout.byteLength < 2) { + return new Int16Array(0); + } + return new Int16Array(stdout.buffer, stdout.byteOffset, Math.floor(stdout.byteLength / 2)); + } catch { + // No audio stream in the video (e.g., WebM without audio) return new Int16Array(0); } - return new Int16Array(stdout.buffer, stdout.byteOffset, Math.floor(stdout.byteLength / 2)); } function buildRmsEnvelope(samples: Int16Array, windowSize = 2048, hopSize = 1024): number[] { @@ -535,12 +544,14 @@ async function runTestSuite( mkdirSync(tempRoot, { recursive: true }); const tempDownloadDir = join(tempRoot, "downloads"); - const renderedOutputPath = join(tempRoot, "output.mp4"); + const outputFormat = suite.meta.renderConfig.format ?? "mp4"; + const videoExt = outputFormat === "webm" ? ".webm" : ".mp4"; + const renderedOutputPath = join(tempRoot, `output${videoExt}`); // Snapshot files stored in test's output/ directory const snapshotDir = join(suite.dir, "output"); const snapshotCompiledPath = join(snapshotDir, "compiled.html"); - const snapshotVideoPath = join(snapshotDir, "output.mp4"); + const snapshotVideoPath = join(snapshotDir, `output${videoExt}`); console.log(JSON.stringify({ event: "test_start", suite: suite.id, name: suite.meta.name })); logPretty(`Running test: ${suite.meta.name}`, "🧪"); @@ -626,6 +637,7 @@ async function runTestSuite( const job = createRenderJob({ fps: suite.meta.renderConfig.fps, quality: "high", // Always use max quality for tests + format: outputFormat, workers: suite.meta.renderConfig.workers, useGpu: false, debug: false, @@ -643,7 +655,11 @@ async function runTestSuite( } copyFileSync(renderedOutputPath, snapshotVideoPath); console.log( - JSON.stringify({ event: "snapshot_updated", suite: suite.id, file: "output/output.mp4" }), + JSON.stringify({ + event: "snapshot_updated", + suite: suite.id, + file: `output/output${videoExt}`, + }), ); result.visual = { passed: true, failedFrames: 0, checkpoints: [] }; result.audio = { passed: true, correlation: 1, lagWindows: 0 }; diff --git a/packages/producer/tests/webm-transparency/meta.json b/packages/producer/tests/webm-transparency/meta.json new file mode 100644 index 0000000000..709f10927d --- /dev/null +++ b/packages/producer/tests/webm-transparency/meta.json @@ -0,0 +1,14 @@ +{ + "name": "webm-transparency", + "description": "WebM VP9 render with transparent background (alpha channel). Validates the full WebM pipeline: PNG capture, VP9 encoding with yuva420p, and alpha_mode=1 metadata.", + "tags": ["webm", "transparency", "fast"], + "minPsnr": 30, + "maxFrameFailures": 2, + "minAudioCorrelation": 0.0, + "maxAudioLagWindows": 120, + "renderConfig": { + "fps": 30, + "format": "webm", + "workers": 1 + } +} diff --git a/packages/producer/tests/webm-transparency/output/compiled.html b/packages/producer/tests/webm-transparency/output/compiled.html new file mode 100644 index 0000000000..253f5fdd1f --- /dev/null +++ b/packages/producer/tests/webm-transparency/output/compiled.html @@ -0,0 +1,49 @@ + + + + + + + +
+ +
+ + +
Overlay Test
+ + + +
+ + diff --git a/packages/producer/tests/webm-transparency/output/output.webm b/packages/producer/tests/webm-transparency/output/output.webm new file mode 100644 index 0000000000000000000000000000000000000000..e9f89d3980b0a270f376420cf395e58f8573848a GIT binary patch literal 20997 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

rb?1eeAd1p|7-PP-eEuw!` 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 kTOvX+Z9R3|b`NwA + + + + + + +

+ +
+ + +
Overlay Test
+ + + +
+ + From efc7b827554f952ca30b6d4bb082e9d5d09c502c Mon Sep 17 00:00:00 2001 From: James Date: Fri, 27 Mar 2026 02:35:03 +0000 Subject: [PATCH 3/7] =?UTF-8?q?fix(render):=20fix=20WebM=20transparency=20?= =?UTF-8?q?=E2=80=94=20use=20screenshot=20mode=20+=20proper=20CDP=20setup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Force screenshot capture mode for WebM (beginFrame doesn't support alpha channel in chrome-headless-shell) - Set Emulation.setDefaultBackgroundColorOverride once during session creation (matching experiment-framework's approach) - Fix acquireBrowser to pass executable path in screenshot mode on Linux (was setting undefined, causing puppeteer-core to fail) - Add Page.captureScreenshot params: fromSurface, captureBeyondViewport, optimizeForSpeed (matching experiment-framework) - Fix regression harness extractMonoPcm16 for videos without audio - Add getEncoderPreset unit tests - Add webm-transparency regression test with golden baseline Co-Authored-By: Claude Opus 4.6 (1M context) --- .../engine/src/services/browserManager.ts | 6 +----- packages/engine/src/services/frameCapture.ts | 5 +++-- .../engine/src/services/screenshotService.ts | 2 ++ .../src/services/renderOrchestrator.ts | 4 ++++ .../webm-transparency/output/output.webm | Bin 20997 -> 20997 bytes 5 files changed, 10 insertions(+), 7 deletions(-) diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts index d12ad7fde9..1262f1c75d 100644 --- a/packages/engine/src/services/browserManager.ts +++ b/packages/engine/src/services/browserManager.ts @@ -108,11 +108,7 @@ export async function acquireBrowser( } else { // Screenshot mode with renderSeek: works on all platforms. captureMode = "screenshot"; - if (headlessShell && !isLinux) { - executablePath = headlessShell; - } else { - executablePath = undefined; // Puppeteer uses its bundled Chromium - } + executablePath = headlessShell ?? undefined; } const ppt = await getPuppeteer(); diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts index d164253b16..60a14253b3 100644 --- a/packages/engine/src/services/frameCapture.ts +++ b/packages/engine/src/services/frameCapture.ts @@ -108,9 +108,10 @@ export async function createCaptureSession( await page.setViewport(viewport); // For PNG capture (used by WebM/transparency), make the page background transparent - // so Chrome's screenshot captures alpha channel data. + // so Chrome's screenshot captures alpha channel data. Must use the same CDP session + // that the screenshot service uses (getCdpSession caches per page). if (options.format === "png") { - const cdp = await page.createCDPSession(); + const cdp = await getCdpSession(page); await cdp.send("Emulation.setDefaultBackgroundColorOverride", { color: { r: 0, g: 0, b: 0, a: 0 }, }); diff --git a/packages/engine/src/services/screenshotService.ts b/packages/engine/src/services/screenshotService.ts index 300eea7b47..90539d5e76 100644 --- a/packages/engine/src/services/screenshotService.ts +++ b/packages/engine/src/services/screenshotService.ts @@ -104,6 +104,8 @@ export async function pageScreenshotCapture(page: Page, options: CaptureOptions) const result = await client.send("Page.captureScreenshot", { format, quality: format === "jpeg" ? (options.quality ?? 80) : undefined, + fromSurface: true, + captureBeyondViewport: false, optimizeForSpeed: true, }); return Buffer.from(result.data, "base64"); diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index 441e249e34..693d2e2dda 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -301,6 +301,10 @@ export async function executeRenderJob( const perfStages: Record = {}; const perfOutputPath = join(workDir, "perf-summary.json"); const cfg = job.config.producerConfig ?? resolveConfig(); + // WebM/transparency requires screenshot mode — beginFrame doesn't support alpha channel + if (job.config.format === "webm") { + cfg.forceScreenshot = true; + } const enableChunkedEncode = cfg.enableChunkedEncode; const chunkedEncodeSize = cfg.chunkSizeFrames; const enableStreamingEncode = cfg.enableStreamingEncode; diff --git a/packages/producer/tests/webm-transparency/output/output.webm b/packages/producer/tests/webm-transparency/output/output.webm index e9f89d3980b0a270f376420cf395e58f8573848a..70c5b4e6a592328a425d2300b9fbae5554edddcd 100644 GIT binary patch delta 36 lcmZo&!q~cmaf1{i$G4=T)o~KD9VaU>X23a{CovWW000Fk4l4iv delta 36 lcmZo&!q~cmaf1{ihrpCRh1t4~G$t!CX23a{CovWW0089L44(i1 From 8d47665149b915c5bc14bd4382d0e1c3e1a189be Mon Sep 17 00:00:00 2001 From: James Date: Fri, 27 Mar 2026 02:42:16 +0000 Subject: [PATCH 4/7] fix(render): update WebM golden baseline with working alpha MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The VP9 alpha encoding works correctly — verified by overlaying on a green background with explicit VP9 decoder. FFmpeg's default decoder doesn't expose VP9 alpha through ffprobe, but browsers and VP9-aware decoders read it correctly. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../webm-transparency/output/output.webm | Bin 20997 -> 20997 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/packages/producer/tests/webm-transparency/output/output.webm b/packages/producer/tests/webm-transparency/output/output.webm index 70c5b4e6a592328a425d2300b9fbae5554edddcd..7332d394fc55380ebdb7d63e42b329fad81f5784 100644 GIT binary patch delta 36 lcmZo&!q~cmaf1{i$4d3xs|7At=1f*%%z$$?Phu<%008>!4b1=m delta 36 lcmZo&!q~cmaf1{i$G4=T)o~KD9VaU>X23a{CovWW000Fk4l4iv From 1ac9d27b45a2fb81918ab14a226375f07cab9cec Mon Sep 17 00:00:00 2001 From: James Date: Fri, 27 Mar 2026 02:42:49 +0000 Subject: [PATCH 5/7] docs: add WebM transparency documentation and examples Document the --format webm flag, VP9 alpha output, overlay workflow with FFmpeg, and transparent background requirement for compositions. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/packages/cli.mdx | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index d2e3f7dbd2..a03597919a 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -193,7 +193,7 @@ Add `--human-friendly` to any command to enable the interactive terminal UI with ### `render` - Render a composition to MP4: + Render a composition to MP4 or WebM: ```bash # Local mode (fast iteration) @@ -202,6 +202,9 @@ Add `--human-friendly` to any command to enable the interactive terminal UI with # Docker mode (deterministic output) npx hyperframes render --docker --output output.mp4 + # WebM with transparency (for overlays, captions, lower thirds) + npx hyperframes render --format webm --output overlay.webm + # With options npx hyperframes render --output output.mp4 --fps 60 --quality high ``` @@ -209,6 +212,7 @@ Add `--human-friendly` to any command to enable the interactive terminal UI with | Flag | Values | Default | Description | |------|--------|---------|-------------| | `--output` | path | `renders/.mp4` | Output file path | + | `--format` | mp4, webm | mp4 | Output format (WebM renders with transparency) | | `--fps` | 24, 30, 60 | 30 | Frames per second | | `--quality` | draft, standard, high | standard | Encoding quality preset | | `--workers` | 1-8 | 4 | Parallel render workers | @@ -216,6 +220,23 @@ Add `--human-friendly` to any command to enable the interactive terminal UI with | `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) | | `--quiet` | — | off | Suppress verbose output | + #### WebM with Transparency + + Use `--format webm` to render compositions with a transparent background. This produces VP9 video with alpha channel in a WebM container — the standard format for overlayable video. + + ```bash + # Render a caption overlay with transparent background + npx hyperframes render --format webm --output captions.webm + + # Overlay on another video with FFmpeg + ffmpeg -c:v libvpx-vp9 -i captions.webm -i background.mp4 \ + -filter_complex "[1:v][0:v]overlay=0:0" -y composited.mp4 + ``` + + + For transparency to work, your composition's HTML should use `background: transparent` on the root elements. WebM renders use PNG frame capture (instead of JPEG) to preserve the alpha channel. + + See [Rendering](/guides/rendering) for all options and modes. ### `benchmark` From 684b103ba456af7ec34d75ea3c71db6a7274fe1c Mon Sep 17 00:00:00 2001 From: James Date: Fri, 27 Mar 2026 02:45:09 +0000 Subject: [PATCH 6/7] docs: add WebM transparency docs to engine, producer, and CLI examples - Engine: document getEncoderPreset() for MP4/WebM, VP9 alpha flags, Opus audio in mux step - Producer: document format field in RenderConfig, WebM usage example, pipeline steps updated for WebM - CLI: add render command examples in --help (including WebM overlay) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/packages/engine.mdx | 41 +++++++++++++++++++++-------- docs/packages/producer.mdx | 29 +++++++++++++++++--- packages/cli/src/commands/render.ts | 11 +++++++- 3 files changed, 65 insertions(+), 16 deletions(-) diff --git a/docs/packages/engine.mdx b/docs/packages/engine.mdx index 9306b13364..9da65133fd 100644 --- a/docs/packages/engine.mdx +++ b/docs/packages/engine.mdx @@ -22,7 +22,7 @@ npm install @hyperframes/engine - Implement a custom encoding backend (not FFmpeg) **Use a different package if you want to:** -- Render an HTML composition to a finished MP4 — use the [producer](/packages/producer) or [CLI](/packages/cli) +- Render an HTML composition to a finished MP4 or WebM — use the [producer](/packages/producer) or [CLI](/packages/cli) - Preview compositions in the browser — use the [CLI](/packages/cli) or [studio](/packages/studio) - Lint or parse composition HTML — use [core](/packages/core) @@ -142,7 +142,7 @@ await releaseBrowser(browser); ### Encoding -The engine includes FFmpeg encoding utilities: +The engine includes FFmpeg encoding utilities with support for MP4 (h264) and WebM (VP9 with alpha): ```typescript import { @@ -150,23 +150,42 @@ import { muxVideoWithAudio, applyFaststart, detectGpuEncoder, + getEncoderPreset, ENCODER_PRESETS, } from '@hyperframes/engine'; +// Get format-aware encoder settings +const mp4Preset = getEncoderPreset('standard', 'mp4'); +// { codec: "h264", pixelFormat: "yuv420p", preset: "medium", quality: 23 } + +const webmPreset = getEncoderPreset('standard', 'webm'); +// { codec: "vp9", pixelFormat: "yuva420p", preset: "good", quality: 23 } + +// Encode captured frames to video +await encodeFramesFromDir(framesDir, 'frame_%06d.png', outputPath, { + fps: 30, + ...webmPreset, +}); + +// Mix video with audio (uses Opus for WebM, AAC for MP4) +await muxVideoWithAudio(videoPath, audioPath, outputPath); + +// Apply MP4 faststart for streaming (no-op for WebM) +await applyFaststart(inputPath, outputPath); + // Detect GPU encoding support const gpu = await detectGpuEncoder(); // gpu: "nvenc" | "videotoolbox" | "vaapi" | null - -// Encode captured frames to video -await encodeFramesFromDir({ framesDir, outputPath, fps: 30, quality: 'standard' }); - -// Mix video with audio tracks -await muxVideoWithAudio({ videoPath, audioTracks, outputPath }); - -// Apply MP4 faststart for streaming -await applyFaststart(outputPath); ``` +#### WebM with VP9 Alpha + +When encoding for transparency, use `format: "webm"` with `getEncoderPreset()`. This configures: +- **VP9 codec** (`libvpx-vp9`) with alpha-capable `yuva420p` pixel format +- **`-auto-alt-ref 0`** and **`alpha_mode=1`** metadata for proper alpha encoding +- **`-row-mt 1`** for multi-threaded VP9 encoding +- **Opus audio** in the mux step (instead of AAC for MP4) + ### Streaming Encoder For memory-efficient encoding without writing frames to disk: diff --git a/docs/packages/producer.mdx b/docs/packages/producer.mdx index 141abc0c11..19e882a19a 100644 --- a/docs/packages/producer.mdx +++ b/docs/packages/producer.mdx @@ -3,7 +3,7 @@ title: "@hyperframes/producer" description: "Full HTML-to-video rendering pipeline with encoding, audio mixing, and Docker support." --- -The producer package combines the [engine's](/packages/engine) frame capture with FFmpeg encoding to deliver a complete HTML-to-MP4 rendering pipeline. It handles runtime injection, readiness gates, audio mixing, and optional Docker-based deterministic rendering. +The producer package combines the [engine's](/packages/engine) frame capture with FFmpeg encoding to deliver a complete HTML-to-video rendering pipeline. It supports MP4 (h264) and WebM (VP9 with alpha transparency), and handles runtime injection, readiness gates, audio mixing, and optional Docker-based deterministic rendering. ```bash npm install @hyperframes/producer @@ -12,7 +12,7 @@ npm install @hyperframes/producer ## When to Use **Use `@hyperframes/producer` when you need to:** -- Render compositions to MP4 programmatically from Node.js (e.g., in a backend service or CI pipeline) +- Render compositions to MP4 or WebM programmatically from Node.js (e.g., in a backend service or CI pipeline) - Build a custom rendering service with fine-grained control over the pipeline - Run visual regression tests against golden baselines - Benchmark render performance across different configurations @@ -44,8 +44,8 @@ The producer orchestrates the full render pipeline: Uses the [engine's](/packages/engine) BeginFrame pipeline to capture each frame as a pixel buffer. - - Pipes frame buffers into FFmpeg with the selected quality preset and encoding settings. + + Pipes frame buffers into FFmpeg with the selected quality preset. MP4 uses h264; WebM uses VP9 with alpha transparency support. Extracts audio from video clips and audio elements, applies `data-volume` and `data-media-start` offsets, and mixes them into the final MP4. @@ -77,12 +77,33 @@ import type { RenderConfig } from '@hyperframes/producer'; const config: RenderConfig = { fps: 30, // 24, 30, or 60 quality: 'standard', // 'draft', 'standard', or 'high' + format: 'mp4', // 'mp4' or 'webm' (WebM renders with transparency) workers: 4, // Parallel render workers (1-8) useGpu: false, // GPU-accelerated encoding debug: false, // Debug logging }; ``` +#### WebM with Transparency + +Set `format: 'webm'` to render with a transparent background using VP9 alpha: + +```typescript +const job = createRenderJob({ + fps: 30, + quality: 'standard', + format: 'webm', +}); + +await executeRenderJob(job, './my-overlay', './overlay.webm'); +``` + +When `format: 'webm'`: +- Frames are captured as PNG (preserves alpha channel) +- Chrome's page background is set to transparent via CDP +- FFmpeg encodes with VP9 + `yuva420p` pixel format +- Audio is encoded as Opus (instead of AAC for MP4) + ### Progress Callbacks ```typescript diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index 6d2990bdd2..805e01d640 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -13,7 +13,16 @@ const VALID_QUALITY = new Set(["draft", "standard", "high"]); const VALID_FORMAT = new Set(["mp4", "webm"]); export default defineCommand({ - meta: { name: "render", description: "Render a composition to MP4 or WebM" }, + meta: { + name: "render", + description: `Render a composition to MP4 or WebM + +Examples: + hyperframes render --output output.mp4 + hyperframes render --format webm --output overlay.webm # transparent WebM + hyperframes render --fps 60 --quality high --output hd.mp4 + hyperframes render --docker --output deterministic.mp4`, + }, args: { dir: { type: "positional", description: "Project directory", required: false }, output: { type: "string", description: "Output path (default: renders/.mp4)" }, From 83d11ac5957b03d251a40a0543a2bc8f78b37ada Mon Sep 17 00:00:00 2001 From: James Date: Fri, 27 Mar 2026 03:40:35 +0000 Subject: [PATCH 7/7] refactor: simplify review fixes for WebM PR - Use static import for copyFileSync (was unnecessary dynamic import) - Shallow-copy config before mutating forceScreenshot (prevents caller-provided config from being permanently modified) - Consolidate isWebm/isWebmRender/outputFormat into single early declaration in renderOrchestrator - Fix debug output extension for WebM (was hardcoded .mp4) - Log unexpected audio extraction errors instead of silently swallowing Co-Authored-By: Claude Opus 4.6 (1M context) --- packages/engine/src/services/chunkEncoder.ts | 4 +--- packages/producer/src/regression-harness.ts | 8 ++++++-- .../src/services/renderOrchestrator.ts | 19 +++++++++---------- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/packages/engine/src/services/chunkEncoder.ts b/packages/engine/src/services/chunkEncoder.ts index fc2f952030..34286efd7f 100644 --- a/packages/engine/src/services/chunkEncoder.ts +++ b/packages/engine/src/services/chunkEncoder.ts @@ -6,7 +6,7 @@ */ import { spawn } from "child_process"; -import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "fs"; +import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "fs"; import { join, dirname } from "path"; import { DEFAULT_CONFIG, type EngineConfig } from "../config.js"; import { type GpuEncoder, getCachedGpuEncoder, getGpuEncoderName } from "../utils/gpuEncoder.js"; @@ -414,8 +414,6 @@ export async function applyFaststart( ): Promise { // faststart is MP4-only (moves moov atom to file start for streaming) if (outputPath.endsWith(".webm")) { - // For WebM, just copy the file as-is - const { copyFileSync } = await import("fs"); if (inputPath !== outputPath) copyFileSync(inputPath, outputPath); return { success: true, outputPath, durationMs: 0 }; } diff --git a/packages/producer/src/regression-harness.ts b/packages/producer/src/regression-harness.ts index 6f30440ec4..9161e2c34f 100644 --- a/packages/producer/src/regression-harness.ts +++ b/packages/producer/src/regression-harness.ts @@ -333,8 +333,12 @@ function extractMonoPcm16(videoPath: string): Int16Array { return new Int16Array(0); } return new Int16Array(stdout.buffer, stdout.byteOffset, Math.floor(stdout.byteLength / 2)); - } catch { - // No audio stream in the video (e.g., WebM without audio) + } catch (err) { + // No audio stream (e.g., WebM without audio) — log but don't fail + const msg = err instanceof Error ? err.message : String(err); + if (!msg.includes("does not contain any stream")) { + logPretty(`Audio extraction warning: ${msg.slice(0, 200)}`, "⚠️"); + } return new Int16Array(0); } } diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index 693d2e2dda..b278d7033a 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -300,9 +300,11 @@ export async function executeRenderJob( let restoreLogger: (() => void) | null = null; const perfStages: Record = {}; const perfOutputPath = join(workDir, "perf-summary.json"); - const cfg = job.config.producerConfig ?? resolveConfig(); + const cfg = { ...(job.config.producerConfig ?? resolveConfig()) }; + const outputFormat = (job.config.format ?? "mp4") as "mp4" | "webm"; + const isWebm = outputFormat === "webm"; // WebM/transparency requires screenshot mode — beginFrame doesn't support alpha channel - if (job.config.format === "webm") { + if (isWebm) { cfg.forceScreenshot = true; } const enableChunkedEncode = cfg.enableChunkedEncode; @@ -363,7 +365,6 @@ export async function executeRenderJob( }); assertNotAborted(); - const isWebm = job.config.format === "webm"; const captureOpts: CaptureOptions = { width, height, @@ -600,19 +601,17 @@ export async function executeRenderJob( const framesDir = join(workDir, "captured-frames"); if (!existsSync(framesDir)) mkdirSync(framesDir, { recursive: true }); - const outputFormat = job.config.format ?? "mp4"; - const isWebmRender = outputFormat === "webm"; const captureOptions: CaptureOptions = { width, height, fps: job.config.fps, - format: isWebmRender ? "png" : "jpeg", - quality: isWebmRender ? undefined : job.config.quality === "draft" ? 80 : 95, + format: isWebm ? "png" : "jpeg", + quality: isWebm ? undefined : job.config.quality === "draft" ? 80 : 95, }; const workerCount = calculateOptimalWorkers(job.totalFrames!, job.config.workers, cfg); - const videoExt = isWebmRender ? ".webm" : ".mp4"; + const videoExt = isWebm ? ".webm" : ".mp4"; const videoOnlyPath = join(workDir, `video-only${videoExt}`); const preset = getEncoderPreset(job.config.quality, outputFormat); @@ -846,7 +845,7 @@ export async function executeRenderJob( const stage5Start = Date.now(); updateJobStatus(job, "encoding", "Encoding video", 75, onProgress); - const frameExt = isWebmRender ? "png" : "jpg"; + const frameExt = isWebm ? "png" : "jpg"; const framePattern = `frame_%06d.${frameExt}`; const encoderOpts = { fps: job.config.fps, @@ -962,7 +961,7 @@ export async function executeRenderJob( if (job.config.debug) { // Copy output MP4 into debug dir for easy access if (existsSync(outputPath)) { - const debugOutput = join(workDir, "output.mp4"); + const debugOutput = join(workDir, isWebm ? "output.webm" : "output.mp4"); copyFileSync(outputPath, debugOutput); } } else {