Spice

README

Spice - Spice Up Your Desktop 🌶️

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.

✨ Key Features

• 🔗 Browser Companion: Use our Chrome Extension or Firefox Add-on 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 or Start a Discussion 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 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 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.

📦 Installation

Head to the Releases Page to download the installer for your OS.

🌐 Browser Companion Extension

• Chrome / Brave / Edge: Install from Chrome Web Store
• Firefox: Install from Firefox Add-ons
• 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 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/<username>/favorites/<id>, 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.

---

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