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

# 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

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

The type of input properties for the composition.

### Composition dimensions

**width** `number`

Canvas width in pixels.

**height** `number`

Canvas height in pixels.

### Time and frames

**duration** `number`

Total duration of the composition in seconds.

**fps** `number`

Frame rate in frames per second.

**currentFrame** `number`

Current playback position in frames.

**currentTime** `number`

Current playback position in seconds. Computed as `currentFrame / fps`.

### Playback status

**isPlaying** `boolean`

Whether the composition is currently playing.

**loop** `boolean`

Whether playback loops at the end.

**playbackRate** `number`

Playback speed multiplier.

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

Active playback range as `[startFrame, endFrame]`, or `null` for full duration.

### Input properties

**inputProps** `TInputProps`

User-defined input properties for the composition.

### Audio state

**volume** `number`

Master volume from 0.0 to 1.0.

**muted** `boolean`

Whether all audio is muted.

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

Per-track audio state. Keys are track IDs, values contain volume and mute state.

**availableAudioTracks** `AudioTrackMetadata[]`

List of available audio tracks with metadata.

### Captions

**captions** `CaptionCue[]`

All caption cues for the composition.

**activeCaptions** `CaptionCue[]`

Caption cues active at the current time.

### Timeline

**activeClips** `HeliosClip[]`

Clips currently active based on the timeline and current time.

**markers** `Marker[]`

Timeline markers for navigation.

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

**id** `string`

Unique identifier for the cue.

**startTime** `number`

Start time in milliseconds.

**endTime** `number`

End time in milliseconds.

**text** `string`

Caption text content.

### Marker

Represents a timeline marker.

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

**id** `string`

Unique identifier for the marker. Required and must be non-empty.

**time** `number`

Marker position in seconds. Must be non-negative.

**label** `string`

Optional human-readable label.

**color** `string`

Optional hex color code for visual representation.

**metadata** `Record\<string, any\>`

Optional custom metadata.

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

**id** `string`

Unique clip identifier.

**source** `string`

Source identifier or path.

**start** `number`

Start time in seconds.

**duration** `number`

Clip duration in seconds.

**track** `number`

Optional track index.

**props** `Record\<string, any\>`

Optional clip properties.

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

**id** `string`

Unique track identifier.

**src** `string`

Audio source URL or path.

**startTime** `number`

Track start time in composition.

**duration** `number`

Track duration in seconds.

**fadeInDuration** `number`

Optional fade-in duration in seconds.

**fadeOutDuration** `number`

Optional fade-out duration in seconds.

**fadeEasing** `string`

Optional easing function for fades.

## 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](https://docs.heliosrender.com/api/types/helios-config.md) - Configuration interface
* [TimeDriver](https://docs.heliosrender.com/api/types/driver-interfaces.md) - Driver interfaces


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