GitHub - kageroumado/phosphene: A video wallpaper engine for macOS Tahoe · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
kageroumado
phosphene
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>1 Commit<br>1 Commit
Phosphene.xcodeproj
Phosphene.xcodeproj
Phosphene
Phosphene
PhospheneExtension
PhospheneExtension
.gitignore
.gitignore
.swift-version
.swift-version
.swiftformat
.swiftformat
.swiftlint.yml
.swiftlint.yml
Info.plist
Info.plist
LICENSE
LICENSE
README.md
README.md
View all files
Repository files navigation
Phosphene
A video wallpaper engine for macOS Tahoe.
Phosphene is a menu bar app + wallpaper extension that plays your own video files as the macOS desktop and lock-screen wallpaper. It plugs into the system's native wallpaper picker, so videos appear alongside Apple's built-in Aerials in System Settings → Wallpaper .
It is built on top of Apple's private WallpaperExtensionKit framework — the same one Apple's own Aerials use — which means playback runs out-of-process, survives app quits, and integrates with the OS-level lock-screen / idle / sleep lifecycle.
⚠️ Private framework. Phosphene loads WallpaperExtensionKit via dlopen and uses Mirror-based runtime introspection to talk to its XPC types. Apple could change this at any major OS release. The project tracks macOS 26 (Tahoe).
Features
Bring your own videos. Import MP4 / MOV / any AVFoundation-readable file. They show up in the system wallpaper picker.
Gapless looping. Frame-accurate loops by offsetting PTS/DTS across loop boundaries — no flush, no stutter.
Multi-display + per-Space selections. Different wallpapers per display, persisted by macOS.
Power-aware playback. A graduated PlaybackPolicy reduces work or pauses entirely based on thermal state, battery level, on-battery vs AC, 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 as you lock and unlock, matching Apple's own Aerials behavior.
Pause when occluded. Detects when every display is fully covered by windows and pauses rendering until the desktop is visible again.
Adaptive variants. Optionally pre-render lower-resolution / lower-fps variants of a video; the renderer swaps to the cheapest variant that satisfies the current policy at each loop boundary.
Menu bar control. Preview the current wallpaper, toggle pause, switch displays, configure behavior, launch at login.
Requirements
macOS Tahoe (26.0+). Phosphene depends on the Wallpaper extension point introduced in macOS 14 but uses Tahoe-only SwiftUI and glassEffect() APIs.
Apple Silicon. Targets arm64-apple-macos26.0.
Xcode 17+ to build, with Swift 6 strict concurrency enabled.
Building
/phosphene<br>cd phosphene<br>open Phosphene.xcodeproj">git clone https://github.com/you>/phosphene<br>cd phosphene<br>open Phosphene.xcodeproj
In Xcode, select the Phosphene scheme and Run. The project uses synchronized filesystem groups, so adding/removing files in Phosphene/ or PhospheneExtension/ requires no pbxproj edits.
You'll need to set a development team for code signing. The wallpaper extension is embedded into the app bundle and registered with the system when the app launches.
Using a video wallpaper
Launch Phosphene. Use the menu bar icon to Manage Library and add one or more videos.
Open System Settings → Wallpaper . Phosphene's videos appear under their own collection.
Pick a video. macOS handles the actual wallpaper assignment — Phosphene's extension provides the frames.
Architecture
┌─────────────────────────┐ ┌──────────────────────────────┐<br>│ Phosphene.app │ │ PhospheneExtension.appex │<br>│ (menu bar UI) │ │ (host: WallpaperAgent) │<br>│ │ │ │<br>│ • Library management │ Darwin │ • XPC handler │<br>│ • Per-video metadata │ ──────▶ │ • AVSampleBufferDisplayLayer │<br>│ • Optimization (HEVC) │ notif. │ • Power / thermal monitor │<br>│ • Preferences │ │ • Snapshot generator...