Efficient JavaScript GIF Parser and Decoder

Common errors

• TypeError: Cannot read properties of undefined (reading 'length')

  cause `parseGIF` received an invalid or malformed `ArrayBuffer`, or an object that is not an `ArrayBuffer`.
  fix Verify that the input `ArrayBuffer` is correctly loaded from a valid GIF file and is indeed an `ArrayBuffer` type. Log the input to `parseGIF` to inspect its type and content before passing it.

• ReferenceError: parseGIF is not defined

  cause Incorrect ES Module import syntax or attempting to use CommonJS `require` in an ES Module context (or vice versa).
  fix For modern JavaScript environments (ESM), use `import { parseGIF, decompressFrames } from 'gifuct-js'`. For CommonJS (Node.js <14 or specific setups), use `const { parseGIF, decompressFrames } = require('gifuct-js')`.

• Canvas shows wrong colors/transparency or 'blurry' frames after decompression.

  cause Misunderstanding `patch` vs `pixels` data, incorrect handling of `disposalType`, or transparency issues when drawing frames, especially when `buildPatch` is `true`.
  fix Review the documentation on `disposalType` and `transparentIndex`. If `buildPatch` is `true`, be aware of its assumptions. For precise rendering, process `pixels` and `colorTable` manually, handling transparency and disposal based on GIF specification, or consult the library's demo for a robust rendering example.

Warnings

• gotcha The library expects GIF data as a `Uint8Array` or `ArrayBuffer`. Passing other formats (e.g., base64 strings, Blobs directly) will result in parsing errors.
  Fix: Ensure your GIF source (e.g., `fetch().arrayBuffer()`, `XMLHttpRequest.responseType = 'arraybuffer'`) provides an `ArrayBuffer` response type before passing it to `parseGIF`.
• gotcha When `decompressFrames` is called with `buildPatch: true`, it generates `Uint8ClampedArray` patches. This process makes assumptions about transparency handling and disposal methods, which might not always align with complex GIF specifications or desired rendering effects, potentially leading to incorrect transparency or visual artifacts (e.g., 'white blurs').
  Fix: For precise control over transparency and blending, set `buildPatch: false` and manually process the `pixels`, `colorTable`, `transparentIndex`, and `disposalType` properties of each frame to render them onto your canvas. Refer to the GIF specification for detailed disposal method rules.
• gotcha The `pixels` property of a decompressed frame contains color table indices, not direct RGBA color values. Developers often mistakenly try to interpret these as direct pixel colors without consulting the `colorTable`.
  Fix: To get the actual RGBA color for a pixel index `i`, you must look up `frame.colorTable[frame.pixels[i]]`. Additionally, consider the `transparentIndex` if present in the frame, as that index should be rendered as fully transparent.
• gotcha Some complex or malformed GIFs may exhibit rendering issues, such as incomplete frames or visual corruption, due to subtleties in the GIF specification or specific implementation choices, particularly concerning graphic control extensions or multiple application blocks.
  Fix: While `gifuct-js` aims for robustness, extremely complex or edge-case GIFs might require custom post-processing of the frame data. Refer to GitHub issues for known problematic GIF examples and community workarounds.

Install

• npm install gifuct-js npm
• yarn add gifuct-js yarn
• pnpm add gifuct-js pnpm

Imports

• parseGIF
  wrong:

  const parseGIF = require('gifuct-js').parseGIF

  correct:

  import { parseGIF } from 'gifuct-js'

  Primary entry point for parsing a GIF `ArrayBuffer`. The library primarily uses named exports. `gifuct-js` ships with TypeScript types.
• decompressFrames
  wrong:

  const decompressFrames = require('gifuct-js').decompressFrames

  correct:

  import { decompressFrames } from 'gifuct-js'

  Processes the parsed GIF structure into an array of frame data. The `buildPatch` argument (second parameter) determines if `Uint8ClampedArray` patches suitable for `CanvasRenderingContext2D.putImageData()` are generated. Understanding GIF disposal methods and `transparentIndex` is crucial for correct rendering, especially when `buildPatch` is `true` as it makes assumptions about transparency handling.
• GIF and Frame types

  import type { GIF, Frame } from 'gifuct-js'

  TypeScript users can import these types for better type checking when working with parsed GIF data and individual frames.

Quickstart

Demonstrates how to fetch a GIF from a URL, parse its `ArrayBuffer`, and decompress its frames (with patches) for further processing.

import { parseGIF, decompressFrames } from 'gifuct-js';

const gifURL = 'https://i.imgur.com/DrxJ5d8.gif'; // Replace with your GIF URL

async function loadAndDecompressGif(url) {
  try {
    const resp = await fetch(url);
    if (!resp.ok) {
      throw new Error(`HTTP error! status: ${resp.status}`);
    }
    const arrayBuffer = await resp.arrayBuffer();
    const gif = parseGIF(arrayBuffer);
    // Set buildPatch to true to get canvas-ready Uint8ClampedArray patches
    const frames = decompressFrames(gif, true);

    console.log('GIF parsed successfully. Number of frames:', frames.length);
    // Example of accessing frame data
    if (frames.length > 0) {
      const firstFrame = frames[0];
      console.log('First frame dimensions:', firstFrame.dims);
      console.log('First frame delay (ms):', firstFrame.delay);
      // firstFrame.patch is a Uint8ClampedArray if buildPatch was true
      // firstFrame.pixels is an array of color table indices
    }
    return frames;
  } catch (error) {
    console.error('Failed to load or decompress GIF:', error);
    return [];
  }
}

loadAndDecompressGif(gifURL).then(frames => {
  // Now you can work with the decompressed frames, e.g., draw them to a canvas
  // For full rendering example, refer to the library's demo.
});