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) <noreply@anthropic.com>
This commit is contained in:
James
2026-03-27 02:45:09 +00:00
co-authored by Claude Opus 4.6
parent 1ac9d27b45
commit 684b103ba4
3 changed files with 65 additions and 16 deletions
+30 -11
View File
@@ -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:
+25 -4
View File
@@ -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:
<Step title="Capture frames via the engine">
Uses the [engine's](/packages/engine) BeginFrame pipeline to capture each frame as a pixel buffer.
</Step>
<Step title="Encode to MP4 via FFmpeg">
Pipes frame buffers into FFmpeg with the selected quality preset and encoding settings.
<Step title="Encode to MP4 or WebM via FFmpeg">
Pipes frame buffers into FFmpeg with the selected quality preset. MP4 uses h264; WebM uses VP9 with alpha transparency support.
</Step>
<Step title="Mix audio tracks">
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
+10 -1
View File
@@ -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/<name>.mp4)" },