Helios Renderer API
The Renderer class enables headless rendering of Helios compositions using Playwright and FFmpeg. It supports both DOM-based and Canvas-based rendering strategies.
Quick Start
import { Renderer } from '@helios-project/renderer';
const renderer = new Renderer({
width: 1920,
height: 1080,
fps: 30,
durationInSeconds: 10,
mode: 'canvas', // or 'dom'
inputProps: { title: "Render Job 1" }
});
await renderer.render(
'http://localhost:3000/composition.html',
'./output.mp4',
{
onProgress: (progress) => console.log(`Rendering: ${(progress * 100).toFixed(1)}%`)
}
);
API Reference
Constructor
new Renderer(options: RendererOptions)
interface RendererOptions {
width: number; // Output width
height: number; // Output height
fps: number; // Frames per second
durationInSeconds: number; // Duration of the clip
frameCount?: number; // Exact total frames (overrides durationInSeconds)
startFrame?: number; // Frame to start rendering from (default: 0)
mode?: 'dom' | 'canvas'; // Rendering strategy (default: 'canvas')
inputProps?: Record<string, any>; // Inject props into window.__HELIOS_PROPS__
// Audio Configuration
audioFilePath?: string; // Path to single audio file
audioTracks?: (string | AudioTrackConfig)[]; // List of audio tracks
audioCodec?: string; // e.g., 'aac', 'libvorbis'
audioBitrate?: string; // e.g., '128k', '192k'
// Video Encoding
videoCodec?: string; // e.g., 'libx264' (default, prioritized), 'libvpx'
pixelFormat?: string; // e.g., 'yuv420p' (default)
crf?: number; // Constant Rate Factor (quality control)
preset?: string; // Encoding preset (e.g., 'fast')
videoBitrate?: string; // e.g., '5M', '1000k'
subtitles?: boolean; // Burn subtitles into video (requires libx264)
// Intermediate Capture (Canvas Mode)
intermediateVideoCodec?: string; // 'vp8' (default), 'vp9', 'av1'
// Intermediate Capture (DOM Mode)
intermediateImageFormat?: 'png' | 'jpeg'; // Default: 'png'
intermediateImageQuality?: number; // 0-100 (only for jpeg)
// System
ffmpegPath?: string; // Custom FFmpeg binary path
browserConfig?: { // Playwright Launch Options
headless?: boolean;
executablePath?: string;
args?: string[];
};
}
interface AudioTrackConfig {
path: string;
volume?: number; // 0.0 to 1.0
offset?: number; // Start time in composition (seconds)
seek?: number; // Start time in source file (seconds)
playbackRate?: number; // Speed multiplier (default: 1.0)
}
Methods
Render
Renders the composition at the given URL to a video file.
async render(
compositionUrl: string,
outputPath: string,
jobOptions?: RenderJobOptions
): Promise<void>
interface RenderJobOptions {
onProgress?: (progress: number) => void; // Callback 0.0 to 1.0
signal?: AbortSignal; // For cancellation
tracePath?: string; // Path to save Playwright trace (for debugging)
}
Diagnose
Check the rendering environment (Playwright, WebCodecs support, FFmpeg).
// Returns a comprehensive diagnostic report
const diagnostics = await renderer.diagnose();
/*
{
browser: {
waapi: boolean,
webCodecs: boolean,
offscreenCanvas: boolean,
userAgent: string
},
ffmpeg: {
version: string,
encoders: string[],
filters: string[]
}
}
*/
Rendering Modes
Canvas Mode (mode: 'canvas')
- Best for: WebGL, Three.js, Pixi.js, 2D Canvas.
- Mechanism: Uses
CdpTimeDriver to control time and CanvasStrategy to capture the canvas context directly.
- Performance: High. Fast capture via CDP.
- Sync: Uses
TreeWalker to recursively discover and sync media in Shadow DOMs.
DOM Mode (mode: 'dom')
- Best for: CSS Animations, HTML/DOM elements, complex video/audio compositions.
- Mechanism: Uses
SeekTimeDriver (seek & screenshot) to ensure DOM layouts settle.
- Performance: Slower than Canvas mode due to full-page screenshots.
- Implicit Audio: Automatically discovers
<audio> and <video> tags in the DOM and includes their audio in the render.
- Media Synchronization: Supports precise control over nested media elements using attributes:
data-helios-offset="2.5": Delay playback start by 2.5 seconds.data-helios-seek="10": Start playing from 10s into the source file.muted: Respects the HTML muted attribute.
- Recursive Sync: Traverses Shadow DOMs (open and closed) to find and synchronize animations and media elements.
- Stability: Waits for
seeked events on all media elements (Multi-Frame Seek) to ensure frames are perfectly aligned before capturing.
Utilities
Distributed Rendering
Split a render job into multiple chunks to run concurrently (e.g., on multiple cores).
import { RenderOrchestrator, DistributedRenderOptions } from '@helios-project/renderer';
const options: DistributedRenderOptions = {
// ...standard Renderer options...
concurrency: 4 // Number of parallel workers (default: CPU cores - 1)
};
await RenderOrchestrator.render(
'http://localhost:3000/composition.html',
'output.mp4',
options,
{ onProgress: (p) => console.log(`Total Progress: ${p}`) }
);
Concatenate Videos
Combine multiple video files into one.
import { concatenateVideos } from '@helios-project/renderer';
await concatenateVideos(['part1.mp4', 'part2.mp4'], 'full-video.mp4');
Common Patterns
Caption Burning
Burn subtitles (e.g. from the player) into the video output. Requires videoCodec: 'libx264'.
const renderer = new Renderer({
// ...
videoCodec: 'libx264',
subtitles: './captions.srt' // path to an SRT file
});
Range Rendering
Render only a specific section of the composition (e.g., for distributed rendering).
const renderer = new Renderer({
// ...
startFrame: 0,
durationInSeconds: 5 // Render only first 5 seconds
});
// To render the next 5 seconds:
// startFrame: 150, durationInSeconds: 5
Fast Draft Renders (DOM Mode)
Use JPEG instead of PNG for faster intermediate screenshots during DOM rendering.
const renderer = new Renderer({
mode: 'dom',
intermediateImageFormat: 'jpeg',
intermediateImageQuality: 80
});
Audio Mixing
Mix multiple audio tracks with offsets and volume control.
const renderer = new Renderer({
// ...
audioTracks: [
{ path: 'music.mp3', volume: 0.5 },
{ path: 'voiceover.wav', volume: 1.0, offset: 2 } // Start voice at 2s
]
});
Source Files
- Main class:
packages/renderer/src/index.ts
- Strategies:
packages/renderer/src/strategies/
- Types:
packages/renderer/src/types.ts