HeliosConfig

Configuration interface for initializing Helios compositions

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

Related types

• HeliosState - Runtime state interface
• RenderOptions - Rendering configuration
• TimeDriver - Time synchronization interface