All guides
Guide

How to Turn a Screen Recording into a GIF for Your README

Trim to one task, cut idle screen, crop and size the loop, then export a GIF, WebP or MP4 small enough for GitHub — with the FFmpeg commands and when to use each format.

Fastest way

Ask your AI to do it

Paste this into the AI agent you already use:

Help me use a Skill with another agent. Ask which agents and package I use, check supported locations and tools, identify any assumptions to change, and verify the workflow with a small example.

Quick answer

Keep the loop to one task of 5–15 seconds, cut the moments where nothing changes, crop to the part that matters and scale to the width it will be shown at (about 800 px for a README). Export a GIF with a generated palette for README files, and a silent MP4 or animated WebP where the page allows: they are several times smaller and sharper.

The FFmpeg way

palettegen picks the best 256 colors for the clip and paletteuse applies them, which avoids the banding and noise of a fixed palette. stats_mode=diff favors the parts of the screen that change.

ffmpeg -ss 1 -to 9 -i recording.mov -vf "fps=15,scale=800:-2:flags=lanczos,split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=sierra2_4a:diff_mode=rectangle" -loop 0 demo.gif

GIF, WebP or MP4

  • GIF: plays anywhere Markdown images do, including README files; limited to 256 colors and usually the largest.
  • Animated WebP: full color and much smaller; supported by current browsers and GitHub.
  • MP4: the smallest and sharpest; on GitHub, drag it into an issue, pull request or README edit to upload it, and use a muted, looping video tag on your own pages.

Size limits

GitHub accepts uploaded images and GIFs up to 10 MB, and videos up to 10 MB on free plans and 100 MB on paid plans. Files committed to a repository get a warning above 50 MB. Smaller is still better: a README loop under 2–3 MB starts quickly on slow connections.

Do it with an AI agent

LoopCast scans the recording for still stretches, cuts them to a short pause, crops, times short captions so they can be read, closes the loop with a crossfade or boomerang, and renders GIF, WebP and MP4 that fit a size budget, with embed snippets and a preview page.

All guides