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

# HeliosConfig

> Configuration interface for initializing Helios compositions

## HeliosConfig

The `HeliosConfig` interface defines the configuration options for initializing a Helios composition. This is the base configuration used by both the core `Helios` class and the `HeliosComposition` interface.

```typescript theme={null}
interface HeliosConfig<TInputProps = Record<string, any>> {
  width?: number;
  height?: number;
  initialFrame?: number;
  duration: number;
  fps: number;
  loop?: boolean;
  playbackRange?: [number, number];
  autoSyncAnimations?: boolean;
  inputProps?: TInputProps;
  schema?: HeliosSchema;
  playbackRate?: number;
  volume?: number;
  muted?: boolean;
  audioTracks?: Record<string, AudioTrackState>;
  availableAudioTracks?: AudioTrackMetadata[];
  captions?: string | CaptionCue[];
  markers?: Marker[];
}
```

### Type parameters

**TInputProps** `Record\<string, any\>` (default: Record\<string, any>)

The type of input properties passed to the composition. Can be customized for type safety.

### Required fields

**duration** `number` *required*

Duration of the composition in seconds. Must be non-negative.

**fps** `number` *required*

Frame rate of the composition in frames per second. Must be greater than 0.

### Dimensions

**width** `number` (default: 1920)

Canvas width in pixels. Must be positive.

**height** `number` (default: 1080)

Canvas height in pixels. Must be positive.

### Playback control

**initialFrame** `number` (default: 0)

The starting frame when the composition is initialized. Will be clamped to valid range.

**loop** `boolean` (default: false)

Whether playback should loop when reaching the end.

**playbackRange** `[number, number]`

Optional range of frames to play. Specified as `[startFrame, endFrame]`. Start must be >= 0 and end must be > start.

**playbackRate** `number` (default: 1)

Playback speed multiplier. 1.0 is normal speed, 2.0 is double speed, 0.5 is half speed.

### Input properties and schema

**inputProps** `TInputProps`

Custom properties passed to the composition. These will be validated against the schema if provided.

**schema** `HeliosSchema`

Schema definition for validating and describing input properties. Enables type checking and default values.

### Animation synchronization

**autoSyncAnimations** `boolean` (default: false)

When true, automatically synchronizes WAAPI animations with Helios playback using a DomDriver.

### Audio control

**volume** `number` (default: 1)

Master volume level from 0.0 (muted) to 1.0 (full volume).

**muted** `boolean` (default: false)

Whether all audio should be muted.

**audioTracks** `Record\<string, AudioTrackState\>`

Per-track audio state configuration. Keys are track IDs.

**availableAudioTracks** `AudioTrackMetadata[]`

Metadata for available audio tracks. Can be used in headless environments where tracks cannot be auto-discovered.

### Captions and markers

**captions** `string | CaptionCue[]`

Captions for the composition. Can be an SRT/WebVTT string or an array of `CaptionCue` objects.

**markers** `Marker[]`

Timeline markers for navigation and annotation.

## HeliosOptions

Extends `HeliosConfig` with additional runtime options for the Helios engine.

```typescript theme={null}
interface HeliosOptions<TInputProps = Record<string, any>> extends HeliosConfig<TInputProps> {
  animationScope?: unknown;
  driver?: TimeDriver;
  ticker?: Ticker;
  timeline?: HeliosTimeline;
}
```

### Additional fields

**animationScope** `unknown` (default: document)

The scope for WAAPI animations. Defaults to `document` in browser environments.

**driver** `TimeDriver`

Custom time driver for managing media synchronization. If not provided, selects automatically based on `autoSyncAnimations`.

**ticker** `Ticker`

Custom ticker for the playback loop. Defaults to `RafTicker` in browser or `TimeoutTicker` in Node.js.

**timeline** `HeliosTimeline`

Timeline definition with tracks and clips for multi-layer compositions.

## AudioTrackState

Represents the playback state of an individual audio track.

```typescript theme={null}
type AudioTrackState = {
  volume: number;
  muted: boolean;
};
```

**volume** `number`

Volume level for this track from 0.0 to 1.0.

**muted** `boolean`

Whether this specific track is muted.

## Usage example

```typescript theme={null}
import { Helios, HeliosConfig } from '@helios/core';

const config: HeliosConfig = {
  width: 1920,
  height: 1080,
  duration: 10,
  fps: 30,
  loop: true,
  playbackRate: 1.0,
  volume: 0.8,
  inputProps: {
    title: 'My Video',
    theme: 'dark'
  },
  schema: {
    title: {
      type: 'string',
      default: 'Untitled'
    },
    theme: {
      type: 'string',
      enum: ['light', 'dark'],
      default: 'light'
    }
  }
};

const helios = new Helios(config);
```

## Related types

* [HeliosState](https://docs.heliosrender.com/api/types/helios-state.md) - Runtime state interface
* [RenderOptions](https://docs.heliosrender.com/api/types/render-options.md) - Rendering configuration
* [TimeDriver](https://docs.heliosrender.com/api/types/driver-interfaces.md) - Time synchronization interface


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