gifuct-js is a lean and efficient JavaScript library specifically designed for parsing and decoding GIF files. It aims to overcome the inefficiencies and complexities found in older GIF processing libraries by providing a streamlined API focused solely on extracting raw frame data. The current stable version is 2.1.2, last updated in November 2021. The library prioritizes performance, making it suitable for resource-constrained environments like mobile hybrid applications, as exemplified by its original development for the Ruffle project. It operates by consuming GIF files as `Uint8Array` buffers and leverages `js-binary-schema-parser` internally for robust parsing. A key differentiator is its 'decode-only' approach; unlike many alternatives, it deliberately omits any built-in drawing or rendering logic, empowering developers to integrate GIF data with their preferred rendering engines (e.g., Canvas, WebGL). While it can optionally generate canvas-ready `Uint8ClampedArray` patches, it leaves full control over animation and display to the implementer. The project maintains a stable release cadence, with updates primarily focusing on parsing accuracy and performance enhancements rather than frequent new feature introductions.
npm install gifuct-jsVerified import paths — ran on the pinned version, not inferred.
Demonstrates how to fetch a GIF from a URL, parse its `ArrayBuffer`, and decompress its frames (with patches) for further processing.
Ensure your GIF source (e.g., `fetch().arrayBuffer()`, `XMLHttpRequest.responseType = 'arraybuffer'`) provides an `ArrayBuffer` response type before passing it to `parseGIF`.
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.
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.
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.
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.
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')`.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.