Show HN: I reverse engineered Apple's video wallpapers

查看原文 / View Original 编辑 / Edit

Show HN: I reverse engineered Apple’s video wallpapers

Phosphene: A video wallpaper engine for macOS Tahoe. Phosphene 是一个适用于 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. Phosphene 是一个菜单栏应用加壁纸扩展，可以将你自己的视频文件作为 macOS 桌面和锁屏壁纸。它接入了系统原生的壁纸选择器，因此视频会与苹果内置的“航拍”壁纸一起出现在“系统设置”→“墙纸”中。它基于苹果私有的 WallpaperExtensionKit 框架构建（与苹果自家的“航拍”壁纸使用同一框架），这意味着播放过程在独立进程中运行，即使应用退出也能持续播放，并与操作系统级的锁屏、空闲和睡眠生命周期完美集成。

⚠️ 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). ⚠️ 私有框架。 Phosphene 通过 dlopen 加载 WallpaperExtensionKit，并使用基于 Mirror 的运行时内省（runtime introspection）来与 XPC 类型进行交互。苹果可能会在任何重大操作系统更新中更改此机制。该项目目前适配 macOS 26 (Tahoe)。

Features (功能特性)

  • Bring your own videos. Import MP4 / MOV / any AVFoundation-readable file. They show up in the system wallpaper picker. 自带视频。 导入 MP4 / MOV 或任何 AVFoundation 可读取的文件，它们会直接显示在系统壁纸选择器中。
  • Gapless looping. Frame-accurate loops by offsetting PTS/DTS across loop boundaries — no flush, no stutter. 无缝循环。 通过在循环边界偏移 PTS/DTS 实现帧级精确循环，无刷新、无卡顿。
  • Multi-display + per-Space selections. Different wallpapers per display, persisted by macOS. 多显示器 + 独立空间选择。 每个显示器可设置不同壁纸，并由 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). 电源感知播放。 分级的 PlaybackPolicy 会根据热状态、电池电量、电池/交流电供电、游戏模式以及演示模式（活动/锁定/空闲）来降低负载或完全暂停播放。
  • 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. macOS Tahoe (26.0+)。 Phosphene 依赖于 macOS 14 引入的壁纸扩展点，但使用了 Tahoe 独有的 SwiftUI 和 glassEffect() API。
  • Apple Silicon. Targets arm64-apple-macos26.0. Apple Silicon。 目标架构为 arm64-apple-macos26.0。
  • Xcode 17+ to build, with Swift 6 strict concurrency enabled. Xcode 17+ 进行构建，并启用了 Swift 6 严格并发检查。

Building (构建)

git clone https://github.com/<you>/phosphene
cd phosphene
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. 在 Xcode 中选择 Phosphene 方案并运行。该项目使用同步文件系统组，因此在 Phosphene/ 或 PhospheneExtension/ 中添加/删除文件无需修改 pbxproj。你需要设置开发团队以进行代码签名。壁纸扩展被嵌入到应用包中，并在应用启动时向系统注册。

Using a video wallpaper (使用视频壁纸)

  1. Launch Phosphene.
  2. Use the menu bar icon to Manage Library and add one or more videos.
  3. Open System Settings → Wallpaper.
  4. Phosphene’s videos appear under their own collection. Pick a video. macOS handles the actual wallpaper assignment — Phosphene’s extension provides the frames.
  5. 启动 Phosphene。
  6. 使用菜单栏图标管理库并添加一个或多个视频。
  7. 打开“系统设置”→“墙纸”。
  8. Phosphene 的视频会出现在其专属集合中。选择一个视频。macOS 负责实际的壁纸分配，而 Phosphene 的扩展负责提供画面帧。

Architecture (架构)

(Diagram omitted for brevity, see original source)

  • 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. 应用端 (Phosphene/)： SwiftUI 菜单栏应用。管理磁盘上的视频库，通过 VideoOptimizationService 转码可选的低分辨率变体，公开偏好设置，并在库发生变化时发送 Darwin 通知。
  • 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. 扩展端 (PhospheneExtension/)： 当 Phosphene 壁纸处于活动状态时，在系统 WallpaperAgent 进程内运行。在运行时加载 WallpaperExtensionKit.framework，注册为壁纸提供程序，并通过 AVSampleBufferDisplayLayer 将帧渲染到远程 CAContext 中。它接收来自 WallpaperAgent 的 XPC 获取/更新/失效/快照调用，并通过 PlaybackPolicy 路由演示模式的更改。

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. PlaybackPolicy 是播放行为的唯一事实来源。输入（热状态、电池、演示模式、用户暂停、遮挡等）会归纳为“完整/降低/最小/暂停”四种状态之一。渲染器会在每次状态更改时应用该策略。

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. VideoRenderer 拥有解码流水线。它不使用在远程 CAContext 中会静默失败的 AVPlayerLayer，而是手动驱动 AVSampleBufferDisplayLayer：一个 AVAssetReader 用于当前循环，另一个预加载用于下一个循环，并使用在循环间增长的 PTS 偏移量来保持时间轴单调递增。结果是无故障的循环，且无需刷新渲染器。

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 and you get a grey lock screen during transitions. WallpaperSnapshotXPC 混淆（Swizzle）。 系统的快照编码器会检查 type(of: coder) == NSXPCCoder.self，但实际的编码器是一个子类。如果没有 PhospheneExtension.swift 中的运行时混淆，快照会静默编码为空，导致你在过渡期间看到灰色的锁屏。
  • 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. 基于 Mirror 的 XPC 解析。 苹果的请求类型（如 WallpaperCreationRequestXPC 等）不属于任何公开的 SDK 头文件。扩展通过 Mirror 反射读取它们。如果苹果重命名了字段，预计会导致功能损坏。
  • 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. 变体仅供参考。 如果电源监控器认为设备处于交流电供电且空闲状态，则不会选择“1080p@30”变体——PlaybackPolicy 总是会选择当前允许的最高级别。

License: MIT. Do whatever you want, no warranty. 许可证： MIT。随意使用，不提供任何担保。

Acknowledgements: Built by @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. 致谢： 由 @kageroumado 开发。Phosphene 最初是一个商业项目；现在开源是因为“macOS 视频壁纸应用”市场比预想的要拥挤得多。

← 返回新闻列表 / Back to news list