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)" },