kageroumado/phosphene 源: https://github.com/kageroumado/phosphene # Phosphene 一款适用于 macOS Tahoe 的视频壁纸引擎。 Phosphene 是一款菜单栏应用 + 壁纸扩展，可将你自己的视频文件设置为 macOS 桌面和锁屏壁纸。它与系统原生的壁纸选择器集成，因此视频会与 Apple 内置的航拍视频一起出现在系统设置 → 壁纸中。它基于 Apple 私有的 WallpaperExtensionKit 框架构建——与 Apple 自己的航拍视频使用的框架相同——这意味着播放运行在进程外，应用退出后仍能继续，并与操作系统级别的锁屏/空闲/休眠生命周期集成。 > ⚠️ 私有框架。 Phosphene 通过 dlopen 加载 WallpaperExtensionKit，并使用基于 Mirror 的运行时自省与其 XPC 类型进行通信。Apple 可能会在任何主要 OS 版本中更改此框架。该项目跟踪 macOS 26 (Tahoe)。 ## 功能 - 使用你自己的视频。 导入 MP4 / MOV / 任何 AVFoundation 可读取的文件。它们会出现在系统壁纸选择器中。 - 无缝循环。 通过偏移循环边界上的 PTS/DTS 实现逐帧精确循环——无刷新、无卡顿。 - 多显示器 + 按空间选择。 每个显示器可设置不同的壁纸，由 macOS 持久化。 - 功耗感知播放。 渐进的 PlaybackPolicy 根据热状态、电池电量、是否使用电池、游戏模式以及呈现模式（活动/锁定/空闲）来减少工作或完全暂停。 - 平滑的锁屏过渡。 启用仅在锁屏时后，壁纸会在锁定和解锁时以三次曲线渐入/渐出，与 Apple 自身的航拍视频行为一致。 - 被遮挡时暂停。 检测到所有显示器均被窗口完全覆盖时，暂停渲染直至桌面再次可见。 - 自适应变体。 可选择为视频预渲染低分辨率/低帧率的变体；渲染器会在每个循环边界切换到满足当前策略的最廉价变体。 - 菜单栏控制。 预览当前壁纸、切换暂停、切换显示器、配置行为、设置登录时启动。 ## 系统要求 - macOS Tahoe (26.0+)。 Phosphene 依赖于 macOS 14 中引入的壁纸扩展点，但使用了 Tahoe 专属的 SwiftUI 和 glassEffect() API。 - Apple Silicon。 目标为 arm64-apple-macos26.0。 - Xcode 17+ 用于构建，启用了 Swift 6 严格并发。 ## 构建 sh git clone https://github.com//phosphene cd phosphene open Phosphene.xcodeproj 在 Xcode 中，选择 Phosphene 方案并运行。该项目使用同步文件系统组，因此在 Phosphene/ 或 PhospheneExtension/ 中添加/删除文件无需编辑 pbxproj。你需要设置一个开发团队用于代码签名。壁纸扩展嵌入到应用包中，并在应用启动时向系统注册。 ### 使用视频壁纸 1. 启动 Phosphene。使用菜单栏图标管理库，添加一个或多个视频。 2. 打开系统设置 → 壁纸。Phosphene 的视频会出现在它们自己的集合下。 3. 选择一个视频。macOS 处理实际的壁纸分配——Phosphene 的扩展提供帧内容。 ## 架构 ┌─────────────────────────┐ ┌──────────────────────────────┐ │ Phosphene.app │ │ PhospheneExtension.appex │ │ (菜单栏 UI) │ │ (宿主: WallpaperAgent) │ │ │ │ │ │ • 库管理 │ Darwin │ • XPC 处理器 │ │ • 按视频元数据 │ ──────▶ │ • AVSampleBufferDisplayLayer │ │ • 优化 (HEVC) │ 通知 │ • 电源 / 热监控 │ │ • 偏好设置 │ │ • 快照生成器 │ └─────────────────────────┘ └──────────────────────────────┘ │ │ └──────────────┬───────────────┘ ▼ 共享 App Group 容器 (~/Library/Group Containers/glass.kagerou.phosphene) • 视频库 + 变体 • WallpaperPrefs.plist • BMP 快照缓存 应用侧 (Phosphene/) — SwiftUI 菜单栏应用。管理磁盘上的视频库，通过 VideoOptimizationService 转码可选的低分辨率变体，暴露偏好设置，并在库发生变化时发送 Darwin 通知。 扩展侧 (PhospheneExtension/) — 当 Phosphene 壁纸处于活动状态时，运行在系统 WallpaperAgent 进程中。在运行时加载 WallpaperExtensionKit.framework，注册为壁纸提供者，并通过 AVSampleBufferDisplayLayer 将帧渲染到远程 CAContext 中。它接收来自 WallpaperAgent 的 XPC acquire / update / invalidate / snapshot 调用，并通过 PlaybackPolicy 路由呈现模式变化。 PlaybackPolicy 是播放行为的单一真相来源。输入（热状态、电池、呈现模式、用户暂停、遮挡等）被简化为 full / reduced / minimal / paused 之一。渲染器在每次状态变化时应用该策略。 VideoRenderer 拥有解码管道。它不是使用 AVPlayerLayer（在远程 CAContext 内会静默失败），而是手动驱动 AVSampleBufferDisplayLayer：一个 AVAssetReader 用于当前循环，另一个预加载的用于下一个循环，以及一个跨循环增长的 PTS 偏移量，以保持时间线单调递增。结果是无需刷新渲染器即可实现无故障循环。 ## 值得了解的怪癖 - WallpaperSnapshotXPC 混写。 系统的快照编码器检查 type(of: coder) == NSXPCCoder.self，但实际的编码器是一个子类。如果没有 PhospheneExtension.swift 中的运行时混写，快照会静默编码为空，导致过渡期间锁屏变灰。 - 基于 Mirror 的 XPC 解析。 Apple 的请求类型（WallpaperCreationRequestXPC 等）不属于任何公共 SDK 头文件。扩展通过 Mirror 反射读取它们。如果 Apple 重命名字段，预计会出现局部故障。 - 变体仅为建议。 如果电源监控认为我们在交流电源且空闲状态，则不会选择“1080p@30”变体——PlaybackPolicy 始终选择仍允许的最高等级。 ## 许可证 MIT。你可以随意使用，无任何担保。 ## 致谢 由 @kageroumado (https://x.com/kageroumado) 构建。Phosphene 最初是一个商业项目；现在开源是因为“macOS 视频壁纸应用”的市场比看起来更拥挤。