A lightweight macOS wallpaper engine — play MP4, MOV, or GIF files silently behind your desktop icons with near-zero CPU overhead.
| Feature | Details |
|---|---|
| Formats | MP4, MOV, GIF |
| Looping | Seamless, silent, infinite |
| Multi-monitor | One wallpaper window per connected display (currently broken) |
| Window level | Behind desktop icons, below Dock and all windows |
| GIF playback | ImageIO + CVDisplayLink — no conversion needed |
| Fullscreen pause | Pauses automatically when a fullscreen app covers the display |
| Battery Saver pause | Optional — pauses when on battery + Low Power Mode |
| Persistence | Remembers your wallpaper across reboots via UserDefaults |
| Launch at Login | SMAppService (macOS 13+) / LaunchAgent fallback |
| Menu bar only | No Dock icon, clean status bar menu |
| No dependencies | Pure Apple frameworks only |
- macOS 12 Monterey or later
- Xcode 15+ (to build)
- Not sandboxed — direct distribution only
open WallpaperEngine.xcodeprojThen press ⌘R to build and run.
xcodebuild -project WallpaperEngine.xcodeproj \
-scheme WallpaperEngine \
-configuration Release \
buildThe built app will be inside ~/Library/Developer/Xcode/DerivedData/.
┌─────────────────────────────┐ ← All apps / Finder windows
│ Desktop Icons │ ← Finder (kCGDesktopIconWindowLevel)
│ ┌─────────────────────┐ │
│ │ WallpaperWindow │ │ ← kCGDesktopWindowLevel (our layer)
│ │ AVPlayerLayer / │ │
│ │ GIF via CALayer │ │
│ └─────────────────────┘ │
│ macOS Desktop Picture │ ← below us
└─────────────────────────────┘
AppDelegate (menu bar, observers, lifecycle)
└─ WallpaperWindow[] (one per NSScreen)
├─ AVPlayerLayer (MP4/MOV — via AVQueuePlayer + AVPlayerLooper)
└─ GIFAnimation (GIF — ImageIO frames + CVDisplayLink tick)
- AVFoundation — video decode + hardware-accelerated playback
- ImageIO — GIF frame extraction
- CoreVideo —
CVDisplayLinkfor vsync-locked GIF timing - IOKit — power source monitoring
- ServiceManagement — launch-at-login (macOS 13+)
- AppKit / Cocoa — window management
- Click the 📷 icon in the menu bar.
- Select "Choose Wallpaper…" and pick an MP4, MOV, or GIF.
- The wallpaper plays immediately on all connected screens.
- Use Pause / Resume to toggle playback.
- Enable Options → Launch at Login to start automatically.
- Enable Options → Pause on Battery Saver to save power.
The project uses ad-hoc signing (CODE_SIGN_IDENTITY = "-") with no sandbox entitlements. This is intentional for direct distribution. If you have a Developer ID certificate, set your team in Xcode → Signing & Capabilities to notarize for distribution.
- Wallpaper windows respawn when displays are added/removed (existing wallpaper reloads automatically).
- On macOS 12, Launch at Login uses a
LaunchAgentplist in~/Library/LaunchAgents/; on macOS 13+ it usesSMAppService. - Video files larger than ~4 GB should work but haven't been explicitly tested.