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

# Helios class

> Core engine class for managing animation state and timeline synchronization

The `Helios` class is the core engine that manages animation state, timeline synchronization, and media playback.

## Constructor

```typescript theme={null}
const helios = new Helios(options);
```

**options** `HeliosOptions\<TInputProps\>` *required*

Configuration options for the Helios instance

**properties**

**duration** `number` *required*

Duration of the composition in seconds

**fps** `number` *required*

Frame rate in frames per second

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

Canvas width in pixels

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

Canvas height in pixels

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

Starting frame number

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

Whether to loop playback

**playbackRange** `[number, number] | null`

Optional playback range as \[startFrame, endFrame]

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

Automatically sync Web Animations API animations to Helios timeline

**inputProps** `TInputProps`

User-defined input properties for the composition

**schema** `HeliosSchema`

Schema defining validation and defaults for inputProps

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

Playback speed multiplier

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

Master audio volume (0.0 to 1.0)

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

Whether audio is muted

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

Per-track audio state (volume and muted)

**availableAudioTracks** `AudioTrackMetadata[]`

Audio track metadata for headless environments

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

SRT/WebVTT string or array of caption cues

**markers** `Marker[]`

Timeline markers

**timeline** `HeliosTimeline`

Timeline structure with tracks and clips

**driver** `TimeDriver`

Custom time driver (defaults to NoopDriver or DomDriver if autoSyncAnimations is true)

**ticker** `Ticker`

Custom ticker for frame updates (defaults to RafTicker or TimeoutTicker)

**animationScope** `unknown`

Scope for Web Animations API (defaults to document)

## Signals

Helios exposes reactive signals that can be subscribed to for updates.

### currentFrame

```typescript theme={null}
helios.currentFrame: ReadonlySignal<number>
```

Signal for the current frame number.

### currentTime

```typescript theme={null}
helios.currentTime: ReadonlySignal<number>
```

Signal for the current time in seconds.

### isPlaying

```typescript theme={null}
helios.isPlaying: ReadonlySignal<boolean>
```

Signal for the playback state.

### loop

```typescript theme={null}
helios.loop: ReadonlySignal<boolean>
```

Signal for the loop state.

### inputProps

```typescript theme={null}
helios.inputProps: ReadonlySignal<TInputProps>
```

Signal for the input properties.

### playbackRate

```typescript theme={null}
helios.playbackRate: ReadonlySignal<number>
```

Signal for the playback rate.

### volume

```typescript theme={null}
helios.volume: ReadonlySignal<number>
```

Signal for the audio volume.

### muted

```typescript theme={null}
helios.muted: ReadonlySignal<boolean>
```

Signal for the audio muted state.

### audioTracks

```typescript theme={null}
helios.audioTracks: ReadonlySignal<Record<string, AudioTrackState>>
```

Signal for per-track audio state.

### availableAudioTracks

```typescript theme={null}
helios.availableAudioTracks: ReadonlySignal<AudioTrackMetadata[]>
```

Signal for discovered audio tracks.

### captions

```typescript theme={null}
helios.captions: ReadonlySignal<CaptionCue[]>
```

Signal for all caption cues.

### activeCaptions

```typescript theme={null}
helios.activeCaptions: ReadonlySignal<CaptionCue[]>
```

Signal for currently active caption cues.

### activeClips

```typescript theme={null}
helios.activeClips: ReadonlySignal<HeliosClip[]>
```

Signal for currently active timeline clips.

### markers

```typescript theme={null}
helios.markers: ReadonlySignal<Marker[]>
```

Signal for timeline markers.

### playbackRange

```typescript theme={null}
helios.playbackRange: ReadonlySignal<[number, number] | null>
```

Signal for the playback range.

### width

```typescript theme={null}
helios.width: ReadonlySignal<number>
```

Signal for the canvas width.

### height

```typescript theme={null}
helios.height: ReadonlySignal<number>
```

Signal for the canvas height.

### duration

```typescript theme={null}
helios.duration: ReadonlySignal<number>
```

Signal for the composition duration in seconds.

### fps

```typescript theme={null}
helios.fps: ReadonlySignal<number>
```

Signal for the frame rate.

## Properties

### isVirtualTimeBound

```typescript theme={null}
helios.isVirtualTimeBound: boolean
```

Returns true if the instance has successfully established a reactive, synchronous binding to the environment's virtual time source.

## Methods

### play()

Starts playback.

```typescript theme={null}
helios.play();
```

### pause()

Pauses playback.

```typescript theme={null}
helios.pause();
```

### seek()

Seeks to a specific frame.

```typescript theme={null}
helios.seek(frame);
```

**frame** `number` *required*

Frame number to seek to (will be clamped to valid range)

### seekToTime()

Seeks to a specific time in seconds.

```typescript theme={null}
helios.seekToTime(seconds);
```

**seconds** `number` *required*

Time in seconds to seek to

### seekToMarker()

Seeks to a marker by ID.

```typescript theme={null}
helios.seekToMarker(id);
```

**id** `string` *required*

Marker ID to seek to

### setDuration()

Updates the composition duration.

```typescript theme={null}
helios.setDuration(seconds);
```

**seconds** `number` *required*

New duration in seconds (must be non-negative)

### setFps()

Updates the frame rate.

```typescript theme={null}
helios.setFps(fps);
```

**fps** `number` *required*

New frame rate (must be greater than 0)

### setSize()

Updates the canvas dimensions.

```typescript theme={null}
helios.setSize(width, height);
```

**width** `number` *required*

New width in pixels

**height** `number` *required*

New height in pixels

### setLoop()

Updates the loop state.

```typescript theme={null}
helios.setLoop(shouldLoop);
```

**shouldLoop** `boolean` *required*

Whether to loop playback

### setInputProps()

Updates the input properties.

```typescript theme={null}
helios.setInputProps(props);
```

**props** `TInputProps` *required*

New input properties (will be validated against schema)

### setPlaybackRate()

Updates the playback rate.

```typescript theme={null}
helios.setPlaybackRate(rate);
```

**rate** `number` *required*

Playback speed multiplier

### setAudioVolume()

Updates the master audio volume.

```typescript theme={null}
helios.setAudioVolume(volume);
```

**volume** `number` *required*

Volume level (0.0 to 1.0, will be clamped)

### setAudioMuted()

Updates the master audio mute state.

```typescript theme={null}
helios.setAudioMuted(muted);
```

**muted** `boolean` *required*

Whether audio should be muted

### setAudioTrackVolume()

Updates the volume for a specific audio track.

```typescript theme={null}
helios.setAudioTrackVolume(trackId, volume);
```

**trackId** `string` *required*

ID of the audio track

**volume** `number` *required*

Volume level (0.0 to 1.0, will be clamped)

### setAudioTrackMuted()

Updates the mute state for a specific audio track.

```typescript theme={null}
helios.setAudioTrackMuted(trackId, muted);
```

**trackId** `string` *required*

ID of the audio track

**muted** `boolean` *required*

Whether the track should be muted

### setAvailableAudioTracks()

Manually sets available audio tracks (useful for headless environments).

```typescript theme={null}
helios.setAvailableAudioTracks(tracks);
```

**tracks** `AudioTrackMetadata[]` *required*

Array of audio track metadata

### setCaptions()

Updates the captions.

```typescript theme={null}
helios.setCaptions(captions);
```

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

SRT/WebVTT string or array of caption cues

### setTimeline()

Updates the timeline.

```typescript theme={null}
helios.setTimeline(timeline);
```

**timeline** `HeliosTimeline` *required*

Timeline structure with tracks and clips

### setMarkers()

Replaces all markers.

```typescript theme={null}
helios.setMarkers(markers);
```

**markers** `Marker[]` *required*

Array of markers (will be validated and sorted)

### addMarker()

Adds a single marker.

```typescript theme={null}
helios.addMarker(marker);
```

**marker** `Marker` *required*

Marker to add (must have unique ID)

### removeMarker()

Removes a marker by ID.

```typescript theme={null}
helios.removeMarker(id);
```

**id** `string` *required*

ID of the marker to remove

### setPlaybackRange()

Sets a playback range.

```typescript theme={null}
helios.setPlaybackRange(startFrame, endFrame);
```

**startFrame** `number` *required*

Starting frame (must be >= 0)

**endFrame** `number` *required*

Ending frame (must be > startFrame)

### clearPlaybackRange()

Clears the playback range.

```typescript theme={null}
helios.clearPlaybackRange();
```

### getState()

Gets the current state snapshot.

```typescript theme={null}
const state = helios.getState();
```

**state** `HeliosState\<TInputProps\>`

Current state object containing all signal values

### subscribe()

Subscribes to state changes.

```typescript theme={null}
const unsubscribe = helios.subscribe((state) => {
  console.log('State changed:', state);
});
```

**callback** `(state: HeliosState\<TInputProps\>) =\> void` *required*

Function called on each state change

**unsubscribe** `() =\> void`

Function to unsubscribe from state changes

### unsubscribe()

Unsubscribes a specific callback.

```typescript theme={null}
helios.unsubscribe(callback);
```

**callback** `HeliosSubscriber\<TInputProps\>` *required*

The callback function to unsubscribe

### waitUntilStable()

Waits for all asynchronous operations to complete.

```typescript theme={null}
await helios.waitUntilStable();
```

**promise** `Promise\<void\>`

Resolves when the composition is stable (images loaded, media seeked, etc.)

### registerStabilityCheck()

Registers a custom stability check.

```typescript theme={null}
const dispose = helios.registerStabilityCheck(async () => {
  await customAsyncOperation();
});
```

**check** `() =\> Promise\<void\>` *required*

Async function that resolves when stable

**dispose** `() =\> void`

Function to unregister the stability check

### getAudioContext()

Gets the shared AudioContext.

```typescript theme={null}
const audioContext = await helios.getAudioContext();
```

**audioContext** `Promise\<unknown\>`

The AudioContext instance or null if not available

### getAudioSourceNode()

Gets the MediaElementAudioSourceNode for a track.

```typescript theme={null}
const sourceNode = await helios.getAudioSourceNode('track-id');
```

**trackId** `string` *required*

ID of the audio track

**sourceNode** `Promise\<unknown\>`

The audio source node or null if not available

### bindTo()

Binds this instance to another Helios instance.

```typescript theme={null}
helios.bindTo(masterHelios);
```

**master** `Helios\<any\>` *required*

The master Helios instance to sync with

### unbind()

Unbinds from any master instance or document timeline.

```typescript theme={null}
helios.unbind();
```

### bindToDocumentTimeline()

Binds to the document.timeline for external synchronization.

```typescript theme={null}
helios.bindToDocumentTimeline();
```

### unbindFromDocumentTimeline()

Unbinds from the document.timeline.

```typescript theme={null}
helios.unbindFromDocumentTimeline();
```

### dispose()

Cleans up resources.

```typescript theme={null}
helios.dispose();
```

## Static methods

### Helios.diagnose()

Runs diagnostics on browser capabilities.

```typescript theme={null}
const report = await Helios.diagnose();
```

**report** `DiagnosticReport`

Diagnostic report containing:

* `waapi`: Web Animations API support
* `webCodecs`: WebCodecs API support
* `offscreenCanvas`: OffscreenCanvas support
* `webgl`: WebGL support
* `webgl2`: WebGL2 support
* `webAudio`: Web Audio API support
* `colorGamut`: Color gamut support
* `videoCodecs`: Supported video codecs
* `audioCodecs`: Supported audio codecs
* `videoDecoders`: Supported video decoders
* `audioDecoders`: Supported audio decoders
* `userAgent`: User agent string

## Example

```typescript theme={null}
import { Helios } from '@heliosvideo/core';

const helios = new Helios({
  duration: 10,
  fps: 30,
  width: 1920,
  height: 1080,
  loop: true,
});

// Subscribe to state changes
helios.subscribe((state) => {
  console.log(`Frame ${state.currentFrame} of ${state.duration * state.fps}`);
});

// Play the composition
helios.play();

// Seek to frame 100
helios.seek(100);

// Pause playback
helios.pause();

// Clean up
helios.dispose();
```


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