👉 Support this work via GitHub Sponsors

macosrec

Take screenshots or videos of macOS windows from the command line (also includes OCR).

See Recording and screenshotting windows: the lazy way.

Note: This gif was captured with macosrec

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

OPTIONS:
  --version               Show version.
  -l, --list              List recordable windows.
  --hidden                Also include hidden windows when listing.
  -x, --screenshot <app name or window id>
                          Take a screenshot.
  -r, --record <app name or window id>
                          Start recording.
  -c, --ocr               Select and recognize text in screen region.
  -b, --clipboard         Save --ocr text to clipboard.
  -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

OCR

Selecting a region

The --ocr flag defaults to selecting a screen region (unless --input) is given.

$ macosrec --ocr

Hello this text was recognized

From existing image

Use the --input flag:

$ macosrec --ocr --input /path/to/image.png

Hello this text was recognized

Save to clipboard

Use the --clipboard flat:

$ macosrec --ocr --input /path/to/image.png --clipboard

Hello this text was recognized

Speech to text

Recognizing text with in speech --speech-to-text is only supported via --input audio file (i.e. .mp3).

$ macosrec --speech-to-text --locale "en-GB" --input path/to/audio.mp3

Hello this text was recognized

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