How to convert a screen recording to a developer-docs gif
- Step 1Crop to the relevant pane — Don't waste GIF pixels on toolbars and tabs. Crop to just the editor pane, terminal, or dashboard widget with the cropper first — a tighter crop means a smaller, sharper GIF at the same width.
- Step 2Trim to the action being documented — Cut to the exact steps with the lossless trimmer (instant keyframe stream-copy). A doc GIF should show one workflow, not the whole session — shorter clips make smaller GIFs.
- Step 3Drop the cropped, trimmed clip onto the converter — Accepts
.mp4,.mov,.mkv,.webm, and the other common containers. It loads into FFmpeg.wasm in your browser — nothing uploads, so the on-screen tokens and internal UI stay private. - Step 4Set width for legible code/UI in the doc — For text-heavy captures, keep width close to half the capture width (e.g. 720 px from a 1440 capture) so glyphs stay sharp. README columns are narrow, so 600–760 px is usually right. Wider = bigger file.
- Step 5Set FPS for the interaction type — 10–12 FPS reads fine for clicking through UI; 15 for cursor-heavy demos. Code that scrolls smoothly benefits from 15–20. Lower FPS = smaller GIF, which keeps the README fast to load.
- Step 6Convert and embed in the doc — Download the
.gifand drop it into the README, JIRA comment, or Notion page — all autoplay and loop it inline. If load time matters more than format compatibility, also consider animated WebP for web docs.
Doc platform GIF support
Where developer-docs GIFs autoplay. GIF is the safe default for inline demos across these tools.
| Platform | GIF inline autoplay | Note |
|---|---|---|
| GitHub README / issues | Yes | Loops inline in Markdown; the canonical demo format |
| JIRA tickets | Yes | Renders attached GIFs inline in descriptions/comments |
| Notion | Yes | Embeds and loops GIFs in-page |
| Web docs (own site) | Yes | Consider WebP for faster page loads |
Settings for legible doc GIFs
Width/FPS combos tuned for text-heavy screen recordings, using the tool's two controls.
| Capture | GIF width | FPS | Why |
|---|---|---|---|
| 1440p code editor | 720 | 12 | Half-width keeps code glyphs sharp; clicking reads at 12 |
| 1080p dashboard | 600 | 12 | Charts stay clear; smaller file for fast README load |
| Cursor-heavy UI walkthrough | 640 | 15 | Smoother pointer motion |
| Smooth scroll demo | 640 | 20 | Higher FPS for scroll fluidity; larger file |
Pre-GIF cleanup tools
Run these before converting so the GIF spends its budget on what the doc needs to show.
| Need | Tool | Effect on the GIF |
|---|---|---|
| Show only one pane | video-cropper | Smaller, sharper — pixels go to the relevant region |
| Show one workflow | lossless-trimmer | Fewer frames, smaller file |
| Fast-forward a long step | video-speed-controller | Fewer frames at same coverage |
| Pull a single hero frame | thumbnail-extractor | Still image instead of GIF when motion isn't needed |
Cookbook
Recipes for crisp, fast-loading developer-docs GIFs. Crop and trim first, then convert with the two-pass palette at a doc-appropriate width.
Feature demo for a GitHub README
A 1440p capture of a new CLI flag. Crop to the terminal, trim to the command, convert at half-width so the monospace text stays sharp.
Step 1: video-cropper -> terminal_only.mp4
Step 2: lossless-trimmer -> demo_5s.mp4
Step 3: video-to-gif: Width 720, FPS 12
scale=720:-1:flags=lanczos -> sharp mono text
-> demo.gif (drops into README.md inline)Bug repro for a JIRA ticket
Show the failing UI interaction. Crop to the relevant pane so the GIF is small enough to attach and clear enough to act on.
Step 1: video-cropper -> form_pane.mp4 Step 2: lossless-trimmer -> repro_4s.mp4 Step 3: video-to-gif: Width 600, FPS 12 -> repro.gif Attach to the JIRA ticket -> autoplays inline; the on-screen data never touched a GIF host.
Fast-forward a long install for Notion docs
A 40-second install is too long for a doc GIF. Speed it up 2x first, then convert a snappy version.
Step 1: video-speed-controller (2x) -> install_2x.mp4 Step 2: video-to-gif: Width 640, FPS 12 -> install.gif Half the frames -> smaller GIF; still reads as a fast-forward of the full install in the Notion page.
Code-scroll demo that needs smooth motion
Scrolling code looks choppy at 12 FPS. Raise FPS for fluid scroll, keep width high for glyph clarity.
video-to-gif: Width 720, FPS 20 scale=720:-1:flags=lanczos -> sharp code Higher FPS smooths the scroll; file is larger but the code stays readable frame to frame.
Hero still instead of a GIF
When the doc just needs one screenshot, skip the GIF entirely and pull a frame.
If no motion is needed: thumbnail-extractor -> hero.png A still PNG is far smaller and sharper than a GIF for a single-state UI screenshot in a README.
Edge cases and what actually happens
Code/UI text is unreadable in the GIF
Width too lowMonospace and small UI fonts need pixels. Shrinking a 1440p capture to 360 px destroys legibility. Keep the GIF width near half the capture width (720 from 1440), and crop to the relevant pane first with the cropper so the text occupies more of the frame.
GIF too large to load fast in a README
Size thresholdLarge doc GIFs slow page loads and can hit attachment limits. Lower FPS to 10–12, crop tighter, and trim shorter. For your own web docs, animated WebP is ~30% of the GIF size at the same clarity — worth it where compatibility allows.
Syntax-highlight colours banded
MitigatedSingle-pass converters band the many subtle colours of a highlighted theme. JAD's two-pass palette (stats_mode=diff) samples those actual colours, so themes render cleanly. If banding persists, the capture likely has heavy gradient backgrounds — crop them out or accept a slightly larger palette workload.
On-screen tokens/secrets in the recording
Stays localThe conversion runs entirely in-browser via FFmpeg.wasm, so a recording showing API tokens or internal UI never uploads. Still, redact secrets in the frame before sharing the GIF — use the redactor to blur a region before converting if the secret is visible.
Converted the whole recording session
By designThis tool converts the entire clip — no in-tool trim. A full session becomes a giant GIF. Trim to the documented action with the lossless trimmer, or speed up long steps with the speed controller first.
Screen-capture tool's codec won't decode
Decode errorMost captures are standard MP4/WebM and decode fine. Some recorders emit unusual codecs that FFmpeg.wasm can't handle, failing the palette pass. Re-encode to standard H.264 MP4 with the transcoder, then convert.
High-DPI capture soft after shrinking
ExpectedA Retina capture at a small width loses detail; Lanczos minimises softening but can't restore resolution. Crop to the region you're documenting so you can use a smaller crop at a larger effective resolution, keeping text crisp.
Cursor jumps between frames at low FPS
ExpectedAt 10–12 FPS a fast cursor can appear to teleport. For cursor-driven walkthroughs raise FPS to 15–20 so pointer motion reads smoothly. The trade-off is a larger file — there's no cursor interpolation in the tool.
Frequently asked questions
How do I keep code and UI text sharp in the GIF?
Two things: keep the GIF width near half the capture width (e.g. 720 px from a 1440p recording) so glyphs have pixels, and crop to the relevant pane first with the cropper so the text fills more of the frame. The Lanczos scaler and two-pass palette do the rest — they're tuned for exactly this.
Will a screen-recording GIF autoplay in a GitHub README?
Yes. GitHub renders GIFs inline in Markdown and autoplays/loops them in READMEs, issues, and PRs. The same is true for JIRA tickets and Notion pages. GIF is the de-facto format for inline 'here's the feature working' demos in developer docs.
Is my screen recording uploaded anywhere?
No. The conversion runs in your browser via FFmpeg.wasm — your recording is read and processed locally and the GIF downloads locally. That's important for captures showing internal tooling, API tokens, or unreleased UI: nothing touches a GIF host or any server.
How do I shrink a doc GIF without making it unreadable?
Lower FPS first (10–12 is fine for click-through demos), then crop to the relevant pane rather than shrinking the width on text-heavy captures. Trim to a single workflow. The two-pass palette keeps quality high even at small sizes, so the limiting factor is usually width versus text legibility.
Can I redact a token or secret visible on screen?
Yes, but in a separate step. The GIF tool can't blur. Use the redactor to blur the region containing the secret before converting, then make the GIF from the redacted clip. The conversion itself stays local, but redact before sharing.
What FPS should a doc GIF use?
10–12 FPS for clicking through UI (smallest file), 15 for cursor-heavy demos, and 15–20 for smooth code-scrolling. Lower FPS keeps the README fast to load. FPS doesn't affect text sharpness — that's width — so you can keep FPS low for size and width high for legibility.
Should I use GIF or WebP for developer docs?
GIF for GitHub, JIRA, and Notion (universal inline autoplay). For your own web documentation, animated WebP loads faster at ~30% of the GIF file size with the same clarity — use it where you control the rendering and know WebP is supported.
What if I only need one screenshot, not motion?
Skip the GIF and pull a still frame with the thumbnail extractor. A PNG is far smaller and sharper than a GIF for a single-state UI screenshot. Use the GIF only when the doc genuinely needs to show motion or a sequence.
What input formats does it accept?
MP4, MOV, MKV, WebM, AVI, M4V, and TS — decoded in-browser by FFmpeg.wasm. If your screen recorder emits an unusual codec that won't decode, re-encode to standard H.264 MP4 with the transcoder first.
Can I crop out the toolbars before converting?
Yes — and you should. The GIF tool can't crop, so use the cropper to isolate the editor pane, terminal, or dashboard widget first. A tighter crop produces a smaller, sharper GIF because the pixel budget goes to the part the doc is documenting.
How long can the source recording be?
Free tier allows a single source up to 1 GB; Pro is 10 GB and 5 files, Pro-media 100 GB and 50 files, Developer 100 GB unlimited. There's no duration cap. You can drop a long raw session and trim/crop it down locally before converting.
Why two passes for a screen recording?
Screen recordings are full of subtle UI colours and syntax-highlight tones that a single generic 256-colour palette would band badly. Pass one builds a palette from your recording's actual colours (stats_mode=diff), and pass two maps frames onto it — which is what keeps code and charts clean in the GIF.
Privacy first
Every JAD Video tool runs entirely in your browser via WebCodecs and FFmpeg (WebAssembly). Your video files never leave your device — verified by zero outbound network requests during processing.