Phosphene puts your own videos on the macOS desktop and lock screen

What Phosphene does that wallpaper apps usually fake

macOS does not let you use your own videos as wallpaper: the desktop takes stills, and the lock screen plays only the Aerials Apple ships. Most tools work around that with a floating window pretending to be a wallpaper, which is the exact approach the README disowns. Phosphene instead plugs into the WallpaperExtensionKit framework, the same wallpaper pipeline Apple uses for its own Aerials. The consequence is concrete: playback runs out of process, survives the app quitting, works on the real lock screen, and integrates with the OS-level lock, idle, and sleep lifecycle. Your imported videos show up in System Settings, under Wallpaper, as their own collection, selectable for the desktop and the lock screen exactly like a built-in option. The app part is a menu bar item for preview, pause, display switching, and the library.

The private-framework gamble, stated plainly

The README carries its own warning, and it is the central trade of this app. Phosphene loads WallpaperExtensionKit via dlopen and uses Mirror-based runtime introspection to talk to its XPC types, because Apple does not document that framework. Apple could change it at any major OS release, and the README says so. The tested ground is macOS 26 (Tahoe) and macOS 27 (beta), with the requirement set at Tahoe 26.0 or newer: the wallpaper extension point itself exists since macOS 14, but Phosphene uses Tahoe-only SwiftUI APIs including glassEffect(). If you run macOS Sequoia or earlier, there is no supported path. This is the kind of dependency that survives for years and then breaks in one October afternoon, and the project stakes its entire mechanism on it rather than pretending otherwise.

Installing from Homebrew or a signed DMG

The simplest path is Homebrew, where Phosphene sits in the official homebrew/cask repository:

brew install --cask phosphene

The alternative is the signed, notarized DMG from the GitHub Releases page: open it, drag Phosphene to Applications, and launch. Releases ship as a universal binary covering arm64 and x86_64, so Intel Macs are supported. Building from source is a separate track that needs Xcode 17 or newer with Swift 6 strict concurrency: clone the repository, open Phosphene.xcodeproj, select the Phosphene scheme, and set a development team for code signing, since the wallpaper extension is embedded into the app bundle and registered with the system when the app launches.

Importing videos and setting your first wallpaper

First use is short. Launch Phosphene and use the menu bar icon to open Manage Library, where you add one or more videos; the README accepts MP4, MOV, or any AVFoundation-readable file. Then open System Settings, go to Wallpaper, and find the videos under their own collection. Pick one, and macOS handles the actual wallpaper assignment while the Phosphene extension supplies the frames. There is no separate player window to keep open and no floating surface to manage, because the extension is the thing macOS itself calls when it needs a wallpaper frame. Multi-display setups get per-display and per-Space selections, persisted by macOS rather than by the app.

Gapless loops and adaptive variants

Two mechanisms carry the playback quality. The first is gapless looping: the README describes frame-accurate loops achieved by offsetting PTS and DTS timestamps across loop boundaries, with no flush and no stutter at the seam. Anyone who has watched a wallpaper tool reset to the first frame every 30 seconds will recognize what this avoids. The second is adaptive variants: the app can optionally pre-render lower-resolution and lower-frame-rate variants of each video, and the renderer swaps to the cheapest variant that satisfies the current power policy, with the swap happening at a loop boundary so the change is invisible. The library and its variants live inside the extension sandbox container, alongside WallpaperPrefs.plist and a BMP snapshot cache used for still previews.

Power-aware playback and the occlusion pause

A graduated PlaybackPolicy decides how much work the wallpaper does. It takes thermal state, battery level, on-battery versus AC power, Game Mode, and presentation mode, which the README enumerates as active, locked, and idle. The policy reduces work or pauses playback entirely as conditions worsen. Two behaviors stand out. When every display is fully covered by windows, Phosphene detects the occlusion and pauses rendering until the desktop is visible again, so a wallpaper nobody can see costs nothing. When the wallpaper is set to appear only on the lock screen, it eases in and out with a cubic curve whenever the screen locks and the session comes back, which the README notes matches the behavior of Apple Aerials. These are the details that decide whether a video wallpaper is a toy or something you leave enabled.

The architecture: app, extension, sandbox

The system splits in two. Phosphene.app is the menu bar UI: library management, per-video metadata, HEVC optimization, and preferences, with Darwin notifications bridging to the second component. PhospheneExtension.appex is the wallpaper extension itself, hosted by the system WallpaperAgent, holding the XPC handler, an AVSampleBufferDisplayLayer for rendering, a power and thermal monitor, and a snapshot generator. Extension data lives in its own sandbox container under ~/Library/Containers/glass.kagerou.phosphene.extension/Data/Documents, which stores the video library and its variants, the WallpaperPrefs.plist settings file, and the BMP snapshot cache. The split is what makes the out-of-process guarantee real: the extension keeps playing when the menu bar app is closed, because the system is talking to the extension, not the app.

Limits, and what to run instead

The limits are the private framework, the Tahoe floor, and the build requirements: Xcode 17 plus a signing team if you compile it yourself. The alternative is the overlay approach used by other video-wallpaper utilities, which the README implicitly contrasts by rejecting it: a transparent window pinned to the desktop level. An overlay dies when the app quits, never reaches the lock screen, and does not follow the OS lock, idle, and sleep lifecycle, which is exactly the list of problems the extension route solves. If you are on macOS Sequoia or earlier, none of this helps, and the choice collapses to Apple stock Aerials or an overlay app. On maintenance: the project is MIT-licensed, the last push was on 2026-09-03, and releases run v1.4.1 through v1.6.

Editorial conclusion

Phosphene fits Mac users on macOS Tahoe 26 or later who want their own videos as genuine wallpapers rather than a window behind their icons, and who accept that it rides on a private Apple framework that could break at any major release. Skip it on Sequoia or older, since the README validates only macOS 26 and 27 beta. Verify the wallpaper picker shows the Phosphene collection after install, and keep the lock-screen ramp enabled if you care about battery.

Frequently asked questions

Official sources

1. kageroumado/phosphene on GitHub
2. License: MIT
3. Project website
4. README
5. Releases