declus
v3.0.2
Published
Create awesome image animations
Downloads
6
Maintainers
Readme
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. Returntrue
to skip andfalse
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 once0
: default, loop indefinitelyPositive number
: loop specific times
quality
number
The quality of output GIF (computational/performance trade-off).
1
: best colors, worst performance20
: suggested maximum but there is no limit10
: 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 to64kB
. Increase if you faceGIF 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
.
frameExtension
string
Extension of the extracted frames from the GIF, defaults to png
.
Allowed formats:
png
jpg
gif
(static)
outputFilename
string
Filename for the output GIF image. Defaults to a unique ID generated through nanoid
.
Events
initCanvasContext
function(context)
A function called during the initialization of the Canvas context.
beforeBaseLayerDraw
function(context, layerImg, index, totalFrames)
A function called each time before a frame of the base layer is drawn.
afterBaseLayerDraw
function(context, layerImg, index, totalFrames)
A function called each time after a frame of the base layer is drawn.
beforeLayerDraw
function(context, layerImg, index, totalFrames, layerIndex)
A function called each time before a frame of a layer is drawn.
afterLayerDraw
function(context, layerImg, index, totalFrames, layerIndex)
A function called each time after a frame of a layer is drawn.
encoderOnData
function(buffer)
Emits a Buffer containing either header bytes, frame bytes, or footer bytes.
encoderOnEnd
function
Signifies end of the encoding has been reached.
encoderOnError
function(error)
Emits an Error when internal buffer is exceeded.
encoderOnReadable
function
Emits when the stream is ready to be .read()
from.
encoderOnWriteHeader
function
Emits when at the start and end of .writeHeader()
.
encoderOnFrame
function
Emits when a new frame is being rendered.
encoderOnFinish
function
Emits when encoding has been finished.