Render options

Configuration types for Renderer and RenderOrchestrator

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...
}