Wallpaper Engine Mac

Native macOS menu bar app for playing locally owned Wallpaper Engine-style video wallpapers.

English · 한국어

Plays the wallpaper assets you already own behind your desktop icons — hardware-decoded, battery-aware, and quiet by default.

---

✨ Highlights

• Imports Wallpaper Engine layouts — a workshop folder such as Steam/steamapps/workshop/content/431960/, an individual wallpaper folder containing project.json, a lone project.json, or a direct .mp4 / .m4v / .mov file.
• Lightweight library window — parses project.json metadata and shows downsampled preview thumbnails for supported and unsupported projects.
• Plays behind your desktop icons on every connected display via AVQueuePlayer + AVPlayerLooper (VideoToolbox hardware decoding).
• GIF scene fallback playback — plays Workshop GIF template scenes that provide an animated preview.gif.
• Automatic Light/Dark wallpapers — assign separate Light/Day and Dark/Night wallpapers and switch by macOS appearance or a simple day/night schedule.
• Lock Screen snapshot sync — when you apply a wallpaper, optionally extract a still frame and set it as the macOS desktop / lock screen wallpaper.
• Interactive image objects — add album covers or custom images on top of a wallpaper, then enable edit mode to click and drag them into place.
• Live2D / Cubism web objects — drop in a licensed local Live2D web bundle and render it as an interactive, transparent WebKit object on top of any wallpaper, sandboxed through a local-only scheme with network access blocked.
• Steam Workshop integration — open Workshop pages and items, import an already-downloaded steamapps/workshop/content/431960 folder, or fetch with a SteamCMD login for an account that owns Wallpaper Engine — without bypassing Steam or redistributing files.
• Audio responsive Workshop support — detects Workshop metadata such as audio reactive / visualizer / spectrum and automatically enables the reactive overlay; local web wallpapers are rendered through WebKit.
• Battery-first power management — pauses when the screen locks, displays sleep, Low Power Mode is on, on battery (optional), the user pauses, or the wallpaper window is occluded.
• Frees decoder resources after a long pause and recreates playback on resume.
• Muted by default, with a one-click toggle.
• Ships with a generated AppIcon.icns under Resources/.

---

🌗 Automatic Light / Dark switching

Assign a pair and let the app follow your system appearance or a day/night schedule.

☀️ Light / Day	🌙 Dark / Night
city-pop-a-long-vacation-upscaled-4k	city-pop-dark-4k-aesthetic-city-night

In the menu bar app, open Automation:

• Use Set Current as Light/Day and Set Current as Dark/Night (or the matching buttons in the library window).
• Pick Follow System Appearance to mirror macOS Light/Dark Mode.
• Pick Follow Day/Night Schedule to switch at the built-in 06:00 and 18:00 boundaries.

---

🧩 Interactive objects

Use Interactive Objects from the menu bar app to place media objects over the active wallpaper:

• Add Image Object to Current Wallpaper... copies the selected image into the active project and adds it to project.json.
• Add Video Object to Current Wallpaper... adds a muted looping .mp4, .m4v, or .mov object above the wallpaper.
• Add Live2D Web Object... copies a local Live2D / Cubism web bundle and renders it as an interactive, transparent WebKit object (see the Live2D web objects section below).
• Edit / Interact With Objects raises the wallpaper into an edit layer so objects can be clicked and dragged. Press Esc or click outside the objects to return the wallpaper behind desktop icons.
• Remove Object removes an object from project.json and deletes the app-copied asset when it lives under InteractiveObjects/.

Use the main menu's Audio Responsive toggle to show the reactive overlay. Imported Workshop items whose metadata says they are audio reactive, music responsive, visualizers, spectrums, or similar are marked Audio Responsive in the library and enable the overlay automatically when applied. For compatible scene packages, the app extracts the real background texture from scene.pkg and recreates recognized creator-configured audio bar styles, including color, bar count, spacing, lower/upper bounds, circle angles, and bottom/top/side/center/stereo/circle placement from Simple Audio Bars. Local web wallpapers are rendered through WebKit and receive a lightweight wallpaperRegisterAudioListener bridge based on the same audio level. macOS may ask for Screen Recording permission because system audio capture is provided by ScreenCaptureKit.

If macOS keeps denying audio capture after you granted permission, quit the app, remove or reset the stale Screen & System Audio Recording entry for local.wallpaper-engine-mac, reopen the exact .app bundle, and grant it again. Locally rebuilt ad-hoc signed apps can get a new code hash, so old TCC grants may not match the fresh build.

Projects can also define objects directly:

{
  "interactive": {
    "objects": [
      {
        "id": "album-cover",
        "type": "albumArt",
        "title": "Album Cover",
        "file": "InteractiveObjects/cover.jpg",
        "frame": { "x": 0.68, "y": 0.24, "width": 0.18, "height": 0.18 },
        "cornerRadius": 12,
        "draggable": true
      }
    ]
  }
}

Frame values are normalized to the screen: x and y start at the top-left, and width / height are fractions of the display.

---

🎎 Live2D web objects

Bring animated Live2D / Cubism characters onto your desktop as interactive objects, layered over any video wallpaper.

• Open Interactive Objects → Add Live2D Web Object... and choose the folder that holds your Live2D web entry file (an index.html with the Cubism runtime and model assets).
• The bundle is copied into the active project and rendered through WebKit with a transparent page and canvas background, so only the character is visible over the wallpaper.
• It loads through an app-local-only URL scheme with all network resources blocked, keeping the object fully offline and sandboxed.
• Enter Edit / Interact With Objects to drag the character into place; press Esc or click outside it to send the wallpaper back behind your desktop icons.
• Combine it with Audio Responsive to layer the character over an audio-reactive scene.

⚠️ The Live2D / Cubism runtime is not bundled with the app. Supply your own local runtime files and model assets that you are licensed to use.

---

🔒 Lock Screen snapshots

macOS does not let normal apps keep a live wallpaper window visible on the Lock Screen. When you apply a wallpaper manually, Wallpaper Engine Mac asks whether to set a matching static Lock Screen image instead. If accepted, it extracts a PNG snapshot from the wallpaper's video, image, scene fallback, or preview, sets that image as the macOS desktop wallpaper underneath the live layer, and writes the Lock Screen cache. macOS may ask for an administrator password for the cache update.

You can also run the same action later from Set Current Snapshot as Lock Screen in the menu bar app.

---

🧰 Steam Workshop helper

The app does not bypass Steam or redistribute Workshop files. The Steam Workshop menu provides helper actions around official Steam paths:

• Open Wallpaper Engine Workshop opens the public Workshop page for Wallpaper Engine.
• Open Workshop Item... accepts a Workshop URL or published file ID and opens it through Steam.
• Import Local Workshop Folder imports the local steamapps/workshop/content/431960 folder when Steam has already installed subscribed items. This is the most reliable path: subscribe in Steam first, wait for the download, then import.
• Download Item with SteamCMD Login... downloads with a Steam account that owns Wallpaper Engine. Credentials are passed to local SteamCMD for that one run and are not stored by the app.

Wallpaper Engine is a paid Steam app, so Workshop downloads normally require account login. Deleted, hidden, incompatible, age-gated, or region-restricted items can still fail even with account login.

Audio responsive Workshop projects are supported through the app's overlay, scene package extraction, and web audio bridge. Native Wallpaper Engine scene packages (.pkg) are imported as playable entries, but they are not executed as a full engine yet; supported scene items use extracted textures, TEX conversion for common RGBA/DXT + LZ4 textures, animated GIF reconstruction for GIF template scenes, and recognized audio effects when available. Packages that use an unknown texture layout still show a scene-package placeholder instead of being handed to the video player. The package reader accepts PKGV**** archives that keep the known entry-table layout, but dynamic text objects such as clocks and dates are intentionally ignored until full scene composition exists. Tiny square scene previews, such as Workshop icon GIFs, are ignored as playable fallbacks so they are not accidentally stretched across the desktop.

---

🖼️ Bundled sample wallpapers

These are arranged as Wallpaper Engine-style video projects so you can import them directly for a quick local test.

Ambient Test Loop SampleWallpapers/ambient-test-loop 4K · 10s · 30 fps	Abstract Macro Fluid SampleWallpapers/mixkit-abstract-macro-fluid-background 1080p · ~13s
City Pop — A Long Vacation ☀️ city-pop-a-long-vacation-upscaled-4k Upscaled 4K · 60 fps	Aesthetic City at Night 🌙 city-pop-dark-4k-aesthetic-city-night 4K · 30 fps

---

🚀 Run

swift run WallpaperEngineMac

The app appears in the menu bar. Use Import Folder or Video to add local assets, then apply a supported video wallpaper from the menu or the library window.

To build the Finder app bundle:

./Scripts/build-app.sh
open ".build/app/Wallpaper Engine Mac.app"

🧪 Test

swift run WallpaperEngineSmokeTests

---

📦 Project layout

WallpaperEngineMac/
├── Sources/
│   ├── WallpaperEngineCore/   # project.json parsing, library scanning
│   ├── WallpaperEngineMac/    # menu bar app, renderer, power manager
│   └── WallpaperEngineSmokeTests/
├── SampleWallpapers/          # importable sample video projects
├── Resources/                 # AppIcon
└── Scripts/build-app.sh       # bundles a .app

---

🎬 Credits & licensing

Each sample folder ships a SOURCE.md with full attribution. Summary:

Sample	Source	License / Note
Ambient Test Loop	Pixabay 4K ambient loop	Local test fixture
Abstract Macro Fluid	Mixkit	Mixkit Free License
City Pop — A Long Vacation	DesktopHut	Personal local use; upscaled
Aesthetic City at Night	MotionBgs	Rights remain with original creators

The app source code is available under the MIT License. Bundled sample wallpapers are not relicensed by this project; they are included for local testing only under each source's terms.

This app does not download or redistribute Wallpaper Engine workshop content. It only plays assets the user has already obtained and imported locally. Please respect each source's terms before reusing bundled sample assets.