gif-frames

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

npm install gif-frames

CDN scripts

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)

<!-- unminified -->
<script src="https://unpkg.com/gif-frames@0.3.0?main=bundled"></script>

<!-- minified -->
<script src="https://unpkg.com/gif-frames@0.3.0?main=bundled-min"></script>

This will expose gifFrames as a global variable.

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

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

Options:

• 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)

The callback accepts the arguments (error, frameData).

Returns:

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

frameData

An array of objects of the form:

{
  getImage,
  frameIndex
}

getImage()

Returns one of:

• A drawn canvas DOM element, if options.outputType is 'canvas'
• A data stream which can be piped to file output, otherwise

frameIndex

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)

Examples

Writing selected frames to the file system in Node:

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

gifFrames(
  { url: 'image.gif', frames: '0-2,7', outputType: 'png' },
  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):

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

Changelog

[0.3.0] - 2017-07-13

Added

• Unminified and minified browser bundles which will expose the library as a global called gifFrames - for those not using npm.

Changed

• Now relying on (hopefully short-term) forks of get-pixels and save-pixels, published to npm. These allow us to run UglifyJS for our minified build, and maintain compatibility with older browsers (the previous jpeg-js dependency relied on ES2015+ features).