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

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

<ParamField path="options" type="HeliosOptions<TInputProps>" required>
  Configuration options for the Helios instance

  <Expandable title="properties">
    <ParamField path="duration" type="number" required>
      Duration of the composition in seconds
    </ParamField>

    <ParamField path="fps" type="number" required>
      Frame rate in frames per second
    </ParamField>

    <ParamField path="width" type="number" default="1920">
      Canvas width in pixels
    </ParamField>

    <ParamField path="height" type="number" default="1080">
      Canvas height in pixels
    </ParamField>

    <ParamField path="initialFrame" type="number" default="0">
      Starting frame number
    </ParamField>

    <ParamField path="loop" type="boolean" default="false">
      Whether to loop playback
    </ParamField>

    <ParamField path="playbackRange" type="[number, number] | null">
      Optional playback range as \[startFrame, endFrame]
    </ParamField>

    <ParamField path="autoSyncAnimations" type="boolean" default="false">
      Automatically sync Web Animations API animations to Helios timeline
    </ParamField>

    <ParamField path="inputProps" type="TInputProps">
      User-defined input properties for the composition
    </ParamField>

    <ParamField path="schema" type="HeliosSchema">
      Schema defining validation and defaults for inputProps
    </ParamField>

    <ParamField path="playbackRate" type="number" default="1">
      Playback speed multiplier
    </ParamField>

    <ParamField path="volume" type="number" default="1">
      Master audio volume (0.0 to 1.0)
    </ParamField>

    <ParamField path="muted" type="boolean" default="false">
      Whether audio is muted
    </ParamField>

    <ParamField path="audioTracks" type="Record<string, AudioTrackState>">
      Per-track audio state (volume and muted)
    </ParamField>

    <ParamField path="availableAudioTracks" type="AudioTrackMetadata[]">
      Audio track metadata for headless environments
    </ParamField>

    <ParamField path="captions" type="string | CaptionCue[]">
      SRT/WebVTT string or array of caption cues
    </ParamField>

    <ParamField path="markers" type="Marker[]">
      Timeline markers
    </ParamField>

    <ParamField path="timeline" type="HeliosTimeline">
      Timeline structure with tracks and clips
    </ParamField>

    <ParamField path="driver" type="TimeDriver">
      Custom time driver (defaults to NoopDriver or DomDriver if autoSyncAnimations is true)
    </ParamField>

    <ParamField path="ticker" type="Ticker">
      Custom ticker for frame updates (defaults to RafTicker or TimeoutTicker)
    </ParamField>

    <ParamField path="animationScope" type="unknown">
      Scope for Web Animations API (defaults to document)
    </ParamField>
  </Expandable>
</ParamField>

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

<ParamField path="frame" type="number" required>
  Frame number to seek to (will be clamped to valid range)
</ParamField>

### seekToTime()

Seeks to a specific time in seconds.

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

<ParamField path="seconds" type="number" required>
  Time in seconds to seek to
</ParamField>

### seekToMarker()

Seeks to a marker by ID.

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

<ParamField path="id" type="string" required>
  Marker ID to seek to
</ParamField>

### setDuration()

Updates the composition duration.

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

<ParamField path="seconds" type="number" required>
  New duration in seconds (must be non-negative)
</ParamField>

### setFps()

Updates the frame rate.

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

<ParamField path="fps" type="number" required>
  New frame rate (must be greater than 0)
</ParamField>

### setSize()

Updates the canvas dimensions.

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

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

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

### setLoop()

Updates the loop state.

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

<ParamField path="shouldLoop" type="boolean" required>
  Whether to loop playback
</ParamField>

### setInputProps()

Updates the input properties.

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

<ParamField path="props" type="TInputProps" required>
  New input properties (will be validated against schema)
</ParamField>

### setPlaybackRate()

Updates the playback rate.

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

<ParamField path="rate" type="number" required>
  Playback speed multiplier
</ParamField>

### setAudioVolume()

Updates the master audio volume.

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

<ParamField path="volume" type="number" required>
  Volume level (0.0 to 1.0, will be clamped)
</ParamField>

### setAudioMuted()

Updates the master audio mute state.

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

<ParamField path="muted" type="boolean" required>
  Whether audio should be muted
</ParamField>

### setAudioTrackVolume()

Updates the volume for a specific audio track.

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

<ParamField path="trackId" type="string" required>
  ID of the audio track
</ParamField>

<ParamField path="volume" type="number" required>
  Volume level (0.0 to 1.0, will be clamped)
</ParamField>

### setAudioTrackMuted()

Updates the mute state for a specific audio track.

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

<ParamField path="trackId" type="string" required>
  ID of the audio track
</ParamField>

<ParamField path="muted" type="boolean" required>
  Whether the track should be muted
</ParamField>

### setAvailableAudioTracks()

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

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

<ParamField path="tracks" type="AudioTrackMetadata[]" required>
  Array of audio track metadata
</ParamField>

### setCaptions()

Updates the captions.

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

<ParamField path="captions" type="string | CaptionCue[]" required>
  SRT/WebVTT string or array of caption cues
</ParamField>

### setTimeline()

Updates the timeline.

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

<ParamField path="timeline" type="HeliosTimeline" required>
  Timeline structure with tracks and clips
</ParamField>

### setMarkers()

Replaces all markers.

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

<ParamField path="markers" type="Marker[]" required>
  Array of markers (will be validated and sorted)
</ParamField>

### addMarker()

Adds a single marker.

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

<ParamField path="marker" type="Marker" required>
  Marker to add (must have unique ID)
</ParamField>

### removeMarker()

Removes a marker by ID.

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

<ParamField path="id" type="string" required>
  ID of the marker to remove
</ParamField>

### setPlaybackRange()

Sets a playback range.

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

<ParamField path="startFrame" type="number" required>
  Starting frame (must be >= 0)
</ParamField>

<ParamField path="endFrame" type="number" required>
  Ending frame (must be > startFrame)
</ParamField>

### clearPlaybackRange()

Clears the playback range.

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

### getState()

Gets the current state snapshot.

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

<ResponseField name="state" type="HeliosState<TInputProps>">
  Current state object containing all signal values
</ResponseField>

### subscribe()

Subscribes to state changes.

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

<ParamField path="callback" type="(state: HeliosState<TInputProps>) => void" required>
  Function called on each state change
</ParamField>

<ResponseField name="unsubscribe" type="() => void">
  Function to unsubscribe from state changes
</ResponseField>

### unsubscribe()

Unsubscribes a specific callback.

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

<ParamField path="callback" type="HeliosSubscriber<TInputProps>" required>
  The callback function to unsubscribe
</ParamField>

### waitUntilStable()

Waits for all asynchronous operations to complete.

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

<ResponseField name="promise" type="Promise<void>">
  Resolves when the composition is stable (images loaded, media seeked, etc.)
</ResponseField>

### registerStabilityCheck()

Registers a custom stability check.

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

<ParamField path="check" type="() => Promise<void>" required>
  Async function that resolves when stable
</ParamField>

<ResponseField name="dispose" type="() => void">
  Function to unregister the stability check
</ResponseField>

### getAudioContext()

Gets the shared AudioContext.

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

<ResponseField name="audioContext" type="Promise<unknown>">
  The AudioContext instance or null if not available
</ResponseField>

### getAudioSourceNode()

Gets the MediaElementAudioSourceNode for a track.

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

<ParamField path="trackId" type="string" required>
  ID of the audio track
</ParamField>

<ResponseField name="sourceNode" type="Promise<unknown>">
  The audio source node or null if not available
</ResponseField>

### bindTo()

Binds this instance to another Helios instance.

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

<ParamField path="master" type="Helios<any>" required>
  The master Helios instance to sync with
</ParamField>

### 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();
```

<ResponseField name="report" type="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
</ResponseField>

## 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();
```