> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/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

<ParamField path="width" type="number" required>
  Video width in pixels.
</ParamField>

<ParamField path="height" type="number" required>
  Video height in pixels.
</ParamField>

<ParamField path="fps" type="number" required>
  Frames per second for the output video.
</ParamField>

<ParamField path="durationInSeconds" type="number" required>
  Total duration of the composition in seconds.
</ParamField>

<ParamField path="startFrame" type="number" default="0">
  Frame number to start rendering from. Useful for distributed rendering where different workers render different frame ranges.
</ParamField>

<ParamField path="frameCount" type="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.
</ParamField>

<ParamField path="inputProps" type="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]
  }
  ```
</ParamField>

### Rendering mode

<ParamField path="mode" type="'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.
</ParamField>

<ParamField path="canvasSelector" type="string" default="'canvas'">
  CSS selector for the canvas element in `canvas` mode. Uses `document.querySelector()` to find the target canvas.
</ParamField>

<ParamField path="targetSelector" type="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.
</ParamField>

### Intermediate capture

<ParamField path="intermediateVideoCodec" type="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`)
</ParamField>

<ParamField path="intermediateImageFormat" type="'png' | 'jpeg'" default="'png'">
  Image format for intermediate capture in `dom` mode, or as a fallback in `canvas` mode when WebCodecs is unavailable.
</ParamField>

<ParamField path="intermediateImageQuality" type="number">
  JPEG quality (0-100) when `intermediateImageFormat` is `jpeg`. Higher values mean better quality.
</ParamField>

<ParamField path="keyFrameInterval" type="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.
</ParamField>

<ParamField path="webCodecsPreference" type="'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
</ParamField>

### Video encoding

<ParamField path="videoCodec" type="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`
</ParamField>

<ParamField path="pixelFormat" type="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)
</ParamField>

<ParamField path="crf" type="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)
</ParamField>

<ParamField path="preset" type="string" default="'fast'">
  Encoding preset balancing speed and compression. Slower presets produce smaller files:

  * `ultrafast`, `superfast`, `veryfast`, `faster`, `fast`
  * `medium`, `slow`, `slower`, `veryslow`
</ParamField>

<ParamField path="videoBitrate" type="string">
  Target video bitrate (e.g., `5M`, `1000k`). If provided, may override CRF for some codecs.
</ParamField>

<ParamField path="hwAccel" type="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.
</ParamField>

### Audio

<ParamField path="audioFilePath" type="string">
  Path to a single audio file to include in the output video.
</ParamField>

<ParamField path="audioTracks" type="(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.
</ParamField>

<ParamField path="audioCodec" type="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
</ParamField>

<ParamField path="audioBitrate" type="string">
  Audio bitrate (e.g., `128k`, `192k`, `320k`). Higher values mean better quality.
</ParamField>

<ParamField path="mixInputAudio" type="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.
</ParamField>

### Subtitles

<ParamField path="subtitles" type="string">
  Path to an SRT subtitle file to burn into the video. Requires video transcoding (`videoCodec` cannot be `copy`).
</ParamField>

### Browser

<ParamField path="browserConfig" type="BrowserConfig">
  Configuration for the Playwright browser instance. See [BrowserConfig](#browserconfig) for details.
</ParamField>

<ParamField path="stabilityTimeout" type="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.
</ParamField>

### FFmpeg

<ParamField path="ffmpegPath" type="string">
  Path to a custom FFmpeg binary. Defaults to the binary provided by `@ffmpeg-installer/ffmpeg`.
</ParamField>

### Determinism

<ParamField path="randomSeed" type="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.
</ParamField>

## RenderJobOptions

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

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

<ParamField path="onProgress" type="(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`);
  }
  ```
</ParamField>

<ParamField path="signal" type="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);
  ```
</ParamField>

<ParamField path="tracePath" type="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'
  });
  ```
</ParamField>

## 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;
}
```

<ParamField path="path" type="string" required>
  Path to the audio file.
</ParamField>

<ParamField path="buffer" type="Buffer">
  Optional audio data buffer. If provided, this buffer is piped to FFmpeg instead of reading from disk.
</ParamField>

<ParamField path="volume" type="number" default="1.0">
  Volume multiplier between 0.0 (silent) and 1.0 (full volume). Values greater than 1.0 amplify the audio.
</ParamField>

<ParamField path="offset" type="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
  }
  ```
</ParamField>

<ParamField path="seek" type="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
  }
  ```
</ParamField>

<ParamField path="fadeInDuration" type="number" default="0">
  Duration in seconds for the audio to fade in from silence.
</ParamField>

<ParamField path="fadeOutDuration" type="number" default="0">
  Duration in seconds for the audio to fade out to silence.
</ParamField>

<ParamField path="loop" type="boolean" default="false">
  Whether to loop the audio track indefinitely. The track will repeat until the end of the composition.
</ParamField>

<ParamField path="playbackRate" type="number" default="1.0">
  Playback speed multiplier:

  * `0.5`: Half speed (slower)
  * `1.0`: Normal speed
  * `2.0`: Double speed (faster)
</ParamField>

<ParamField path="duration" type="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.
</ParamField>

### 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[];
}
```

<ParamField path="headless" type="boolean" default="true">
  Whether to run the browser in headless mode. Set to `false` to see the browser window during rendering (useful for debugging).
</ParamField>

<ParamField path="executablePath" type="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`
</ParamField>

<ParamField path="args" type="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'
    ]
  }
  ```
</ParamField>

## DistributedRenderOptions

Extends `RendererOptions` with distributed rendering settings.

```typescript theme={null}
interface DistributedRenderOptions extends RendererOptions {
  concurrency?: number;
  executor?: RenderExecutor;
}
```

<ParamField path="concurrency" type="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.
</ParamField>

<ParamField path="executor" type="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.
</ParamField>

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