A wallpaper setter gui, developed with ricing in mind! 🍚

Why

How to install

Usage

TODO

Gallery

Special Thanks

Important

Project Status: This project was inactive for a while as I moved into a DevOps engineering role and didn't have the time to maintain it. I've recently come back to active development and the project is undergoing a major rewrite. Waypaper Engine is not abandoned or archived — it's being rebuilt from the ground up with a new Go daemon backend, pluggable wallpaper backend support, and a modernized UI. The current main branch reflects the older codebase; the rewrite is happening on the refactor/wayaper-daemon branch and will be merged once stable. Expect breaking changes, new features, and updated install instructions when the rewrite lands.

What's New (v3 Rewrite)

The rewrite replaces the old Node.js backend with a Go daemon and overhauls the frontend. Here's what's been implemented so far:

Architecture

• Go daemon backend — A standalone Go service that handles all wallpaper, playlist, image, and monitor operations over a Unix socket HTTP API. Replaces the old Node.js/SQLite backend entirely. No more node dependency issues breaking the app.
• Pluggable wallpaper backends — Support for swww, hyprpaper, feh, and many more to come, with a registry that allows runtime switching. No longer locked to swww, and laying the ground work for my next project, a wallpaper setter that can render animations just like lively wallpaper or waypaper engine! :).
• CloverDB storage — Lightweight embedded database replacing SQLite, managed entirely by the daemon.
• Server-Sent Events (SSE) — Real-time event streaming from daemon to frontend for image processing progress, wallpaper changes, playlist updates, and config changes.
• Cobra CLI — Full CLI (start, stop, status, set, random, next, previous, image/playlist/monitor/backend/config management) that talks to the running daemon over the socket.

Features

• Image renaming — Rename images from the gallery (inline or detail sidebar), with automatic deduplication and physical file rename on disk. Playlists are unaffected since they reference images by stable IDs.
• Wallhaven integration — Search, browse, and download wallpapers from Wallhaven directly into your gallery.
• URL/drag-and-drop import — Drop image URLs or files onto the window to import them. HTTP(S) URLs are downloaded automatically.
• Image detail sidebar — View metadata, edit tags with autocomplete, and rename images from a slide-over panel.
• Context menus — Right-click context menus throughout the gallery with wallpaper setting, playlist management, selection, rename, delete, and file manager integration.
• Multi-resolution thumbnails — Automatic thumbnail generation at multiple resolutions (720p, 1080p, 1440p, 4K) for fast gallery rendering.
• Monitor auto-detection — Native detection via hyprctl, swaymsg, wlr-randr, or xrandr depending on the compositor, with manual override support.
• Wallpaper history — Per-monitor history log with forward/back navigation.

UI

• Neobrutalist design mode — Optional design mode with configurable shadow offsets, border widths, corner radius, and polaroid-style image cards. Toggleable alongside the standard DaisyUI look.
• Expanded theme library — 30+ themes including Gruvbox, Catppuccin, Tokyo Night, Nord, Dracula, Rosé Pine, Everforest, and more, on top of all DaisyUI built-in themes.
• Modernized layout — Drawer-based navigation with sidebar, image processing progress overlay, toast notifications, and confirm dialogs.

Current Status

https://www.youtube.com/watch?v=tVfqcAUs8ME

Legacy Features

These features carry over from the original version:

• Multi monitor support.
• Four different types of playlists (Time of day, daily, interval based or static).
• Tray controls.
• Filter images by format, resolution, name, etc.

---

2024-05-06.22-11-19.1.mp4

---

Why

I started this project for two main reasons, one as a learning oportunity, and two because the available options for a tool like this didn't suit my needs fully. I really like swww but it lacks a lot of the features that I missed from wallpaper engine in windows, so this is my attempt to bridge that gap a little.

Install

Simply install from the aur like so:

yay -S waypaper-engine

or

yay -S waypaper-engine-git

Both the normal and -git version conflict with each other, so make sure to delete the other with yay -Rns package_name package_name-debug before installing either.

Manual installation

Be advised you will need to run some of the commands with sudo privileges as you will be copying files to protected paths.

1. Clone this repo git clone git@github.com:0bCdian/Waypaper-Engine.git or download and extract the zip file
2. cd into Waypaper-Engine
3. run npm run build
4. cd into release cd release
5. Optional: if you want to change the tray icon, change the 512x512.png image inside linux-unpacked/resources/icons
6. Optional: copy the 512x512.png file to the icons system directory cp linux-unpacked/resources/icons/512x512.png /usr/share/icons/hicolor/512x512/apps/waypaper-engine.png
7. copy the whole directory to it's final destination sudo cp ./linux-unpacked -rt /opt/waypaper-engine
8. go back to root dir cd ..
9. cd into cli cd cli
10. copy waypaper-engine file to your $PATH or /usr/bin sudo cp ./waypaper-engine /usr/bin or cp ./waypaper/engine $HOME/.local/bin be advised, if you do not copy the cli file to /usr/bin, the path you're copying it into must be in your $PATH, read this for more info
11. go back to root cd ..
12. copy the .desktop file to /usr/share/applications sudo cp ./waypaper-engine.desktop /usr/share/applications/

and you're done!

Usage

Simply start the app and add wallpapers to the gallery, from there you can double click to set the wallpapers or right click for more options, to create playlists simply click on the checkboxes that appear when hover over the images, and configure it, and then save it to auto start it.

Examples

Autostart on hyprland just the daemon

Add to your hyprland.conf the following lines:

exec-once=waypaper-engine daemon

Add scripts to run on each image set

Warning

Make sure the script in question has execution permissions by using chmod +x scriptname.sh Put you bash scripts in this path:

$HOME/.waypaper_engine/scripts

The scripts are always passsed as an argument the path of the image being set, so you can do stuff like this:

2024-05-06.22-22-49.mp4

TODO

• Add testing.
• Have a ci/cd pipeline.
• Implement a logger for errors.
• Publish in the aur.
• Find a good icon/logo for the app (Thank you Cristian Avendaño!).
• Add flatpak support.
• Add scripts feature.
• Add playlists per monitor.

If you encounter any problems or would like to make a suggestion, please feel free to open an issue.

Gallery

Special Thanks

LGFae - for the amazing little tool that swww is ! ❤️

Simon Ser - for wlr-randr, without it making this work across different wayland wm's would've been a nightmare 🥲

Cristian Avendaño - for creating the amazing logo! 💪