# gif-extract-frames

> Extracts frames from a GIF including inter-frame coalescing.

Latest version **1.0.2** (published 2018-05-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install gif-extract-frames
pnpm add gif-extract-frames
yarn add gif-extract-frames
bun add gif-extract-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.2 |
| Published | 2018-05-03 |
| First published | 2018-05-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8 |
| Dependencies | 4 |
| Unpacked size | 8.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 33 |
| Author | Travis Fischer |
| Maintainers | fisch0920 |
| Keywords | gif, frames, extract, explode |

## Links

- npm: https://www.npmjs.com/package/gif-extract-frames
- Repository: https://github.com/transitive-bullshit/gif-extract-frames
- npm.io page: https://npm.io/package/gif-extract-frames

## Dependencies (4)

- [pify](https://npm.io/package/pify.md) ^3.0.0
- [get-pixels](https://npm.io/package/get-pixels.md) ^3.3.0
- [save-pixels](https://npm.io/package/save-pixels.md) ^2.3.4
- [pump-promise](https://npm.io/package/pump-promise.md) ^1.0.0

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 1.0.2 (latest) — 2018-05-03
- 1.0.1 — 2018-05-03
- 1.0.0 — 2018-05-03

## README

# gif-extract-frames

> Extracts frames from GIFs including inter-frame coalescing.

[![NPM](https://img.shields.io/npm/v/gif-extract-frames.svg)](https://www.npmjs.com/package/gif-extract-frames) [![Build Status](https://travis-ci.org/transitive-bullshit/gif-extract-frames.svg?branch=master)](https://travis-ci.org/transitive-bullshit/gif-extract-frames) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)


## Why?

Some GIFs store delta information between frames instead of storing complete frames. Here's an example:

---

Original gif ([source](https://giphy.com/gifs/ycagKBYEmaili)).

![Input gif bubbles](https://raw.githubusercontent.com/transitive-bullshit/gif-extract-frames/master/media/bubbles.gif)

---

5 extracted frames **without** coalescing.

![Example without coalescing](https://raw.githubusercontent.com/transitive-bullshit/gif-extract-frames/master/media/example-without-coalescing.png)

---

5 extracted frames **with** coalescing.

![Example without coalescing](https://raw.githubusercontent.com/transitive-bullshit/gif-extract-frames/master/media/example-with-coalescing.png)

---

## Install

This module requires `node >= 8`.

```bash
npm install --save gif-extract-frames
```

## Usage

```js
const extractFrames = require('gif-extract-frames')

const results = await extractFrames({
  input: './media/bubbles.gif',
  output: 'frame-%d.png'
})
console.log('number of frames', results.shape[0])
```


## API

### extractFrames(opts)

Returns: `Promise<ndarray>`

Returns a modified version of the [ndarray](https://github.com/scijs/ndarray) returned by [get-pixels](https://github.com/scijs/get-pixels).

#### opts.input

Type: `String`
**Required**

Path to a GIF file.

#### opts.output

Type: `String`
Example: `'output/frame-%d.png'`

Optional frame pattern if you want to write each frame to disk. Should contain a `%d` that will be replaced with the frame number (starting at 0).

The resulting [ndarray](https://github.com/scijs/ndarray) will be returned whether or not an `output` is given.

#### opts.coalesce

Type: `Boolean`
Default: `true`

Whether or not to perform inter-frame coalescing.


## Related

- [gifsicle](https://github.com/kohler/gifsicle) - GIF manipulation library capable of *exploding* gifs, but AFAIK does not support frame coalescing when exporting frames.
- [gif-explode](https://github.com/hughsk/gif-explode) - Alternative which uses [gifsicle](https://github.com/kohler/gifsicle) but does not support frame coalescing.
- [omggif](https://github.com/deanm/omggif) - JavaScript GIF encoder & decoder used under the hood.
- [ffmpeg-extract-frames](https://github.com/transitive-bullshit/ffmpeg-extract-frames) - Analogous module for extracting frames from video files.


## License

MIT © [Travis Fischer](https://github.com/transitive-bullshit)

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