Render options

Type definitions for rendering and session management

RenderSession

The RenderSession class provides an async iterable interface for frame-by-frame rendering. It handles seeking to each frame and waiting for stability before yielding.

class RenderSession implements AsyncIterable<number> {
  constructor(
    helios: Helios,
    options: RenderSessionOptions
  )

  [Symbol.asyncIterator](): AsyncIterator<number>
}

Constructor parameters

helios · Helios · required

The Helios instance to render.

options · RenderSessionOptions · required

Configuration for the render session.

Methods

[Symbol.asyncIterator] · () => AsyncIterator<number>

Returns an async iterator that yields frame numbers. Each iteration seeks to the next frame and waits for stability.

RenderSessionOptions

Configuration options for creating a render session.

interface RenderSessionOptions {
  startFrame: number;
  endFrame: number;
  abortSignal?: AbortSignal;
}

startFrame · number · required

Starting frame number. Must be non-negative.

endFrame · number · required

Ending frame number (inclusive). Must be >= startFrame.

abortSignal · AbortSignal

Optional abort signal for canceling the render session.

HeliosTimeline

Defines a multi-track timeline structure for compositions.

interface HeliosTimeline {
  tracks: HeliosTrack[];
}

tracks · HeliosTrack[]

Array of timeline tracks.

HeliosTrack

Represents a single track in the timeline.

interface HeliosTrack {
  id: string;
  name?: string;
  clips: HeliosClip[];
}

id · string

Unique track identifier.

name · string

Optional human-readable track name.

clips · HeliosClip[]

Array of clips in this track.

HeliosClip

Represents a clip within a track.

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 composition reference.

start · number

Start time in seconds within the timeline.

duration · number

Clip duration in seconds.

track · number

Optional track number for layering.

props · Record<string, any>

Optional properties passed to the clip composition.

HeliosComposition

Extends HeliosConfig with timeline support for multi-layer compositions.

interface HeliosComposition<TInputProps = Record<string, any>> 
  extends HeliosConfig<TInputProps> {
  timeline?: HeliosTimeline;
}

Inherits all fields from HeliosConfig.

timeline · HeliosTimeline

Optional timeline definition with tracks and clips.

StabilityCheck

Callback type for custom stability checks.

type StabilityCheck = () => Promise<void>;

Stability checks are async functions that resolve when a custom system is ready. Used with helios.registerStabilityCheck() to block waitUntilStable() until external operations complete.

DiagnosticReport

Runtime capability detection report.

interface DiagnosticReport {
  waapi: boolean;
  webCodecs: boolean;
  offscreenCanvas: boolean;
  webgl: boolean;
  webgl2: boolean;
  webAudio: boolean;
  colorGamut: 'srgb' | 'p3' | 'rec2020' | null;
  videoCodecs: {
    h264: boolean;
    vp8: boolean;
    vp9: boolean;
    av1: boolean;
  };
  audioCodecs: {
    aac: boolean;
    opus: boolean;
  };
  videoDecoders: {
    h264: boolean;
    vp8: boolean;
    vp9: boolean;
    av1: boolean;
  };
  audioDecoders: {
    aac: boolean;
    opus: boolean;
  };
  userAgent: string;
}

Generated by Helios.diagnose(). All codec support fields are boolean values indicating availability.

waapi · boolean

Web Animations API support (document.timeline).

webCodecs · boolean

WebCodecs API support.

offscreenCanvas · boolean

OffscreenCanvas support.

webgl · boolean

WebGL 1.0 support.

webgl2 · boolean

WebGL 2.0 support.

webAudio · boolean

Web Audio API support.

colorGamut · 'srgb' | 'p3' | 'rec2020' | null

Highest supported color gamut.

videoCodecs · object

Video encoding support for h264, vp8, vp9, and av1.

audioCodecs · object

Audio encoding support for aac and opus.

videoDecoders · object

Video decoding support for h264, vp8, vp9, and av1.

audioDecoders · object

Audio decoding support for aac and opus.

userAgent · string

Browser or runtime user agent string.

Usage examples

Render session

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

const helios = new Helios({
  duration: 10,
  fps: 30
});

const session = new RenderSession(helios, {
  startFrame: 0,
  endFrame: 299, // 10 seconds at 30fps
  abortSignal: AbortSignal.timeout(60000) // 1 minute timeout
});

// Render each frame
for await (const frame of session) {
  console.log(`Rendering frame ${frame}`);
  // Capture canvas, encode video, etc.
}

Timeline composition

import { HeliosComposition } from '@helios/core';

const composition: HeliosComposition = {
  duration: 30,
  fps: 30,
  timeline: {
    tracks: [
      {
        id: 'main',
        name: 'Main Timeline',
        clips: [
          {
            id: 'intro',
            source: 'intro-composition',
            start: 0,
            duration: 5,
            props: { theme: 'dark' }
          },
          {
            id: 'main',
            source: 'main-composition',
            start: 5,
            duration: 20
          },
          {
            id: 'outro',
            source: 'outro-composition',
            start: 25,
            duration: 5
          }
        ]
      }
    ]
  }
};

Diagnostic check

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

const report = await Helios.diagnose();

console.log('WebCodecs:', report.webCodecs);
console.log('H264 encoding:', report.videoCodecs.h264);
console.log('Color gamut:', report.colorGamut);

if (!report.webCodecs) {
  console.warn('WebCodecs not supported, rendering may be slower');
}

Related types

• HeliosConfig - Configuration interface
• HeliosState - Runtime state interface
• TimeDriver - Driver interfaces