> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosrender.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

```typescript theme={null}
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.

```typescript theme={null}
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](#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](#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.

```typescript theme={null}
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.

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

**signal** `AbortSignal`

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

```typescript theme={null}
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.

```typescript theme={null}
await renderer.render(url, output, {
  tracePath: './traces/debug.zip'
});
```

## AudioTrackConfig

Detailed configuration for individual audio tracks.

```typescript theme={null}
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.

```typescript theme={null}
{
  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.

```typescript theme={null}
{
  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

```typescript theme={null}
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.

```typescript theme={null}
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:

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

Example custom args:

```typescript theme={null}
browserConfig: {
  args: [
    '--disable-gpu',
    '--no-sandbox',
    '--disable-dev-shm-usage'
  ]
}
```

## DistributedRenderOptions

Extends `RendererOptions` with distributed rendering settings.

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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...
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.