Drop a cap on that README GIF.
github caps drag-drop uploads at 10 mb. gifcap binary-searches quality until your gif fits.
- github's 10 mb cap. your screen recording is 240 mb.
- every readme PR review starts with "please compress this."
- compress too much, the gif blurs. compress too little, github rejects it.
gifcap. drag your obs/loom/sharex recording in. set the cap to 10 mb (or 8). gifcap binary-searches quality until every clip fits, ships the gif. one click.
| axis | manual ffmpeg / online tools | gifcap |
|---|---|---|
| hits 10 mb on first try | trial-and-error | always — binary search |
| quality at the cap | often dithered | gifski per-frame palettes |
| workflow | cli flags or upload bar | drag-drop, one click |
| privacy | recording leaves your machine | stays local |
| cost | free | free tier; pro $29 lifetime |
How gifcap solves this — in detail
GitHub caps drag-drop image uploads at 10 mb — that applies to README files, issue bodies, and PR comments equally. GitHub's own community discussion recommends staying under 8 mb, keeping the clip to 20 seconds or less, and 15 fps. for a 1080p screen recording at 30 fps, those numbers are tight. most people solve this with one of three workflows, and all three are worse than they should be: manual ffmpeg trial-and-error (encode, check size, re-encode with lower quality, repeat), an online converter (upload the recording to a third party and hope the output fits), or aggressive downscaling (lose half the detail to hit the cap).
gifcap's size cap handles this with a binary-search loop on gifski's quality setting. you tell it "8 mb," point it at the recording, and it probes quality values between 10 and 100 until the output lands just under the target. the first encode that fits is the one you ship. if the combination of fps, dimensions, and duration makes the target physically impossible at quality 10, gifcap says so and suggests which lever to pull — lower fps, lower scale, or shorter clip — instead of silently shipping a garbage file.
hosting is the other quiet part. READMEs don't need the GIF committed to the repo — it bloats the checkout and the binary delta is useless to git. the cleaner pattern is to drag the GIF into a draft issue or PR comment, let GitHub's CDN assign a stable URL, then paste that URL into the README markdown. GIFs autoplay and loop in READMEs, issues, and PR comments by default; GitHub overlays a pause control on hover. one upload, one URL, one markdown line — the repo stays lean.
GitHub README GIF — the spec
- GitHub drag-drop cap: 10 mb per image upload (GIFs included). Files above this are rejected.
- GitHub recommended size: under 8 mb to leave headroom for page rendering and mobile.
- GitHub recommended duration: 20 seconds or shorter — loops carry the rest.
- GitHub recommended fps: 15 fps — double it only if the content needs smooth motion.
- Hosting pattern: upload via draft issue/PR comment, copy the assigned CDN URL, paste into README markdown.
- Autoplay: yes, on by default in READMEs, issues, and PR comments — user can pause on hover.
- gifcap suggested preset: size cap 8 mb, fps 15, dimensions scaled to content width.