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@1.0.1?main=bundled"></script>

<!-- minified -->
<script src="https://unpkg.com/gif-frames@1.0.1?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)
• 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).

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,
  frameInfo
}

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)

frameInfo

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

See GIF spec for details

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', 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):

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

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

1.0.1 2018-12-03

Changed

• Updated some dependencies to resolve security vulnerabilities reported by npm audit.

1.0.0 - 2018-10-15

Added

• New API for getting frameInfo from gif (#9). Thanks @Snelius30!

Changed

• Using get-pixels fork which fetches frameInfo from omggif.

0.4.1 - 2018-08-17

Changed

• Updated some dependencies to resolve security vulnerabilities reported by npm audit.

0.4.0 - 2017-12-05

Added

• cumulative option for computing frames by layering on top of prior frames

Removed

• path import that was no longer being used

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

0.2.4 - 2017-06-26

Added

• This changelog
• Detailing of getImage and frameIndex in frame result object

Changed

• GIF type specification for get-pixels in the browser (see this issue)
• Improved/actually correct browser usage example
• getImageStream in frame result object now called getImage (since it can return a canvas element or a stream)

0.2.3 - 2017-06-26

Added

• npm registry badge in readme

Changed

• Promise gets returned even if we bail during options validation

0.2.2 - 2017-06-26

Added

• More terse intro code example included in readme

Changed

• Passing 'all' as frames option really works now (actually)

0.2.1 - 2017-06-26

Changed

• Passing 'all' as frames option actually works now (almost! just kidding)

0.2.0 - 2017-06-26

Added

• frames option for specifying which frames we want
• getFrames returns a Promise if available in environment
• Callback and promise pass a data stream for each requested frame
• Dependency on multi-integer-range

Changed

• Better browser usage example (but it doesn't work!)

Removed

• File writing - users can do that themselves (helps with interoperability between Node / browser)

0.1.0 - 2017-06-25

Added

• Initial module definition
• All GIF frames written to file with fs
• Accepts optional error callback
• Dependencies on get-pixels and save-pixels