Skip to main content

​
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