Native video wallpapers for macOS Tahoe.
Import any video. It shows up in System Settings — just like Apple's own aerials.
AerialWall transcodes your video into the exact HEVC format macOS expects, injects it into the wallpaper manifest, and adds it as a native AerialWall category in System Settings → Wallpaper. No overlays. No fake windows. No custom renderers — your wallpaper plays through the same WallpaperAerialsExtension that Apple's own aerials use.
- Native integration — appears in System Settings → Wallpaper alongside Apple's landscapes
- Lock screen + desktop — works on both, survives lock/unlock cycle
- Tahoe-native — built around macOS 26's JSON manifest architecture (
entries.json) - Hardware-accelerated — VideoToolbox HEVC with 2-layer temporal hierarchy (required by
WallpaperAerialsExtension) - Non-destructive — full backup of
entries.jsonbefore every change, atomic writes throughout - Open source — AGPL-3.0, no telemetry, no subscription
- macOS 26 (Tahoe) ≥ 26.4
- Non-sandboxed — needs access to
~/Library/Application Support/com.apple.wallpaper
brew tap CatKinKitKat/aerialwall
brew install --cask aerialwallThe cask strips Gatekeeper's quarantine attribute after install, so the app opens without the "unidentified developer" warning. AerialWall is not notarized — paying Apple US$99/yr just to skip one dialog isn't on the table.
Download AerialWall-*.zip from the
releases page,
unzip, drag AerialWall.app to /Applications, then right-click → Open
once to dismiss Gatekeeper. After that it launches normally.
git clone https://github.com/CatKinKitKat/AerialWall
cd AerialWall
./scripts/build-app.sh # produces build/AerialWall.app
open build/AerialWall.appOr run without bundling:
swift run AerialWall| Format | Notes |
|---|---|
.mp4, .mov, .m4v |
Direct import |
.webm, .mkv, .avi |
Convert to .mp4 first (HandBrake) |
- You pick a video in the import sheet (name + description)
- AerialWall transcodes it to HEVC Main 10 with the right 2-layer temporal structure
- The result lands in
~/Library/Application Support/com.apple.wallpaper/aerials/ - Your video appears in the AerialWall category in System Settings → Wallpaper
- A persistence watcher re-injects entries if macOS ever resets the manifest
See SPEC.md for the full reverse-engineering notes and invariants.
See CONTRIBUTING.md for the branch model and spec-driven development workflow.
