Reverse-Engineering Apple's Video Wallpaper Engine: Phosphene

Phosphene is an open-source macOS app that plays your own video files as the desktop and lock-screen wallpaper. It uses the same private framework — WallpaperExtensionKit — that Apple's own Aerials use. The project, now MIT-licensed, was built by @kageroumado and targets macOS Tahoe (26.0+).

How It Works

Phosphene consists of two components: a menu-bar app (Phosphene.app) and a wallpaper extension (PhospheneExtension.appex). The extension runs inside the system WallpaperAgent process, loading WallpaperExtensionKit.framework at runtime via dlopen. It uses Mirror-based runtime introspection to parse Apple's private XPC request types (e.g., WallpaperCreationRequestXPC) that aren't part of any public SDK.

The extension renders frames into a remote CAContext using AVSampleBufferDisplayLayer. Instead of AVPlayerLayer (which silently fails inside a remote context), 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. This ensures glitch-free looping without flushing the renderer.

Key Features

  • Gapless looping: Frame-accurate loops by offsetting PTS/DTS across boundaries — no flush, no stutter.
  • Multi-display + per-Space selections: Different wallpapers per display, persisted by macOS.
  • Power-aware playback: A PlaybackPolicy reduces work or pauses based on thermal state, battery level, AC vs battery, 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, matching Apple's Aerials.
  • Pause when occluded: Detects when every display is fully covered by windows and pauses rendering.
  • Adaptive variants: Optionally pre-render lower-resolution/fps variants; the renderer swaps to the cheapest variant that satisfies the current policy at each loop boundary.

Architecture Details

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

The app side manages the on-disk video library, transcodes optional lower-resolution variants via VideoOptimizationService, and posts a Darwin notification when the library changes. The extension side loads WallpaperExtensionKit.framework at runtime, registers as a wallpaper provider, and renders frames. It receives XPC acquire/update/invalidate/snapshot calls from WallpaperAgent and routes presentation-mode changes through PlaybackPolicy.

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, resulting in a grey lock screen during transitions.
  • Mirror-based XPC parsing: Apple's request types aren't public. 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 PowerMonitor thinks you're on AC and idle — PlaybackPolicy always picks the highest tier that's still allowed.

Requirements and Building

  • macOS Tahoe (26.0+)
  • Apple Silicon (arm64)
  • Xcode 17+ with Swift 6 strict concurrency

To build:

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

Set a development team for code signing. The wallpaper extension is embedded into the app bundle and registered when the app launches.

How to Use

  1. Launch Phosphene. Use the menu bar icon to "Manage Library" and add videos (MP4, MOV, or any AVFoundation-readable file).
  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.

Why This Matters for Developers

Phosphene is a rare example of reverse-engineering a private Apple framework for legitimate, user-facing functionality. It demonstrates how to use dlopen for dynamic loading, Mirror for runtime introspection, and manual AVSampleBufferDisplayLayer management. The project's PlaybackPolicy system is a clean pattern for power-aware media playback. Developers working on macOS media apps or system extensions will find the architecture instructive.

License

MIT. Do whatever you want, no warranty.

Next Steps

Clone the repo, build it, and inspect the XPC protocol handling in PhospheneExtension.swift. If you're building for macOS 26, consider contributing adaptive variant encoding or additional playback policies.