MyWallpaperX

macOS 原生动态壁纸工作台本地素材管理 · 在线资源浏览 · Steam Workshop 播放 · Metal Scene 渲染

界面预览

本地壁纸库 _{导入、搜索、收藏与标签管理}	浏览与管理 _{macOS 原生列表、网格与 Quick Look 预览}	在线壁纸资源 _{浏览 Pixabay 在线库并下载纳入本地}
Steam Workshop _{原生网格浏览、下载和管理创意工坊}	下载与详情面板 _{集中查看下载状态、文件位置和素材信息}	桌面播放 _{独立守护进程承载视频 / Web / Scene 渲染}

核心能力

MyWallpaperX 深度利用 macOS 原生能力，围绕素材管理 → 资源获取 → 桌面播放三条主线设计。

模块	状态	说明
本地视频壁纸库	✅	导入视频文件，支持收藏、最近使用、标签管理、Quick Look 预览、排序和详情检查器，面向长期积累
图片壁纸管理	✅	管理本地图片素材，瀑布流 / 网格双布局，标签整理，与视频库共享侧边栏与工具栏
Pixabay 在线库	✅	浏览 Pixabay 在线资源，异步下载并纳入本地库管理，支持下载状态追踪
Steam Workshop 浏览	✅	完全原生的 AppKit NSCollectionView 网格浏览 Wallpaper Engine 创意工坊，内置 SteamCMD Runtime
视频壁纸播放	✅	独立守护进程承载视频播放，支持切换、音量、播放速率、音量控制，DaemonProtocol 跨进程通信
Web 壁纸支持	✅	`project.json → descriptor → runtime model → playback context` 四层解析管线，本地 scheme 资源加载、属性系统、音频桥接与兼容脚本注入
Scene 壁纸渲染	🚧	Metal 驱动的一阶段渲染器已实现图像层合成与基础变换；effect / material / shader / 粒子 / SceneScript / puppet 等高级特性仍在开发中
系统音频频谱	✅	面向音频响应类壁纸的系统音频采集，支持均衡跳动与频带起伏两种风格
菜单栏控制	✅	状态栏入口，GPU 占用实时显示，快速访问播放控制与模块切换

Scene 壁纸说明：Scene 渲染器已完成 scene.json 解析、scene.pkg 资源包解包、TEX 纹理加载、Metal 管线搭建和桌面宿主窗口。当前可渲染基础图像层，但效果通道（effect passes）、材质着色器编译、DirectX shader 转译、粒子系统、SceneScript 脚本执行和 puppet warp 等能力尚未实现，这些特性会在后续版本逐步补齐。

系统架构

主界面与播放链路解耦，各模块独立可组合——删除任意模块文件夹，其余代码正常编译运行。

MyWallpaperX.app
├─ App / Shell                 ← 主窗口、侧边栏、状态栏、菜单栏、模块导航
├─ Modules
│  ├─ VideoLibrary             ← 本地视频壁纸库（导入、收藏、标签、播放设置）
│  ├─ StaticImageLibrary       ← 本地图片壁纸库（瀑布流 / 网格、Quick Look）
│  ├─ OnlineLibrary            ← Pixabay 在线资源浏览与下载管理
│  └─ SteamWorkshop
│     ├─ Core                  ← Workshop API 模型、网络调度、下载管理、详情刷新
│     ├─ Web                   ← Web 壁纸属性系统、运行时缓存、校验与兼容诊断
│     ├─ Scene                 ← Scene 壁纸详情、诊断信息与播放路由
│     ├─ UI                    ← 原生 NSCollectionView 网格浏览、下载列表、详情面板
│     └─ Toolbar               ← Workshop 专用工具栏与操作
├─ Core
│  ├─ Playback                 ← WallpaperEngine、DaemonProtocol、系统音频频谱
│  ├─ SteamWorkshopWeb         ← Web 壁纸引擎（本地 scheme 处理器、兼容脚本注入、运行时桥接）
│  ├─ SteamWorkshopScene       ← Metal Scene 渲染器（场景解析、纹理加载、渲染管线）
│  └─ System                   ← 全局快捷键、系统状态监控
├─ Shared                      ← 通用 UI 组件、缩略图缓存、Inspector、网格布局
├─ Models                      ← VideoWallpaper 数据模型、播放设置
└─ Resources                   ← SteamCMD Runtime、内置视频素材

WallpaperDaemonSources         ← 独立守护进程，承载视频 / Web 播放与频谱采集

安装

前往 GitHub Releases 下载最新 MyWallpaperX-*.dmg。

打开 DMG，将 MyWallpaperX.app 拖入 Applications 即可。发布包由 GitHub Actions 自动构建，经 Developer ID 签名与 Apple Notarization 公证。

系统要求

macOS 26.0+
支持 Apple Silicon 与 Intel Mac
Steam Workshop 功能需可访问 Steam 服务

开发

# Xcode 打开项目
open MyWallpaperX.xcodeproj

# 脚本构建并运行
script/build_and_run.sh            # 构建并启动
script/build_and_run.sh debug      # 进入 LLDB 调试
script/build_and_run.sh logs       # 构建、运行并查看应用日志
script/build_and_run.sh verify     # 构建、运行并做最小启动验证

# 或直接使用 xcodebuild
xcodebuild -project MyWallpaperX.xcodeproj -scheme MyWallpaperX -configuration Debug -derivedDataPath .codex/DerivedData build

免责声明

MyWallpaperX 是一个面向 macOS 的个人壁纸管理与播放工具。

本应用不声称拥有用户导入、下载或播放的任何壁纸、视频、Web 内容或 Steam Workshop 内容的版权，用户应自行确认素材的版权归属与授权范围。
本项目不隶属于 Steam、Valve、Wallpaper Engine、Pixabay 或其他第三方内容平台。Steam 创意工坊能力仅用于访问用户可合法使用的内容。
因用户导入内容、账号使用、网络环境或违反第三方条款导致的风险由用户自行承担。本项目按现状提供，不对持续可用性或第三方服务稳定性作保证。

【投稿】MyWallpaperX