Skip to content
noggin

GIF encoding: ffmpeg, gifski, animated WebP/AVIF, video (2026-11-01)

Question (Cansin): the README hero and the gesture GIFs are Blender PNG frames encoded by ffmpeg, and the hero is squeezed to 48 colours to stay under 3 MB. Is there a better free option for quality per byte?

  • encode() runs one ffmpeg graph per motion: palettegen=max_colors=N:stats_mode=diff, then paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle, -loop 0; it fails the build over the byte cap (model/render/pictures.py:272-288). ffmpeg is imageio-ffmpeg’s bundled binary (pictures.py:291-292; uv.lock 0.7.0), so CI installs no ffmpeg (.github/workflows/site-checks.yml:139-140).
  • Hero: 800x400, 48 colours, 3 MB cap (pictures.py:48-49), 8 fps like every GIF (pictures.py:56), joined by join("hero") (pictures.py:255-267). Gestures: 400x300, 64 colours, 1 MB cap (pictures.py:40, 56).
  • The README shows the hero from the site’s absolute URL, https://yellowpine.com/noggin/images/hero.gif (README.md:15), so GitHub serves it through its Camo proxy.
  • The look is not flat colour: satin mixed 45/55 with a two-step toon shadow, one highlight band and black lines (docs/model-notes.md:18-24). A full-colour still of it has 14,313 colours (measured on the site’s exploded.jpg at 800 wide), so the satin gradients are what the palette has to squeeze.

Source: hero.gif from the site, 1,558,637 B: 64 frames, 800x400, delays 12/13 cs (8 fps), 47 colours used. Frames extracted with ffmpeg and re-encoded at the same size and frame rate with imageio-ffmpeg’s 7.1 (what make pictures runs), gifski 1.34.0 and libwebp’s gif2webp/img2webp. SSIM is ffmpeg’s ssim filter over all 64 frames on one 8 fps timeline, against the extracted frames (1.0 = identical).

Caveat. The frames are already 47 colours, so every lossy option is judged against a quantised picture, and ffmpeg’s palette finds those 47 colours exactly. This understates what any option gains over the original PNG frames, and it cannot rank ffmpeg’s palette settings at all.

Option Bytes vs today SSIM
live hero.gif (ffmpeg, 48 colours) 1,558,637 100 % 1.0000
ffmpeg re-encode, current settings 1,558,637 100 % 1.0000
ffmpeg, 64/128 colours, stats_mode=full, dither=none/sierra2_4a, no diff_mode (each) 1,558,637 100 % 1.0000
gifski --quality 90 1,417,999 91 % 0.9930
gifski --quality 90 --lossy-quality 60 1,209,491 78 % n/m
gifski --quality 70 1,146,774 74 % n/m
gifski --quality 50 809,043 52 % 0.9528
animated WebP, lossless (gif2webp -min_size -m 6) 1,164,700 75 % 1.0000
animated WebP, lossless (ffmpeg libwebp_anim) 1,189,552 76 % 1.0000
animated WebP, lossy q90 (ffmpeg) 1,499,224 96 % 0.9926
animated WebP, mixed q80 (img2webp) 832,152 53 % 0.9877
animated WebP, lossy q75 (ffmpeg) 845,496 54 % 0.9824
animated AVIF, libaom crf 30 221,924 14 % 0.9899
MP4 H.264 crf 18 (yuv420p, veryslow) 510,731 33 % n/m
MP4 H.264 crf 23 279,301 18 % 0.9902
WebM VP9 crf 32 284,234 18 % 0.9891
WebM AV1 crf 32 194,067 12 % n/m

n/m: not measured on the common timeline. Second data point, bored.gif (400x300, 92 frames, 553,421 B): lossless WebP 458,614 (83 %), gifski q90 486,198, WebP q75 354,412, H.264 crf 23 98,559, AVIF crf 30 93,425.

Visual check (frame crops at 2-4x, read as images):

  • Re-encodes of the hero: WebP q75 and AV1 smooth the Bayer crosshatch out of the satin and keep the outlines sharp; H.264 crf 23 keeps some of the crosshatch, outlines clean; gifski q70 turns the crosshatch into visible grain.
  • Full-colour still at 800 wide (exploded.jpg, same look and lights), one frame each: ffmpeg 48 colours Bayer 53,427 B, SSIM 0.9876, a crosshatch and a pink cast on the grey ring; 48 colours dither=none 48,799 B, 0.9916, visible bands on the ring; 48 colours sierra2_4a 53,811 B, 0.9821; 128 colours Bayer 73,404 B, 0.9943; 256 colours 86,020 B, 0.9988; gifski q90 50,436 B, 0.9903, no visible pattern; WebP q90 27,166 B, 0.9962, no visible artefact. At 48 colours the dither choice matters more than the palette statistics, and gifski’s is the cleanest at the same size.

Encode time: gifski took 0.3 s for the hero’s 64 frames, gif2webp 2.1 s (this Mac).

  • ffmpeg palettegen/paletteuse. stats_mode=diff weighs only “the part that differs from previous frame”; diff_mode=rectangle reprocesses only the changing rectangle and gives “less moving noise and better GIF compression”; bayer_scale 5 is the least visible pattern “at the cost of more banding”; the default dither is sierra2_4a (FFmpeg filters: palettegen, paletteuse). One palette for the whole clip, at most 256 colours.
  • gifski 1.34.0 (2025-07-13; repo pushed 2026-06-17, not archived). “Highest-quality GIF encoder based on pngquant”: cross-frame palettes and temporal dithering, “thousands of colors” per frame. Licence “AGPL 3 or later”, commercial licences on request (README). macOS: brew install gifski (installed here, 1.34.0). ubuntu-latest: no Ubuntu package (packages.ubuntu.com); the 1.34.0 release tarball (14 MB) carries linux/gifski, mac/gifski and win/ binaries, and 1.33.0 also had a .deb (releases); cargo install gifski builds from source.
  • Animated WebP and AVIF in the browser. Chrome, Edge, Firefox, Opera and Safari show both; Firefox animates AVIF from 113; MDN suggests WebP, AVIF or APNG for animation sequences over GIF (MDN image types).
  • CI has the encoders already. imageio-ffmpeg 0.7.0’s Linux binary (ffmpeg 7.0.2) is built with libwebp, libaom, libvpx and libx264 (read from the manylinux wheel); the macOS 7.1 binary lists libwebp_anim, libaom-av1, libsvtav1, libvpx-vp9, libx264. WebP, AVIF and video need no new install.
  • GitHub README. GitHub’s attachment docs list PNG, GIF, JPEG, SVG and video (.mp4, .mov, .webm) as “supported in all contexts”, 10 MB for images and GIFs; WebP and AVIF are not listed (attaching files). No GitHub doc says whether animated WebP or AVIF render in a README. Tested:
    • erikjuhani/basalt’s README shows an animated AVIF (2,383 frames, from raw.githubusercontent.com). Headless Chrome on github.com gave four different element screenshots 0.7 s apart: it renders and animates.
    • GitHub’s live Camo served external AVIFs from two READMEs (inclusionAI/Ming, q5play/q5play) with Content-Type: image/avif, byte for byte the origin’s. Camo checks the Content-Type against its list (anonymized URLs); the open-source Camo’s list (archived 2021) has image/webp and image/gif, no AVIF (mime-types.json), so the live one is newer.
    • Not tested: an animated WebP through Camo in a browser (no README with an external one found), Safari, GitHub Mobile.
  • Video in the README. Video uploads work “everywhere you can author Markdown in GitHub” (changelog 2021-05-13), but only as a file uploaded to GitHub, a hand step that ADR 0009 rules out (outputs built in CI, served by the site: docs/adr/0009-sources-only.md:44-47). The docs say nothing about autoplay or loop for those players. Out.
  • Astro / Starlight (spec #331). “Images in Starlight use Astro’s built-in optimized asset support” (Starlight authoring). Astro processes local images in src/ and authorised remote images; “Images stored in the public/ folder are never optimized” and remote images from other sources are “displayed with no processing”; “There is also no native video support in Astro” (Astro images). Its Sharp service opens every frame (pages: -1), outputs WebP by default (DEFAULT_OUTPUT_FORMAT = 'webp') and forces loop: 0 for GIF input (fixed in #13683, closed 2025-05-13); animated AVIF it cannot decode and passes through with a warning (sharp.ts, consts.ts, Astro 7.4.4). Inferred: the README’s absolute site URLs are unauthorised remote images, so Starlight serves our GIF, WebP or AVIF untouched; a GIF moved into src/ would be re-encoded to lossy animated WebP by Sharp. A muted looping video needs a raw <video autoplay muted loop playsinline> in the page, which the README cannot carry.
  1. Keep GIF from ffmpeg as the README format: the only animated format GitHub documents. The palette settings cannot be ranked on this source; on the full-colour still, at 48 colours the dither choice dominates (Bayer: a crosshatch; none: bands).
  2. Consider, cheapest: spend the hero’s headroom. It ships at 1.56 MB under a 3 MB cap; the “64 colours went to 3.2 MB” note (pictures.py:49) dates from 640x480 at 10 fps, and 800x400 at 8 fps has about 17 % fewer pixels a second (inferred). Raising HERO_COLOURS to 64 is one constant, and encode() fails CI if it no longer fits.
  3. Consider: gifski for the GIF step. On the still it matches ffmpeg’s bytes at 48 colours without the crosshatch, and it is not bound to one 256-colour palette for the clip. Cost: a pinned, sha256-checked 14 MB tarball in the render job (as Blender is), an AGPL CLI called by the build, and a re-tune of the byte caps. Its gain on the real PNG frames is unmeasured: one CI run comparing both on the same frames settles it.
  4. Switch candidate, after a trial: animated WebP. Lossless is pixel-identical to today’s GIF at 75 % of the bytes; lossy q75 is 54 % with the dither smoothed out. No new tool (libwebp_anim in imageio-ffmpeg). It needs one README trial PR viewed on GitHub web (Chrome, Safari, Firefox) and GitHub Mobile, because GitHub does not document it; a <picture> with a GIF fallback might hedge, but whether GitHub keeps <source type> is untested.
  5. Not now: animated AVIF (smallest at 14 % of today’s bytes, but undocumented on GitHub, Sharp cannot process it, Firefox animates it only from 113) and MP4/WebM video (12-18 %, but no README path under ADR 0009, and the site’s pages are the README’s Markdown). Video fits only a site-only page such as the viewer.
  • The gain over the original Blender PNG frames: no full-colour frames were rendered (CI only). The still stands in.
  • Animated WebP through Camo in a browser; Safari and GitHub Mobile for WebP or AVIF in a README.
  • Whether GitHub’s sanitiser keeps <picture><source type="image/webp">.
  • gifski on ubuntu-latest (only the tarball’s listing was checked, the binary was not run).
  • Whether GitHub Pages serves .webp and .avif with image content types (Camo needs them).
byYellow PineYellow Pine

noggin v0.2.26-6-g09bf9b7 · 09bf9b7