Skip to main content

​
HeliosConfig

The HeliosConfig interface defines the configuration options for initializing a Helios composition. This is the base configuration used by both the core Helios class and the HeliosComposition interface. 
interface HeliosConfig<TInputProps = Record<string, any>> {
  width?: number;
  height?: number;
  initialFrame?: number;
  duration: number;
  fps: number;
  loop?: boolean;
  playbackRange?: [number, number];
  autoSyncAnimations?: boolean;
  inputProps?: TInputProps;
  schema?: HeliosSchema;
  playbackRate?: number;
  volume?: number;
  muted?: boolean;
  audioTracks?: Record<string, AudioTrackState>;
  availableAudioTracks?: AudioTrackMetadata[];
  captions?: string | CaptionCue[];
  markers?: Marker[];
}

​
Type parameters

​
TInputProps
Record<string, any>
default:"Record<string, any>"
The type of input properties passed to the composition. Can be customized for type safety.

​
Required fields

​
duration
number
required
Duration of the composition in seconds. Must be non-negative.
​
fps
number
required
Frame rate of the composition in frames per second. Must be greater than 0.

​
Dimensions

​
width
number
default:"1920"
Canvas width in pixels. Must be positive.
​
height
number
default:"1080"
Canvas height in pixels. Must be positive.

​
Playback control

​
initialFrame
number
default:"0"
The starting frame when the composition is initialized. Will be clamped to valid range.
​
loop
boolean
default:"false"
Whether playback should loop when reaching the end.
​
playbackRange
[number, number]
Optional range of frames to play. Specified as [startFrame, endFrame]. Start must be >= 0 and end must be > start.
​
playbackRate
number
default:"1"
Playback speed multiplier. 1.0 is normal speed, 2.0 is double speed, 0.5 is half speed.

​
Input properties and schema

​
inputProps
TInputProps
Custom properties passed to the composition. These will be validated against the schema if provided.
​
schema
HeliosSchema
Schema definition for validating and describing input properties. Enables type checking and default values.

​
Animation synchronization

​
autoSyncAnimations
boolean
default:"false"
When true, automatically synchronizes WAAPI animations with Helios playback using a DomDriver.

​
Audio control

​
volume
number
default:"1"
Master volume level from 0.0 (muted) to 1.0 (full volume).
​
muted
boolean
default:"false"
Whether all audio should be muted.
​
audioTracks
Record<string, AudioTrackState>
Per-track audio state configuration. Keys are track IDs.
​
availableAudioTracks
AudioTrackMetadata[]
Metadata for available audio tracks. Can be used in headless environments where tracks cannot be auto-discovered.

​
Captions and markers

​
captions
string | CaptionCue[]
Captions for the composition. Can be an SRT/WebVTT string or an array of CaptionCue objects.
​
markers
Marker[]
Timeline markers for navigation and annotation.

​
HeliosOptions

Extends HeliosConfig with additional runtime options for the Helios engine. 
interface HeliosOptions<TInputProps = Record<string, any>> extends HeliosConfig<TInputProps> {
  animationScope?: unknown;
  driver?: TimeDriver;
  ticker?: Ticker;
  timeline?: HeliosTimeline;
}

​
Additional fields

​
animationScope
unknown
default:"document"
The scope for WAAPI animations. Defaults to document in browser environments.
​
driver
TimeDriver
Custom time driver for managing media synchronization. If not provided, selects automatically based on autoSyncAnimations.
​
ticker
Ticker
Custom ticker for the playback loop. Defaults to RafTicker in browser or TimeoutTicker in Node.js.
​
timeline
HeliosTimeline
Timeline definition with tracks and clips for multi-layer compositions.

​
AudioTrackState

Represents the playback state of an individual audio track. 
type AudioTrackState = {
  volume: number;
  muted: boolean;
};
​
volume
number
Volume level for this track from 0.0 to 1.0.
​
muted
boolean
Whether this specific track is muted.

​
Usage example

import { Helios, HeliosConfig } from '@helios/core';

const config: HeliosConfig = {
  width: 1920,
  height: 1080,
  duration: 10,
  fps: 30,
  loop: true,
  playbackRate: 1.0,
  volume: 0.8,
  inputProps: {
    title: 'My Video',
    theme: 'dark'
  },
  schema: {
    title: {
      type: 'string',
      default: 'Untitled'
    },
    theme: {
      type: 'string',
      enum: ['light', 'dark'],
      default: 'light'
    }
  }
};

const helios = new Helios(config);

Build docs developers (and LLMs) love

Get started for freeTalk to us