Programmatic frames (onStart)

Use GIFOptions.onStart when frames are generated programmatically instead of supplied as a static GIFInputFrame[].

The modes are exclusive: if onStart is present, pass undefined for gifFrames. Supplying a non-empty static frame list and onStart together is rejected.

#Callback shape

1onStart?: (2  frameCountHint: number,3  painter: unknown4) => Promise<GIFEncodedFrame[] | AsyncIterable<GIFEncodedFrame>>;

The runtime passes the active ApexPainter instance as the second argument.

frameCountHint is advisory and always bounded by the configured maxGifFrames. It is derived from:

1. options.frameCount, when provided
2. otherwise ceil(options.duration / options.delay) when a positive delay makes that calculation possible
3. otherwise 30

The hint does not weaken the actual generated-frame limit. The creator checks the real number of frames independently.

#GIFEncodedFrame

1interface GIFEncodedFrame {2  buffer: string | Buffer | Uint8Array | URL;3  duration?: number;4  dispose?: 0 | 1 | 2 | 3;5  transparentColor?: number | string | null;6  watermark?: GIFWatermarkSpec;7}

buffer is required but is a GIFFrameSource, so it is not limited to an in-memory Buffer. The same central media/network policy used for static frames applies.

duration falls back to options.delay, then 100 ms.

#Array mode

Returning GIFEncodedFrame[] materializes the generated source list before encoding. Apexify validates every generated frame and rejects an array that exceeds the applicable generated-frame bound.

Use this mode for small/generated sets where keeping the source list in memory is acceptable.

#True AsyncIterable streaming

Returning AsyncIterable<GIFEncodedFrame> is the memory-bounded Phase 7 path.

The consumer sequence is intentionally:

1request one frame2→ validate it3→ resolve its source4→ decode5→ draw/overlay6→ encode7→ release per-frame references8→ request the next frame

There is no prefetch from the generated async iterator and no conversion to an array. Backpressure therefore reaches the producer: Apexify does not ask it for frame N + 1 until frame N has completed the per-frame encode path.

Generated streams are still bounded. If the iterator produces more frames than the configured/declared limit, creation fails rather than continuing indefinitely. An iterator that yields zero frames is also rejected.

##Streaming example

1const gif = await painter.createGIF(undefined, {2  outputFormat: 'buffer',3  width: 320,4  height: 180,5  quality: 10,6  delay: 100,7  frameCount: 120,8  onStart: async (_hint, p) => (async function* () {9    for (let i = 0; i < 120; i++) {10      const { buffer } = await p.createCanvas({11        width: 320,12        height: 180,13        colorBg: `hsl(${i * 3} 70% 45%)`,14      });15      yield { buffer, duration: 100 };16    }17  })(),18});

For long animations, prefer yielding frames as they are produced instead of first building a separate Buffer[] and then yielding that array.

#Cancellation and producer errors

Pass options.signal to cancel generated work. Apexify checks cancellation between frame pulls and propagates the signal into remote media resolution. It stops requesting additional frames after cancellation/failure.

Errors already represented by Apexify's structured error classes retain their type. Other failures thrown by the onStart callback or iterator are wrapped as GIF decode/generation errors with the original cause attached.