From 684b103ba456af7ec34d75ea3c71db6a7274fe1c Mon Sep 17 00:00:00 2001 From: James Date: Fri, 27 Mar 2026 02:45:09 +0000 Subject: [PATCH] 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)" },