@clicks/gif-frames
v2.0.2
Published
Pure JavaScript tool for extracting GIF frames and saving to file
Downloads
14
Readme
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/[email protected]?main=bundled"></script>
<!-- minified -->
<script src="https://unpkg.com/[email protected]?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 Bufferframes
(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 (seetype
forsave-pixels
)quality
(optional): Jpeg quality (seequality
forsave-pixels
)cumulative
(optional, defaultfalse
): Many animated GIFs will only contain partial image information in each frame after the first. Specifyingcumulative
astrue
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
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));