Skip to content
This repository has been archived by the owner on Aug 26, 2023. It is now read-only.

friday/lottie-node

Repository files navigation

⚠️ lottie-node is unmaintained
lottie-node has always relied on hacks that make it brittle. I've not been using it myself for a very long time, so I have no interest in maintaining it.
For a more stable solution. I recommend puppeteer-lottie instead. It is doing the same thing, except via pupeteer (Chrome headless), instead of Node-canvas.

lottie-node

lottie-node is an API for runnig Lottie with the canvas renderer in Node.js, with the help of node-canvas and jsdom. This is intended for rendering Lottie animations to images or video. Using Node for rendering is advantageous over something like PhantomJS, since it's faster and allows you to export images with opacity. It doesn't have to record in real-time, and you won't have a problem with frame-skipping.

Installation

Install lottie-node and the peer-dependencies:

npm i canvas jsdom lottie-web lottie-node or yarn add canvas jsdom lottie-web lottie-node

Node-Canvas will most likely download a pre-built binary release for your cpu architecture rather than building it. If this isn't the case for you, you should install the libraries needed for the build.

If you want to render to video you also need ffmpeg. See Rendering to video

Usage

const lottieNode = require("lottie-node");

or

import lottieNode from "lottie-node";

If you need to specify the path to Lottie (if you have altered it for example) you can do it this way:

const lottieNode = require("lottie-node").factory("/path/to/lottie.js");

lottieNode (as created above) is a similar to lottie-web's loadAnimation, but the arguments are simplified since most of the Lottie options aren't relevant for rendering on the server.

It takes three arguments:

  • data: Same as lottie-web. Can also be a path to the json file
  • rendererSettings: See wiki. You can also pass the canvas directly instead of this argument. This is recommended unless you want to set preserveAspectRatio)
  • options: Any other options you want to pass to Lottie's loadAnimation(). Apart from assetsPath, most of these doesn't make sense for rendering animations on the server.

To render to a file, call goToAndStop() on the animation object. This renders a frame which is ready on the next "tick". use canvas.toBuffer(). Save the buffer directly to a file or piped them to ffmpeg to create a video (see Examples).

Examples

The examples render an animation from lottie-react-native to PNG or a full video. It's a good place to start.

Make sure you have ffmpeg (see Rendering to video below). Then run the examples in node:

cd examples
yarn # (or 'npm i')
node render-snapshot.js lottie-logo2.json logo.png
node render-video.js lottie-logo2.json logo.mp4 # Video render takes a little longer
# Downloaded from lottiefiles.com (has embedded or linked images)
node render-video.js 34070-corgi-with-blue-balloon.json corgi.mp4 # Corgi with blue balloon by Jonhson Subianto
node render-video.js 28141-sate-traveling.json traveling.mp4 # Sate Traveling by Reza
node render-video.js 18162-rotating-sun.json sun.mp4 # rotating sun by elad p
node render-video-replacing-image.js # Same as above, but replacing the sun with a custom local image

Rendering to video

If you want to render to video you need ffmpeg. Use a package manager or the official compilation guide for how to compile it on your platform. Package managers tends to ship older versions and can't be customized, but they are significantly easier to install.

How it works

Lottie wasn't written to support rendering in Node.js. Node-canvas and jsdom has some quirks when used together, and for some reason Lottie skipped frames for some animations when I tried running scripts the recommended jsdom way. Because of these challenges, while writing lottie-node I had to resort to some hacky methods that are generally discouraged. Rather than importing lottie-web as a module, it's loaded as a string, patched to work server-side, and then run using eval.

This type of solution is risky and can break with the upgrade of any of the peer dependencies, but at least the module is isolated and doesn't add dom-shims to the global scope. The examples have their own package.json and yarn lockfile, so in case the peer-dependencies updates and breaks lottie-node, they should still work.

Lottie's HTML renderer cannot be supported using jsdom. The SVG renderer may be possible to support by converting SVG to canvas. See issue 7 if you want to help out (I'm not going to add this).

Caveats and known issues

  • #8 lottie-node is not working with some json files although they work in lottie-web

Alternatives

puppeteer-lottie (I haven't tried it, but since it doesn't use node-canvas it doesn't have the same issues as lottie-node and supports SVG.