Building Native Video Wallpapers for macOS Tahoe with Phosphene

For years, macOS users have relied on third-party apps that overlay windows or hack the desktop environment to display video wallpapers. These solutions are often resource-heavy, battery-draining, and prone to flickering. Enter Phosphene, an open-source engine for macOS Tahoe that takes a radically different approach: it integrates directly into the system's native wallpaper picker.

The "Native" Advantage

Phosphene isn't just another overlay app. It is built on top of Apple's private WallpaperExtensionKit framework—the same technology powering Apple’s own "Aerial" screensavers. By hooking into this system-level extension point, Phosphene allows your custom videos to appear directly within System Settings → Wallpaper alongside native options.

Because the rendering happens out-of-process within the system's WallpaperAgent, the wallpaper persists even if the main Phosphene app is quit. It respects the OS-level lock-screen, idle, and sleep lifecycles, providing a level of stability that traditional overlay apps simply cannot match.

Under the Hood: Architecture and Engineering

Phosphene splits its workload into two distinct components:

Phosphene.app (Menu Bar UI): Handles library management, metadata, and transcoding. It uses a VideoOptimizationService to generate lower-resolution or lower-fps variants of your videos, ensuring the system can swap to lighter assets when battery is low or thermal pressure is high.
PhospheneExtension.appex (The Engine): This is the heavy lifter. It runs within the WallpaperAgent process, using AVSampleBufferDisplayLayer to render frames.

Solving the "Gapless Loop" Problem

One of the most impressive technical feats in Phosphene is its approach to looping. Standard AVPlayerLayer implementations often cause a micro-stutter or a "flash" when restarting a video. Phosphene avoids this by manually driving the decoding pipeline. It maintains an AVAssetReader for the current loop while preloading the next, using a monotonically increasing Presentation Time Stamp (PTS) offset across loop boundaries. This results in perfectly seamless, frame-accurate loops.

Power-Aware Playback

Phosphene doesn't just play video; it manages it based on the system state. Its PlaybackPolicy acts as the single source of truth, collapsing inputs like:

Battery level vs. AC power
Thermal state
Game Mode status
Window occlusion (pausing rendering if the desktop is fully covered)

This logic ensures that your wallpaper doesn't become a performance bottleneck during intensive tasks.

A Note on Private Frameworks

It is important to note that Phosphene uses dlopen to load WallpaperExtensionKit and relies on Mirror-based runtime introspection to communicate with XPC types. Because these are private APIs, the project is inherently tied to the internal structures of macOS Tahoe. The developer has implemented clever workarounds, such as a WallpaperSnapshotXPC swizzle, to ensure the lock screen doesn't turn grey during transitions—a common issue when Apple's private encoders expect specific class types.

Getting Started

If you are a developer interested in how this works, you can build it from source. The project requires Xcode 17+ and Swift 6 strict concurrency.

git clone https://github.com/kageroumado/phosphene.git
cd phosphene
open Phosphene.xcodeproj

For a headless build (useful for CI or local testing without signing identities), you can use:

xcodebuild -project Phosphene.xcodeproj -scheme Phosphene -configuration Debug \
-destination 'generic/platform=macOS' \
CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY='' build

Phosphene is a masterclass in reverse-engineering system-level integration. Whether you want to use it to customize your desktop or study how to interface with private macOS frameworks, it is a project worth exploring.

Source

kageroumado/phosphene: A video wallpaper engine for macOS Tahoe