Streaming GIF encoder
This is built as part of the gifsockets project. It is forked from gif.js to allow for a streaming API and performance optimization.
Install the module with: npm install gif-encoder
// Create a 10 x 10 gif
var GifEncoder = require('gif-encoder');
var gif = new GifEncoder(10, 10);
// using an rgba array of pixels [r, g, b, a, ... continues on for every pixel]
// This can be collected from a <canvas> via context.getImageData(0, 0, width, height).data
var pixels = [0, 0, 0, 255/*, ...*/];
// Collect output
var file = require('fs').createWriteStream('img.gif');
gif.pipe(file);
// Write out the image into memory
gif.writeHeader();
gif.addFrame(pixels);
// gif.addFrame(pixels); // Write subsequent rgba arrays for more frames
gif.finish();
gif-encoder
exports GifEncoder
, a constructor function which extends readable-stream@~1.1.9
. This means you can use any streams1
/streams2
functionality. I will re-iterate what this means below.
// streams1
var gif = new GifEncoder(10, 10);
gif.on('data', console.log);
gif.on('end', process.exit);
// streams2
var gif = new GifEncoder(10, 10);
gif.on('readable', function () {
console.log(gif.read());
});
new GifEncoder(width, height, [options])
Constructor for a new GifEncoder
Number
- Width, in pixels, of the GIF
to outputNumber
- Height, in pixels, of the GIF
to outputObject
- Optional container for any options
Number
- Number, in bytes, to store in internal buffer. Defaults to 64kB.NEVER CALL .removeAllListeners()
. NO DATA EVENTS WILL BE ABLE TO EMIT.
We implement the GIF89a specification which can be found at
data
function (buffer) {}
Emits a Buffer
containing either header bytes, frame bytes, or footer bytes.
end
function () {}
Signifies end of the encoding has been reached. This will be emitted once .finish()
is called.
error
function (error) {}
Emits an Error
when internal buffer is exceeded. This occurs when you do not read
(either via .on('data')
or .read()
) and we cannot flush prepared data.
If you have a very large GIF, you can update
options.highWaterMark
via the Constructor.
readable
function () {}
Emits when the stream is ready to be .read()
from.
writeHeader#start/stop
function () {}
Emits when at the start and end of .writeHeader()
.
frame#start/stop
function () {}
Emits when at the start and end of .addFrame()
finish#start/stop
function () {}
Emits when at the start and end of .finish()
gif.setDelay(ms)
Set milliseconds to wait between frames
Number
- Amount of milliseconds to delay between framessetFrameRate(framesPerSecond)
Set delay based on amount of frames per second. Cannot be used with gif.setDelay
.
Number
- Amount of frames per secondsetDispose(disposalCode)
Set the disposal code
Number
- Alters behavior of how to render between frames
Values : 0 - No disposal specified. The decoder is
not required to take any action.
1 - Do not dispose. The graphic is to be left
in place.
2 - Restore to background color. The area used by the
graphic must be restored to the background color.
3 - Restore to previous. The decoder is required to
restore the area overwritten by the graphic with
what was there prior to rendering the graphic.
4-7 - To be defined.
Taken from http://www.w3.org/Graphics/GIF/spec-gif89a.txt
setRepeat(n)
Sets amount of times to repeat GIF
Number
n
is -1, play once.n
is 0, loop indefinitely.n
is a positive number, loop n
times.setTransparent(color)
Define the color which represents transparency in the GIF
.
Hexadecimal Number
- Color to represent transparent background
0x00FF00
setQuality(quality)
Set the quality (computational/performance trade-off).
Positive number
read([size])
Read out size
bytes or until the end of the buffer. This is implemented by readable-stream
.
Number
- Optional number of bytes to read outwriteHeader()
Write out header bytes. We are following GIF89a
specification.
addFrame(imageData, options)
Write out a new frame to the GIF.
Array
- Array of pixels for the new frame. It should follow the sequence of r, g, b, a
and be 4 * height * width
in length.
palette
and indexedPixels
, then this becomes the index in the palette (e.g. 0
for color #0
)Object
- Optional container for options
Array
- Array of pixels to use as palette for the frame. It should follow the sequence of r, g, b, a
options.indexedPixels
Boolean
- Indicator to treat imageData
as RGBA values (false
) or indicies in palette
(true
)finish()
Write out footer bytes.
For performance in gifsockets, we needed to open up some lower level methods for fancy tricks.
Don't use these unless you know what you are doing.
flushData()
We have a secondary internal buffer that collects each byte from writeByte
. This is to prevent create a new Buffer
and data
event for every byte of data.
This method empties the internal buffer and pushes it out to the stream
buffer for reading.
pixels
Internal store for imageData
passed in by addFrame
.
analyzeImage(imageData, options)
First part of addFrame
; runs setImagePixels(removeAlphaChannel(imageData))
and runs analyzePixels()
.
Array
- Same as that in addFrame
Object
- Optional container for options
Boolean
- Indicator to treat imageData
as RGBA values (false
) or indicies in palette
(true
)removeAlphaChannel(imageData)
Reduces imageData
into a Uint8Array
of length 3 * width * height
containing sequences of r, g, b
; removing the alpha channel.
Array
- Same as that in addFrame
; array containing r, g, b, a
sequences.setImagePixels(pixels)
Save pixels
as this.pixels
for image analysis.
Array
- Same as imageData
from addFrame
GifEncoder
will mutate the original data.setImagePalette(palette)
Save palette
as this.userPalette
for frame writing.
Array
- Same as options.palette
from addFrame
writeImageInfo()
Second part of addFrame
; behavior varies on if it is the first frame or following frame.
In either case, it writes out a bunch of bytes about the image (e.g. palette, color tables).
outputImage()
Third part of addFrame
; encodes the analyzed/indexed pixels for the GIF format.
Support this project and others by twolfson via donations.
http://twolfson.com/support-me
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via grunt and test via npm test
.
As of Nov 11 2013, Todd Wolfson has released all code differences since initial fork from gif.js to the public domain.
These differences have been released under the UNLICENSE.
At the gif.js time of forking, gif.js was using the MIT license.