> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/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

<ResponseField name="helios" type="Helios" required>
  The Helios instance to render.
</ResponseField>

<ResponseField name="options" type="RenderSessionOptions" required>
  Configuration for the render session.
</ResponseField>

### Methods

<ResponseField name="[Symbol.asyncIterator]" type="() => AsyncIterator<number>">
  Returns an async iterator that yields frame numbers. Each iteration seeks to the next frame and waits for stability.
</ResponseField>

## RenderSessionOptions

Configuration options for creating a render session.

```typescript theme={null}
interface RenderSessionOptions {
  startFrame: number;
  endFrame: number;
  abortSignal?: AbortSignal;
}
```

<ResponseField name="startFrame" type="number" required>
  Starting frame number. Must be non-negative.
</ResponseField>

<ResponseField name="endFrame" type="number" required>
  Ending frame number (inclusive). Must be >= startFrame.
</ResponseField>

<ResponseField name="abortSignal" type="AbortSignal">
  Optional abort signal for canceling the render session.
</ResponseField>

## HeliosTimeline

Defines a multi-track timeline structure for compositions.

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

<ResponseField name="tracks" type="HeliosTrack[]">
  Array of timeline tracks.
</ResponseField>

## HeliosTrack

Represents a single track in the timeline.

```typescript theme={null}
interface HeliosTrack {
  id: string;
  name?: string;
  clips: HeliosClip[];
}
```

<ResponseField name="id" type="string">
  Unique track identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Optional human-readable track name.
</ResponseField>

<ResponseField name="clips" type="HeliosClip[]">
  Array of clips in this track.
</ResponseField>

## 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>;
}
```

<ResponseField name="id" type="string">
  Unique clip identifier.
</ResponseField>

<ResponseField name="source" type="string">
  Source identifier or composition reference.
</ResponseField>

<ResponseField name="start" type="number">
  Start time in seconds within the timeline.
</ResponseField>

<ResponseField name="duration" type="number">
  Clip duration in seconds.
</ResponseField>

<ResponseField name="track" type="number">
  Optional track number for layering.
</ResponseField>

<ResponseField name="props" type="Record<string, any>">
  Optional properties passed to the clip composition.
</ResponseField>

## 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](/api/types/helios-config).

<ResponseField name="timeline" type="HeliosTimeline">
  Optional timeline definition with tracks and clips.
</ResponseField>

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

<ResponseField name="waapi" type="boolean">
  Web Animations API support (document.timeline).
</ResponseField>

<ResponseField name="webCodecs" type="boolean">
  WebCodecs API support.
</ResponseField>

<ResponseField name="offscreenCanvas" type="boolean">
  OffscreenCanvas support.
</ResponseField>

<ResponseField name="webgl" type="boolean">
  WebGL 1.0 support.
</ResponseField>

<ResponseField name="webgl2" type="boolean">
  WebGL 2.0 support.
</ResponseField>

<ResponseField name="webAudio" type="boolean">
  Web Audio API support.
</ResponseField>

<ResponseField name="colorGamut" type="'srgb' | 'p3' | 'rec2020' | null">
  Highest supported color gamut.
</ResponseField>

<ResponseField name="videoCodecs" type="object">
  Video encoding support for h264, vp8, vp9, and av1.
</ResponseField>

<ResponseField name="audioCodecs" type="object">
  Audio encoding support for aac and opus.
</ResponseField>

<ResponseField name="videoDecoders" type="object">
  Video decoding support for h264, vp8, vp9, and av1.
</ResponseField>

<ResponseField name="audioDecoders" type="object">
  Audio decoding support for aac and opus.
</ResponseField>

<ResponseField name="userAgent" type="string">
  Browser or runtime user agent string.
</ResponseField>

## 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](/api/types/helios-config) - Configuration interface
* [HeliosState](/api/types/helios-state) - Runtime state interface
* [TimeDriver](/api/types/driver-interfaces) - Driver interfaces