Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dixieflatline76/spice

Spice - A Modern Wallpaper Manager for Windows and MacOS
https://github.com/dixieflatline76/spice

fyne go golang macos multiplatform pexels-downloader spice unsplash-client wallhaven wallhaven-downlader wallpaper wallpaper-changer wikimedia-commons windows

Last synced: 28 days ago
JSON representation

Spice - A Modern Wallpaper Manager for Windows and MacOS

Awesome Lists containing this project

README 

          


Spice logo



Spice - Spice Up Your Desktop 🌶️





  Build Status

  Go Report Card

  Latest Release

  Chrome Web Store

  Firefox Add-ons




Spice is a minimalist wallpaper manager that brings a continuous stream of delight to your screen while not getting in your way. It automatically downloads high-quality wallpapers from your favorite image services like Wallhaven and Unsplash, keeping your desktop fresh and fun.



**Note:** Spice runs quietly in your **Windows system tray** or **macOS menu bar**, doing its magic in the background while giving you full control when you need it.





  Spice Screenshot




## ✨ Key Features



* **🔗 Browser Companion:** Use our [**Chrome Extension**](https://chromewebstore.google.com/detail/ekodikedjmhnganfcfleabcfohdjkoeb) or [**Firefox Add-on**](https://addons.mozilla.org/en-US/firefox/addon/spice-wallpaper-manager/) to instantly add wallpapers from the web to your desktop.

  > **Pin the extension to your toolbar.** It will flash when it detects a supported image collection (like Wallhaven or Unsplash). Simply click the Spice icon to send the current view to your desktop! Supports Chrome, Firefox, and Safari with LiveSync technology.



* **� Automated Inspiration:** Spice handles the heavy lifting—fetching, caching, and cycling wallpapers based on your preferences so you always have something new to look at.



* **� Wallhaven Integration:** Our original and primary source! Access the vast library of **Wallhaven.cc** with full support for API keys, NSFW filters, and your private collections (Favorites).



* **📸 Native Pexels Integration:** Browse **Pexels** to access millions of professional, high-quality photos.



* **🖼️ Google Photos:** Connect your personal cloud! Securely browse and select your favorite albums or photos from your **Google Photos** library using the native Google Photos Picker.

  > [!NOTE]

  > **Google Photos is currently in "Test Mode".** To use this feature, you must be added as a beta tester. Please [**Open a GitHub Issue**](https://github.com/dixieflatline76/Spice/issues) or [**Start a Discussion**](https://github.com/dixieflatline76/Spice/discussions) with your request to be added!

 

* **❤️ Local Favorites:** Love a wallpaper? Mark it as a favorite to save a permanent local copy. You can then switch to your "Favorite Images" collection to cycle exclusively through your best picks.

  > **Tip:** Selected "Favorite Images" as your source? Click the **"Source: Favorites"** text in the menu to instantly open your local favorites folder in Finder/Explorer.



* **🏛️ Wikimedia Commons:** Access the wealth of human history and nature with support for **Featured Pictures** and Category composition on Wikimedia Commons.



* **📏 Smart Fit with Face Detection:** Never worry about bad crops again. **Smart Fit Mode** lets you choose between **Standard (Strict)** aspect ratio matching or **Relaxed (Aggressive)** usage of high-res images. Plus, our advanced **Face Boost** technology ensures people are perfectly framed—no more chopped-off heads!



* **⚡ Ultra-Responsive:** Built with advanced concurrency patterns and "Debounced Persistence" to ensure the UI stays buttery smooth, even when managing large collections or downloading in the background.



* **⏯️ Pause & Resume:** Found a wallpaper you absolutely love? Simply **Pause** the rotation to keep it for as long as you want, then **Resume** when you're ready for something new.



* **⌨️ Global Hotkeys:** Control Spice instantly from anywhere:

  * **Next / Previous:** `Ctrl + Alt + Right/Left` (Windows) / `Cmd + Opt + Right/Left` (macOS)

  * **Favorite:** `Ctrl + Alt + Up` / `Cmd + Opt + Up` (Strict Add)

  * **Trash/Block:** `Ctrl + Alt + Down` / `Cmd + Opt + Down`

  * **Pause/Resume:** `Ctrl + Alt + P` / `Cmd + Opt + P`

  * **Preferences:** `Ctrl + Alt + O` / `Cmd + Opt + O`



* **🏷️ Enhanced Attribution:** Know the artist! Spice displays the real uploader or photographer name directly in the tray menu, updating *instantly* with every wallpaper change.



* **⛔ Blocklist:** Don't like a wallpaper? Trash it with a hotkey or click, and Spice will block it forever.



## Developers



* **Architecture:** Curious how Spice works under the hood? Read our [**Architecture Documentation**](docs/architecture.md) for a deep dive into our Single-Writer concurrency model.

* **New Providers:** Want to add your own wallpaper source? Check out our [**Provider Creation Guide**](docs/creating_new_providers.md) to learn how to implement the `ImageProvider` interface in minutes.

* **New Plugins:** Want to extend Spice with completely new features? Read our [**Plugin Development Guide**](docs/creating_new_plugins.md).



## 📦 Installation



Head to the [**Releases Page**](https://github.com/dixieflatline76/Spice/releases/latest) to download the installer for your OS.



### 🌐 Browser Companion Extension



*   **Chrome / Brave / Edge:** [**Install from Chrome Web Store**](https://chromewebstore.google.com/detail/ekodikedjmhnganfcfleabcfohdjkoeb)

*   **Firefox:** [**Install from Firefox Add-ons**](https://addons.mozilla.org/en-US/firefox/addon/spice-wallpaper-manager/)

*   **Safari:** Included in the macOS App.



### For Windows



1.  Download `Spice-Setup-x.y.z-amd64.exe`.

2.  Double-click to install.

3.  *(Optional)* Find the **Spice Chrome Extension** on the [**Chrome Web Store**](https://chromewebstore.google.com/detail/ekodikedjmhnganfcfleabcfohdjkoeb) and click **Add to Chrome**.



### For macOS (Apple Silicon)



1.  Download `Spice-vx.y.z-arm64.dmg`.

2.  Open the `.dmg`.

3.  Drag **Spice.app** into your **Applications** folder.

4.  *(Optional)* Drag **Spice Wallpaper Manager Extension.app** into your **Applications** folder if you want Safari support.

5.  **Enable the Safari Extension:**

    *   Open Safari Settings > Extensions.

    *   Check the box for **Spice Wallpaper Manager**.

    *   Click "Always Allow on Every Website" to ensure seamless detection.



## 🚀 Usage



### Tips



* **Wallhaven Favorites:** To use your private collection, use the URL format with your User ID: `https://wallhaven.cc/user//favorites/`, rather than the generic favorites link.

* **Disable Local Favorites:** To turn off the "Favorite Images" provider, simply uncheck the "Active" box next to its query in the **Spice Preferences** > **Wallpaper** tab.



## 🔮 Roadmap



We have big plans for Spice!



* **Multi-Monitor Support:** Bringing Spice to all your screens, not just the main one.

* **Linux & Intel Mac Support:** While we currently focus on Apple Silicon (arm64), we plan to expand our official builds to Intel Macs and Linux.

* **More Providers:** Adding support for other wallpaper sources like **Pixabay** and **The Met Open Access**.

* **Local Collections:** Point Spice to any folder on your computer to use your existing wallpaper library.



## ⚠️ Known Limitations



* **Blocklist Editing:** You can currently reset the whole blocklist, but removing single images is coming soon.



## 💬 Feedback



Found a bug or have an idea? Please open an issue on [GitHub](https://github.com/dixieflatline76/Spice/issues).



---

Privacy Policy | MIT License - Copyright (c) 2025 Karl Kwong