Reverse Engineering macOS Tahoe's Video Wallpapers

Apple's introduction of cinematic "Aerials" in recent macOS versions has transformed the desktop experience, but the system remains a closed garden. Users cannot natively add their own video files to the system wallpaper picker. Enter Phosphene, an open-source project by developer kageroumado that reverse-engineers the underlying system frameworks to bring custom video wallpapers to macOS Tahoe.

The Core Challenge: WallpaperExtensionKit

Phosphene does not simply overlay a video on the desktop; it integrates directly into the native macOS wallpaper picker in System Settings → Wallpaper. To achieve this, the developer had to dive into WallpaperExtensionKit.framework, a private Apple framework that powers the system's own Aerials.

Because this framework is private, there is no public SDK. Phosphene employs several advanced techniques to communicate with the OS:

• Dynamic Loading: The app uses dlopen to load the private framework at runtime.
• Runtime Introspection: Since the XPC types (the communication protocol between the app and the system) aren't in public headers, Phosphene uses Swift's Mirror reflection to parse and interact with these types.
• Method Swizzling: To prevent the lock screen from turning grey during transitions, the developer had to swizzle the WallpaperSnapshotXPC encoder. The system expects a specific coder type (NSXPCCoder), but the actual coder is a subclass; without this runtime modification, snapshots fail to encode.

System Architecture

Phosphene is split into two primary components that communicate via a shared App Group container:

1. The Menu Bar App (Phosphene.app)

This serves as the management layer. It handles the video library, manages metadata, and performs HEVC optimization. It also includes a VideoOptimizationService that can pre-render lower-resolution or lower-fps variants of a video to save system resources.

2. The Wallpaper Extension (PhospheneExtension.appex)

This is the host for the WallpaperAgent. It runs out-of-process, meaning the wallpaper continues to play even if the main menu bar app is quit. This extension handles the actual rendering into a remote CAContext using AVSampleBufferDisplayLayer.

Engineering for Performance and Battery Life

One of the most significant hurdles in implementing video wallpapers is the impact on battery and thermal performance. Phosphene implements a sophisticated PlaybackPolicy to ensure the wallpaper doesn't drain the laptop's battery or cause thermal throttling.

Power-Aware Playback

The PlaybackPolicy acts as a single source of truth, collapsing various inputs—thermal state, battery level, AC power status, Game Mode, and presentation mode—into four states: full, reduced, minimal, or paused.

Intelligent Occlusion Detection

To save GPU cycles, Phosphene detects when every display is fully covered by windows. When the desktop is no longer visible, the renderer pauses entirely until the desktop is exposed again.

Gapless Looping

Standard AVPlayerLayer often fails inside a remote CAContext. To solve this, the developer implemented a manual decode pipeline. By using one AVAssetReader for the current loop and a preloaded one for the next, and by applying a PTS (Presentation Time Stamp) offset that grows across loops, the engine achieves frame-accurate, glitch-free looping without needing to flush the renderer.

Technical Requirements and Constraints

For those looking to build or install Phosphene, the requirements are strict due to the dependencies on the latest macOS APIs:

• OS: macOS Tahoe (26.0+), as it relies on on Tahoe-specific SwiftUI and glassEffect() APIs.
• Hardware: Apple Silicon (arm64-apple-macos26.0).
• Tooling: Xcode 17+ with Swift 6 strict concurrency enabled.

Conclusion

Phosphene represents a masterclass in reverse engineering private Apple frameworks. While the author originally intended it as a commercial product, the project is now open-source, providing a glimpse into how macOS handles its high-end visual effects and offering users a way to customize their desktops with a level of precision that Apple does not natively allow.