Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/transitive-bullshit/puppeteer-lottie
Renders Lottie animations via Puppeteer to image, GIF, or MP4.
https://github.com/transitive-bullshit/puppeteer-lottie
ffmpeg gifski lottie lottie-web puppeteer
Last synced: 4 days ago
JSON representation
Renders Lottie animations via Puppeteer to image, GIF, or MP4.
- Host: GitHub
- URL: https://github.com/transitive-bullshit/puppeteer-lottie
- Owner: transitive-bullshit
- Created: 2019-05-10T12:20:24.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-07-25T14:36:07.000Z (over 1 year ago)
- Last Synced: 2025-01-01T09:03:03.631Z (11 days ago)
- Topics: ffmpeg, gifski, lottie, lottie-web, puppeteer
- Language: JavaScript
- Size: 3.44 MB
- Stars: 367
- Watchers: 6
- Forks: 70
- Open Issues: 19
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
- awesome-lottie - View
- awesome-puppeteer - puppeteer-lottie - Renders [Lottie](http://airbnb.io/lottie) animations via [Puppeteer](https://github.com/GoogleChrome/puppeteer) to **image**, **GIF** or **MP4**. (Packages)
README
# puppeteer-lottie
> Renders [Lottie](http://airbnb.io/lottie) animations via [Puppeteer](https://github.com/GoogleChrome/puppeteer) to **image**, **GIF** or **MP4**.
[](https://www.npmjs.com/package/puppeteer-lottie) [](https://travis-ci.com/transitive-bullshit/puppeteer-lottie) [](https://standardjs.com)
This module is also available as a [CLI](https://github.com/transitive-bullshit/puppeteer-lottie-cli).
## Install
```bash
npm install --save puppeteer-lottie
```
If you want to generate **GIFs**, you must also install [gifski](https://gif.ski/). On macOS, you can run:
```bash
brew install gifski
```
If you want to generate **MP4s**, you must also install [ffmpeg](https://ffmpeg.org/). On macOS, you can run:
```bash
brew install ffmpeg
```
## Usage
```js
const renderLottie = require('puppeteer-lottie')
// Create an MP4 from a lottie animation
await renderLottie({
path: 'fixtures/bodymovin.json',
output: 'example.mp4'
})
// Create a GIF with width 640px from a lottie animation
await renderLottie({
path: 'fixtures/bodymovin.json',
output: 'example.gif',
width: 640
})
// Render each frame of the animation as PNG images with height 128px
await renderLottie({
path: 'fixtures/bodymovin.json',
output: 'frame-%d.png', // sprintf format
height: 128
})
// Render the first frame of the animation as a JPEG image
await renderLottie({
path: 'fixtures/bodymovin.json',
output: 'preview.jpg'
})
```
#### Output Size
If you don't pass `width` or `height`, the animation's intrinsic size will be used, and if that doesn't exist it will use 640x480.
If you pass `width` or `height`, the other dimension will be inferred by maintaining the original animation's aspect ratio.
If both `width` and `height` are passed, the output will have those dimensions, but there will be extra whitespace (or transparency if rendering PNGs) due to `lottie-web`'s default `rendererSettings.preserveAspectRatio` of `xMidyMid meet` ([docs](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio) and [demo](https://codepen.io/giodif/pen/VYpaeo)).
For `mp4` outputs, the height may be different by a pixel due to the `x264` encoder requiring even heights.
## API
### [renderLottie](https://[email protected]/:transitive-bullshit/puppeteer-lottie/blob/233718bd1e709d87415aedf49c3425b8302ff822/index.js#L60-L382)
Renders the given Lottie animation via Puppeteer.
You must pass either `path` or `animationData` to specify the Lottie animation.
`output` must be one of the following:
- An image to capture the first frame only (png or jpg)
- An image pattern (eg. sprintf format 'frame-%d.png' or 'frame-%012d.jpg')
- An mp4 video file (requires FFmpeg to be installed)
- A GIF file (requires Gifski to be installed)
Type: `function (opts): Promise`
- `opts` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Configuration options
- `opts.output` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Path or pattern to store result
- `opts.animationData` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON exported animation data
- `opts.path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Relative path to the JSON file containing animation data
- `opts.width` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Optional output width
- `opts.height` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Optional output height
- `opts.jpegQuality` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** JPEG quality for frames (does nothing if using png) (optional, default `90`)
- `opts.quiet` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Set to true to disable console output (optional, default `false`)
- `opts.deviceScaleFactor` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Window device scale factor (optional, default `1`)
- `opts.renderer` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Which lottie-web renderer to use (optional, default `'svg'`)
- `opts.rendererSettings` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional lottie renderer settings
- `opts.puppeteerOptions` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional puppeteer launch settings
- `opts.ffmpegOptions` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional ffmpeg settings for
crf, profileVideo and preset values
- `opts.gifskiOptions` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional gifski settings (only for GIF outputs)
- `opts.style` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Optional JS [CSS styles](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Properties_Reference) to apply to the animation container (optional, default `{}`)
- `opts.inject` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Optionally injects arbitrary string content into the head, style, or body elements. (optional, default `{}`)
- `opts.inject.head` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Optionally injected into the document
- `opts.inject.style` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Optionally injected into a tag within the document <head>
- `opts.inject.body` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Optionally injected into the document <body>
- `opts.browser` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional puppeteer instance to reuse
## Compatibility
All [lottie-web](https://github.com/airbnb/lottie-web) features should be fully supported by the `svg`, `canvas`, and `html` renderers.
This includes all of the animations on [lottiefiles.com](https://lottiefiles.com/)! 🔥
Also see Lottie's full list of [supported features](https://airbnb.io/lottie/#/supported-features).
## Related
- [puppeteer-lottie-cli](https://github.com/transitive-bullshit/puppeteer-lottie-cli) - CLI for this module.
- [puppeteer](https://github.com/GoogleChrome/puppeteer) - Headless Chrome Node API.
- [awesome-puppeteer](https://github.com/transitive-bullshit/awesome-puppeteer) - Curated list of awesome puppeteer resources.
- [lottie](http://airbnb.io/lottie) - Render After Effects animations natively on Web, Android and iOS, and React Native.
## License
MIT © [Travis Fischer](https://transitivebullsh.it)
Support my OSS work by <a href="https://twitter.com/transitive_bs">following me on twitter <img src="https://storage.googleapis.com/saasify-assets/twitter-logo.svg" alt="twitter" height="24px" align="center"></a>