Skip to content

Latest commit

 

History

History
145 lines (103 loc) · 5.24 KB

README.md

File metadata and controls

145 lines (103 loc) · 5.24 KB
Raw

Please note that open-source maintenance is not my main focus at the moment.

I will not be investing significant effort in the very near future to review and address issues on this repository. However I do want my software to be useable!

If you have an issue that must be resolved for your work, please open a pull request to fix it, and send me a direct email to make sure that I see it. I ignore most messages from GitHub these days.

I'm also happy to help out if you have a question about how to use the library.

My email can be found at the top of this commit.

Keep in mind that I have a full-time job and a personal life as well as other hobbies that have taken priority over open source, so I might not respond immediately. But don't hesitate to follow up after a few days if you think I've missed your email.

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.

NPM

Install

npm install gif-frames

CDN scripts

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

<!-- 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:
  • 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:

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:

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