Local video rendering

The Renderer class provides local video rendering capabilities for Helios compositions. It captures frames from a browser instance and encodes them to video using FFmpeg.

Basic usage

Create a renderer instance and call the render method:

import { Renderer } from '@helios-project/renderer';

const renderer = new Renderer({
  width: 1920,
  height: 1080,
  fps: 60,
  durationInSeconds: 5,
  mode: 'canvas'
});

await renderer.render(
  'http://localhost:3000/composition.html',
  './output.mp4'
);

Renderer options

The RendererOptions interface defines the configuration for rendering:

Required options

width

number

required

Output video width in pixels

height

number

required

Output video height in pixels

fps

number

required

Frames per second for the output video

durationInSeconds

number

required

Duration of the composition in seconds

Render mode

mode

'canvas' | 'dom'

default:"'canvas'"

The rendering mode:

'canvas': Captures frames by converting the first <canvas> element to a data URL using WebCodecs. Best for canvas-based animations.
'dom': Captures frames by taking a screenshot of the entire viewport. Best for CSS/DOM-based animations.

canvasSelector

string

default:"'canvas'"

CSS selector to find the canvas element in ‘canvas’ mode. Supports Shadow DOM.

targetSelector

string

CSS selector to find the target element in ‘dom’ mode. If provided, the screenshot will be limited to this element. Supports deep selection across Shadow DOM boundaries.

Video encoding

videoCodec

string

default:"'libx264'"

The video codec to use for final output (e.g., 'libx264', 'libx265', 'libvpx-vp9', 'copy')

pixelFormat

string

default:"'yuv420p'"

The pixel format for the output video

crf

number

Constant Rate Factor for quality control. Lower values mean better quality. Range varies by codec (typically 0-51 for H.264).

preset

string

default:"'fast'"

Encoding preset (e.g., 'ultrafast', 'fast', 'medium', 'slow', 'veryslow')

videoBitrate

string

Video bitrate (e.g., '5M', '1000k'). If provided, overrides CRF for some codecs.

Intermediate capture

intermediateVideoCodec

string

default:"'vp8'"

The codec to use for intermediate capture in ‘canvas’ mode with WebCodecs:

'vp8': Widely supported, good performance
'vp9': Better compression, higher quality
'av1': Best compression, requires newer hardware/browsers
'avc1.4d002a': H.264 High Profile

intermediateImageFormat

'png' | 'jpeg'

default:"'png'"

The image format to use for intermediate capture in ‘dom’ mode, or as a fallback in ‘canvas’ mode if WebCodecs is not available

intermediateImageQuality

number

The quality of the intermediate image (0-100). Only applicable if intermediateImageFormat is 'jpeg'.

keyFrameInterval

number

The number of frames between keyframes (GOP size) when using WebCodecs in ‘canvas’ mode. Defaults to 2 seconds worth of frames (fps * 2).

Audio configuration

audioFilePath

string

Path to an audio file to include in the output video

audioTracks

(string | AudioTrackConfig)[]

Array of audio tracks to mix with the video. Can be simple file paths or configuration objects.

audioCodec

string

The audio codec to use. Defaults to 'aac' (or 'libvorbis' for WebM)

audioBitrate

string

Audio bitrate (e.g., '128k', '192k')

Advanced options

startFrame

number

default:"0"

The frame to start rendering from. Useful for rendering a range of frames (distributed rendering).

frameCount

number

The exact number of frames to render. If provided, this overrides durationInSeconds for calculating loop limits.

subtitles

string

Path to an SRT file to burn into the video. Note: This requires video transcoding (videoCodec cannot be 'copy').

inputProps

Record<string, any>

Optional props to inject into the composition. These will be available as window.__HELIOS_PROPS__.

randomSeed

number

default:"0x12345678"

Seed for the deterministic random number generator

stabilityTimeout

number

default:"30000"

Timeout in milliseconds to wait for the frame to stabilize (e.g., loading fonts, images, custom hooks)

ffmpegPath

string

Path to the FFmpeg binary. Defaults to the binary provided by @ffmpeg-installer/ffmpeg.

hwAccel

string

Hardware acceleration method to use for FFmpeg (e.g., 'cuda', 'vaapi', 'qsv', 'videotoolbox', 'auto')

webCodecsPreference

'hardware' | 'software' | 'disabled'

default:"'hardware'"

Preference for using WebCodecs hardware acceleration in ‘canvas’ mode:

'hardware': Prioritize hardware-accelerated codecs
'software': Prioritize software-based codecs (useful for deterministic testing)
'disabled': Disable WebCodecs entirely and fall back to image capture

mixInputAudio

boolean

default:"false"

Whether to mix the audio from the input video (stream 0:a) into the output. Useful for multi-pass rendering.

Browser configuration

browserConfig

BrowserConfig

Configuration for the Playwright browser instance:

interface BrowserConfig {
  headless?: boolean;        // Default: true
  executablePath?: string;   // Path to custom browser
  args?: string[];           // Additional browser arguments
}

Audio track configuration

For advanced audio mixing, use the AudioTrackConfig interface:

interface AudioTrackConfig {
  path: string;              // Path to audio file
  buffer?: Buffer;           // Optional buffer instead of file
  volume?: number;           // Volume multiplier (0.0 to 1.0)
  offset?: number;           // Start time in composition (seconds)
  seek?: number;             // Seek into source file (seconds)
  fadeInDuration?: number;   // Fade in duration (seconds)
  fadeOutDuration?: number;  // Fade out duration (seconds)
  loop?: boolean;            // Loop indefinitely
  playbackRate?: number;     // Playback speed multiplier
  duration?: number;         // Source audio duration (seconds)
}

Example with audio tracks

const renderer = new Renderer({
  width: 1920,
  height: 1080,
  fps: 60,
  durationInSeconds: 10,
  audioTracks: [
    {
      path: './music.mp3',
      volume: 0.8,
      fadeInDuration: 1,
      fadeOutDuration: 2
    },
    {
      path: './voiceover.mp3',
      offset: 2,
      volume: 1.0
    }
  ]
});

Job options

The render method accepts optional job configuration:

interface RenderJobOptions {
  onProgress?: (progress: number) => void;
  signal?: AbortSignal;
  tracePath?: string;
}

onProgress

(progress: number) => void

Callback for progress updates. Receives a number between 0 and 1.

signal

AbortSignal

An AbortSignal to cancel the rendering process

tracePath

string

Path to save the Playwright trace file (zip). If provided, Playwright tracing will be enabled for the session.

Example with progress tracking

const controller = new AbortController();

await renderer.render(
  'http://localhost:3000',
  './output.mp4',
  {
    onProgress: (progress) => {
      console.log(`Rendering: ${(progress * 100).toFixed(1)}%`);
    },
    signal: controller.signal,
    tracePath: './trace.zip'
  }
);

Rendering workflow

Initialize browser

The Renderer launches a Chromium instance with GPU acceleration flags:

const DEFAULT_BROWSER_ARGS = [
  '--use-gl=egl',
  '--ignore-gpu-blocklist',
  '--enable-gpu-rasterization',
  '--enable-zero-copy',
  '--disable-web-security',
  '--allow-file-access-from-files',
];

Navigate to composition

The browser navigates to the composition URL and injects inputProps if provided via window.__HELIOS_PROPS__.

Initialize time driver

Based on the mode, either CdpTimeDriver (canvas) or SeekTimeDriver (DOM) is initialized to control time.

Prepare render strategy

The selected strategy (Canvas or DOM) prepares for capture:

Preloads fonts and images
Validates target element exists
Initializes WebCodecs encoder (canvas mode)
Scans for audio tracks in the DOM

Spawn FFmpeg process

FFmpeg is spawned with arguments generated by FFmpegBuilder, which handles:

Video input format (H.264, IVF, or image2pipe)
Audio track mixing and filtering
Output encoding parameters

Capture loop

For each frame:

Set the composition time using the time driver
Capture the frame using the render strategy
Write the frame data to FFmpeg’s stdin
Report progress via callback

Finalize encoding

After all frames are captured:

Call strategy.finish() to flush any remaining data
Close FFmpeg stdin
Wait for FFmpeg to complete encoding
Clean up browser and temporary resources

GPU acceleration

Helios automatically attempts to use GPU acceleration at multiple levels:

Browser GPU acceleration

The renderer enables GPU acceleration in Chromium with these flags:

--use-gl=egl: Use EGL for OpenGL
--ignore-gpu-blocklist: Override GPU blocklists
--enable-gpu-rasterization: Enable GPU rasterization
--enable-zero-copy: Enable zero-copy texture uploads

WebCodecs hardware encoding

In canvas mode, Helios uses the WebCodecs API for hardware-accelerated encoding:

const renderer = new Renderer({
  mode: 'canvas',
  intermediateVideoCodec: 'avc1.4d002a', // H.264 hardware codec
  webCodecsPreference: 'hardware'
});

The renderer automatically detects available hardware codecs and selects the best option. Priority order:

H.264 (AVC) - Best hardware support
VP9 - Good quality/compression
AV1 - Best compression (requires newer hardware)
VP8 - Fallback option

FFmpeg hardware acceleration

For the final encoding step, you can specify FFmpeg hardware acceleration:

const renderer = new Renderer({
  hwAccel: 'cuda',  // For NVIDIA GPUs
  videoCodec: 'h264_nvenc'  // Use NVIDIA encoder
});

Supported hwAccel values:

'cuda': NVIDIA CUDA
'vaapi': Video Acceleration API (Linux)
'qsv': Intel Quick Sync Video
'videotoolbox': Apple VideoToolbox (macOS)
'auto': Let FFmpeg choose

The renderer validates that the requested hardware acceleration method is available in your FFmpeg build. If not available, a warning is logged.

Diagnostics

Use the diagnose() method to check browser and FFmpeg capabilities:

const renderer = new Renderer({ /* options */ });
const diagnostics = await renderer.diagnose();

console.log(diagnostics);
// {
//   browser: {
//     videoEncoder: true,
//     offscreenCanvas: true,
//     userAgent: "...",
//     codecs: {
//       h264: { supported: true, hardware: true, type: 'hardware' },
//       vp8: { supported: true, hardware: false, type: 'software' },
//       vp9: { supported: true, hardware: true, type: 'hardware' },
//       av1: { supported: false }
//     }
//   },
//   ffmpeg: {
//     version: "5.1.2",
//     hwaccels: ["cuda", "vaapi"]
//   }
// }

Error handling

The renderer captures and propagates errors from:

Page crashes
Console errors
FFmpeg failures
Abort signals

try {
  await renderer.render(url, output);
} catch (error) {
  if (error.message === 'Aborted') {
    console.log('Render was cancelled');
  } else {
    console.error('Render failed:', error);
  }
}

Page errors are captured during rendering:

// Renderer.ts:104-116
page.on('console', (msg) => console.log(`PAGE LOG: ${msg.text()}`));
page.on('pageerror', (err) => {
  console.error(`PAGE ERROR: ${err.message}`);
  capturedErrors.push(err);
});
page.on('crash', () => {
  const err = new Error('Page crashed!');
  capturedErrors.push(err);
});

Get Started

Core Concepts

Framework Guides

Features

Rendering

Tools

Component Registry

Advanced

Local video rendering

Basic usage

Renderer options

Required options

Render mode

Video encoding

Intermediate capture

Audio configuration

Advanced options

Browser configuration

Audio track configuration

Example with audio tracks

Job options

Example with progress tracking

Rendering workflow

GPU acceleration

Browser GPU acceleration

WebCodecs hardware encoding

FFmpeg hardware acceleration

Diagnostics

Error handling

Build docs developers (and LLMs) love

Get Started

Core Concepts

Framework Guides

Features

Rendering

Tools

Component Registry

Advanced

​Basic usage

​Renderer options

​Required options

​Render mode

​Video encoding

​Intermediate capture

​Audio configuration

​Advanced options

​Browser configuration

​Audio track configuration

​Example with audio tracks

​Job options

​Example with progress tracking

​Rendering workflow

​GPU acceleration

​Browser GPU acceleration

​WebCodecs hardware encoding

​FFmpeg hardware acceleration

​Diagnostics

​Error handling

Build docs developers (and LLMs) love

Basic usage

Renderer options

Required options

Render mode

Video encoding

Intermediate capture

Audio configuration

Advanced options

Browser configuration

Audio track configuration

Example with audio tracks

Job options

Example with progress tracking

Rendering workflow

GPU acceleration

Browser GPU acceleration

WebCodecs hardware encoding

FFmpeg hardware acceleration

Diagnostics

Error handling