macosrec

Take screenshots or videos of macOS windows from the command line.

See Recording and screenshotting windows: the lazy way.

Note: This gif was captured with macosrec

$ macosrec
USAGE: record-command [--list] [--screenshot <app name or window id>] [--record <app name or window id>] [--mov] [--gif] [--save] [--abort] [--output <optional output file path>]

OPTIONS:
  -l, --list              List recordable windows.
  -x, --screenshot <app name or window id>
                          Take a screenshot.
  -r, --record <app name or window id>
                          Start recording.
  -m, --mov               Record as mov.
  -g, --gif               Record as gif.
  -s, --save              Save active recording.
  -a, --abort             Abort active recording.
  -o, --output <optional output file path>
  -h, --help              Show help information.

Install

Homebrew

brew tap xenodium/macosrec
brew install macosrec

Build

swift build

Screenshot

Before taking a screenshot, identify the window number using --list.

$ macosrec --list

21902 Emacs
22024 Dock - Desktop Picture - Stone.png
22035 Firefox - Planet Emacslife

Use --screenshot + window number to take a screenshot.

~ $ macosrec --screenshot 21902
~/Desktop/2023-04-14-08:21:45-Emacs.png

Videos

Before taking a video, identify the window number using --list.

$ macosrec --list

21902 Emacs
22024 Dock - Desktop Picture - Stone.png
22035 Firefox - Planet Emacslife

Use --record + window number to start recording a video (gif).

Note: you can also use application name and it will use the first window it finds belonging to it.

To end recording, send a SIGINT signal (Ctrl+C from terminal). Alternatively, running macosrec --save from another session would also end the recording.

~ $ macosrec --record 21902 --gif
Saving...
~/Desktop/2023-04-14-08:21:45-Emacs.gif

Note: you can also use application name and it will use the first window it finds belonging to it.

~ $ macosrec --record emacs --mov
Saving...
~/Desktop/2023-04-14-08:21:45-Emacs.mov

Optimizing gif

The gifs can get pretty large fairly quickly depending on the lenght of the recording. Consider using something like gifsicle to reduce size. For example:

gifsicle -O3 large.gif --lossy=80 -o smaller.gif

Disclaimer

I built this util to record demos I post at xenodium.com. Does the job so far, but can likely take improvements, specially around image handling efficiency. PRs totally welcome.

Resizing windows while recording (not supported)

While a video will be recorded if you resize the window during the recording session, it’s unlikely to produce a file with the expected outcome. This feature is currently unsupported and out of scope. Having said that, if anyone’s keen to implement it, a PR is totally welcome.

👉 Support this work via GitHub Sponsors

xenodium / macosrec