Input frames (GIFInputFrame)

Use GIFInputFrame[] when not using options.onStart. The list must be non-empty, must stay within the configured GIF frame/resource limits, and each frame must select exactly one raster source.

#Frame shape

1type GIFFrameSource = string | Buffer | Uint8Array | URL;2 3interface GIFInputFrame {4  duration?: number;5  buffer?: GIFFrameSource;6  background?: GIFFrameSource;7  dispose?: 0 | 1 | 2 | 3;8  transparentColor?: number | string | null;9  watermark?: GIFWatermarkSpec;10}

##Required source rule

Each frame must provide exactly one of:

• buffer
• background

Providing neither is invalid. Providing both is also invalid. The two names are retained for API compatibility; both feed the same Phase 7 source-resolution pipeline.

##Duration

duration is optional. Resolution is:

frame.duration ?? options.delay ?? 100 milliseconds.

A provided duration must be finite and within the GIF delay range. GIF timing is encoded in hundredths of a second, so the encoder rounds millisecond values to 10 ms units.

#Supported source forms

buffer / background accept:

• Buffer or Uint8Array raster bytes
• filesystem path strings
• supported base64 data:image/... URLs
• http: / https: URLs allowed by the configured network policy
• URL objects, including supported file/remote URLs

Remote data is resolved through Apexify's shared media layer. Protocol/host restrictions, SSRF protections, redirect handling, timeouts, remote-byte limits, and global remote concurrency policy therefore apply automatically.

For ordinary frame arrays, Apexify may resolve several frames ahead, but the queue is bounded by the central batch/network concurrency limits and preserves input order. It does not launch an unconstrained Promise.all over the whole animation.

Per-frame remote payloads use the central transport without retaining every one-use frame in the shared media cache.

#Per-frame overrides

Frame-local transparency/disposal state is reset deterministically before every addFrame, so one frame's override does not leak into the next frame.

#Sizing

All frames are composited onto the configured GIF output canvas (width × height, default 1200 × 1200). A source whose dimensions differ from the output is stretched to the output dimensions.

When skipResizeWhenDimensionsMatch is omitted or true, an exact-size source is drawn directly. false forces the explicit sized draw path even when dimensions already match; it does not change the public stretch-to-output sizing rule.

#Example

1const gif = await painter.createGIF(2  [3    { buffer: frame1Png, duration: 120 },4    { background: './frames/step2.png' }, // falls back to options.delay5    { background: new URL('https://cdn.example.com/frame3.png'), duration: 200 },6  ],7  {8    outputFormat: 'buffer',9    width: 480,10    height: 270,11    quality: 12,12    delay: 100,13  }14);

For remote examples, the host/protocol must be permitted by your Apexify runtime network configuration.