GIF Creation

Create high-quality, optimized GIFs from videos, image sequences, or WebGL shader renders using FFmpeg's 2-pass palette generation, ImageMagick, or Playwright-based headless capture pipelines.

Quick Start

From video

ffmpeg -i video.mp4 \
  -vf "fps=15,scale=480:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
  -loop 0 output.gif

From image sequence

magick -delay 7 -loop 0 -dispose Background frames/frame_*.png output.gif

From WebGL shader (interactive)

cd <project-dir>
pnpm dev
# → http://localhost:3000  — tweak params, click ⬇ Save GIF

Source Detection

Automatically detect the source type and choose the appropriate pipeline:

Pipeline 1: Video → GIF (FFmpeg 2-Pass)

The gold standard for video-to-GIF conversion. Two passes produce better colour fidelity and smaller files than single-pass approaches.

Pass 1 — Generate palette

ffmpeg -ss <start> -t <duration> -i video.mp4 \
  -vf "fps=<FPS>,scale=<WIDTH>:-1:flags=lanczos,palettegen=stats_mode=diff" \
  -y /tmp/palette.png

Pass 2 — Encode GIF

ffmpeg -ss <start> -t <duration> -i video.mp4 -i /tmp/palette.png \
  -lavfi "fps=<FPS>,scale=<WIDTH>:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5" \
  -loop 0 \
  output.gif

Optimization Presets

Pipeline 2: Image Sequence → GIF

With ImageMagick (recommended for transparency)

magick -delay <DELAY> -loop 0 -dispose Background "frames/frame_*.png" output.gif

Delay calculation: delay = 100 / FPS (centiseconds). E.g. 15 FPS → delay 7.

ImageMagick's -dispose Background is essential for transparent GIFs — it clears each frame before drawing the next, preventing ghosting artefacts.

With FFmpeg

ffmpeg -framerate <FPS> -pattern_type glob -i "frames/*.png" \
  -vf "scale=<WIDTH>:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
  -loop 0 \
  output.gif

Pipeline 3: WebGL Shader → GIF (Playwright + ImageMagick)

For generating GIFs from programmatic WebGL/shader sources — no screen recording needed. This pipeline was developed in the dithering-gif project.

Architecture

shader.html  →  Playwright (headless)  →  PNG frames  →  ImageMagick  →  GIF
                     │                         │
                     └─ page.evaluate()        └─ temp dir (cleaned up)
                        drives u_time
                        deterministically

Key Concepts

1. Deterministic capture: Drive the shader's u_time uniform manually (one value per frame) rather than recording real-time playback. This gives pixel-perfect, timing-independent frames and guarantees seamless loops.
2. gl.readPixels for reliable export: WebGL clears its drawing buffer after each frame swap. Use gl.readPixels + an offscreen 2D canvas to bypass this and get reliable PNG data.
3. Row-flip: WebGL is bottom-left origin; PNG/2D canvas is top-left. Flip rows during the readback copy.
4. Dynamic sizing: The shader's canvas.width/canvas.height and the gl.viewport must be updated together when changing output resolution. The readPixels buffer must be reallocated to match.

Shader Page Contract

The shader HTML page must expose these globals for headless capture:

window.__ready      = true;                      // signals page is loaded
window.__setParams  = (params) => { /* ... */ };  // apply uniform overrides
window.__render     = (uTime) => { /* ... */ };   // render one frame at time t
window.__getDataUrl = () => canvas.toDataURL();   // return PNG as data URL

Capture Script Pattern (Node.js)

import { chromium } from 'playwright';

const LOOP_PERIOD = 8 * Math.PI;  // exact loop period for the animation
const FRAME_COUNT = 90;
const step        = LOOP_PERIOD / FRAME_COUNT;

const browser = await chromium.launch({ args: ['--enable-webgl', '--use-gl=egl'] });
const page    = await (await browser.newContext({
  viewport: { width: 480, height: 480 },
})).newPage();

await page.goto('http://localhost:3000/shader.html');
await page.waitForFunction(() => window.__ready === true);

// Push params before capture
await page.evaluate((p) => window.__setParams(p), params);

for (let i = 0; i < FRAME_COUNT; i++) {
  await page.evaluate((t) => window.__render(t), i * step);
  const b64 = await page.evaluate(() => window.__getDataUrl().split(',')[1]);
  writeFileSync(`frame_${String(i).padStart(4, '0')}.png`, Buffer.from(b64, 'base64'));
}

await browser.close();

Encode with ImageMagick

magick -delay <DELAY> -loop 0 -dispose Background "frames/frame_*.png" output.gif

Seamless Loop Calculation

To find the exact loop period for sinusoidal animations:

1. Identify all time-dependent terms: e.g. cos(a × t) and sin(b × t).
2. Each term's period in t is 2π / coefficient.
3. The animation's period is the LCM of all individual periods.
4. Drive u_time from 0 to that LCM over exactly FRAME_COUNT frames.

Example: cos(0.75t) has period 8π/3; sin(0.625t) has period 16π/5. LCM = 8π. So 90 frames over 8π gives a mathematically exact loop.

Transparency

In GIFs (general)

GIF supports only 1-bit transparency (fully transparent or fully opaque per pixel). Use alpha_threshold=128 in FFmpeg or ImageMagick's palette handling.

With ImageMagick (recommended)

magick -delay 7 -loop 0 -dispose Background frames/frame_*.png output.gif

-dispose Background is critical — without it, transparent pixels accumulate ghost frames from previous iterations.

With FFmpeg

ffmpeg -framerate 15 -pattern_type glob -i "frames/*.png" \
  -vf "split[s0][s1];[s0]palettegen=reserve_transparent=1[p];[s1][p]paletteuse=alpha_threshold=128" \
  -gifflags +transdiff \
  -loop 0 output.gif

Configuration Defaults

Size Estimation

Approximate file sizes at the balanced preset:

Factors affecting size: width, FPS, duration, scene complexity, and optimisation preset (quality > balanced > size).

Platform Limits

Post-Processing (Optional)

gifsicle — further compression

gifsicle -O3 --lossy=80 output.gif -o output_optimized.gif

Best Practices

Reducing file size

• Lower FPS (12–15 is sufficient for most content).
• Smaller width (480 px or less).
• Use the size optimisation preset.
• Trim to the shortest necessary duration.
• Apply gifsicle -O3 --lossy=80 as a post-processing step.

Better quality

• Higher FPS (24–30 for smooth motion).
• Larger width (640–800 px).
• Use the quality optimisation preset.
• Use floyd_steinberg dithering for photographic content.

Smooth motion

• 24+ FPS for fast action or camera movement.
• 12–15 FPS for simple content, UI demos, or talking heads.

Transparent GIFs

• Always use -dispose Background with ImageMagick.
• Prefer ImageMagick over FFmpeg for transparent output — more reliable disposal.
• Test the output in multiple viewers; some render GIF transparency inconsistently.

Shader / WebGL GIFs

• Use deterministic u_time stepping — never record real-time playback.
• Calculate the exact loop period mathematically from the animation's frequency components.
• Use gl.readPixels + offscreen canvas — never rely on canvas.toDataURL directly (WebGL clears the drawing buffer between frames).
• Expose a __setParams API so the capture script can override uniforms without editing the shader source.

Requirements

Install (macOS)

brew install ffmpeg imagemagick gifsicle

Verify

ffmpeg -version | head -n 1
magick -version | head -n 1
gifsicle --version | head -n 1