Mirage — a native live wallpaper engine for macOS (scene / web / video, Wallpaper Engine compatible)

[laobamac_yyds]

Hi everyone,

I'm laobamac. Some of you may know me from my Hackintosh work here — this time I'm sharing something different: Mirage, a native live wallpaper manager and renderer for macOS that I've been building over the past months.

 

macOS still has no real answer to animated wallpapers. The tools that do exist are usually a video player behind a window, and none of them can run the enormous library of content people already own on Windows. Mirage takes the other route: it's a native SwiftUI/AppKit app with three dedicated renderer processes, and it can play scene, web, and video wallpapers — including Wallpaper Engine–style packages straight from the Steam Workshop.

 

It's free and open source (GPL-3.0), Intel and Apple Silicon, no ads, no accounts, no telemetry.

• Source: https://github.com/laobamac/MirageWallpaper
• Documentation (CN): https://mirage.simplehac.cn/
• Documentation (EN): https://mirage.simplehac.cn/en/
• Downloads: https://github.com/laobamac/MirageWallpaper/releases

 

 

---

What it does

Three wallpaper types, three real renderers

Component	Tech	Job
Mirage	SwiftUI + AppKit	Library, Workshop, settings, process management, macOS integration
SceneWallpaper	C++20 + Vulkan via MoltenVK	scene.pkg / scene.json: materials, particles, LUTs, text, user properties
WebWallpaper	Objective-C++ + WKWebView	HTML/JS wallpapers, media, mouse events, user properties
VideoWallpaper	Objective-C++ + AVFoundation	Looping video, volume, playback rate, fill mode
MirageScreenSaver	Swift + WebKit/AVFoundation/Metal	Standalone live screen saver

Renderers are separate processes driven by line-delimited JSON over stdin, so a misbehaving wallpaper can't take the app down with it. Scene playback goes through Vulkan → MoltenVK → Metal, with zero-copy VideoToolbox frame import for video layers inside scenes.

Wallpaper library

• Search, sorting, filters by type/source/tag/content rating, favorites.
• Import any folder containing a project.json, or drop in an .mp4 / .mov / .m4v and Mirage wraps it into a local wallpaper package for you.
• Reads wallpapers from the system Steam client, Mirage's own SteamCMD directory, and any custom folders you add.

Steam Workshop integration

• Browse trending / recent / popular / top-rated and tag-filtered Workshop content in-app.
• Managed SteamCMD install in an isolated directory (it does not touch your real Steam client data), Steam sign-in with Steam Guard (code or mobile confirmation), and a persistent authenticated session instead of re-logging in for every download. Your password is handed to the local SteamCMD process only and is never sent to a third-party server; logs redact secrets.
• Download queue with real launch/connect/download/validate/complete states and progress.
• Workshop presets are detected and labelled; if a preset needs a base wallpaper you don't have, Mirage tells you its name and size and asks before pulling it too.
• Browsing uses the Steam Web API. There's a shared built-in key, but you can drop your own into Settings → General to dodge the shared rate limit.

Playback and macOS integration

• Multi-display coverage, menu-bar controls, launch at login, desktop placeholder image restore.
• Per-wallpaper volume, playback rate, fill mode, plus whatever custom properties the wallpaper author exposed.
• Wallpaper Engine–style playlists with per-screen rotation and transitions.
• Power/behaviour rules: continue, mute, pause, or stop when another app goes fullscreen, when another app plays audio, when the display sleeps, or when you're on battery.
• Survives the macOS "click the wallpaper to reveal the desktop" interaction and resumes properly.
• Web wallpapers get a security confirmation before their first run.

Live screen saver Mirage ships a standalone MirageScreenSaver.saver you install from Settings → Screen Saver. It plays video, web, and scene wallpapers, keeps your chosen preset and custom properties, and does not require Mirage to be running.

 

---

Honest status

Mirage is early. Video and web wallpapers are in good shape. Scene compatibility is the hard part — it means reimplementing another engine's material, particle, shader, and scripting behaviour — and it's improving steadily, but complex scenes can still look wrong or miss effects. It is not, and may never be, a pixel-perfect clone.

But now the rendering engine of Mirage can achieve more than 90% of the scene wallpaper effect, which is perfect enough! And I will continue to update this project in the future.

Also worth stating plainly: Mirage is an independent, clean-room implementation. It ships no Wallpaper Engine code or assets, and it doesn't bypass anything — Workshop downloads happen through official SteamCMD under your own Steam account.

If something breaks, a GitHub Issue with your macOS version, app version, repro steps, and logs is the fastest way to get it fixed. Reports of specific Workshop items that render incorrectly (with the item link) are especially useful — that's exactly how scene compatibility gets better.

Feedback, testing on unusual configurations, and PRs are all very welcome. Thanks for reading.

— laobamac