I reverse engineered Apple's video wallpapers

Phosphene

A video wallpaper engine for macOS Tahoe.

Phosphene is a menu bar app + wallpaper extension that plays your own video files as the macOS desktop and lock-screen wallpaper. It plugs into the system's native wallpaper picker, so videos appear alongside Apple's built-in Aerials in System Settings → Wallpaper.

It is built on top of Apple's private WallpaperExtensionKit framework — the same one Apple's own Aerials use — which means playback runs out-of-process, survives app quits, and integrates with the OS-level lock-screen / idle / sleep lifecycle.

⚠️ Private framework. Phosphene loads WallpaperExtensionKit via dlopen and uses Mirror-based runtime introspection to talk to its XPC types. Apple could change this at any major OS release. The project tracks macOS 26 (Tahoe).

Features

• Bring your own videos. Import MP4 / MOV / any AVFoundation-readable file. They show up in the system wallpaper picker.
• Gapless looping. Frame-accurate loops by offsetting PTS/DTS across loop boundaries — no flush, no stutter.
• Multi-display + per-Space selections. Different wallpapers per display, persisted by macOS.
• Power-aware playback. A graduated PlaybackPolicy reduces work or pauses entirely based on thermal state, battery level, on-battery vs AC, Game Mode, and presentation mode (active / locked / idle).
• Smooth lock-screen ramp. When Only on Lock Screen is enabled, the wallpaper eases in/out with a cubic curve as you lock and unlock, matching Apple's own Aerials behavior.
• Pause when occluded. Detects when every display is fully covered by windows and pauses rendering until the desktop is visible again.
• Adaptive variants. Optionally pre-render lower-resolution / lower-fps variants of a video; the renderer swaps to the cheapest variant that satisfies the current policy at each loop boundary.
• Menu bar control. Preview the current wallpaper, toggle pause, switch displays, configure behavior, launch at login.

Requirements

• macOS Tahoe (26.0+). Phosphene depends on the Wallpaper extension point introduced in macOS 14 but uses Tahoe-only SwiftUI and glassEffect() APIs.
• Apple Silicon. Targets arm64-apple-macos26.0.
• Xcode 17+ to build, with Swift 6 strict concurrency enabled.

Building

git clone https://github.com/<you>/phosphene cd phosphene open Phosphene.xcodeproj

In Xcode, select the Phosphene scheme and Run. The project uses synchronized filesystem groups, so adding/removing files in Phosphene/ or PhospheneExtension/ requires no pbxproj edits.

You'll need to set a development team for code signing. The wallpaper extension is embedded into the app bundle and registered with the system when the app launches.

Using a video wallpaper

1. Launch Phosphene. Use the menu bar icon to Manage Library and add one or more videos.
2. Open System Settings → Wallpaper. Phosphene's videos appear under their own collection.
3. Pick a video. macOS handles the actual wallpaper assignment — Phosphene's extension provides the frames.

Architecture

┌─────────────────────────┐ ┌──────────────────────────────┐ │ Phosphene.app │ │ PhospheneExtension.appex │ │ (menu bar UI) │ │ (host: WallpaperAgent) │ │ │ │ │ │ • Library management │ Darwin │ • XPC handler │ │ • Per-video metadata │ ──────▶ │ • AVSampleBufferDisplayLayer │ │ • Optimization (HEVC) │ notif. │ • Power / thermal monitor │ │ • Preferences │ │ • Snapshot generator │ └─────────────────────────┘ └──────────────────────────────┘ │ │ └──────────────┬───────────────┘ ▼ Shared App Group container (~/Library/Group Containers/glass.kagerou.phosphene) • Video library + variants • WallpaperPrefs.plist • BMP snapshot cache

App side (Phosphene/) — SwiftUI menu-bar app. Manages the on-disk video library, transcodes optional lower-resolution variants via VideoOptimizationService, exposes preferences, and posts a Darwin notification when the library changes.

Extension side (PhospheneExtension/) — runs inside the system WallpaperAgent process when a Phosphene wallpaper is active. Loads WallpaperExtensionKit.framework at runtime, registers as a wallpaper provider, and renders frames into a remote CAContext via AVSampleBufferDisplayLayer. It receives XPC acquire / update / invalidate / snapshot calls from WallpaperAgent and routes presentation-mode changes through PlaybackPolicy.

PlaybackPolicy is the single source of truth for playback behavior. Inputs (thermal state, battery, presentation mode, user pause, occlusion, etc.) collapse to one of full / reduced / minimal / paused. The renderer applies the policy on every state change.

VideoRenderer owns the decode pipeline. Instead of AVPlayerLayer — which silently fails inside a remote CAContext — it drives AVSampleBufferDisplayLayer manually: one AVAssetReader for the current loop, a preloaded one for the next, and a PTS offset that grows across loops to keep the timeline monotonically increasing. Result is glitch-free looping without flushing the renderer.

Quirks worth knowing

• WallpaperSnapshotXPC swizzle. The system's snapshot encoder checks type(of: coder) == NSXPCCoder.self, but the real coder is a subclass. Without the runtime swizzle in PhospheneExtension.swift, snapshots silently encode to nothing and you get a grey lock screen during transitions.
• Mirror-based XPC parsing. Apple's request types (WallpaperCreationRequestXPC etc.) aren't part of any public SDK header. The extension reads them via Mirror reflection. If Apple renames fields, expect surgical breakage.
• Variants are advisory. A "1080p@30" variant won't be selected if Power-Monitor thinks we're on AC and idle — PlaybackPolicy always picks the highest tier that's still allowed.

License

MIT. Do whatever you want, no warranty.

Acknowledgements

Built by @kageroumado. Phosphene was originally a commercial project; it's open-source now because the market for "video wallpaper apps on macOS" turned out to be more crowded than it looked.