Phosphene: Technical Analysis of macOS Video Wallpaper Engine

Phosphene presents an interesting technical approach to solving a long-standing limitation in macOS: the inability to use video files as desktop or lock screen wallpapers. This open-source project from kageroumado implements a video wallpaper engine that plugs directly into macOS's native wallpaper system, offering capabilities beyond what third-party solutions have previously achieved.

What Phosphene Claims

Phosphene is positioned as a menu bar application combined with a wallpaper extension that allows users to play their own video files as both desktop and lock screen wallpapers. Its key selling points include integration with the system's native wallpaper picker, gapless video looping, multi-display support, power-aware playback, and smooth transitions when the screen locks.

Technical Implementation

The most notable aspect of Phosphene is its approach to system integration. Rather than implementing a traditional overlay solution that might conflict with macOS's window management, Phosphene leverages Apple's private WallpaperExtensionKit framework—the same framework Apple uses for its own Aerials videos. This approach provides several advantages:

1. Out-of-process playback: The video rendering occurs in a separate process, ensuring it survives if the main application quits.
2. System-level lifecycle integration: The wallpaper properly responds to macOS events like sleep, idle, and screen locking.
3. Native integration: Videos appear alongside Apple's built-in wallpapers in System Settings.

The implementation uses dlopen to dynamically load WallpaperExtensionKit at runtime, employing Mirror-based runtime introspection to communicate with the framework's XPC types. This technique allows the developers to interface with Apple's private APIs without directly linking against them, which would make the app incompatible with App Store distribution.

Architecture Breakdown

Phosphene consists of two main components:

1. Phosphene.app: The user-facing menu bar application written in SwiftUI. It manages the video library, handles transcoding of optional lower-resolution variants, exposes preferences, and notifies the system when the library changes.

2. PhospheneExtension.appex: The wallpaper extension that runs inside the system WallpaperAgent process when a Phosphene wallpaper is active. This component handles the actual video rendering and interfaces with the macOS wallpaper system.

Both components communicate through a shared App Group container located at ~/Library/Group Containers/glass.kagerou.phosphene, which stores the video library, preferences, and cached snapshots.

Technical Merits

Several technical aspects of Phosphene stand out:

Gapless Looping Implementation

Phosphene implements frame-accurate looping without stuttering or visual artifacts. This is achieved by offsetting Presentation Time Stamps (PTS) and Decode Time Stamps (DTS) across loop boundaries, maintaining a monotonically increasing timeline. The system uses two AVAssetReader instances—one for the current loop and one preloaded for the next—to ensure seamless transitions.

Power-Aware Playback

The implementation includes a sophisticated PlaybackPolicy that adjusts rendering behavior based on multiple system factors:

• Thermal state of the device
• Battery level and power source (AC vs. battery)
• Game Mode status
• Presentation mode (active, locked, or idle)

This policy reduces rendering workload or pauses playback entirely when the system is under stress, conserving battery and preventing thermal issues.

Custom Rendering Pipeline

Instead of using AVPlayerLayer (which fails in remote Core Animation contexts), Phosphene implements a custom VideoRenderer that drives AVSampleBufferDisplayLayer manually. This approach provides more control over the rendering pipeline and enables features like adaptive variants that automatically switch to lower-resolution or lower-framerate versions of videos when system resources are constrained.

Limitations and Caveats

Despite its technical sophistication, Phosphene has several important limitations:

1. Private Framework Dependency: The most significant limitation is its reliance on Apple's private WallpaperExtensionKit framework. Apple could modify or remove this framework at any major OS release, potentially breaking Phosphene without recourse for the developers.

2. Runtime Introspection Risks: The Mirror-based approach to parsing XPC types is fragile. If Apple renames fields in its internal types, Phosphene could break without a clear path to fixing it.

3. Snapshot Workaround: The implementation requires a WallpaperSnapshotXPC swizzle to properly encode snapshots. Without this, the system would generate grey screens during transitions.

4. Variant Selection Logic: The adaptive variants are advisory rather than strictly enforced. The system may still select higher-quality variants when system conditions permit, regardless of pre-rendered lower-quality options.

Practical Implications

For end users, Phosphene offers a way to use personal videos as wallpapers with system-level integration that previous third-party solutions couldn't match. The power-aware playback ensures the feature doesn't significantly impact system performance, and the native integration means it behaves like any other wallpaper in macOS.

For developers, Phosphene demonstrates sophisticated techniques for leveraging macOS private frameworks while maintaining compatibility. The implementation shows deep understanding of macOS's wallpaper system, Core Animation, and media playback pipelines.

The project's GitHub repository (https://github.com/kageroumado/phosphene) provides detailed build instructions and implementation notes for those interested in the technical details or wanting to compile the application themselves.

Conclusion

Phosphene represents an impressive technical achievement in macOS customization, successfully implementing a system-integrated video wallpaper solution through careful navigation of Apple's private frameworks. While its reliance on undocumented APIs presents inherent risks, the implementation demonstrates deep system knowledge and thoughtful engineering that results in a polished, macOS-integrated experience.