html5-animation-video-renderer

A Node.js script that renders an HTML5-based animation (*) into a high-quality video. It renders the animation frame-by-frame using Puppeteer without using screen capturing, so no frameskips!

It works by opening a headless browser and calls seekToFrame(frameNumber) for each frame of your animation. Your web page is expected to display that frame on the screen. It then captures a screenshot for that frame. Each frame is then sent to ffmpeg to encode the video without needing to save temporary files to disk. Because it works by capturing the page screenshot, it can render:

• HTML elements
• SVG elements
• Canvas
• WebGL

However, the renderer needs to get the webpage to display a specific frame before rendering. Therefore, it does not support:

• CSS animations and transitions
• Nondeterministic animation

Features:

• Works with GSAP.
• It can run multiple instances of headless Chrome to speed up rendering.

Examples and demos

All videos and preview images here are generated by CircleCI on every commit.

Creating your HTML5 animation

Your HTML5-based animation can be created using any tool, so long as the webpage has these properties:

• The webpage should contain a #scene element in the DOM, positioned at top: 0; left: 0;. The dimensions of the #scene element will be the video’s dimensions. You can use the provided lib/style.css as a starting point.

• The webpage should contain these global JavaScript functions:

  • getInfo() should return an object with the following properties:

    • fps The video frame rate.
    • numberOfFrames The number of frames to render.

  • seekToFrame(frameNumber) should display the frame at the specified frameNumber. This function may return a promise, in this case the renderer will wait for it to resolve. Please make sure that all assets (such as images/fonts) are already loaded.

  See an example at examples/gsap-hello-world.html.

Install the prerequisites

Install Node.js 12, Yarn and ffmpeg, then install the project dependencies with:

yarn install

Running the renderer

To see help text, run:

node render --help

Rendering a video

node render --url=<URL> --video=<FILE>.mp4

Controlling parallelism

By default, the renderer will spawn multiple headless Chrome processes matching the number of CPU cores detected on your machine. However, more running Chrome instances means more memory consumption. This may be undesirable.

For instance, CircleCI instances have 2 vCPUs and 4 GB of RAM. However it reports as having 36 cores, leading to a lot of crashes due to out-of-memory condition.

You can control the number of headless Chrome processes using the --parallelism option:

node render --url=<URL> --video=<FILE>.mp4 --parallelism=4

Render as image files instead

You can also render individual frames as different image files using the --png option. This can help you avoid losing your work in case you want to render a long video, in exchange for more disk usage.

node render --url=<URL> --video=<FILE>.mp4 --png=<DIR>

This will render each frame to <DIR>/frameNNNNNN.png. Note that you will have to assemble these frames into a video file yourself. You can use this in conjunction with --no-video to render just the image files, without the video.

Render only some part of the video

You can also set the starting and ending frame numbers.

node render --url=<URL> --video=<FILE>.mp4 --start=60 --end=120

This will render the frames 60–119. Note that the ending frame is not rendered.

Do not render a video

Use the --no-video option. Useful when used with --png.

node render --url=<URL> --no-video

Render a single frame

Just set --end to (--start + 1) and render out a --png file.

node render --url=<URL> --png=<DIR> --start=60 --end=61

Upscale/downscale the video

Use the --scale option to scale up or scale down the browser viewport.

node render --url=<URL> --video=<FILE>.mp4 --scale=0.5
node render --url=<URL> --video=<FILE>.mp4 --scale=2