Does GitHub support animated WebP in READMEs?

Yes — GitHub renders animated WebP in markdown images, and its upload flow accepts them like any image. Keep files reasonably small (a few MB): huge uploads get flagged, and fellow developers on slow connections will silently judge a 50MB README regardless of format.

How much smaller is animated WebP than GIF?

Typically 80–90% smaller for screen recordings: a 50MB demo GIF becomes a 3–8MB WebP at equal or better visual quality, because WebP uses modern video-style compression (VP8) with millions of colors instead of GIF's 256-color frames from 1987.

How do I convert MP4 to animated WebP with FFmpeg?

Use libwebp with loop enabled: 'ffmpeg -i demo.mp4 -c:v libwebp -loop 0 -q:v 80 -vf "scale=800:-1,fps=15" demo.webp'. Scale down (demos don't need 1080p), cap 10–15fps, quality 70–85. -loop 0 means infinite looping like a GIF.

Can I use MP4 video directly in a README instead?

Markdown images can't embed playable video — GitHub renders only image formats inline. Video uploads work in issues, PRs, and releases (drag-and-drop MP4 plays with controls), but the README body itself needs an animated image: WebP (or GIF as the legacy fallback).

Animated WebP vs GIF for documentation?

WebP on every axis that matters: ~90% smaller files, 16M colors vs 256, and universal browser support. GIF survives only where tooling rejects everything else. For docs specifically, smaller files also mean faster page loads and happier contributors.

How do I batch convert demo clips to WebP?

Loop FFmpeg over the folder with a fixed recipe (800px wide, 15fps, quality 80), or drop the folder into a batch converter with a WebP recipe and per-file sizes. Verify each output visually once — text-heavy UI recordings compress differently than gameplay.

← Back to Complete Guide

MP4 to Animated WebP: Stop Putting 50MB GIFs in READMEs

Every 50MB README GIF is a loading screen your visitors didn't ask for. The one command that turns any screen recording into a 5MB animated WebP — plus quality settings, GitHub notes, and the batch shortcut.

By Hadi Karaki, maker of FormatifSeptember 16, 20268 min read

The command (then the explanation)

MP4 → animated WebP, README-ready

ffmpeg -i demo.mp4 -c:v libwebp -loop 0 -q:v 80 -vf "scale=800:-1,fps=15" demo.webp

Flag	Does	Tune it
-loop 0	Loops forever, like a GIF	Leave it
-q:v 80	Quality 0–100	70–85 for docs; text needs 80+
scale=800:-1	800px wide, aspect kept	600–800px for READMEs
fps=15	15 frames per second	10–15 for UI; 20+ for motion

Quick Solution

Demo folder full of MP4s? Skip the flags.

The command works, but every demo needs its own scale/fps judgment call. Formatif Pro ($8.95 one-time) batch-converts whole demo folders to animated WebP offline — quality slider per recipe (70–85 for docs), live preview before you commit, per-file sizes after. No terminal, no per-file flag guessing.

Download free trial

Why WebP wins (and the two GitHub gotchas)

GIF stores every frame as a 256-color image with 1987 compression; WebP uses modern VP8 video compression with millions of colors. Same animation, 80–90% smaller, sharper text — which matters because README demos are mostly text on screens, GIF's worst case. Markdown images can't embed playable video, so animated WebP is the ceiling for README bodies (MP4 drag-and-drop works in issues, PRs, and releases — not in markdown itself).

Gotchas: keep uploads to a few MB (huge files get flagged and slow every visitor's page load), and verify text legibility after conversion — small UI fonts are the first casualty of aggressive quality settings. When in doubt: 800px, q80, 15fps, check once, ship.

Animated WebP questions, answered

Does GitHub support animated WebP?

Yes — renders in markdown like any image. Keep files to a few MB for load times and upload sanity.

How much smaller than GIF?

Typically 80–90%: 50MB demo GIF → 3–8MB WebP, sharper (16M colors vs 256).

FFmpeg MP4 to WebP command?

-c:v libwebp -loop 0 -q:v 80 with scale=800:-1,fps=15. Loop flag = infinite like GIF.

MP4 directly in README?

No — markdown images can't play video. MP4 works in issues/PRs/releases; README bodies need animated images.

WebP vs GIF for docs?

WebP everywhere it renders: smaller, sharper, faster loads. GIF only where tooling rejects WebP.

Batch convert demos?

Fixed-recipe FFmpeg loop, or a batch converter with WebP recipe + per-file sizes. Spot-check text-heavy UIs.

Keep learning

Stop using GIF

The full GIF-replacement map — reactions, web, transparency.

WebP vs AVIF

Still images: compression, support, and when each wins.

Convert MKV to MP4

Recordings to shareable files — remux in seconds, zero loss.

Demos that load before the scroll.

Formatif Pro ($8.95 one-time) and Formatif AI ($12.95 one-time) handle video, image, and audio conversion offline — with batch workflows, no file size limits, and a 3-day free trial.

Download free trial Read: stop using GIF

The command above is complete and free forever — pick whichever method fits your demo count.

Written by

Hadi KarakiLinkedIn

Founder of Formatif, a local-first offline media processing suite for Windows and Linux. Hadi writes about video, image, and audio formats, compression, and privacy-first desktop workflows.