'saveGif()' the p5.js animation GIF generater.

The saveGif() function allows you to generate an animated GIF directly from your p5.js sketch.

In the past, I often avoided creating animated sketches with p5.js because I found the process of making a movie much easier using Processing.

Now, with the introduction of the saveGif() function in p5.js version 1.5.0, I'm eager to explore its usability and see how it streamlines the animation capture process.

👉 この記事は日本語でも読めます。

Getting Started: The Basics of `saveGif()`

I began by following the basic usage outlined in the p5.js reference documentation.

saveGif() | reference | p5.js

The example code below is set to a frame rate of 30 frames per second (`30fps`). When the 's' key is pressed, it captures one second of animation and saves the result as an animated GIF named `'01.gif'`.

/**
 * saveGif() test.
 * ref. https://p5js.org/reference/#/p5/saveGif
 * 
 * @author @deconbatch
 * @version 0.1
 * @license CC0
 * p5.js 1.5.0
 * created 2022.11.05
 */

const frmRate = 30;

function setup() {
  createCanvas(480, 480);
  smooth();
  frameRate(frmRate);
  fill(96);
  noStroke();
}

function draw() {
  const t = map(frameCount % frmRate, 0, frmRate, 0.0, 1.0);
  const x = width * 0.4 * cos(TWO_PI * t);
  const y = height * 0.4 * sin(TWO_PI * t);

  background(240);
  translate(width * 0.5, height * 0.5);
  circle(x, y, 50);
}

function keyPressed() {
  if (key === 's') {
    saveGif('01.gif', 1); // 1 sec
  }
}

Please note that you need to be using p5.js version 1.5.0 or newer. If you are using OpenProcessing, you can check the p5.js version near the 'mode' setting and select a different version by clicking on it.

When I pressed the 's' key, this code generated an animated GIF like this.

It truly is convenient!

You can also specify the duration in frames (instead of seconds) using an options object, like this:

saveGif('01.gif', 30, {delay: 0, units : 'frames'});

Exploring Edge Cases

Now, let's test some less common scenarios and interesting questions.

Attempt 1: Placing `saveGif()` in `setup()`

Will placing `saveGif()` inside `setup()` capture the animation starting from the very first frame? No. Doing so only resulted in a blank, black GIF.

The p5.js reference page also mentions that this configuration "won't work properly."

Attempt 2: Using `clear()` instead of `background()`

What happens if we use `clear()` instead of `background()`? When I used `clear()`, the resulting GIF animation had a transparent background that appeared black.

Attempt 3: Can I use decimal values for seconds?

Yes you can. The function handles decimal values smoothly.

saveGif('01.gif', 0.5); // 0.5 sec

Attempt 4: Multiple `saveGif()` calls?

The code below attempts to call `saveGif()` twice in quick succession. While it prompts two save dialogs, the resulting movie files may be broken or corrupted.

saveGif('01.gif', 0.5);
saveGif('02.gif', 1.0);

Handling Computationally Intensive Sketches

I next tested the function with a sketch that draws a Turing pattern. Since complex calculations are involved, drawing a single frame takes approximately one second.

The function worked perfectly! It successfully created a 60-frame movie, with `frameRate(30)` resulting in a two-second animation.

Generating the animated GIF took over three minutes, but the resulting file shows a smooth, two-second animation. This is an incredible feat that traditional screen capture tools simply cannot achieve.

Can the Recording Start Precisely from Frame 1?

This remains a challenge.

As noted before, placing `saveGif()` in `setup()` results in a black GIF.

Placing it in `draw()` to trigger on the first frame also produced the same problematic result:

  if (frameCount === 1) {
    saveGif('01.gif', 1.0);
  }

I then attempted a workaround: "If 's' is pressed, start recording only when the current frame count is near the beginning of a cycle."

const frmRate = 1;
const gifLen = frmRate * 8;

function keyPressed() {
  if (
      key === 's' &&
      frameCount % gifLen == 1
     ) {
    saveGif('08.gif', gifLen, {delay: 0, units : 'frames'}); // no delay, gifLen frames
  }
}

However, this attempt did not work properly. It frequently failed to start exactly from the intended first frame or resulted in skipped frames.

Summary: Key Takeaways for Using `saveGif()`

Here are the essential points for effectively using the `saveGif()` function:

1. Version: Use p5.js version 1.5.0 or newer.
2. Syntax:
   

   By Seconds:

   `saveGif('file_name', seconds_number)`

   By Frames:

   `saveGif('file_name', frames_number, {delay: 0, units : 'frames'})`

   For customizing delay:

   Please refer to the official documentation.

3. Placement: Trigger the function from a user-input event (e.g., `keyPressed()`). Do not place it in `setup()` or conditionally in `draw()`.
4. Background: Use `background()` for drawing; do not use `clear()`.

While `saveGif()` is remarkably easy and convenient to use, it does have a few limitations: it is challenging to start the recording precisely from the absolute first frame of the animation, and it lacks the adaptability of external tools (like combining Processing with shell scripting).

Despite these minor limitations, the function's charm lies in its convenience. Crucially, the ability to effortlessly generate animated GIFs from computationally heavy sketches is a significant advantage./p>

For reference : Recording with the OpenProcessing only

Just click and save! How to record your 'p5.js' animation in mp4.