mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 06:19:21 +00:00
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:
+30
-11
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)" },
|
||||
|
||||
Reference in New Issue
Block a user