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

• � 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 Unsplash & Pexels Integration: Securely log in to Unsplash or browse Pexels to access millions of professional, high-quality photos.

• 🏛️ 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: Ctrl + Alt + Right Arrow
  • Previous: Ctrl + Alt + Left Arrow
  • Pause/Resume: Ctrl + Alt + Up Arrow
  • Trash/Block: Ctrl + Alt + Down Arrow

• 🏷️ 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.

For Windows

1. Download Spice-Setup-x.y.z-amd64.exe.
2. Double-click to install.

For macOS (Apple Silicon)

1. Download Spice-vx.y.z-arm64.dmg.
2. Open the .dmg and drag Spice into your Applications folder.

🚀 Usage

Tips

• Unsplash: You can revoke Spice's access at any time from your Unsplash Account Settings.
• 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.

🔮 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: Expanding our platform reach.
• More Providers: Adding support for other wallpaper sources.

⚠️ 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