Declus NPM | npm.io

Declus - GIF manipulation

Playing with GIF images made much easier

Installation & Usage

npm i declus

const declus = require('declus');

// Using callback
declus(options)
  .then((buffer) => {
    ...
  })
  .catch(console.error);

// Inside an async function, using await
const buffer = await declus(options);

:warning: Requires access to write extracted frames to a directory. If file-system is restricted, use the `inMemory` option to store extracted frames in memory

Getting started

Basic example

const fs = require('fs');
const declus = require('declus');

declus({
  height: 360,
  width: 640,
  baseLayer: {
    data: 'https://raw.githubusercontent.com/HexM7/declus/master/assets/sample.gif',
  },
  layers: [
    {
      data: 'https://raw.githubusercontent.com/HexM7/declus/master/assets/transparentKitten.png',
    }
  ],
  stretchLayers: true,
}).then((buffer) => {
  fs.createWriteStream('./myImage.gif')
    .write(buffer);
});

Accepts Buffer, absolute URLs and paths to images

data: myBuffer,
data: './sampleImage.gif',

Layer options

layer: {
  data: Buffer || URL || Path, // Required
  marginLeft: Number,
  marginTop: Number,
  width: Number,
  height: Number,
  drawFunction: function(context, layerImg, index, totalFrames),
  skipFunction: function(index, totalFrames),
  skipIndexes: Array,
}

data - Layer data, can be an image buffer, URL or path.
marginLeft - Left layer margin relative to the base width.
marginTop - Top layer margin relative to the base height.
width - Layer width.
height - Layer height.
drawFunction - A custom function to draw the layer onto the base layer.

{
  drawFunction: function(context, layerImg, index, totalFrames) {
    const drawProgress = (index / totalFrames).toFixed(1);

    context.drawImage(
      layerImg,
      width * drawProgress,
      height * drawProgress,
      64,
      64,
    );
  },
}

skipFunction - Function to decide wether or not to skip the current frame. Return true to skip and false to render the frame.

{
  skipFunction: function(index, totalFrames) {
    // Skip all frames with even index
    if (index % 2 === 0) return true;
    return false;
  },
}

skipIndexes - Frames indexes to skip layers.

{
  skipIndexes: [5, 15, 25, 50],
}

Options

*`width` number

Width of the output image.

*`height` number

Height of the output image.

*`baseLayer` object

An object with data to build the base layer.

Check baseLayer options.

`layers` array

An array of layer objects. The stacking order is defined by the position of the layer in the array.

Check layer options.

`repeat` number

Amount of times to repeat the output GIF.

-1: play once
0: default, loop indefinitely
Positive number: loop specific times

`quality` number

The quality of output GIF (computational/performance trade-off).

1: best colors, worst performance
20: suggested maximum but there is no limit
10: default, provided an even trade-off

`delay` number, ms

Amount of milliseconds to delay between frames.

`frameRate` number

Frames per second.

:warning: `delay` and `frameRate` cannot be used together

`alpha` boolean

Wether or not to have a transparent background.

`alphaColor` number, hexadecimal

Defines the color which represents transparency in the output GIF.

`coalesce` boolean

Whether or not to perform inter-frame coalescing, defaults to true.

`stretchLayers` boolean

Whether or not to stretch the layers to their maximum, defaults to false.

`encoderOptions` object

Options passed to gif-encoder.

highWaterMark: Number, in bytes, to store in internal buffer. Defaults to 64kB. Increase if you face GIF memory limit exceeded error.

`outputDir` string

Directory to store temporary frames extracted from the GIF, defaults to . (root). A new folder is created and automatically gets removed after the encoding has been finished.

`inMemory` boolean

Whether or not to extract frames to memory store instead of writing them to a directory. If true, the GIF image will render faster as the frames will be written and read from the memory instead of a directory at cost of increasing memory usage such as when dealing with large images. Useful when you do not have access to write to the file system. Defaults to false.