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

options

HeliosOptions<TInputProps>

required

Configuration options for the Helios instance

Show properties

duration

number

required

Duration of the composition in seconds

fps

number

required

Frame rate in frames per second

width

number

default:"1920"

Canvas width in pixels

height

number

default:"1080"

Canvas height in pixels

initialFrame

number

default:"0"

Starting frame number

loop

boolean

default:"false"

Whether to loop playback

playbackRange

[number, number] | null

Optional playback range as [startFrame, endFrame]

autoSyncAnimations

boolean

default:"false"

Automatically sync Web Animations API animations to Helios timeline

inputProps

TInputProps

User-defined input properties for the composition

schema

HeliosSchema

Schema defining validation and defaults for inputProps

playbackRate

number

default:"1"

Playback speed multiplier

volume

number

default:"1"

Master audio volume (0.0 to 1.0)

muted

boolean

default:"false"

Whether audio is muted

audioTracks

Record<string, AudioTrackState>

Per-track audio state (volume and muted)

availableAudioTracks

AudioTrackMetadata[]

Audio track metadata for headless environments

captions

string | CaptionCue[]

SRT/WebVTT string or array of caption cues

markers

Marker[]

Timeline markers

timeline

HeliosTimeline

Timeline structure with tracks and clips

driver

TimeDriver

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

ticker

Ticker

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

animationScope

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

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

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

seconds

number

required

New duration in seconds (must be non-negative)

setFps()

Updates the frame rate.

helios.setFps(fps);

fps

number

required

New frame rate (must be greater than 0)

setSize()

Updates the canvas dimensions.

helios.setSize(width, height);

width

number

required

New width in pixels

height

number

required

New height in pixels

setLoop()

Updates the loop state.

helios.setLoop(shouldLoop);

shouldLoop

boolean

required

Whether to loop playback

setInputProps()

Updates the input properties.

helios.setInputProps(props);

props

TInputProps

required

New input properties (will be validated against schema)

setPlaybackRate()

Updates the playback rate.

helios.setPlaybackRate(rate);

rate

number

required

Playback speed multiplier

setAudioVolume()

Updates the master audio volume.

helios.setAudioVolume(volume);

volume

number

required

Volume level (0.0 to 1.0, will be clamped)

setAudioMuted()

Updates the master audio mute state.

helios.setAudioMuted(muted);

muted

boolean

required

Whether audio should be muted

setAudioTrackVolume()

Updates the volume for a specific audio track.

helios.setAudioTrackVolume(trackId, volume);

trackId

string

required

ID of the audio track

volume

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

trackId

string

required

ID of the audio track

muted

boolean

required

Whether the track should be muted

setAvailableAudioTracks()

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

helios.setAvailableAudioTracks(tracks);

tracks

AudioTrackMetadata[]

required

Array of audio track metadata

setCaptions()

Updates the captions.

helios.setCaptions(captions);

captions

string | CaptionCue[]

required

SRT/WebVTT string or array of caption cues

setTimeline()

Updates the timeline.

helios.setTimeline(timeline);

timeline

HeliosTimeline

required

Timeline structure with tracks and clips

setMarkers()

Replaces all markers.

helios.setMarkers(markers);

markers

Marker[]

required

Array of markers (will be validated and sorted)

addMarker()

Adds a single marker.

helios.addMarker(marker);

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

startFrame

number

required

Starting frame (must be >= 0)

endFrame

number

required

Ending frame (must be > startFrame)

clearPlaybackRange()

Clears the playback range.

helios.clearPlaybackRange();

getState()

Gets the current state snapshot.

const state = helios.getState();

state

HeliosState<TInputProps>

Current state object containing all signal values

Subscribes to state changes.

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

callback

(state: HeliosState<TInputProps>) => void

required

Function called on each state change

unsubscribe

() => void

Function to unsubscribe from state changes

unsubscribe()

Unsubscribes a specific callback.

helios.unsubscribe(callback);

callback

HeliosSubscriber<TInputProps>

required

The callback function to unsubscribe

waitUntilStable()

Waits for all asynchronous operations to complete.

await helios.waitUntilStable();

promise

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

check

() => Promise<void>

required

Async function that resolves when stable

dispose

() => void

Function to unregister the stability check

getAudioContext()

Gets the shared AudioContext.

const audioContext = await helios.getAudioContext();

audioContext

Promise<unknown>

The AudioContext instance or null if not available

getAudioSourceNode()

Gets the MediaElementAudioSourceNode for a track.

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

trackId

string

required

ID of the audio track

sourceNode

Promise<unknown>

The audio source node or null if not available

bindTo()

Binds this instance to another Helios instance.

helios.bindTo(masterHelios);

master

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

report

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

Core

Renderer

Player

CLI

Types

​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