Animated Wallpaper

A native macOS menu-bar app that plays a video as your desktop wallpaper and on your lock screen, without Electron, Homebrew, or any dependencies. Single 500 KB binary built from a shell script — no Xcode project.

Features

• Desktop video wallpaper — one video, one decode pipeline, mirrored to every display.
• Lock-screen video — swaps Apple's Aerial asset (HEVC, ≤1080p, ≤30 fps) and keeps a backup for one-click restore.
• FPS cap — transcode once to a lower frame rate to cut GPU load.
• Battery-aware — pause below a chosen charge level, or dynamically drop FPS in 4 quantized steps (Dynamic on battery).
• Pause rules — paused automatically on lock, display sleep, battery threshold, or a fullscreen app.
• Start at login, menu-bar control, settings window, and a --selftest covering the pure logic.

Efficiency

Measured on an Apple M4, macOS 15.8.1, playing a 1920×1080 30 fps H.264 file:

Metric	Result
App binary	499 KB (510,736 bytes)
Peak memory (RSS)	~35 MB
CPU while playing 1080p30	~4 % of one core (0.15 s CPU / 3.78 s wall)
Playback responsiveness	first frame in <0.1 s; 1.98 s of video decoded in 2.00 s
Clean build	4.7 s (./build.sh, includes self-test)
Source	1,358 lines across 3 files
External dependencies	0 (system frameworks only)

Decoding runs on the hardware video engine via AVFoundation, and compositing is left to the GPU/WindowServer, which is why the process itself stays at ~4 % CPU. The measurement excludes that out-of-process compositing and is a fair picture of the app's own footprint. Methodology: --probe a test clip while sampling with top/time -l.

Build

Requires macOS 14+ and Xcode command-line tools (swiftc, Swift 6.1 tested).

./build.sh            # builds build/AnimatedWallpaper.app and runs the self-test
open build/AnimatedWallpaper.app

Usage

1. Launch the app — it lives in the menu bar (no Dock icon).
2. Pick a video with Choose Video.
3. Optionally cap FPS, set Pause rules, or enable Start at login.
4. Set Lock Screen replaces the current Aerial; Restore puts Apple's back.

The first lock-screen write on macOS 14–15 may ask for admin once (to take ownership of Apple's Aerial folder); macOS 26 needs no permission.

Command-line flags

Flag	Purpose
--selftest	Assert-based checks for FPS math, fullscreen detection, plist handling.
--status	Print lock-screen state and Aerial folder, then exit.
--probe <video> [--no-waits]	Play a video headlessly and report playback progress.

How it works

A single AVQueuePlayer + AVPlayerLooper feeds one borderless, click-through NSWindow per screen, placed just below the desktop icons. A 5-second timer and system notifications (lock/unlock, display sleep, screen changes) drive one pause policy, so there is no polling and no second player. The same player backs the settings preview, so the preview costs no extra decode.

---

© 2026 mikyss