Custom Mac screensavers,
in plain language

What is macpaper?

macpaper is a free command-line tool for Mac. You point it at a folder of videos. It registers those videos so they show up in System Settings → Screen Saver (and Wallpaper) like Apple’s own Aerials.

It does not keep a special app running on top of your desktop. macOS plays the videos itself.

What you need

• macOS 26 (Tahoe) or newer
• Homebrew installed
• A folder of videos (mp4, mov, etc.)
• At least one built-in Aerial downloaded in System Settings → Wallpaper / Screen Saver (this creates Apple’s catalog file the first time)

On first encode, macpaper may ask macOS to install Xcode Command Line Tools — click Install if prompted.

Install

Easiest: paste this in Terminal and press Return.

curl -fsSL https://raw.githubusercontent.com/anantdark/macpaper/refs/heads/main/scripts/install.sh | bash

Or with Homebrew directly:

brew tap anantdark/macpaper
brew trust anantdark/macpaper
brew install macpaper
macpaper version

You should see something like macpaper 1.4.6 (or newer).

Make your first screensaver

1. Create a folder, e.g. ~/Movies/MyClips, and put videos in it.
2. Register it:

macpaper register ~/Movies/MyClips --name "My Clips"

3. When asked to save copies under ./transcoded/, answer y if you want unregister → register later without re-encoding.
4. Wait while new clips encode (a few minutes each on first run; already-ready files are skipped).
5. Quit System Settings if it was open, then reopen it.
6. Go to Screen Saver → find My Clips → choose a video.

Tip: run macpaper with no arguments for an interactive menu.

Everyday commands

Encoding & caching

Clips are encoded to HEVC with temporal layers (VideoToolbox on Apple silicon) so stop-screensaver → freeze-as-wallpaper works. Encode is once-through by default — short clips are not padded to ~5 minutes unless you ask.

• Re-run register — keeps finished aerial encodes; only new or changed sources encode.
• Interrupted batch — run register again; completed clips are kept, the rest continue.
• transcoded/ — optional local .mov copies. Unregister removes Settings entries but keeps these files; the next register reuses them.
• --force-transcode — ignore caches and encode everything again.

macpaper register ~/Movies/MyClips --save-transcoded

Register options

Check a file & re-encode

Not sure if a clip is ready for the native freeze-as-wallpaper effect?

macpaper check ~/Movies/MyClips/sunset.mp4

• ready — screensaver + freeze both OK
• screensaver only — plays, but freeze needs a temporal re-encode
• needs encode — register will encode it

To force-fix everything in a folder (e.g. after upgrading macpaper):

macpaper register ~/Movies/MyClips --force-transcode

Remove clips safely

unregister never deletes your original files in Movies / Downloads. It removes Settings listings and aerial-cache copies under Apple’s folder. Files in <folder>/transcoded/ are kept so a later register can reuse them.

macpaper list
macpaper unregister sunset.mp4 --yes
macpaper unregister ~/Movies/MyClips --yes

Troubleshooting

I don’t see my category in Settings

Quit System Settings completely, run macpaper refresh, reopen Settings. Confirm with macpaper list.

Screensaver works but unlock goes black / no freeze

Re-encode with temporal layers: macpaper register ~/Movies/MyClips --force-transcode.

Register is re-encoding a clip I thought was done

Reuse needs either a good aerial cache or a ready file in transcoded/. Clips never saved there must encode once. Preview with --dry-run.

I stopped midway through a batch

Run register again on the same folder. Finished encodes are kept; the rest continue.

Install says tap isn’t trusted

Run brew trust anantdark/macpaper, then install again.

Encode fails / asks for developer tools

Install Xcode Command Line Tools: xcode-select --install. Use macpaper 1.4.5+ if you hit AVAssetWriter -16364 on 23.976 fps sources.

“Aerial manifest not found”

In System Settings, download any built-in Aerial once so macOS creates entries.json.

Uninstall

macpaper unregister ~/Movies/MyClips --yes
brew uninstall macpaper
brew untap anantdark/macpaper
rm -rf ~/Library/Application\ Support/macpaper