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.gifGIF, 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.