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

# 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

<ResponseField name="TInputProps" type="Record<string, any>" default="Record<string, any>">
  The type of input properties passed to the composition. Can be customized for type safety.
</ResponseField>

### Required fields

<ResponseField name="duration" type="number" required>
  Duration of the composition in seconds. Must be non-negative.
</ResponseField>

<ResponseField name="fps" type="number" required>
  Frame rate of the composition in frames per second. Must be greater than 0.
</ResponseField>

### Dimensions

<ResponseField name="width" type="number" default="1920">
  Canvas width in pixels. Must be positive.
</ResponseField>

<ResponseField name="height" type="number" default="1080">
  Canvas height in pixels. Must be positive.
</ResponseField>

### Playback control

<ResponseField name="initialFrame" type="number" default="0">
  The starting frame when the composition is initialized. Will be clamped to valid range.
</ResponseField>

<ResponseField name="loop" type="boolean" default="false">
  Whether playback should loop when reaching the end.
</ResponseField>

<ResponseField name="playbackRange" type="[number, number]">
  Optional range of frames to play. Specified as `[startFrame, endFrame]`. Start must be >= 0 and end must be > start.
</ResponseField>

<ResponseField name="playbackRate" type="number" default="1">
  Playback speed multiplier. 1.0 is normal speed, 2.0 is double speed, 0.5 is half speed.
</ResponseField>

### Input properties and schema

<ResponseField name="inputProps" type="TInputProps">
  Custom properties passed to the composition. These will be validated against the schema if provided.
</ResponseField>

<ResponseField name="schema" type="HeliosSchema">
  Schema definition for validating and describing input properties. Enables type checking and default values.
</ResponseField>

### Animation synchronization

<ResponseField name="autoSyncAnimations" type="boolean" default="false">
  When true, automatically synchronizes WAAPI animations with Helios playback using a DomDriver.
</ResponseField>

### Audio control

<ResponseField name="volume" type="number" default="1">
  Master volume level from 0.0 (muted) to 1.0 (full volume).
</ResponseField>

<ResponseField name="muted" type="boolean" default="false">
  Whether all audio should be muted.
</ResponseField>

<ResponseField name="audioTracks" type="Record<string, AudioTrackState>">
  Per-track audio state configuration. Keys are track IDs.
</ResponseField>

<ResponseField name="availableAudioTracks" type="AudioTrackMetadata[]">
  Metadata for available audio tracks. Can be used in headless environments where tracks cannot be auto-discovered.
</ResponseField>

### Captions and markers

<ResponseField name="captions" type="string | CaptionCue[]">
  Captions for the composition. Can be an SRT/WebVTT string or an array of `CaptionCue` objects.
</ResponseField>

<ResponseField name="markers" type="Marker[]">
  Timeline markers for navigation and annotation.
</ResponseField>

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

<ResponseField name="animationScope" type="unknown" default="document">
  The scope for WAAPI animations. Defaults to `document` in browser environments.
</ResponseField>

<ResponseField name="driver" type="TimeDriver">
  Custom time driver for managing media synchronization. If not provided, selects automatically based on `autoSyncAnimations`.
</ResponseField>

<ResponseField name="ticker" type="Ticker">
  Custom ticker for the playback loop. Defaults to `RafTicker` in browser or `TimeoutTicker` in Node.js.
</ResponseField>

<ResponseField name="timeline" type="HeliosTimeline">
  Timeline definition with tracks and clips for multi-layer compositions.
</ResponseField>

## AudioTrackState

Represents the playback state of an individual audio track.

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

<ResponseField name="volume" type="number">
  Volume level for this track from 0.0 to 1.0.
</ResponseField>

<ResponseField name="muted" type="boolean">
  Whether this specific track is muted.
</ResponseField>

## 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](/api/types/helios-state) - Runtime state interface
* [RenderOptions](/api/types/render-options) - Rendering configuration
* [TimeDriver](/api/types/driver-interfaces) - Time synchronization interface