# apng-js

> Parse and play animated PNG (APNG)

Latest version **1.1.5** (published 2025-01-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install apng-js
pnpm add apng-js
yarn add apng-js
bun add apng-js
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.5 |
| Published | 2025-01-25 |
| First published | 2016-09-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 43.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 366 |
| Author | David Mzareulyan |
| Maintainers | davidmz |

## Links

- npm: https://www.npmjs.com/package/apng-js
- Repository: https://github.com/davidmz/apng-js
- npm.io page: https://npm.io/package/apng-js

## Recent versions

- 1.1.5 (latest) — 2025-01-25
- 1.1.4 — 2024-09-05
- 1.1.2 — 2024-05-28
- 1.1.1 — 2020-04-20
- 1.1.0 — 2018-06-22
- 1.0.4 — 2017-11-25
- 1.0.3 — 2016-09-09
- 1.0.2 — 2016-09-08
- 1.0.1 — 2016-09-08
- 1.0.0 — 2016-09-08

## README

# apng-js

`apng-js` provides functions for parse and render animated PNG's 
([APNG](https://en.wikipedia.org/wiki/APNG)).
 
## Demo page

[https://davidmz.github.io/apng-js/](https://davidmz.github.io/apng-js/)
 
## Usage
`npm install apng-js`
 
## API

### parseAPNG(buf: ArrayBuffer): (APNG|Error)

**Default exported function**. Parses APNG data, returns APNG object (see below) or Error.
This function can be used in node.js environment.
Object methods relies on browser features (canvas, requestAnimationFrame…)
and should work only in browser.

Usage:
```
import parseAPNG from 'apng-js';

const apng = parseAPNG(buffer);
if (apng instanceof Error) {
    // handle error
}
// work with apng object
```

### isNotPNG(err: Error): boolean

Checks if Error is 'Not a PNG' error.

### isNotAPNG(err: Error): boolean

Checks if Error is 'Not an animated PNG' error.

## Classes

### APNG
Structure of APNG file.
````
class APNG {
    width: number     // with of canvas, pixels
    height: number    // height of canvas, pixels
    numPlays: number  // number of times to loop animation (0 = infinite looping)
    playTime: number  // total duration of one loop in milliseconds
    frames: Frame[]   // array of frames

    // Methods
    createImages(): Promise // create imageElement's for all frames
    getPlayer(context: CanvasRenderingContext2D, autoPlay: boolean = false): Promise.<Player>
        // Create Player (see below) on given context and start playing
        // if autoPlay is true.
}
````

### Frame
Individual APNG frame.
````
class Frame {
    left: number      // left offset of frame, pixels
    top: number       // top offset of frame, pixels
    width: number     // with of frame, pixels
    height: number    // height of frame, pixels
    delay: number     // time to show frame in milliseconds
    disposeOp: number // type of dispose operation (see APNG spec.)
    blendOp: number   // type of blend operation (see APNG spec.)
    imageData: Blob   // image data in PNG (not animated) format
    
    imageElement: HTMLImageElement // image data rendered as HTML Image element.
                                   // This field is null right after 'parse',
                                   // use Frame.createImage() or APNG.createImages()
                                   // to fill this field.
                                   
    // Methods
    createImage(): Promise // create imageElement for this frame
}
````
### Player
Player renders APNG frames on given rendering context and plays APNG animation.
````
class Player {
    context: CanvasRenderingContext2D
    playbackRate: number = 1.0 // animation playback rate
           
    currFrameNumber: number // current frame number (read only)
    currFrame: Frame        // current frame (read only)
    paused: boolean         // playback is paused (read only)
    ended: boolean          // playback is ended (read only)

    // Methods
    play()      // start or resume playback
    pause()     // pause playback
    stop()      // stop playback and rewind to start
    
    renderNextFrame()       // move to next frame and render it on context
                            // Use this method to manual, frame by frame, rendering.
}
````

Player object is an [EventEmitter](https://nodejs.org/api/events.html). You can listen to following events:

  * **play** — playback started;
  * **frame** — frame played (frame number passed as event parameter);
  * **pause** — playback paused;
  * **stop** — playback stopped;
  * **end** — playback ended (for APNG with finite count of plays).

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