laobamac/MirageWallpaper
laobamac/MirageWallpaper has 704 GitHub stars and 25 forks. Star changes are not measured yet. Last checked 2026-11-15 23:35 UTC. Last push 2026-11-08.
Measured star growth
- in 24h
- Update delayed
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
The most perfect live wallpaper engine for macOS, supporting web/video/scene wallpaper
Creative & MediaREADME_EN.md
Original
Mirage
English · 简体中文
A native macOS live-wallpaper manager and a compatible runtime for Wallpaper Engine content.
[!IMPORTANT] Mirage is still in an early stage. If you encounter a problem, please file a detailed GitHub Issue with your macOS/App version, reproduction steps, expected and actual results, and relevant logs. You can also join the QQ feedback group: 2160040437.
Mirage uses SwiftUI and AppKit for wallpaper browsing, management, and macOS integration. Three independent renderer processes play scene, web, and video wallpapers. It can discover local Wallpaper Engine-style wallpaper packages, browse the Steam Workshop, sign in to Steam, and download supported Workshop items.
Mirage is actively developed. Compatibility with Wallpaper Engine scene content is still improving, and complex works may differ in effects, scripts, or materials.
Support Mirage
Mirage will remain free and open for development. If it brings value to your desktop, voluntary support is warmly appreciated; every contribution helps fund maintenance, compatibility improvements, and new features. Sponsorship is entirely optional and never affects functionality.
| Afdian | WeChat Pay | Alipay |
|---|---|---|
![]() Click the image to open Afdian |
![]() |
![]() |
International users may also support via USDT:
0xFc0a5C52e3A085FEc7b077FE3D2C413114Bf880D
Please independently verify the network, address, and amount before transferring.
Highlights
- Supports
scene,web, andvideolive wallpapers. - Browses installed wallpapers with search, sorting, type/source/tag/content-rating filters, and favorites.
- Imports directories containing
project.json, or turns.mp4,.mov, and.m4vfiles into local wallpaper packages. - Browses Workshop trending, recent, popular, top-rated, and tag-based content.
- Detects and downloads Workshop presets; asks before downloading a required base wallpaper.
- Includes an embedded Steam service based on SteamKit2 3.4.0, with QR, password, and Steam Guard sign-in. Refresh tokens are stored in macOS Keychain.
- Calls SteamKit2 manifest and CDN APIs directly for Workshop downloads. The implementation follows proven design patterns from DepotDownloader without bundling or launching its executable.
- Reuses one persistent Steam session instead of starting and signing in again for every download.
- Downloads up to three Workshop items concurrently with live CDN byte counts, speed, progress, and estimated time remaining. Each task can be canceled independently.
- Plays downloaded works directly and exposes volume, playback rate, fill mode, position, and wallpaper-provided properties.
- Per-display playlists can rotate wallpapers by timer, logon, time of day, day of week, or video end, with sorted/random order and transitions.
- Supports multi-display coverage, menu-bar controls, login launch, the subscribed-items tab, and restoring a desktop placeholder image.
- Installs Mirage's standalone dynamic screen saver, which independently plays video and scene wallpapers while retaining the selected preset and custom properties.
- Offers two experimental dynamic lock-screen schemes: Scheme A requires macOS 26+, Scheme B requires macOS 14.2+; both support video and scene wallpapers only.
- Optionally follows desktop wallpaper selections and playlist changes for the screen saver and dynamic lock screen independently, using the system main display by default or a selected source display.
- Lets you continue, mute, pause, or stop playback when another app is fullscreen, another app plays audio, the display sleeps, or the Mac is on battery.
- Restores playback after macOS "click wallpaper to reveal desktop" interaction.
- Shows a security confirmation before first running a web wallpaper and supports Wallpaper Engine user properties and mouse events.
Rendering Architecture
| Component | Technology | Responsibility |
|---|---|---|
| Mirage | SwiftUI, AppKit | UI, wallpaper library, Workshop, settings, process management, and macOS integration |
| SceneWallpaper | C++20, Vulkan, MoltenVK | scene.pkg / scene.json, materials, particles, LUTs, text, and user properties |
| WebWallpaper | Objective-C++, WKWebView | HTML wallpapers, JavaScript, media, mouse events, and user properties |
| VideoWallpaper | Objective-C++, AVFoundation | Video looping, volume, playback rate, and fill mode |
| MirageScreenSaver | Swift, WebKit, AVFoundation, Metal | Independently installed dynamic screen-saver host |
Renderers run as separate processes. Mirage sends line-delimited JSON control messages through standard input, so a renderer failure does not directly corrupt the main application.
Steam Workshop
Mirage uses two independent Steam integrations:
| Purpose | Service | API key required? |
|---|---|---|
| Browsing, search, and Workshop metadata | Steam Web API | Yes |
| Sign-in, Steam Guard, and downloading works | Embedded Steam service (SteamKit2; download flow informed by DepotDownloader) | No; a Steam account is required |
The built-in Steam Web API key is only used for initial browsing and is shared by all users. To avoid shared-rate-limit congestion, set your own key in Settings → General → Steam API Key. Obtain one from the Steam API Key page.
Users in mainland China can choose the SteamCF browsing mirror in Settings. It only proxies Workshop browsing APIs; it does not accelerate Steam sign-in or content downloads and is only available in mainland China.
Mirage writes downloaded content to its own directory instead of reusing the system Steam client's data:
~/Library/Application Support/Mirage/Workshop/content/431960
After sign-in, the Steam session remains active while Mirage runs. Mirage resolves items concurrently through the shared session and uses bounded CDN chunk concurrency to serve up to three items fairly. Canceling one task does not interrupt other downloads.
Mirage directly depends on SteamKit2 to communicate with Valve services. Its overall approach to manifest resolution, CDN server selection, chunk transfer, validation, and resumable reuse is informed by DepotDownloader. Mirage uses its own embedded service and task scheduler; it does not include the DepotDownloader command-line application or launch an external downloader.
Workshop presets are explicitly marked in browsing, details, download management, and installed views. A preset contains property values and optional assets, but depends on a base wallpaper. If the dependency is installed, selecting the preset applies it immediately and opens customization. Otherwise, Mirage displays the dependency's name and size and asks whether to download it as well. Presets and base wallpapers remain separate installed items.
Wallpaper Package Format
A wallpaper directory uses project.json as its entry point:
wallpaper-folder/
├── project.json
├── preview.jpg
└── wallpaper-file
Minimal video-wallpaper example:
{
"title": "My Wallpaper",
"type": "video",
"file": "demo.mp4",
"preview": "preview.jpg"
}
type |
Typical entry | Renderer |
|---|---|---|
scene |
scene.pkg, scene.json |
SceneWallpaper |
web |
An HTML file, usually index.html |
WebWallpaper |
video |
A common video file | VideoWallpaper |
Mirage resolves the declared entry point and supports some non-standard directory layouts for compatibility. A valid project.json is still required.
System and Build Requirements
- Intel (
x86_64) or Apple Silicon (arm64) Mac - macOS 14.2 or later
- Full Xcode installation
- Homebrew
- CMake 4.3.1 or later
- .NET 10 SDK
- Homebrew LLVM, Ninja, pkg-config, MoltenVK, Vulkan Loader/Headers, glslang, GLFW, FreeType, Fontconfig, LZ4, and FFmpeg
Install dependencies:
xcode-select --install
brew install cmake ninja pkg-config llvm molten-vk vulkan-loader vulkan-headers \
glslang glfw freetype fontconfig lz4 ffmpeg dav1d nasm
Renderer scripts automatically build a pinned decoder-only FFmpeg. Mobile scene export separately bundles Homebrew FFmpeg and a pinned EtcTool, including their required libraries and licenses. dav1d supplies AV1 decoding; nasm supplies Intel assembly support.
Build from Source
git clone https://github.com/laobamac/MirageWallpaper.git
cd MirageWallpaper
MIRAGE_ALLOW_NETWORK_FETCH=1 ./scripts/build_all.sh
open "Mirage/dist/Mirage.app"
The resulting application is located at:
Mirage/dist/Mirage.app
The app includes MirageScreenSaver.saver, which can be installed from Settings → Screen Saver. It is copied to ~/Library/Screen Savers for the current user and does not require Mirage to remain running. The packaging script embeds the scene screen-saver runtime and required resources.
build_all.sh builds the three renderers, Steam service, and main app in order, then packages the complete app bundle. Use ./scripts/build_all.sh debug for a Debug build or ./scripts/build_all.sh app to rebuild only the app.
Set MIRAGE_ALLOW_NETWORK_FETCH=1 for the first package build to fetch and verify the pinned Etc2Comp source. Once the source is cached, the variable can be omitted. Offline packaging requires this cache to be prepared beforehand.
Configure a Built-in Steam Web API Key Locally
The source tree does not contain a default API key. For a complete local package, place your key in a Git-ignored file:
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 reads this file, writes it through a temporary xcconfig into the App's Info.plist, and removes the temporary configuration when the build ends. You can instead provide the environment variable for one command:
MIRAGE_STEAM_WEB_API_KEY='YOUR_32_CHARACTER_STEAM_WEB_API_KEY' \
./Mirage/scripts/build.sh Release
Without a built-in key, the App still builds normally; set a key in Settings after launching it.
GitHub Actions Packaging
Build macOS App uses macos-15-intel and macos-15 to build all three renderers and Mirage for x86_64 and arm64 when:
- changes are pushed to
main; - a tag beginning with
vis pushed; or - the workflow is run manually from the Actions page.
Before the first run, add these Repository Secrets in Settings → Secrets and variables → Actions:
MIRAGE_STEAM_WEB_API_KEY 32-character Steam Web API key
MIRAGE_SPARKLE_PRIVATE_KEY Mirage's Sparkle Ed25519 private key
APPLE_DEVELOPER_ID_APPLICATION_P12 Base64-encoded Developer ID Application P12 certificate
APPLE_DEVELOPER_ID_APPLICATION_P12_PASSWORD P12 certificate password
APPLE_NOTARY_APPLE_ID Apple ID
APPLE_NOTARY_PASSWORD Apple ID app-specific password
APPLE_DEVELOPER_TEAM_ID Apple Developer Team ID
If GitHub CLI is installed locally, you can run:
gh secret set MIRAGE_STEAM_WEB_API_KEY < .secrets/steam_web_api_key
MIRAGE_SPARKLE_PRIVATE_KEY is only used by Actions to generate Ed25519-signed updates and appcasts. Never commit it. Keep the original key in a logged-in keychain and maintain an offline backup. The client only contains the public key.
To compile the optional sign-in-free download component in the same Action, keep its source in a separate private repository and configure MirageWallpaper as follows:
| Type | Name | Value |
|---|---|---|
| Repository variable | MIRAGE_DIRECT_WORKSHOP_REPOSITORY |
The private component repository's owner/name |
| Repository variable | MIRAGE_DIRECT_WORKSHOP_REF |
Its full 40-character commit SHA, shared by both architecture builds |
| Repository secret | MIRAGE_DIRECT_WORKSHOP_DEPLOY_KEY |
An SSH deploy private key restricted to reading that repository; add its public key under the private repository's Deploy keys without write access |
The private repository must contain Service, Tests/Tests.csproj, Tests/Program.cs, build.sh, and LICENSE. Preserve the existing public Service/VerificationKey.cs; do not regenerate the signing identity. Do not commit secrets/, the activation signing private key, or test activation codes, or supply them to Actions. The workflow fetches the pinned commit into the runner's temporary directory, tests and compiles the helper, and bundles only its dist binaries. Private source and compiler logs are never uploaded as artifacts. Packaging verification checks that the helper starts and rejects an invalid activation code.
Leaving all three settings unset builds the standard edition. Partial configuration or a private build failure fails the job rather than silently omitting the feature. After updating the component, update MIRAGE_DIRECT_WORKSHOP_REF and run the Action manually or trigger the next main repository build. Changes to the private repository alone do not trigger the main workflow.
The workflow writes the full Git commit and an incrementing build number from git rev-list --count into the App. No manual version bump is required. Only a build with a greater build number is installed, preventing a newer development build from being downgraded to an older release.
- Pushing a
v*tag creates a normal GitHub Release and stable update feed. - Pushing to
mainreplaces the rollingprereleaseGitHub Release and beta update feed. - The App checks and downloads stable updates automatically by default. Turning off automatic updates in Settings → Software Update stops background checking/downloading but keeps manual checks available. Enabling prerelease updates also checks the beta channel.
- Each architecture uses an independent appcast. Update archives, appcasts, and release notes are signed with Sparkle Ed25519.
On the next launch after updating, Mirage also checks any installed MirageScreenSaver.saver. It atomically replaces the installed component and restarts relevant screen-saver services only when its build number is older than the App's bundled component.
GitHub Secrets prevent a key from appearing in the repository and ordinary build logs, but they cannot make a key embedded in a distributed client truly secret. Anyone capable of inspecting the App can extract it. If a non-extractable credential is required later, move the request to a controlled server that holds the key; do not rely on client-side obfuscation.
The workflow imports the Developer ID Application certificate into a temporary keychain, signs the complete App with Hardened Runtime and a secure timestamp, submits it to Apple for notarization, staples the ticket, and verifies its signature, ticket, and Gatekeeper acceptance before packaging. Sparkle Ed25519 signing continues to protect the authenticity of subsequent updates independently.
Data Directories
| Data | Default location |
|---|---|
| Mirage local wallpapers | ~/Library/Application Support/Mirage/Wallpapers |
| Mirage Workshop downloads | ~/Library/Application Support/Mirage/Workshop/content/431960 |
| System Steam Workshop content | ~/Library/Application Support/Steam/steamapps/workshop/content/431960 |
| Workshop preview cache | ~/Library/Caches/Mirage/WorkshopCache |
| Wallpaper runtime settings | UserDefaults |
| Dynamic screen-saver configuration | ~/Library/Application Support/Mirage/screensaver.json |
| Installed dynamic screen saver | ~/Library/Screen Savers/MirageScreenSaver.saver |
Mirage discovers valid works from the system Steam client, the Mirage download directory, and custom directories.
Repository Layout
.
├── Mirage/ # SwiftUI / AppKit application and packaging scripts
│ └── Mirage Screen Saver/ # Standalone dynamic screen-saver target
├── SteamService/ # SteamKit2 authentication service and DepotDownloader-informed downloader
├── SceneRenderer/ # C++20 + Vulkan/MoltenVK scene renderer
├── WebRenderer/ # WKWebView web renderer
├── VideoRenderer/ # AVFoundation video renderer
├── assets/ # Scene runtime assets, materials, shaders, fonts, and LUTs
├── .github/workflows/ # macOS build and packaging automation
└── LICENSE
Run Renderers Independently
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>
Desktop hosts are produced under each renderer's build directory: Tools/SceneWallpaper, Tools/WebWallpaper, and Tools/VideoWallpaper.
Contributing
Before submitting a change, verify at least that:
- All three renderers build independently.
./scripts/build_all.shproduces a complete App bundle.- The App bundle contains all three renderers, runtime libraries, the MoltenVK ICD, and
assets. - No API keys, Steam sign-in data, build directories, or user wallpapers are committed.
Development Team
| Name | Role | GitHub |
|---|---|---|
| Xiaoci Wang | Project Author · Developer | @laobamac |
| Jiale Yu | Developer | @dawalishi821 |
| Pikachu Ren | Developer | @PIKACHUIM |
| Yinan Qin | Developer | @elysia-best |
Acknowledgements
- SteamKit2 — direct dependency of Mirage's embedded Steam service; version 3.4.0, licensed under LGPL-2.1.
- DepotDownloader — an important design reference for Workshop manifest, CDN chunk download, and validation flows; licensed under GPL-2.0. Mirage does not bundle its executable.
- MoltenVK for runtime translation.
- wallpaper-engine-mac for the UI framework.
- waywallen/ParticleSystem for the particle-system reference.
- laobamac/OpenMetalWallpaper for model parsing.
- rstd.
License
Mirage is released under GPL-3.0. Steam service notices are stored in SteamService/Licenses; all other third-party code and resources remain under their respective licenses. Mirage is not affiliated with or endorsed by Valve, Steam, or Wallpaper Engine.
The standalone editor integration in StandaloneEditor/ is provided under the proprietary terms in its README, outside the main project's GPL-3.0 license scope. Wallpaper Engine's proprietary executables, interface code, and resources are not included in this repository.
Optional sign-in-free Workshop downloads are disabled by default and require a device-specific activation code in Settings → General. This mode supports downloads only, without Steam subscriptions, favorites or comments. Its independent helper is not included in this open-source repository; builds without it retain normal Steam downloads. Release builds can supply a precompiled component using MIRAGE_DIRECT_WORKSHOP_BUNDLE. Do not include private source or activation signing material in this repository.


