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.

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.

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.

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.

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.

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.

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

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 - Configuration interface
• TimeDriver - Driver interfaces