GIF 89a Encoder/Decoder

Common errors

• TypeError: omggif.GifReader is not a constructor

  cause Attempting to use `omggif` with ES module `import` syntax (`import { GifReader } from 'omggif';`) in an environment that doesn't correctly resolve CommonJS exports for a module declared as ESM, or when the `omggif` module itself is not correctly exposed for ESM imports.
  fix Use CommonJS `require` syntax: `const { GifReader } = require('omggif');`. Alternatively, ensure your build tool (like Webpack or Rollup) is configured to handle CommonJS dependencies within an ESM project, or use dynamic `import('omggif')` for asynchronous loading.

• Error: Invalid GIF 89a stream.

  cause The input `Uint8Array` provided to `GifReader` does not contain a valid GIF 89a header or is otherwise malformed according to the GIF specification. This often happens with corrupted files or incorrect data sources.
  fix Verify the integrity of the GIF data buffer being passed to `GifReader`. Ensure it's a complete and correctly formatted GIF byte stream. Add robust error handling around `GifReader` instantiation to gracefully manage invalid input.

• RangeError: offset is outside the bounds of the DataView

  cause This error can occur when `GifReader` tries to read beyond the provided buffer, or when `GifWriter` attempts to write more data than its pre-allocated buffer can hold, especially if the `end()` method returns a larger size than the buffer length.
  fix For `GifWriter`, ensure the initial `Uint8Array` buffer is sufficiently large to contain the entire GIF. For `GifReader`, confirm the input buffer actually contains a full GIF and is not truncated. Debug the offsets being accessed if manually manipulating the buffer.

Warnings

• breaking The `omggif` package is abandoned and has not received updates since June 2017. This means it may not be compatible with newer JavaScript features, Node.js versions, or browser environments, and could contain unpatched bugs or security vulnerabilities.
  Fix: For new projects, consider actively maintained alternatives like `gif.js` (for browser-side encoding) or `gifencoder` (Node.js encoding) which provide more modern APIs and ongoing support. For decoding, `gifuct-js` is a popular alternative.
• gotcha omggif was primarily designed for CommonJS (`require`) module systems prevalent when it was last updated. Directly using ES Modules (`import`) in modern Node.js projects without appropriate bundler configuration (`webpack`, `rollup`) or Node.js settings can lead to `TypeError: require is not defined` or module resolution errors.
  Fix: Ensure your project is configured to handle CommonJS modules (e.g., using `require('omggif')` or a bundler that transpiles). If forced to use ES modules, dynamic `import()` or wrapper files might be necessary. Avoid setting `"type": "module"` in package.json without understanding its implications for CJS dependencies.
• gotcha The `GifWriter` requires a pre-allocated `Uint8Array` buffer for its output. If the buffer is too small, the `end()` method might return a size larger than the allocated buffer, potentially causing data truncation or errors if not handled, as there's no automatic buffer resizing.
  Fix: Always allocate a buffer that is generously sized to accommodate all frames and GIF metadata, or implement logic to progressively write to a dynamic buffer if the exact size is unpredictable. The `getOutputBufferPosition()` method can help monitor current usage.
• gotcha omggif operates at a very low level, requiring manual management of color palettes for each frame or a global palette. Incorrectly defining palettes or pixel indices can lead to corrupted or incorrectly colored GIF output. The library does not perform color quantization or optimization automatically.
  Fix: Thoroughly understand the GIF palette specification. Ensure pixel data arrays contain indices that correctly map to the provided palette. Pre-process image data for color reduction and palette generation before passing it to `omggif` for optimal results.

Install

• npm install omggif npm
• yarn add omggif yarn
• pnpm add omggif pnpm

Imports

• GifReader
  wrong:

  import { GifReader } from 'omggif';

  correct:

  const { GifReader } = require('omggif');

  omggif was published before widespread ESM adoption. It primarily exports CommonJS modules. Direct ESM `import` might fail without specific Node.js `--experimental-modules` flags, `type: "module"` in package.json with `import` compatibility layers, or a bundler to transpile.
• GifWriter
  wrong:

  import { GifWriter } from 'omggif';

  correct:

  const { GifWriter } = require('omggif');

  Similar to GifReader, `GifWriter` is exposed via CommonJS. For modern ESM projects, consider using dynamic `import('omggif').then(mod => mod.GifWriter)` or a build step if direct `import` causes errors.
• All exports (CommonJS)

  const omggif = require('omggif');
  const reader = new omggif.GifReader(...);

  This pattern imports the entire module object, which is robust for older CommonJS libraries that might not explicitly define named exports for destructuring, though `omggif` does support it.

Quickstart

This quickstart demonstrates how to use `omggif` to encode a simple two-frame animated GIF from raw pixel data and then how to initialize a `GifReader` for a given GIF byte buffer to extract metadata like dimensions and frame count. It highlights the low-level byte buffer manipulation required by the library.

const { GifWriter, GifReader } = require('omggif');

// --- Encoding a simple GIF ---
const width = 100;
const height = 100;
const frameCount = 2;

// A generous buffer size for a 2-frame, 100x100 GIF with a palette
// Realistically, calculate based on (width * height * numFrames) + header/metadata overhead
const outputBuffer = new Uint8Array((width * height * frameCount * 2) + 768); 

const writer = new GifWriter(outputBuffer, width, height, { loop: 0 });

// Define a simple palette (red, blue)
const palette = [
  0xFF0000, // Red
  0x0000FF  // Blue
];

// Frame 1: All red pixels (index 0 in palette)
const pixels1 = new Uint8Array(width * height).fill(0);
writer.addFrame(0, 0, width, height, pixels1, { palette, delay: 20 }); // 20ms delay

// Frame 2: All blue pixels (index 1 in palette)
const pixels2 = new Uint8Array(width * height).fill(1);
writer.addFrame(0, 0, width, height, pixels2, { palette, delay: 20 }); // 20ms delay

// Finalize the GIF and get the actual size
const finalSize = writer.end();
const encodedGifBuffer = outputBuffer.slice(0, finalSize);

console.log(`Generated GIF of size: ${finalSize} bytes`);
// In a Node.js environment, you could save this:
// require('fs').writeFileSync('output.gif', encodedGifBuffer);

// --- Decoding a GIF (example with a dummy buffer) ---
// For actual use, 'gifDataBuffer' would come from a file read or network request
// This is a minimal valid 1x1 GIF (header + LSD + GCT + IMG descriptor + LZW data + trailer)
const dummyGifDataBuffer = new Uint8Array([
  0x47, 0x49, 0x46, 0x38, 0x39, 0x61, // GIF89a
  0x01, 0x00, 0x01, 0x00,             // 1x1 canvas
  0x80, 0x00, 0x00,                   // GCT present, 2 colors (2^1)
  0xFF, 0xFF, 0xFF,                   // White (index 0)
  0x00, 0x00, 0x00,                   // Black (index 1)
  0x2C, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00, // Image Descriptor: 1x1 at 0,0
  0x02,                               // LZW Minimum Code Size
  0x02, 0x4C, 0x01,                   // LZW Data (clear, data, EOI)
  0x3B                                // GIF Trailer
]);

try {
  const reader = new GifReader(dummyGifDataBuffer);
  console.log(`Decoded GIF: ${reader.width}x${reader.height}, ${reader.numFrames()} frame(s)`);

  if (reader.numFrames() > 0) {
    const frameInfo = reader.frameInfo(0);
    console.log(`  First frame dimensions: ${frameInfo.width}x${frameInfo.height}`);
    // To get pixel data, you'd use decodeAndBlitFrameRGBA:
    // const pixelsRGBA = new Uint8Array(frameInfo.width * frameInfo.height * 4);
    // reader.decodeAndBlitFrameRGBA(0, pixelsRGBA);
  }
} catch (e) {
  console.error("Error reading GIF data:", e.message);
}