Wallpaper Changer for macOS

Lightweight app for setting wallpapers on all spaces of all displays.

Features

• Comfy GUI with adaptive light/dark mode.
• Set a random wallpaper from the dark or light directory, or from either.
• Set a black wallpaper.
• Add effects to the current wallpaper:
  • Pixelate
  • Blur
  • Darken
  • Undo all effects

Quick Start

1. Get a local copy of this project

Clone this repo:

git clone https://github.com/mapleroyal/Wallpaper-Changer-for-macOS.git

2. Install the dependencies

Navigate your terminal to the cloned repo, then run:

npm install

3. Run the development build:

From the project directory, run:

npm run dev

That will build the app in a temporary state, and launch it for immediate use and development (with hot-reloading).

Installation

1. Follow the quick start steps, but on step 3 run npm run build instead of npm run dev.

2. Install or run the app

From the project root, the app will be at /dist/mac-arm64/Wallpaper Changer for macOS.app. It can be run directly from there by double clicking the file, or "installed" by dragging the file to ~/Applications.

For debugging (terminal output), right click on the .app file and select "Show Package Contents", and from there navigate to Contents > MacOS. You will see the app's binary file, named Wallpaper Changer for macOS. Drag it into your terminal and press Return to run the app from the terminal, where errors and debugging outputs will show.

🚨 NOTE:

The app looks for wallpapers in these two directories:

~/Pictures/wallpapers/dark

~/Pictures/wallpapers/light

Support for custom directories and subdirectories is on the roadmap.

Documentation

This app uses ImageMagick on the backend to manipulate images.

To set a wallpaper on all spaces and displays, it sends the command

/usr/libexec/PlistBuddy -c "set AllSpacesAndDisplays:Desktop:Content:Choices:0:Files:0:relative file:///${wallpaperPath}" "${PLIST_PATH}" && killall WallpaperAgent

where

const PLIST_PATH = join(homedir(), "Library", "Application Support", "com.apple.wallpaper", "Store", "Index.plist");

In this MVP, all functionality is contained in the home view component src/renderer/components/Home.vue and the main process file src/main/main.ts.

License

This project is licensed under the GPL2 License, with some of the template using the MIT License. See the LICENSE file for details.

Acknowledgments

• electron-vue-template by Deluze https://github.com/Deluze/electron-vue-template?tab=MIT-1-ov-file
• imagemagick https://imagemagick.org/script/license.php

Known Bugs

• Works on my machine. On a friend's machine, applying anything causes the wallpaper to flash and then change to a system default wallpaper, suggesting that at least the killall WallpaperAgent is working. I suspect the app functionality is also working (e.g. manipulating wallpaper files, and possibly even setting them), but something about how it interfaces with macOS needs to be debugged.

Roadmap

Short term:

• Get all features (at this point, basically the effects) working in a production build like they do in dev.
• Add buttons to reset the sliders to their default values.
• Allow the app to run in the menu bar for quick access.
  • Menu bar item context menu
  • Automatic cycling on a schedule
• Option to start app with the system.

Longer term:

• Allow to set a wallpaper by dragging it into the app. (There are simpler and even built-in ways to set a wallpaper, but they don't set it across all spaces on all monitors.)
• User-specified directories.
  • Support for subdirectories.
  • In this case, allow to select multiple directories to find a random wallpaper from.
• Automatically darken/lighten the wallpaper when the system light/dark state changes.

Changelog

• 0.6 All basic functionality working in the built app
• 0.5 MVP for development environment