laobamac/MirageWallpaper
Public
Star 历史趋势
数据来源: GitHub API · 生成自 Stargazers.cn
README.md

Mirage 图标

Mirage

English · 简体中文

面向 macOS 的原生动态壁纸管理器与 Wallpaper Engine 兼容运行时。

Build macOS App macOS Architecture Swift C++ License

[!IMPORTANT] Mirage 当前仍处于早期阶段。 如果遇到问题，请认真撰写 GitHub Issue，说明系统与 App 版本、复现步骤、预期结果、实际现象和相关日志；也可以加入 QQ 交流群 2160040437 反馈。

Mirage 使用 SwiftUI 与 AppKit 提供壁纸浏览、管理和系统集成，并通过三个独立渲染进程播放场景、网页和视频壁纸。应用可以读取本地 Wallpaper Engine 风格的壁纸包，也可以直接浏览 Steam 创意工坊、登录 Steam 并下载壁纸。

Mirage 正在持续开发，Wallpaper Engine 场景格式的兼容性仍在完善。复杂作品可能存在特效、脚本或材质表现差异。

支持 Mirage

Mirage 会继续免费开放开发。如果它为你的桌面带来了价值，欢迎按自己的意愿赞助；每一份支持都会用于持续维护、兼容性改进和新功能开发。赞助完全自愿，不影响任何功能使用。

爱发电微信支付支付宝
在爱发电赞助 laobamac
点击二维码或图片打开爱发电		微信支付赞助二维码支付宝赞助二维码

海外用户也可以赞助 USDT：

0xFc0a5C52e3A085FEc7b077FE3D2C413114Bf880D

转账前请自行确认网络、地址和金额。

主要功能

  • 支持 scene、web、video 三类动态壁纸。
  • 浏览已安装壁纸，支持搜索、排序、类型/来源/标签/内容分级筛选和收藏。
  • 直接导入包含 project.json 的目录，或把 .mp4、.mov、.m4v 视频转换为本地壁纸包。
  • 浏览 Steam 创意工坊的趋势、最新、热门、评分和标签分类内容。
  • 识别并下载创意工坊预设；缺少基础壁纸时会先征求同意再加入下载队列，依赖已安装时可直接应用。
  • 内置基于 SteamKit2 3.4.0 的 Steam 服务，支持二维码、密码和 Steam Guard 登录，刷新令牌保存在 macOS 钥匙串。
  • 创意工坊下载器直接调用 SteamKit2 的清单与 CDN API，实现参考 DepotDownloader 的成熟下载流程，但不捆绑或启动 DepotDownloader 可执行程序。
  • 复用一个长驻 Steam 会话，避免每次下载前重复启动和登录。
  • 最多同时下载三个创意工坊作品，实时显示 CDN 接收字节、下载速度、进度和预计剩余时间；每个任务可独立取消。
  • 已下载作品可直接播放，并打开音量、速度、填充模式及作品自定义属性侧栏。
  • 支持多显示器覆盖、菜单栏控制、登录启动和桌面占位图恢复。
  • 可安装 Mirage 自带的动态屏保，直接播放视频、网页和场景壁纸，并保留当前预设与自定义属性。
  • 可在全屏应用、其他应用播放音频、屏幕休眠或电池供电时选择继续、静音、暂停或停止。
  • 使用 macOS“点按墙纸以显示桌面”时会自动恢复播放。
  • 网页壁纸首次运行前显示安全确认，并支持 Wallpaper Engine 用户属性与鼠标事件。

渲染架构

组件技术职责
MirageSwiftUI、AppKit界面、壁纸库、创意工坊、设置、进程管理和系统集成
SceneWallpaperC++20、Vulkan、MoltenVKscene.pkg / scene.json、材质、粒子、LUT、文字和用户属性
WebWallpaperObjective-C++、WKWebViewHTML 壁纸、JavaScript、媒体、鼠标事件和用户属性
VideoWallpaperObjective-C++、AVFoundation视频循环、音量、速度和填充模式
MirageScreenSaverSwift、WebKit、AVFoundation、Metal独立安装的动态屏保宿主

渲染器作为独立进程运行。Mirage 通过标准输入发送逐行 JSON 控制消息，因此单个渲染器异常不会直接破坏主应用状态。

Steam 创意工坊

Mirage 对 Steam 的两类访问彼此独立：

用途服务是否需要 API Key
浏览、搜索和读取作品信息Steam Web API是
登录、Steam Guard 和下载作品内置 Steam 服务（SteamKit2；下载流程参考 DepotDownloader）否，需要 Steam 账户

应用内置的 Steam Web API Key 只用于首次浏览，并由所有用户共享。建议在“设置 → 通用 → Steam API Key”中填写自己的 Key，以避免共享额度繁忙。Key 可在 Steam Web API Key 申请页面 获取。

中国大陆用户可以在设置中选择 SteamCF 浏览镜像。镜像只代理创意工坊浏览 API，不会加速 Steam 登录或内容下载，并且仅允许中国大陆用户访问。

Mirage 将下载内容写入自己的目录，不复用系统 Steam 客户端的数据：

~/Library/Application Support/Mirage/Workshop/content/431960

登录成功后，Steam 会话会在 Mirage 运行期间持续保持。Mirage 使用共享会话并行解析作品，并通过受限的 CDN 分块并发公平地服务最多三个作品；取消一个任务不会中断其他下载。

Mirage 直接依赖 SteamKit2 与 Valve 服务通信。清单解析、CDN 服务器选择、分块下载、校验和断点复用的整体设计参考了 DepotDownloader；Mirage 使用自己的应用内服务和任务调度，不包含 DepotDownloader 命令行程序，也不会启动外部下载器。

创意工坊预设会在浏览页、详情页、下载管理和“已安装”中明确标记。预设本身只保存属性与附带素材，并依赖一个基础壁纸：基础壁纸已经安装时，点击预设会直接应用并打开自定义侧栏；尚未安装时，Mirage 会显示基础壁纸名称和大小，询问是否一起下载。预设与基础壁纸都会保留为独立的已安装项目。

壁纸包格式

壁纸目录以 project.json 为入口：

wallpaper-folder/
├── project.json
├── preview.jpg
└── wallpaper-file

最小视频壁纸示例：

{
  "title": "My Wallpaper",
  "type": "video",
  "file": "demo.mp4",
  "preview": "preview.jpg"
}
type常见入口渲染方式
scenescene.pkg、scene.jsonSceneWallpaper
webHTML 文件，通常为 index.htmlWebWallpaper
video常见视频文件VideoWallpaper

Mirage 会解析作品声明的入口文件，并对部分非标准目录布局进行兼容查找。目录仍必须包含有效的 project.json。

系统与构建要求

  • Intel Mac（x86_64）或 Apple Silicon Mac（arm64）
  • macOS 14.2 或更高版本
  • 完整版 Xcode
  • Homebrew
  • CMake 4.3.1 或更高版本
  • .NET 10 SDK
  • Homebrew LLVM、Ninja、pkg-config、MoltenVK、Vulkan Loader/Headers、glslang、GLFW、FreeType、Fontconfig、LZ4 和 FFmpeg

安装依赖：

xcode-select --install
brew install cmake ninja pkg-config llvm molten-vk vulkan-loader vulkan-headers \
  glslang glfw freetype fontconfig lz4 ffmpeg

从源码构建

git clone https://github.com/laobamac/MirageWallpaper.git
cd MirageWallpaper

./scripts/build_all.sh

open "Mirage/dist/Mirage.app"

最终 App 位于：

Mirage/dist/Mirage.app

App 内包含可在“设置 → 屏保”中安装的 MirageScreenSaver.saver。屏保组件会被复制到当前用户的 ~/Library/Screen Savers，不要求 Mirage 主程序保持运行。场景屏保运行库和所需资源由打包脚本一并嵌入。

build_all.sh 会按顺序构建三个渲染器、Steam 服务和主程序，并完成 App Bundle 打包。Debug 构建使用 ./scripts/build_all.sh debug；只重建主程序时可使用 ./scripts/build_all.sh app。

本地配置内置 Steam Web API Key

源码不包含默认 API Key。本地完整打包时，可以把 Key 放入已被 Git 忽略的文件：

mkdir -p .secrets
chmod 700 .secrets
printf '%s\n' 'YOUR_32_CHARACTER_STEAM_WEB_API_KEY' > .secrets/steam_web_api_key
chmod 600 .secrets/steam_web_api_key

Mirage/scripts/build.sh 会读取该文件，通过临时 xcconfig 写入 App 的 Info.plist，并在构建结束后删除临时配置。也可以只对当前命令传入环境变量：

MIRAGE_STEAM_WEB_API_KEY='YOUR_32_CHARACTER_STEAM_WEB_API_KEY' \
  ./Mirage/scripts/build.sh Release

没有内置 Key 时 App 仍可正常编译，开发者可以在运行后的设置中填写自己的 Key。

GitHub Actions 自动打包

Build macOS App 会在以下情况使用 macos-15-intel 和 macos-15 自动构建三个渲染器和 Mirage（x86_64 和 arm64）：

  • 推送到 main；
  • 推送名称以 v 开头的标签；
  • 在 Actions 页面手动运行。

首次运行前，在仓库的 Settings → Secrets and variables → Actions 中添加 Repository Secret：

MIRAGE_STEAM_WEB_API_KEY      32 位 Steam Web API Key
MIRAGE_SPARKLE_PRIVATE_KEY    Mirage 专用 Sparkle Ed25519 私钥

如果本机安装了 GitHub CLI，也可以执行：

gh secret set MIRAGE_STEAM_WEB_API_KEY < .secrets/steam_web_api_key

MIRAGE_SPARKLE_PRIVATE_KEY 只用于 Actions 生成 Ed25519 签名的更新包和 appcast。它绝不能提交到仓库；应保留登录钥匙串中的原始密钥，并另存一份离线备份。客户端仅包含可公开的公钥。

Workflow 为每次构建自动将完整 Git commit 与 git rev-list --count 生成的递增构建号写入 App，因此不需要手动更新版本号。只有构建号更高的 commit 才会被安装，避免把较新的开发构建降级为较旧 Release。

  • 推送 v* 标签会创建正式 GitHub Release，并写入稳定更新源；
  • 推送 main 会替换滚动的 prerelease GitHub Release，并写入 beta 更新源；
  • App 默认自动检查并下载正式版；在“设置 → 软件更新”关闭自动更新后不再后台检查或下载，但仍可手动检查；开启“接收测试版更新”后，Sparkle 会同时检查 beta channel；
  • 两个架构各自使用独立 appcast，更新包、appcast 和更新说明均经 Sparkle Ed25519 签名。

App 更新后的下一次启动会同时检查已经安装到 ~/Library/Screen Savers 的 Mirage 屏保组件；仅当其构建号落后于 App 内置组件时才会原子替换并重启相关系统屏保服务。

GitHub Secrets 可以避免 Key 出现在仓库和普通构建日志中，但无法让客户端内置 Key 成为真正的秘密：发布后的 App 必须包含它，有能力分析 App 的人仍可以提取。若未来需要不可提取的凭据，应把对应请求放到受控服务端，由服务端持有 Key；不要依赖客户端混淆。

当前 Workflow 使用临时签名，不包含 Apple Developer ID 签名和公证。首次安装的用户仍可能需要在 macOS Gatekeeper 中手动允许 Mirage；但后续更新的真实性由内置 Ed25519 公钥验证。

数据目录

数据默认位置
Mirage 本地壁纸~/Library/Application Support/Mirage/Wallpapers
Mirage 创意工坊下载内容~/Library/Application Support/Mirage/Workshop/content/431960
系统 Steam 创意工坊内容~/Library/Application Support/Steam/steamapps/workshop/content/431960
创意工坊预览缓存~/Library/Caches/Mirage/WorkshopCache
壁纸运行时设置UserDefaults
动态屏保配置~/Library/Application Support/Mirage/screensaver.json
已安装动态屏保~/Library/Screen Savers/MirageScreenSaver.saver

Mirage 会同时发现系统 Steam、Mirage 下载目录和自定义目录中的有效作品。

仓库结构

.
├── Mirage/                 # SwiftUI / AppKit 主应用与打包脚本
│   └── Mirage Screen Saver/ # 独立动态屏保目标
├── SteamService/           # SteamKit2 登录服务与参考 DepotDownloader 设计的下载器
├── SceneRenderer/          # C++20 + Vulkan/MoltenVK 场景渲染器
├── WebRenderer/            # WKWebView 网页渲染器
├── VideoRenderer/          # AVFoundation 视频渲染器
├── assets/                 # 场景运行时资源、材质、着色器、字体和 LUT
├── .github/workflows/      # macOS 自动构建与打包
└── LICENSE

独立调试渲染器

SceneRenderer/build/macos-clang-release/Tools/SceneViewer/SceneViewer <scene.pkg>
WebRenderer/build/release/Tools/WebViewer/WebViewer <web-wallpaper-directory>
VideoRenderer/build/release/Tools/VideoViewer/VideoViewer <video-wallpaper-directory>

桌面 Host 分别输出到各项目构建目录下的 Tools/SceneWallpaper、Tools/WebWallpaper 和 Tools/VideoWallpaper。

贡献

提交前请至少确认：

  1. 三个渲染器可以独立构建；
  2. ./scripts/build_all.sh 能生成完整 App Bundle；
  3. App Bundle 中包含三个渲染器、运行时动态库、MoltenVK ICD 和 assets；
  4. 没有提交 API Key、Steam 登录数据、构建目录或用户壁纸。

鸣谢

许可证

Mirage 使用 GPL-3.0 发布。Steam 服务相关第三方声明位于 SteamService/Licenses，其余第三方代码与资源继续遵循各自许可证。Mirage 与 Valve、Steam 或 Wallpaper Engine 没有关联，也未获得其官方认可。

关于 About

The most perfect live wallpaper engine for macOS, supporting web/video/scene wallpaper
mirage.simplehac.cn/
dynamic-wallpapermacosmiragemiragewallpaper

语言 Languages

C++47.4%
Swift25.0%
GLSL14.7%
Objective-C++6.7%
C#1.7%
C1.1%
JavaScript0.8%
Shell0.8%
CMake0.6%
Objective-C0.6%
CSS0.3%
Astro0.3%
TypeScript0.0%

提交活跃度 Commit Activity

代码提交热力图
过去 52 周的开发活跃度
407
Total Commits
峰值: 67次/周
Less
More

核心贡献者 Contributors