> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosrender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
interface HeliosTimeline {
  tracks: HeliosTrack[];
}
```

**tracks** `HeliosTrack[]`

Array of timeline tracks.

## HeliosTrack

Represents a single track in the timeline.

```typescript theme={null}
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.

```typescript theme={null}
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.

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

Inherits all fields from [HeliosConfig](https://docs.heliosrender.com/api/types/helios-config.md).

**timeline** `HeliosTimeline`

Optional timeline definition with tracks and clips.

## StabilityCheck

Callback type for custom stability checks.

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](https://docs.heliosrender.com/api/types/helios-config.md) - Configuration interface
* [HeliosState](https://docs.heliosrender.com/api/types/helios-state.md) - Runtime state interface
* [TimeDriver](https://docs.heliosrender.com/api/types/driver-interfaces.md) - Driver interfaces


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.