@libshub/gif-cutter

Browser-side GIF processing library powered by WASM. It can crop, rotate, flip, scale, optimize GIFs, adjust frame delay, and export GIF / PNG / JPG / WebP.

npm i @libshub/gif-cutter

Features

• GIF processing in the browser through gifsicle-wasm-browser
• Crop, rotate, mirror flip, and scale
• GIF optimization options: optimize level, lossy compression, color count, loop count
• Exact GIF frame delay control with speed in milliseconds
• Export formats: animated gif, or one png, jpg, or webp file per GIF frame
• Event bus for WASM loading, processing progress, config, success, and errors
• Abort support through AbortSignal

Quick Start

import {
  ensureGifWasm,
  processGif,
  downloadGif,
  onGifEvent,
} from '@libshub/gif-cutter';

const off = onGifEvent('process:progress', (event) => {
  console.log(event.phase, event.progress, event.message);
});

await ensureGifWasm();

const result = await processGif(file, {
  crop: { x: 0, y: 0, width: 320, height: 180 },
  rotate: 90,
  flipX: false,
  flipY: false,
  scale: 1,
  format: 'gif',
  optimizeLevel: 2,
  lossy: 40,
  colors: 256,
  loopCount: 0,
  speed: 80,
  outputName: 'edited.gif',
});

const firstOutput = result.outputs[0];
downloadGif(firstOutput.file, firstOutput.file.name);
off();

Exports

| API | Description | | --- | --- | | ensureGifWasm() | Loads and probes the GIF WASM runtime. | | getGifWasmState() | Returns the current WASM state and error. | | subscribeGifWasmState(listener) | Subscribes to WASM state changes. | | processGif(source, options?) | Processes a GIF and returns a downloadable result. | | buildGifsicleCommand(options, outputName?) | Builds the underlying gifsicle command string. | | isGifFile(file) | Checks whether a File / Blob is a GIF. | | downloadGif(blob, fileName?) | Triggers a browser download. | | revokeGifResult(result) | Revokes every preview URL in result.outputs. | | gifEventBus | Event bus object with on, off, and once. | | onGifEvent(eventName, listener) | Subscribes to one event. | | offGifEvent(eventName, listener) | Removes an event listener. |

Exported types include GifSource, CropRect, RotateDegrees, ExportFormat, WasmLoadState, GifProgressPhase, GifOperationOptions, GifOutputOptions, ProcessGifOptions, ProcessGifOutput, ProcessGifResult, GifEventMap, GifEventName, and GifEventListener.

WASM Lifecycle

import {
  ensureGifWasm,
  getGifWasmState,
  subscribeGifWasmState,
} from '@libshub/gif-cutter';

const unsubscribe = subscribeGifWasmState((state, error) => {
  console.log(state, error);
});

await ensureGifWasm();

console.log(getGifWasmState());
unsubscribe();

WasmLoadState can be:

type WasmLoadState = 'idle' | 'loading' | 'ready' | 'error';

Process GIF

const result = await processGif(file, {
  crop: { x: 12, y: 20, width: 480, height: 270 },
  rotate: 180,
  flipX: true,
  scale: 0.75,
  format: 'webp',
  quality: 0.9,
  outputName: 'preview.webp',
});

ProcessGifOptions

type ProcessGifOptions = GifOperationOptions & GifOutputOptions & {
  signal?: AbortSignal;
};

GifOperationOptions

| Field | Type | Description | | --- | --- | --- | | crop | CropRect \| null | Crop rectangle in source pixels. | | scale | number | Scale ratio. 1 keeps the original size. | | rotate | 0 \| 90 \| 180 \| 270 | Rotation angle. | | flipX | boolean | Horizontal mirror flip. | | flipY | boolean | Vertical mirror flip. |

GifOutputOptions

| Field | Type | Description | | --- | --- | --- | | format | 'gif' \| 'png' \| 'jpg' \| 'webp' | Output format. Default is gif. | | optimizeLevel | 0 \| 1 \| 2 \| 3 | GIF optimize level. 0 disables optimization. | | lossy | number | GIF lossy compression value, clamped to 1..200 when enabled. | | colors | number | GIF color count, clamped to 2..256. | | loopCount | number \| null | GIF loop count. 0 means infinite loop. | | speed | number | GIF frame delay in milliseconds. Omit it to keep the original delay. | | quality | number | JPG / WebP quality, clamped to 0.1..1. | | backgroundColor | string | Canvas background, useful for JPG export. | | outputName | string | Output file name. Extension is normalized by format. |

ProcessGifResult

type ProcessGifResult = {
  outputs: ProcessGifOutput[];
  command: string;
  format: ExportFormat;
  inputBytes: number;
  outputBytes: number;
};

type ProcessGifOutput = {
  file: File;
  url: string;
  frameIndex: number | null;
  durationMs: number | null;
  width: number | null;
  height: number | null;
};

outputs is the single source of generated files. GIF exports have one item; PNG, JPG, and WebP exports have one item per decoded frame. Use result.outputs[0] when only one output is expected, and call revokeGifResult(result) when the preview URLs are no longer needed.

Export Formats

GIF

GIF output keeps animation. It supports crop, rotate, flip, scale, optimization, color count, loop count, and frame delay.

await processGif(file, {
  format: 'gif',
  optimizeLevel: 2,
  lossy: 30,
  colors: 128,
  loopCount: 0,
  speed: 100,
});

PNG / JPG / WebP frame sequences

Raster formats decode every frame from the processed GIF and return numbered files such as preview-0001.jpg, preview-0002.jpg, and so on.

const result = await processGif(file, {
  format: 'jpg',
  quality: 0.92,
  backgroundColor: '#ffffff',
});

for (const output of result.outputs) {
  downloadGif(output.file, output.file.name);
}

Events

The library emits events for WASM loading and GIF processing. Consumers can use these events to update UI progress, display logs, or collect diagnostics.

import { gifEventBus, onGifEvent } from '@libshub/gif-cutter';

const offProgress = onGifEvent('process:progress', (event) => {
  console.log(event.progress, event.phase, event.message);
});

const offError = gifEventBus.on('process:error', ({ error }) => {
  console.error(error);
});

offProgress();
offError();

Event Names

| Event | Payload | | --- | --- | | wasm:state | { state, error } | | wasm:progress | { phase, progress, message } | | process:start | { inputBytes } | | process:config | { options, command, format, outputName } | | process:progress | { phase, progress, message } | | process:success | { result } | | process:error | { error } | | process:finish | { ok } |

progress is a number from 0 to 1.

Abort

const controller = new AbortController();

const promise = processGif(file, {
  format: 'gif',
  signal: controller.signal,
});

controller.abort();
await promise;

When aborted, processGif rejects with a DOM AbortError.

Command Preview

import { buildGifsicleCommand } from '@libshub/gif-cutter';

const command = buildGifsicleCommand({
  crop: { x: 0, y: 0, width: 320, height: 180 },
  rotate: 90,
  optimizeLevel: 2,
});

console.log(command);

This returns the command passed to gifsicle WASM. It is useful for debugging and displaying execution details in demos.

Browser Notes

This package targets browsers. It uses DOM APIs such as File, Blob, URL.createObjectURL, document.createElement, canvas, and createImageBitmap.

For preview URLs returned by processGif, remember to clean up:

const result = await processGif(file);
const firstOutput = result.outputs[0];

image.src = firstOutput.url;

// Later:
revokeGifResult(result);