GIF & animation — overview

await painter.createGIF(gifFrames, options[, painterOpts]) encodes animated GIFs with @skyra/gifenc. It supports local and remote raster sources, bounded frame processing, true incremental AsyncIterable generation, watermarks, rich text overlays, chroma transparency, disposal codes, cancellation, and file/Buffer/base64/attachment outputs.

await painter.animate(frames, defaultDuration, defaultWidth?, defaultHeight?, options?, painterOpts?) builds each frame on a fresh canvas from declarative Frame definitions and returns PNG Buffer[] or writes an optional GIF file. Use createGIF when you need the full GIF-specific pipeline.

Implementation: lib-next/gif/gif-creator.ts, gif-validation.ts, animate-frames.ts, and types/gif.ts. GIFCreator.setPainter wires the onStart/onEnd callback painter argument to the active ApexPainter instance.

#Signatures

1await painter.createGIF(2  gifFrames: GIFInputFrame[] | undefined,3  options: GIFOptions,4  painterOpts?5);6 7await painter.animate(8  frames: Frame[],9  defaultDuration: number,10  defaultWidth?: number,   // default 80011  defaultHeight?: number, // default 60012  options?: AnimateOptions,13  painterOpts?14);

Optional painterOpts.resolveAssetRefs resolves supported $… asset references before the domain API runs. renderSceneToGIF also delegates to the same GIF creator, so the encoder/output/resource semantics documented in this section apply there as well.

#Modes (createGIF)

Passing both a non-empty gifFrames array and options.onStart is rejected. The input modes are intentionally exclusive.

#Source and network policy

GIFFrameSource is string | Buffer | Uint8Array | URL. String/URL sources may be filesystem paths, supported data-image URLs, or permitted remote URLs.

Remote frames and watermarks use Apexify's central media/network layer. That means the normal protocol/host trust policy, SSRF protections, redirects/timeouts, remote-byte limits, and central remote concurrency limits apply. GIF code does not use a separate Axios/direct-HTTP path.

Per-frame remote bytes are not retained in the shared media cache, which prevents long animations from filling it with one-use frame payloads. Reusable static watermark data may use bounded caching.

#Output model

GIFOptions.outputFormat is one of:

• "file" — writes a validated GIF to outputFile; primary return is undefined.
• "buffer" — returns encoded GIF bytes as Buffer.
• "base64" — returns raw GIF bytes encoded with Buffer.toString("base64").
• "attachment" — returns GIFAttachment[]; each attachment contains a Buffer, a .gif filename, and contentType: "image/gif".

If onEnd returns a still-image Buffer, non-file outputs become { gif, static }; file output returns the static Buffer because the GIF itself already lives at outputFile.

#Important limits

GIF creation participates in the central runtime limits, including maximum GIF dimensions, maximum frame count, aggregate GIF resource cost, decoded-image limits, remote image bytes, and bounded remote/batch concurrency. Generated streams are checked as frames arrive, so an unbounded producer cannot bypass the configured maximum.

GIFOptions.signal accepts an AbortSignal. Cancellation stops further frame pulls/resolution and tears down output work as far as the encoder/Node streams permit; partially written file output is removed on failure.

#Types (apexify.js)

GIFOptions.basDir remains in the type for source compatibility only; the Phase 7 GIF creator ignores it.

#Guide map

#Scenes

SceneBuilder / renderSceneToGIF delegates to GIFCreator.createGIF. Scene composition has its own validation, but final GIF output still follows the same output, encoder, frame-limit, network-policy, and callback contracts described here.