# gif-frames

> Pure JavaScript tool for extracting GIF frames and saving to file

Latest version **1.0.1** (published 2018-12-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install gif-frames
pnpm add gif-frames
yarn add gif-frames
bun add gif-frames
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2018-12-04 |
| First published | 2017-06-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 1.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 172 |
| Author | Ben Wiley |
| Maintainers | benwiley4000 |
| Keywords | gif, frames, extract, save, images, javascript, pure-js |

## Links

- npm: https://www.npmjs.com/package/gif-frames
- Repository: https://github.com/benwiley4000/gif-frames
- Homepage: https://github.com/benwiley4000/gif-frames#readme
- Issues: https://github.com/benwiley4000/gif-frames/issues
- npm.io page: https://npm.io/package/gif-frames

## Dependencies (3)

- [multi-integer-range](https://npm.io/package/multi-integer-range.md) ^3.0.0
- [save-pixels-jpeg-js-upgrade](https://npm.io/package/save-pixels-jpeg-js-upgrade.md) ^2.3.4-jpeg-js-upgrade.0
- [get-pixels-frame-info-update](https://npm.io/package/get-pixels-frame-info-update.md) ^3.3.2

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2018-12-04
- 1.0.0 — 2018-10-15
- 0.4.1 — 2018-08-17
- 0.4.0 — 2017-12-06
- 0.3.0 — 2017-07-14
- 0.2.4 — 2017-06-26
- 0.2.3 — 2017-06-26
- 0.2.2 — 2017-06-26
- 0.2.1 — 2017-06-26
- 0.2.0 — 2017-06-26
- 0.1.0 — 2017-06-26

## README

# gif-frames

A pure JavaScript tool for extracting GIF frames and saving to file. Works in Node or the browser. Uses [get-pixels](https://github.com/scijs/get-pixels) and [save-pixels](https://github.com/scijs/save-pixels) under the hood.

[![NPM](https://nodei.co/npm/gif-frames.png)](https://npmjs.org/package/gif-frames)

## Install

```bash
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](https://unpkg.com/gif-frames?main=bundled) (Unminified)
* [https://unpkg.com/gif-frames?main=bundled-min](https://unpkg.com/gif-frames?main=bundled-min) (Minified)

```html
<!-- unminified -->
<script src="https://unpkg.com/gif-frames@0.4.0?main=bundled"></script>

<!-- minified -->
<script src="https://unpkg.com/gif-frames@0.4.0?main=bundled-min"></script>
```

This will expose `gifFrames` as a global variable.

## `require('gif-frames')(options[, callback])`

```javascript
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](http://nodejs.org/api/buffer.html)
* `frames` (**required**): The set of frames to extract. Can be one of:
  - `'all'` (gets every frame)
  - Any valid [`Initializer`](https://github.com/smikitky/node-multi-integer-range#initializers) accepted by the [multi-integer-range library](https://github.com/smikitky/node-multi-integer-range)
* `outputType` (*optional*, default `'jpg'`): Type to use for output (see [`type`](https://github.com/scijs/save-pixels#requiresave-pixelsarray-type-options) for `save-pixels`)
* `quality` (*optional*): Jpeg quality (see [`quality`](https://github.com/scijs/save-pixels#requiresave-pixelsarray-type-options) 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:

```javascript
{
  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](http://www.onicos.com/staff/iz/formats/gif.html)

## Examples

Writing selected frames to the file system in Node:

```javascript
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`):

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

---
_Source: https://npm.io/package/gif-frames · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._