Render session

Frame iteration and rendering control for Helios

RenderSessionOptions

Configuration options for a render session.

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

startFrame · number · required

First frame to render (must be non-negative)

endFrame · number · required

Last frame to render (must be >= startFrame)

abortSignal · AbortSignal

Optional AbortSignal to cancel the render session

RenderSession

Async iterable session for rendering frames sequentially.

class RenderSession implements AsyncIterable<number> {
  constructor(helios: Helios, options: RenderSessionOptions)
  
  async *[Symbol.asyncIterator](): AsyncIterator<number>
}

helios · Helios · required

Helios instance to control

options · RenderSessionOptions · required

Render session configuration

Usage

RenderSession is an async iterable that yields frame numbers. For each frame, it:

1. Seeks the Helios instance to the frame
2. Waits for the frame to be stable (all animations settled)
3. Yields the frame number
4. Checks if the session was aborted

Example

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

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

// Render all frames
const session = new RenderSession(helios, {
  startFrame: 0,
  endFrame: 150
});

for await (const frame of session) {
  console.log(`Rendering frame ${frame}`);
  // Capture frame, encode, etc.
  const canvas = document.querySelector('canvas');
  const blob = await canvas.toBlob();
  // ... save blob
}

Partial rendering

// Render a specific range
const partialSession = new RenderSession(helios, {
  startFrame: 30,
  endFrame: 90
});

for await (const frame of partialSession) {
  // Only renders frames 30-90
}

Aborting a session

const controller = new AbortController();

const session = new RenderSession(helios, {
  startFrame: 0,
  endFrame: 1000,
  abortSignal: controller.signal
});

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  for await (const frame of session) {
    console.log(`Rendering frame ${frame}`);
  }
} catch (error) {
  console.log('Render aborted');
}

Integration with capture

import { RenderSession } from '@helios-project/core';
import { captureFrame } from '@helios-project/renderer';

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

const session = new RenderSession(helios, {
  startFrame: 0,
  endFrame: 300
});

for await (const frame of session) {
  const blob = await captureFrame();
  frames.push(blob);
  
  // Progress reporting
  const progress = ((frame / 300) * 100).toFixed(1);
  console.log(`Progress: ${progress}%`);
}

console.log('Render complete!');

Error handling

Throws an error if:

• startFrame is negative
• endFrame is less than startFrame

// Invalid: negative startFrame
try {
  new RenderSession(helios, {
    startFrame: -10,
    endFrame: 100
  });
} catch (error) {
  console.error(error.message);
  // 'Invalid startFrame: -10. Must be non-negative.'
}

// Invalid: endFrame < startFrame
try {
  new RenderSession(helios, {
    startFrame: 100,
    endFrame: 50
  });
} catch (error) {
  console.error(error.message);
  // 'Invalid range: startFrame (100) > endFrame (50).'
}

Notes

• The session automatically waits for each frame to be stable before yielding
• Abort checks occur before starting, before each frame, and after waiting
• The session gracefully exits when aborted (does not throw)
• Frame seeking is sequential; parallel rendering requires multiple instances