gif-frames

A pure JavaScript tool for extracting GIF frames and saving to file. Works in Node or the browser. Uses get-pixels and save-pixels under the hood.


Install

``bash
npm install gif-frames
`

$3

If you're not using npm, you can include one of these in your HTML file:

* https://unpkg.com/gif-frames?main=bundled (Unminified)
* https://unpkg.com/gif-frames?main=bundled-min (Minified)

`html





`

This will expose gifFrames as a global variable.

require('gif-frames')(options[, callback])

`javascript
var gifFrames = require('gif-frames');
var fs = require('fs');

gifFrames({ url: 'image.gif', frames: 0 }).then(function (frameData) {
frameData[0].getImage().pipe(fs.createWriteStream('firstframe.jpg'));
});
`

$3

* url (required): The pathname to the file, or an in-memory Buffer
* frames (required): The set of frames to extract. Can be one of:
- 'all' (gets every frame)
- Any valid Initializer accepted by the multi-integer-range library
outputType (optional*, default 'jpg'): Type to use for output (see type for save-pixels)
quality (optional*): Jpeg quality (see quality for save-pixels)
cumulative (optional, default false): Many animated GIFs will only contain partial image information in each frame after the first. Specifying cumulative as true will compute each frame by layering it on top of previous frames. Note: the cost of this computation is proportional to the size of the last requested frame index.*

The callback accepts the arguments (error, frameData).

$3

A Promise resolving to the frameData array (if promises are supported in the running environment)

frameData

An array of objects of the form:

`javascript
{
getImage,
frameIndex,
frameInfo
}
`

$3

Returns one of:
* A drawn canvas DOM element, if options.outputType is 'canvas'
* A data stream which can be piped to file output, otherwise

$3

The index corresponding to the frame's position in the original GIF (not necessarily the same as the frame's position in the result array)

$3

It is an Object with metadata of the frame. Fields:

Name|Type|Description
----|-----|-----------
x | Integer | Image Left Position
y | Integer | Image Top Position
width | Integer | Image Width
height | Integer | Image Height
has_local_palette | Boolean | Image local palette presentation flag
palette_offset | Integer | Image palette offset
palette_size | Integer | Image palette size
data_offset | Integer | Image data offset
data_length | Integer | Image data length
transparent_index | Integer | Transparent Color Index
interlaced | Boolean | Interlace Flag
delay | Integer | Delay Time (1/100ths of a second)
disposal | Integer | Disposal method

See GIF spec for details

Examples

Writing selected frames to the file system in Node:

`javascript
var gifFrames = require('gif-frames');
var fs = require('fs');

gifFrames(
{ url: 'image.gif', frames: '0-2,7', outputType: 'png', cumulative: true },
function (err, frameData) {
if (err) {
throw err;
}
frameData.forEach(function (frame) {
frame.getImage().pipe(fs.createWriteStream(
'image-' + frame.frameIndex + '.png'
));
});
}
);
`

Drawing first frame to canvas in browser (and using a Promise):

`javascript
var gifFrames = require('gif-frames');

gifFrames({ url: 'image.gif', frames: 0, outputType: 'canvas' })
.then(function (frameData) {
document.body.appendChild(frameData[0].getImage());
}).catch(console.error.bind(console));
``