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?
What we do today
Section titled “What we do today”encode()runs one ffmpeg graph per motion:palettegen=max_colors=N:stats_mode=diff, thenpaletteuse=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.
Measured on the live hero
Section titled “Measured on the live hero”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=none48,799 B, 0.9916, visible bands on the ring; 48 colourssierra2_4a53,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).
The tools
Section titled “The tools”- ffmpeg palettegen/paletteuse.
stats_mode=diffweighs only “the part that differs from previous frame”;diff_mode=rectanglereprocesses only the changing rectangle and gives “less moving noise and better GIF compression”;bayer_scale5 is the least visible pattern “at the cost of more banding”; the default dither issierra2_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) carrieslinux/gifski,mac/gifskiandwin/binaries, and 1.33.0 also had a.deb(releases);cargo install gifskibuilds 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.
Constraints
Section titled “Constraints”- 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 theContent-Typeagainst its list (anonymized URLs); the open-source Camo’s list (archived 2021) hasimage/webpandimage/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 thepublic/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 forcesloop: 0for 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 intosrc/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.
Recommendation
Section titled “Recommendation”- 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).
- 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_COLOURSto 64 is one constant, andencode()fails CI if it no longer fits. - 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.
- 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_animin 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. - 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.
Not verified
Section titled “Not verified”- 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
.webpand.avifwith image content types (Camo needs them).
noggin v0.2.26-6-g09bf9b7 · 09bf9b7