Nondeterministic Polynomial Munchies

    gif-encoder
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/gif-encoder package

    0.7.2 • Public • Published

    gif-encoder Build status

    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.

    Getting Started

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

    Documentation

    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

    • width Number - Width, in pixels, of the GIF to output
    • height Number - Height, in pixels, of the GIF to output
    • options Object - Optional container for any options
      • highWaterMark 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

    http://www.w3.org/Graphics/GIF/spec-gif89a.txt

    Events

    Event: data

    function (buffer) {}

    Emits a Buffer containing either header bytes, frame bytes, or footer bytes.

    Event: end

    function () {}

    Signifies end of the encoding has been reached. This will be emitted once .finish() is called.

    Event: 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.

    Event: readable

    function () {}

    Emits when the stream is ready to be .read() from.

    Event: writeHeader#start/stop

    function () {}

    Emits when at the start and end of .writeHeader().

    Event: frame#start/stop

    function () {}

    Emits when at the start and end of .addFrame()

    Event: finish#start/stop

    function () {}

    Emits when at the start and end of .finish()

    Settings

    gif.setDelay(ms)

    Set milliseconds to wait between frames

    • ms Number - Amount of milliseconds to delay between frames

    setFrameRate(framesPerSecond)

    Set delay based on amount of frames per second. Cannot be used with gif.setDelay.

    • framesPerSecond Number - Amount of frames per second

    setDispose(disposalCode)

    Set the disposal code

    • disposalCode Number - Alters behavior of how to render between frames
      • If no transparent color has been set, defaults to 0.
      • Otherwise, defaults to 2.
    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

    • n Number
      • If n is -1, play once.
      • If n is 0, loop indefinitely.
      • If n is a positive number, loop n times.

    setTransparent(color)

    Define the color which represents transparency in the GIF.

    • color Hexadecimal Number - Color to represent transparent background
      • Example: 0x00FF00

    setQuality(quality)

    Set the quality (computational/performance trade-off).

    • quality Positive number
      • 1 is best colors, worst performance.
      • 20 is suggested maximum but there is no limit.
      • 10 is the default, provided an even trade-off.

    Input/output

    read([size])

    Read out size bytes or until the end of the buffer. This is implemented by readable-stream.

    • size Number - Optional number of bytes to read out

    writeHeader()

    Write out header bytes. We are following GIF89a specification.

    addFrame(imageData, options)

    Write out a new frame to the GIF.

    • imageData 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.
      • If used with the options palette and indexedPixels, then this becomes the index in the palette (e.g. 0 for color #0)
    • options Object - Optional container for options
      • palette Array - Array of pixels to use as palette for the frame. It should follow the sequence of r, g, b, a
        • At the moment, this must be used with options.indexedPixels
      • indexedPixels Boolean - Indicator to treat imageData as RGBA values (false) or indicies in palette (true)

    finish()

    Write out footer bytes.

    Low-level

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

    • imageData Array - Same as that in addFrame
    • options Object - Optional container for options
      • indexedPixels 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.

    • imageData Array - Same as that in addFrame; array containing r, g, b, a sequences.

    setImagePixels(pixels)

    Save pixels as this.pixels for image analysis.

    • pixels Array - Same as imageData from addFrame
      • GifEncoder will mutate the original data.

    setImagePalette(palette)

    Save palette as this.userPalette for frame writing.

    • palette 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.

    Donating

    Support this project and others by twolfson via donations.

    http://twolfson.com/support-me

    Contributing

    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.

    UNLICENSE

    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.

    Install

    npm i gif-encoder

    DownloadsWeekly Downloads

    103,923

    Version

    0.7.2

    License

    none

    Unpacked Size

    76.1 kB

    Total Files

    23

    Last publish

    Collaborators

    • twolfson