Helios class - Helios

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

Constructor

const helios = new Helios(options);

HeliosOptions<TInputProps>

required

Configuration options for the Helios instance

Show properties

number

required

Duration of the composition in seconds

number

required

Frame rate in frames per second

number

default:"1920"

Canvas width in pixels

number

default:"1080"

Canvas height in pixels

number

default:"0"

Starting frame number

boolean

default:"false"

Whether to loop playback

[number, number] | null

Optional playback range as [startFrame, endFrame]

boolean

default:"false"

Automatically sync Web Animations API animations to Helios timeline

TInputProps

User-defined input properties for the composition

HeliosSchema

Schema defining validation and defaults for inputProps

number

default:"1"

Playback speed multiplier

number

default:"1"

Master audio volume (0.0 to 1.0)

boolean

default:"false"

Whether audio is muted

Record<string, AudioTrackState>

Per-track audio state (volume and muted)

AudioTrackMetadata[]

Audio track metadata for headless environments

string | CaptionCue[]

SRT/WebVTT string or array of caption cues

Marker[]

Timeline markers

HeliosTimeline

Timeline structure with tracks and clips

TimeDriver

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

Ticker

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

unknown

Scope for Web Animations API (defaults to document)

Signals

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

currentFrame

helios.currentFrame: ReadonlySignal<number>

Signal for the current frame number.

currentTime

helios.currentTime: ReadonlySignal<number>

Signal for the current time in seconds.

isPlaying

helios.isPlaying: ReadonlySignal<boolean>

Signal for the playback state.

loop

helios.loop: ReadonlySignal<boolean>

Signal for the loop state.

inputProps

helios.inputProps: ReadonlySignal<TInputProps>

Signal for the input properties.

playbackRate

helios.playbackRate: ReadonlySignal<number>

Signal for the playback rate.

volume

helios.volume: ReadonlySignal<number>

Signal for the audio volume.

muted

helios.muted: ReadonlySignal<boolean>

Signal for the audio muted state.

audioTracks

helios.audioTracks: ReadonlySignal<Record<string, AudioTrackState>>

Signal for per-track audio state.

availableAudioTracks

helios.availableAudioTracks: ReadonlySignal<AudioTrackMetadata[]>

Signal for discovered audio tracks.

captions

helios.captions: ReadonlySignal<CaptionCue[]>

Signal for all caption cues.

activeCaptions

helios.activeCaptions: ReadonlySignal<CaptionCue[]>

Signal for currently active caption cues.

activeClips

helios.activeClips: ReadonlySignal<HeliosClip[]>

Signal for currently active timeline clips.

markers

helios.markers: ReadonlySignal<Marker[]>

Signal for timeline markers.

playbackRange

helios.playbackRange: ReadonlySignal<[number, number] | null>

Signal for the playback range.

width

helios.width: ReadonlySignal<number>

Signal for the canvas width.

height

helios.height: ReadonlySignal<number>

Signal for the canvas height.

duration

helios.duration: ReadonlySignal<number>

Signal for the composition duration in seconds.

fps

helios.fps: ReadonlySignal<number>

Signal for the frame rate.

Properties

isVirtualTimeBound

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.

helios.play();

pause()

Pauses playback.

helios.pause();

seek()

Seeks to a specific frame.

helios.seek(frame);

number

required

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

seekToTime()

Seeks to a specific time in seconds.

helios.seekToTime(seconds);

number

required

Time in seconds to seek to

seekToMarker()

Seeks to a marker by ID.

helios.seekToMarker(id);

string

required

Marker ID to seek to

setDuration()

Updates the composition duration.

helios.setDuration(seconds);

number

required

New duration in seconds (must be non-negative)

setFps()

Updates the frame rate.

helios.setFps(fps);

number

required

New frame rate (must be greater than 0)

setSize()

Updates the canvas dimensions.

helios.setSize(width, height);

number

required

New width in pixels

number

required

New height in pixels

setLoop()

Updates the loop state.

helios.setLoop(shouldLoop);

boolean

required

Whether to loop playback

setInputProps()

Updates the input properties.

helios.setInputProps(props);

TInputProps

required

New input properties (will be validated against schema)

setPlaybackRate()

Updates the playback rate.

helios.setPlaybackRate(rate);

number

required

Playback speed multiplier

setAudioVolume()

Updates the master audio volume.

helios.setAudioVolume(volume);

number

required

Volume level (0.0 to 1.0, will be clamped)

setAudioMuted()

Updates the master audio mute state.

helios.setAudioMuted(muted);

boolean

required

Whether audio should be muted

setAudioTrackVolume()

Updates the volume for a specific audio track.

helios.setAudioTrackVolume(trackId, volume);

string

required

ID of the audio track

number

required

Volume level (0.0 to 1.0, will be clamped)

setAudioTrackMuted()

Updates the mute state for a specific audio track.

helios.setAudioTrackMuted(trackId, muted);

string

required

ID of the audio track

boolean

required

Whether the track should be muted

setAvailableAudioTracks()

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

helios.setAvailableAudioTracks(tracks);

AudioTrackMetadata[]

required

Array of audio track metadata

setCaptions()

Updates the captions.

helios.setCaptions(captions);

string | CaptionCue[]

required

SRT/WebVTT string or array of caption cues

setTimeline()

Updates the timeline.

helios.setTimeline(timeline);

HeliosTimeline

required

Timeline structure with tracks and clips

setMarkers()

Replaces all markers.

helios.setMarkers(markers);

Marker[]

required

Array of markers (will be validated and sorted)

addMarker()

Adds a single marker.

helios.addMarker(marker);

Marker

required

Marker to add (must have unique ID)

removeMarker()

Removes a marker by ID.

helios.removeMarker(id);

string

required

ID of the marker to remove

setPlaybackRange()

Sets a playback range.

helios.setPlaybackRange(startFrame, endFrame);

number

required

Starting frame (must be >= 0)

number

required

Ending frame (must be > startFrame)

clearPlaybackRange()

Clears the playback range.

helios.clearPlaybackRange();

getState()

Gets the current state snapshot.

const state = helios.getState();

HeliosState<TInputProps>

Current state object containing all signal values

Subscribes to state changes.

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

(state: HeliosState<TInputProps>) => void

required

Function called on each state change

() => void

Function to unsubscribe from state changes

unsubscribe()

Unsubscribes a specific callback.

helios.unsubscribe(callback);

HeliosSubscriber<TInputProps>

required

The callback function to unsubscribe

waitUntilStable()

Waits for all asynchronous operations to complete.

await helios.waitUntilStable();

Promise<void>

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

registerStabilityCheck()

Registers a custom stability check.

const dispose = helios.registerStabilityCheck(async () => {
  await customAsyncOperation();
});

() => Promise<void>

required

Async function that resolves when stable

() => void

Function to unregister the stability check

getAudioContext()

Gets the shared AudioContext.

const audioContext = await helios.getAudioContext();

Promise<unknown>

The AudioContext instance or null if not available

getAudioSourceNode()

Gets the MediaElementAudioSourceNode for a track.

const sourceNode = await helios.getAudioSourceNode('track-id');

string

required

ID of the audio track

Promise<unknown>

The audio source node or null if not available

bindTo()

Binds this instance to another Helios instance.

helios.bindTo(masterHelios);

Helios<any>

required

The master Helios instance to sync with

unbind()

Unbinds from any master instance or document timeline.

helios.unbind();

bindToDocumentTimeline()

Binds to the document.timeline for external synchronization.

helios.bindToDocumentTimeline();

unbindFromDocumentTimeline()

Unbinds from the document.timeline.

helios.unbindFromDocumentTimeline();

dispose()

Cleans up resources.

helios.dispose();

Static methods

Helios.diagnose()

Runs diagnostics on browser capabilities.

const report = await Helios.diagnose();

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

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

​Constructor

​Signals

​currentFrame

​currentTime

​isPlaying

​loop

​inputProps

​playbackRate

​volume

​muted

​audioTracks

​availableAudioTracks

​captions

​activeCaptions

​activeClips

​markers

​playbackRange

​width

​height

​duration

​fps

​Properties

​isVirtualTimeBound

​Methods

​play()

​pause()

​seek()

​seekToTime()

​seekToMarker()

​setDuration()

​setFps()

​setSize()

​setLoop()

​setInputProps()

​setPlaybackRate()

​setAudioVolume()

​setAudioMuted()

​setAudioTrackVolume()

​setAudioTrackMuted()

​setAvailableAudioTracks()

​setCaptions()

​setTimeline()

​setMarkers()

​addMarker()

​removeMarker()

​setPlaybackRange()

​clearPlaybackRange()

​getState()

​subscribe()

​unsubscribe()

​waitUntilStable()

​registerStabilityCheck()

​getAudioContext()

​getAudioSourceNode()

​bindTo()

​unbind()

​bindToDocumentTimeline()

​unbindFromDocumentTimeline()

​dispose()

​Static methods

​Helios.diagnose()

​Example

Constructor

Signals

currentFrame

currentTime

isPlaying

loop

inputProps

playbackRate

volume

muted

audioTracks

availableAudioTracks

captions

activeCaptions

activeClips

markers

playbackRange

width

height

duration

fps

Properties

isVirtualTimeBound

Methods

play()

pause()

seek()

seekToTime()

seekToMarker()

setDuration()

setFps()

setSize()

setLoop()

setInputProps()

setPlaybackRate()

setAudioVolume()

setAudioMuted()

setAudioTrackVolume()

setAudioTrackMuted()

setAvailableAudioTracks()

setCaptions()

setTimeline()

setMarkers()

addMarker()

removeMarker()

setPlaybackRange()

clearPlaybackRange()

getState()

subscribe()

unsubscribe()

waitUntilStable()

registerStabilityCheck()

getAudioContext()

getAudioSourceNode()

bindTo()

unbind()

bindToDocumentTimeline()

unbindFromDocumentTimeline()

dispose()

Static methods

Helios.diagnose()

Example