Typebar
Download Buy $9

Make a GIF with keystrokes for a bug report or README on a Mac

· 6 min read

To make a GIF that shows the keys you press, put your keys on screen with a key display, record just the area that matters with Command-Shift-5 (⇧⌘5), trim the clip in QuickTime Player, and convert it with a free tool such as ffmpeg or Gifski. QuickTime Player and the Screenshot toolbar only save movies, so the last step needs one of those. Keep the clip to one action, around ten seconds, and record a small area so the keys are still readable once the GIF is scaled down.

Why the keys belong in the GIF

A GIF in a bug report shows what happened, but not what you did to make it happen. The steps to reproduce are in the text, yet the GIF is what people actually watch, and a palette that opens out of nowhere, or a line that vanishes, leaves them guessing whether you pressed a shortcut, clicked something, or hit a bug. With the keys in the frame, the cause and the effect sit side by side.

In a README the job is different but the problem is the same. If the feature you are showing off is a shortcut, the GIF should show that shortcut being pressed, not only the result.

Set up the keys for a small frame

GIFs end up narrow: a README shows them in a column, and a bug report shows them inside a comment. That changes how you set up the keys.

  • Use a compact display. A keystroke pill takes far less room than a whole on-screen keyboard. In Typebar, choose Show > Pill Only from the menu bar icon.
  • Make it big for the area you record. Whatever you record gets shrunk later, so size the keys against the window you are capturing, not the whole screen.
  • Put it inside the area you record, near the action. Drag it by its handle. A key display that is outside the box you record does not appear in the clip.
  • Decide what to show. Show only shortcuts if the typing is noise, or everything, including Return and Tab, if the bug is in the typing.

Typebar’s pill also names each shortcut with the name it has in the app’s own menus, such as “⇧⌘4 Screenshot Selection”, so a reader can find the same command without knowing the keys. Clicks can show in the pill as Click, Right Click or ⌘ Click, and as ripples around the pointer. If you only need clicks, the Screenshot toolbar can do it on its own: Options > Show Mouse Clicks.

Record only what matters

  1. Press Command-Shift-5 to open the Screenshot toolbar.
  2. Click Record Selected Portion and drag the box around the window or panel with the bug, with the pill inside it.
  3. Open Options if you want Show Mouse Clicks, or to change where the recording is saved.
  4. Click Record and do the action once, deliberately. Leave a second of stillness at the start and at the end, so the loop has a clear beginning.
  5. Stop with the Stop button in the menu bar, or press Command-Control-Escape.

Rehearse it once before you record, and turn on a Focus such as Do Not Disturb from Control Center so a notification does not land in the middle of the clip.

On a Retina display, the area you select records at twice its size in pixels. A box that looks 700 by 450 on screen becomes a 1400 by 900 pixel movie, which is useful to know when you pick the GIF’s size below.

Trim it in QuickTime Player

Open the recording in QuickTime Player, choose Edit > Trim (Command-T), drag the yellow handles to the first and last moments you need, and click Trim. Save the result with File > Save.

The default file name is long and full of spaces. Rename it to something like demo.mov before the next step, so the command is easy to type.

Convert it with ffmpeg

ffmpeg is free and makes good GIFs, but it runs in Terminal. If you use Homebrew, install it with brew install ffmpeg. Then, in the folder with your clip:

ffmpeg -i demo.mov -vf "fps=12,scale=iw/2:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" -loop 0 demo.gif

What each part does:

  • fps=12 keeps twelve frames a second, which is plenty for keys and menus and keeps the file down. Go to 10 if it is still large.
  • scale=iw/2:-1 halves the width, which brings a Retina recording back to the size it looked on screen. For a fixed width, use scale=800:-1 instead.
  • palettegen and paletteuse build a palette from your clip. A GIF can only hold 256 colors in a frame, and a palette made from your own footage keeps text and keycaps clean instead of speckled.
  • -loop 0 makes it loop forever.

To trim in the same step, put a start time and a length before the input, for example -ss 1.5 -t 8 to skip the first second and a half and keep eight seconds.

Or use Gifski

If you would rather not use Terminal, Gifski is a free, open-source app in the Mac App Store that does the same conversion with a window. Drop the trimmed clip on it, choose the size, frame rate and quality, and save the GIF. Use the same choices as above: about half the recorded width for a Retina recording and a low frame rate.

Keep the GIF small enough to post

GIFs get big fast, because every frame is a full picture with a limited palette. Four things keep them down:

  • One action per GIF. If a bug takes three steps, three short GIFs or one video beat a single long GIF.
  • A narrow frame. Record the window, not the screen.
  • A low frame rate. 10 to 12 frames a second for interface work.
  • A still background. Areas that do not change compress well; a scrolling page or a moving wallpaper does not.

If it is still too big, consider a video instead. GitHub issues and pull requests accept MP4 and MOV files, and a short video is sharper and far smaller than a GIF of the same clip. For a README, a GIF is still the safe choice, because it plays anywhere Markdown shows images. To control how wide it shows, use an HTML tag instead of Markdown’s image syntax, such as <img src="docs/demo.gif" width="640">.

Keep secrets out of a public GIF

A GIF in a public repository is public forever, and every frame is in it. Before you record:

  • Typebar shows nothing typed in a field macOS marks as secure, and the pill says “Typing hidden in a password field”.
  • Hide letters, in Typebar’s Privacy settings, shows shortcuts and special keys but turns letters into dots, which suits a clip where you type a token or a real address.
  • Hide typing in these apps covers 1Password, Bitwarden, Keychain Access and Passwords, and you can add your own.

Hide what you type but keep shortcuts visible goes into these settings, and showing keys without leaking a password covers the rest of what a recording can give away.

Questions

Can QuickTime Player save a GIF?

No. QuickTime Player and the Screenshot toolbar save movies. Convert the movie with ffmpeg or Gifski.

Why are the keys blurry in my GIF?

Usually because the GIF was scaled down too far. Record a smaller area with bigger keys, so less scaling is needed, and use a palette as in the ffmpeg command above.

Which is better for a bug report, a GIF or a video?

Where video uploads work, such as GitHub issues, a short video is sharper and smaller. A GIF is better where it needs to play inline without a click, as in a README. For more on recording with the Screenshot toolbar, see showing keys in a Command-Shift-5 recording.

Typebar is $9 once for up to 5 Macs, with a free 24-hour trial.