omggif

library1.0.10jsnpmunverified

omggif is a JavaScript library designed for low-level encoding and decoding of GIF 89a format images. It provides explicit `GifReader` and `GifWriter` classes that operate directly on byte buffers, typically `Uint8Array`s or Node.js `Buffer`s. This gives developers granular control over every aspect of GIF generation, including frame dimensions, color palettes, delays, and other GIF specification details. First released in 2013 and last updated to version 1.0.10 in June 2017, the package is considered abandoned and has received no further maintenance or feature updates. While historically useful for both browser and Node.js environments due to its lightweight and pure JavaScript implementation, modern projects might find it lacks contemporary features, active community support, or the high-level abstractions found in more actively maintained GIF manipulation libraries.

serialization

npm install omggif

github ↗package ↗

INSTALL

IMPORT

SIG · OMGGIF

omggif

serializationjavascriptv1.0.10

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GifReader

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

✗ import { GifReader } from '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

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

✗ import { GifWriter } from '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.

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); }

Debug

Known issues

breakingThe `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.

affects: >=1.0.10

gotchaomggif 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.

affects: >=1.0.10

gotchaThe `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.

affects: >=1.0.0

gotchaomggif 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: omggif.GifReader is not a constructor

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.

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

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.

Upgrade

Version history

1.0.10latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/deanm/omggif ↗

packagehttps://www.npmjs.com/package/omggif ↗