{"id":50161829,"url":"https://github.com/kageroumado/phosphene","last_synced_at":"2026-05-27T19:00:32.842Z","repository":{"id":359447618,"uuid":"1245114544","full_name":"kageroumado/phosphene","owner":"kageroumado","description":"A video wallpaper engine for macOS Tahoe","archived":false,"fork":false,"pushed_at":"2026-05-24T21:14:02.000Z","size":95,"stargazers_count":685,"open_issues_count":9,"forks_count":17,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T18:27:34.459Z","etag":null,"topics":["animated-wallpaper","desktop-wallpaper","macos","macos-wallpaper"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kageroumado.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"kageroumado"}},"created_at":"2026-05-20T23:33:59.000Z","updated_at":"2026-05-26T17:49:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kageroumado/phosphene","commit_stats":null,"previous_names":["kageroumado/phosphene"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kageroumado/phosphene","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kageroumado%2Fphosphene","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kageroumado%2Fphosphene/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kageroumado%2Fphosphene/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kageroumado%2Fphosphene/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kageroumado","download_url":"https://codeload.github.com/kageroumado/phosphene/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kageroumado%2Fphosphene/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33579668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animated-wallpaper","desktop-wallpaper","macos","macos-wallpaper"],"created_at":"2026-05-24T16:44:36.589Z","updated_at":"2026-05-27T19:00:32.807Z","avatar_url":"https://github.com/kageroumado.png","language":"Swift","funding_links":["https://ko-fi.com/kageroumado"],"categories":[],"sub_categories":[],"readme":"# Phosphene\n\nA video wallpaper engine for macOS Tahoe.\n\nPhosphene 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**.\n\nIt 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.\n\n\u003e ⚠️ **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).\n\n## Features\n\n- **Bring your own videos.** Import MP4 / MOV / any AVFoundation-readable file. They show up in the system wallpaper picker.\n- **Gapless looping.** Frame-accurate loops by offsetting PTS/DTS across loop boundaries — no flush, no stutter.\n- **Multi-display + per-Space selections.** Different wallpapers per display, persisted by macOS.\n- **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).\n- **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.\n- **Pause when occluded.** Detects when every display is fully covered by windows and pauses rendering until the desktop is visible again.\n- **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.\n- **Menu bar control.** Preview the current wallpaper, toggle pause, switch displays, configure behavior, launch at login.\n\n## Requirements\n\n- **macOS Tahoe (26.0+).** Phosphene depends on the Wallpaper extension point introduced in macOS 14 but uses Tahoe-only SwiftUI and `glassEffect()` APIs.\n- **Apple Silicon.** Targets `arm64-apple-macos26.0`.\n- **Xcode 17+** to build, with Swift 6 strict concurrency enabled.\n\n## Building\n\n```sh\ngit clone https://github.com/kageroumado/phosphene.git\ncd phosphene\nopen Phosphene.xcodeproj\n```\n\nIn 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.\n\nYou'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.\n\nFor a headless compile check without local signing identities:\n\n```sh\nxcodebuild -project Phosphene.xcodeproj -scheme Phosphene -configuration Debug \\\n  -destination 'generic/platform=macOS' \\\n  CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY='' build\n```\n\nOn the default DerivedData path, the unsigned debug app is produced at:\n\n```text\n~/Library/Developer/Xcode/DerivedData/Phosphene-*/Build/Products/Debug/Phosphene.app\n```\n\nTo install that local debug build into Applications:\n\n```sh\nrm -rf /Applications/Phosphene.app\ncp -R ~/Library/Developer/Xcode/DerivedData/Phosphene-*/Build/Products/Debug/Phosphene.app /Applications/\n```\n\n### Using a video wallpaper\n\n1. Launch Phosphene. Use the menu bar icon to **Manage Library** and add one or more videos.\n2. Open **System Settings → Wallpaper**. Phosphene's videos appear under their own collection.\n3. Pick a video. macOS handles the actual wallpaper assignment — Phosphene's extension provides the frames.\n\n## Architecture\n\n```\n┌─────────────────────────┐         ┌──────────────────────────────┐\n│  Phosphene.app          │         │  PhospheneExtension.appex     │\n│  (menu bar UI)          │         │  (host: WallpaperAgent)       │\n│                         │         │                              │\n│  • Library management   │  Darwin │  • XPC handler                │\n│  • Per-video metadata   │ ──────▶ │  • AVSampleBufferDisplayLayer │\n│  • Optimization (HEVC)  │  notif. │  • Power / thermal monitor    │\n│  • Preferences          │         │  • Snapshot generator         │\n└─────────────────────────┘         └──────────────────────────────┘\n                  │                              │\n                  └──────────────┬───────────────┘\n                                 ▼\n                  Shared App Group container\n                  (~/Library/Group Containers/glass.kagerou.phosphene)\n                  • Video library + variants\n                  • WallpaperPrefs.plist\n                  • BMP snapshot cache\n```\n\n**App side** (`Phosphene/`) — SwiftUI menu-bar app. Manages the on-disk video library, transcodes optional lower-resolution variants via `VideoOptimizationService`, exposes preferences, and posts a Darwin notification when the library changes.\n\n**Extension side** (`PhospheneExtension/`) — runs inside the system `WallpaperAgent` process when a Phosphene wallpaper is active. Loads `WallpaperExtensionKit.framework` at runtime, registers as a wallpaper provider, and renders frames into a remote `CAContext` via `AVSampleBufferDisplayLayer`. It receives XPC `acquire` / `update` / `invalidate` / `snapshot` calls from `WallpaperAgent` and routes presentation-mode changes through `PlaybackPolicy`.\n\n**`PlaybackPolicy`** is the single source of truth for playback behavior. Inputs (thermal state, battery, presentation mode, user pause, occlusion, etc.) collapse to one of `full / reduced / minimal / paused`. The renderer applies the policy on every state change.\n\n**`VideoRenderer`** owns the decode pipeline. Instead of `AVPlayerLayer` — which silently fails inside a remote `CAContext` — 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. Result is glitch-free looping without flushing the renderer.\n\n## Quirks worth knowing\n\n- **`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 and you get a grey lock screen during transitions.\n- **Mirror-based XPC parsing.** Apple's request types (`WallpaperCreationRequestXPC` etc.) aren't part of any public SDK header. The extension reads them via `Mirror` reflection. If Apple renames fields, expect surgical breakage.\n- **Variants are advisory.** A \"1080p@30\" variant won't be selected if Power-Monitor thinks we're on AC and idle — `PlaybackPolicy` always picks the highest tier that's still allowed.\n\n## License\n\n[MIT](LICENSE). Do whatever you want, no warranty.\n\n## Acknowledgements\n\nBuilt by [@kageroumado](https://x.com/kageroumado). Phosphene was originally a commercial project; it's open-source now because the market for \"video wallpaper apps on macOS\" turned out to be more crowded than it looked.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkageroumado%2Fphosphene","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkageroumado%2Fphosphene","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkageroumado%2Fphosphene/lists"}