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 intelligently pans images to fit your screen aspect ratio. Plus, our advanced Face Crop and Face Boost technology ensures people are perfectly framed—no more chopped-off heads!

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

---

MIT License - Copyright (c) 2025 Karl Kwong