Render options

This page documents all configuration interfaces for the Helios renderer package.

RendererOptions

Primary configuration interface for the Renderer class.

interface RendererOptions {
  // Composition settings
  width: number;
  height: number;
  fps: number;
  durationInSeconds: number;
  startFrame?: number;
  frameCount?: number;
  inputProps?: Record<string, any>;

  // Rendering mode
  mode?: 'canvas' | 'dom';
  canvasSelector?: string;
  targetSelector?: string;

  // Intermediate capture
  intermediateVideoCodec?: string;
  intermediateImageFormat?: 'png' | 'jpeg';
  intermediateImageQuality?: number;
  keyFrameInterval?: number;
  webCodecsPreference?: 'hardware' | 'software' | 'disabled';

  // Video encoding
  videoCodec?: string;
  pixelFormat?: string;
  crf?: number;
  preset?: string;
  videoBitrate?: string;
  hwAccel?: string;

  // Audio
  audioFilePath?: string;
  audioTracks?: (string | AudioTrackConfig)[];
  audioCodec?: string;
  audioBitrate?: string;
  mixInputAudio?: boolean;

  // Subtitles
  subtitles?: string;

  // Browser
  browserConfig?: BrowserConfig;
  stabilityTimeout?: number;

  // FFmpeg
  ffmpegPath?: string;

  // Determinism
  randomSeed?: number;
}

Composition settings

width

number

required

Video width in pixels.

height

number

required

Video height in pixels.

fps

number

required

Frames per second for the output video.

durationInSeconds

number

required

Total duration of the composition in seconds.

startFrame

number

default:"0"

Frame number to start rendering from. Useful for distributed rendering where different workers render different frame ranges.

frameCount

number

Exact number of frames to render. If provided, overrides durationInSeconds for calculating the render loop. Useful for distributed rendering to avoid floating-point errors.

inputProps

Record<string, any>

Custom properties to inject into the composition. Accessible as window.__HELIOS_PROPS__ in your HTML.

inputProps: {
  title: 'My Video',
  theme: 'dark',
  data: [1, 2, 3]
}

Rendering mode

mode

'canvas' | 'dom'

default:"'canvas'"

Rendering strategy:

canvas: Captures frames from a canvas element using WebCodecs or image export. Best for canvas-based animations and WebGL.
dom: Captures frames via viewport screenshots. Best for CSS and DOM animations.

canvasSelector

string

default:"'canvas'"

CSS selector for the canvas element in canvas mode. Uses document.querySelector() to find the target canvas.

targetSelector

string

CSS selector for the target element in dom mode. If provided, screenshots are limited to this element’s bounding box. Supports Shadow DOM traversal.

Intermediate capture

intermediateVideoCodec

string

default:"'vp8'"

Codec for intermediate video capture in canvas mode (when using WebCodecs):

vp8: Widely supported, good performance
vp9: Better compression, higher quality
av1: Best compression, requires modern hardware
Custom codec strings (e.g., av01.0.05M.08)

intermediateImageFormat

'png' | 'jpeg'

default:"'png'"

Image format for intermediate capture in dom mode, or as a fallback in canvas mode when WebCodecs is unavailable.

intermediateImageQuality

number

JPEG quality (0-100) when intermediateImageFormat is jpeg. Higher values mean better quality.

keyFrameInterval

number

default:"fps * 2"

Number of frames between keyframes (GOP size) when using WebCodecs in canvas mode. For example, at 30fps, a value of 60 means a keyframe every 2 seconds.

webCodecsPreference

'hardware' | 'software' | 'disabled'

default:"'hardware'"

WebCodecs acceleration preference in canvas mode:

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

Video encoding

videoCodec

string

default:"'libx264'"

FFmpeg video codec for final output. Common values:

libx264: H.264 (widely compatible)
libx265: H.265/HEVC (better compression)
libvpx: VP8 for WebM
libvpx-vp9: VP9 for WebM
copy: Copy video stream without re-encoding (requires matching input codec)
Hardware encoders: h264_nvenc, h264_qsv, h264_videotoolbox

pixelFormat

string

default:"'yuv420p'"

FFmpeg pixel format. Common values:

yuv420p: 8-bit 4:2:0 (standard, widely compatible)
yuv420p10le: 10-bit 4:2:0
yuv444p: 4:4:4 (higher quality, larger file size)

crf

number

Constant Rate Factor for quality control. Lower values mean better quality (larger files). Range varies by codec:

libx264/libx265: 0-51 (recommended: 18-28)
libvpx/libvpx-vp9: 4-63 (recommended: 10-31)

preset

string

default:"'fast'"

Encoding preset balancing speed and compression. Slower presets produce smaller files:

ultrafast, superfast, veryfast, faster, fast
medium, slow, slower, veryslow

videoBitrate

string

Target video bitrate (e.g., 5M, 1000k). If provided, may override CRF for some codecs.

hwAccel

string

Hardware acceleration method for FFmpeg. Common values:

cuda: NVIDIA GPU acceleration
vaapi: Video Acceleration API (Linux)
qsv: Intel Quick Sync Video
videotoolbox: macOS hardware acceleration
auto: Let FFmpeg choose

The renderer validates that the specified method is available in your FFmpeg build.

Audio

audioFilePath

string

Path to a single audio file to include in the output video.

audioTracks

(string | AudioTrackConfig)[]

Array of audio tracks to mix into the output. Each item can be:

A string file path
An AudioTrackConfig object with volume, offset, fades, etc.

See AudioTrackConfig for details.

audioCodec

string

default:"'aac'"

Audio codec for final output:

aac: AAC audio (widely compatible)
libmp3lame: MP3
libvorbis: Vorbis (for WebM)
libopus: Opus (modern, efficient)
pcm_s16le: Uncompressed PCM
copy: Copy audio stream without re-encoding

audioBitrate

string

Audio bitrate (e.g., 128k, 192k, 320k). Higher values mean better quality.

mixInputAudio

boolean

default:"false"

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

Subtitles

subtitles

string

Path to an SRT subtitle file to burn into the video. Requires video transcoding (videoCodec cannot be copy).

Browser

browserConfig

BrowserConfig

Configuration for the Playwright browser instance. See BrowserConfig for details.

stabilityTimeout

number

default:"30000"

Maximum time in milliseconds to wait for the page to stabilize after setting each frame time. Useful for waiting on font loading, image decoding, or custom async operations.

FFmpeg

ffmpegPath

string

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

Determinism

randomSeed

number

default:"0x12345678"

Seed for the deterministic random number generator. The renderer overrides Math.random() in the composition with a seeded PRNG to ensure reproducible renders.

RenderJobOptions

Options for individual render jobs, including progress tracking and cancellation.

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

onProgress

(progress: number) => void

Callback invoked periodically during rendering with a progress value between 0 and 1.

onProgress: (progress) => {
  console.log(`${(progress * 100).toFixed(1)}% complete`);
}

signal

AbortSignal

AbortSignal to cancel the rendering process. Use AbortController to create and trigger signals:

const controller = new AbortController();
await renderer.render(url, output, { signal: controller.signal });

// Cancel after 10 seconds
setTimeout(() => controller.abort(), 10000);

tracePath

string

Path to save a Playwright trace file (ZIP format). Useful for debugging rendering issues. The trace includes screenshots, snapshots, and network activity.

await renderer.render(url, output, {
  tracePath: './traces/debug.zip'
});

AudioTrackConfig

Detailed configuration for individual audio tracks.

interface AudioTrackConfig {
  path: string;
  buffer?: Buffer;
  volume?: number;
  offset?: number;
  seek?: number;
  fadeInDuration?: number;
  fadeOutDuration?: number;
  loop?: boolean;
  playbackRate?: number;
  duration?: number;
}

path

string

required

Path to the audio file.

buffer

Buffer

Optional audio data buffer. If provided, this buffer is piped to FFmpeg instead of reading from disk.

volume

number

default:"1.0"

Volume multiplier between 0.0 (silent) and 1.0 (full volume). Values greater than 1.0 amplify the audio.

offset

number

default:"0"

Time in seconds when this track should start in the composition timeline.

{
  path: './voiceover.mp3',
  offset: 5 // Start at 5 seconds
}

seek

number

default:"0"

Time in seconds to seek into the source audio file before playing. Useful for trimming the beginning of a track.

{
  path: './song.mp3',
  seek: 30 // Skip first 30 seconds
}

fadeInDuration

number

default:"0"

Duration in seconds for the audio to fade in from silence.

fadeOutDuration

number

default:"0"

Duration in seconds for the audio to fade out to silence.

loop

boolean

default:"false"

Whether to loop the audio track indefinitely. The track will repeat until the end of the composition.

playbackRate

number

default:"1.0"

Playback speed multiplier:

0.5: Half speed (slower)
1.0: Normal speed
2.0: Double speed (faster)

duration

number

Duration of the source audio in seconds, if known. Allows smart calculation of fade-out relative to the clip end rather than the composition end.

Audio track example

audioTracks: [
  {
    path: './background-music.mp3',
    volume: 0.6,
    fadeInDuration: 3,
    fadeOutDuration: 5,
    loop: true
  },
  {
    path: './voiceover.wav',
    offset: 2,
    volume: 1.0
  },
  {
    path: './sound-effect.mp3',
    offset: 10,
    volume: 0.8,
    seek: 1.5,
    playbackRate: 1.2
  }
]

BrowserConfig

Configuration for the Playwright browser instance.

interface BrowserConfig {
  headless?: boolean;
  executablePath?: string;
  args?: string[];
}

headless

boolean

default:"true"

Whether to run the browser in headless mode. Set to false to see the browser window during rendering (useful for debugging).

executablePath

string

Path to a custom browser executable instead of the bundled Chromium:

/usr/bin/google-chrome
/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
C:\Program Files\Google\Chrome\Application\chrome.exe

args

string[]

Additional command-line arguments to pass to the browser. These are merged with the default arguments:

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

Example custom args:

browserConfig: {
  args: [
    '--disable-gpu',
    '--no-sandbox',
    '--disable-dev-shm-usage'
  ]
}

DistributedRenderOptions

Extends RendererOptions with distributed rendering settings.

interface DistributedRenderOptions extends RendererOptions {
  concurrency?: number;
  executor?: RenderExecutor;
}

concurrency

number

default:"os.cpus().length - 1"

Number of parallel render workers. Determines how many chunks the composition is split into.When set to 1, the orchestrator skips chunking and uses a standard Renderer directly.

executor

RenderExecutor

Custom executor for running render chunks. Defaults to LocalExecutor which runs chunks as parallel processes on the local machine.Implement the RenderExecutor interface to run chunks on cloud infrastructure or distributed systems.

RenderExecutor interface

interface RenderExecutor {
  render(
    compositionUrl: string,
    outputPath: string,
    options: RendererOptions,
    jobOptions?: RenderJobOptions
  ): Promise<void>;
}

Custom executors must implement a single render method that accepts the same parameters as Renderer.render().

Example custom executor

import { RenderExecutor } from '@helios/renderer';

class CloudExecutor implements RenderExecutor {
  async render(
    compositionUrl: string,
    outputPath: string,
    options: RendererOptions,
    jobOptions?: RenderJobOptions
  ): Promise<void> {
    // Upload composition to cloud storage
    const cloudUrl = await this.uploadComposition(compositionUrl);
    
    // Trigger cloud render job
    const jobId = await this.startCloudJob(cloudUrl, options);
    
    // Poll for completion
    await this.waitForCompletion(jobId, jobOptions?.onProgress);
    
    // Download rendered output
    await this.downloadOutput(jobId, outputPath);
  }

  // Implementation details...
}

Core

Renderer

Player

CLI

Types

Render options

RendererOptions

Composition settings

Rendering mode

Intermediate capture

Video encoding

Audio

Subtitles

Browser

FFmpeg

Determinism

RenderJobOptions

AudioTrackConfig

Audio track example

BrowserConfig

DistributedRenderOptions

RenderExecutor interface

Example custom executor

Build docs developers (and LLMs) love

Core

Renderer

Player

CLI

Types

​RendererOptions

​Composition settings

​Rendering mode

​Intermediate capture

​Video encoding

​Audio

​Subtitles

​Browser

​FFmpeg

​Determinism

​RenderJobOptions

​AudioTrackConfig

​Audio track example

​BrowserConfig

​DistributedRenderOptions

​RenderExecutor interface

​Example custom executor

Build docs developers (and LLMs) love

RendererOptions

Composition settings

Rendering mode

Intermediate capture

Video encoding

Audio

Subtitles

Browser

FFmpeg

Determinism

RenderJobOptions

AudioTrackConfig

Audio track example

BrowserConfig

DistributedRenderOptions

RenderExecutor interface

Example custom executor