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

# HeliosState

> Runtime state interface for Helios compositions

## HeliosState

The `HeliosState` interface represents the complete runtime state of a Helios composition. It combines configuration, playback status, and computed values.

```typescript theme={null}
type HeliosState<TInputProps = Record<string, any>> = {
  width: number;
  height: number;
  duration: number;
  fps: number;
  currentFrame: number;
  loop: boolean;
  isPlaying: boolean;
  inputProps: TInputProps;
  playbackRate: number;
  volume: number;
  muted: boolean;
  audioTracks: Record<string, AudioTrackState>;
  availableAudioTracks: AudioTrackMetadata[];
  captions: CaptionCue[];
  activeCaptions: CaptionCue[];
  activeClips: HeliosClip[];
  markers: Marker[];
  playbackRange: [number, number] | null;
  currentTime: number;
};
```

### Type parameters

<ResponseField name="TInputProps" type="Record<string, any>" default="Record<string, any>">
  The type of input properties for the composition.
</ResponseField>

### Composition dimensions

<ResponseField name="width" type="number">
  Canvas width in pixels.
</ResponseField>

<ResponseField name="height" type="number">
  Canvas height in pixels.
</ResponseField>

### Time and frames

<ResponseField name="duration" type="number">
  Total duration of the composition in seconds.
</ResponseField>

<ResponseField name="fps" type="number">
  Frame rate in frames per second.
</ResponseField>

<ResponseField name="currentFrame" type="number">
  Current playback position in frames.
</ResponseField>

<ResponseField name="currentTime" type="number">
  Current playback position in seconds. Computed as `currentFrame / fps`.
</ResponseField>

### Playback status

<ResponseField name="isPlaying" type="boolean">
  Whether the composition is currently playing.
</ResponseField>

<ResponseField name="loop" type="boolean">
  Whether playback loops at the end.
</ResponseField>

<ResponseField name="playbackRate" type="number">
  Playback speed multiplier.
</ResponseField>

<ResponseField name="playbackRange" type="[number, number] | null">
  Active playback range as `[startFrame, endFrame]`, or `null` for full duration.
</ResponseField>

### Input properties

<ResponseField name="inputProps" type="TInputProps">
  User-defined input properties for the composition.
</ResponseField>

### Audio state

<ResponseField name="volume" type="number">
  Master volume from 0.0 to 1.0.
</ResponseField>

<ResponseField name="muted" type="boolean">
  Whether all audio is muted.
</ResponseField>

<ResponseField name="audioTracks" type="Record<string, AudioTrackState>">
  Per-track audio state. Keys are track IDs, values contain volume and mute state.
</ResponseField>

<ResponseField name="availableAudioTracks" type="AudioTrackMetadata[]">
  List of available audio tracks with metadata.
</ResponseField>

### Captions

<ResponseField name="captions" type="CaptionCue[]">
  All caption cues for the composition.
</ResponseField>

<ResponseField name="activeCaptions" type="CaptionCue[]">
  Caption cues active at the current time.
</ResponseField>

### Timeline

<ResponseField name="activeClips" type="HeliosClip[]">
  Clips currently active based on the timeline and current time.
</ResponseField>

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

## HeliosSubscriber

Callback type for subscribing to state changes.

```typescript theme={null}
type HeliosSubscriber<TInputProps = Record<string, any>> = 
  (state: HeliosState<TInputProps>) => void;
```

Subscribers are called whenever any reactive state changes.

## Related types

### CaptionCue

Represents a single caption cue.

```typescript theme={null}
interface CaptionCue {
  id: string;
  startTime: number; // milliseconds
  endTime: number;   // milliseconds
  text: string;
}
```

<ResponseField name="id" type="string">
  Unique identifier for the cue.
</ResponseField>

<ResponseField name="startTime" type="number">
  Start time in milliseconds.
</ResponseField>

<ResponseField name="endTime" type="number">
  End time in milliseconds.
</ResponseField>

<ResponseField name="text" type="string">
  Caption text content.
</ResponseField>

### Marker

Represents a timeline marker.

```typescript theme={null}
interface Marker {
  id: string;
  time: number; // seconds
  label?: string;
  color?: string;
  metadata?: Record<string, any>;
}
```

<ResponseField name="id" type="string">
  Unique identifier for the marker. Required and must be non-empty.
</ResponseField>

<ResponseField name="time" type="number">
  Marker position in seconds. Must be non-negative.
</ResponseField>

<ResponseField name="label" type="string">
  Optional human-readable label.
</ResponseField>

<ResponseField name="color" type="string">
  Optional hex color code for visual representation.
</ResponseField>

<ResponseField name="metadata" type="Record<string, any>">
  Optional custom metadata.
</ResponseField>

### HeliosClip

Represents a clip in a timeline.

```typescript theme={null}
interface HeliosClip {
  id: string;
  source: string;
  start: number;
  duration: number;
  track?: number;
  props?: Record<string, any>;
}
```

<ResponseField name="id" type="string">
  Unique clip identifier.
</ResponseField>

<ResponseField name="source" type="string">
  Source identifier or path.
</ResponseField>

<ResponseField name="start" type="number">
  Start time in seconds.
</ResponseField>

<ResponseField name="duration" type="number">
  Clip duration in seconds.
</ResponseField>

<ResponseField name="track" type="number">
  Optional track index.
</ResponseField>

<ResponseField name="props" type="Record<string, any>">
  Optional clip properties.
</ResponseField>

### AudioTrackMetadata

Metadata for an audio track.

```typescript theme={null}
interface AudioTrackMetadata {
  id: string;
  src: string;
  startTime: number;
  duration: number;
  fadeInDuration?: number;
  fadeOutDuration?: number;
  fadeEasing?: string;
}
```

<ResponseField name="id" type="string">
  Unique track identifier.
</ResponseField>

<ResponseField name="src" type="string">
  Audio source URL or path.
</ResponseField>

<ResponseField name="startTime" type="number">
  Track start time in composition.
</ResponseField>

<ResponseField name="duration" type="number">
  Track duration in seconds.
</ResponseField>

<ResponseField name="fadeInDuration" type="number">
  Optional fade-in duration in seconds.
</ResponseField>

<ResponseField name="fadeOutDuration" type="number">
  Optional fade-out duration in seconds.
</ResponseField>

<ResponseField name="fadeEasing" type="string">
  Optional easing function for fades.
</ResponseField>

## Usage example

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

const helios = new Helios({
  duration: 10,
  fps: 30
});

// Subscribe to state changes
const unsubscribe = helios.subscribe((state: HeliosState) => {
  console.log('Current frame:', state.currentFrame);
  console.log('Current time:', state.currentTime);
  console.log('Is playing:', state.isPlaying);
  
  // Active captions
  state.activeCaptions.forEach(cue => {
    console.log('Caption:', cue.text);
  });
});

// Get current state snapshot
const currentState = helios.getState();
console.log(currentState);

// Clean up
unsubscribe();
```

## Related types

* [HeliosConfig](/api/types/helios-config) - Configuration interface
* [TimeDriver](/api/types/driver-interfaces) - Driver interfaces