Wallpapers
The davinci wallpaper kernel, xwww and mpvpaper, the Quickshell picker, search providers and slideshow.
Wallpapers are managed by equisdots/davinci, a headless kernel that applies, thumbnails, searches and rotates wallpapers. The Quickshell picker is only a frontend: the UI decides what to apply, the kernel decides how.
The stack
| Piece | Role |
|---|---|
xwww / xwww-daemon |
Applies still images and interactive scenes. |
mpvpaper |
Applies video wallpapers. |
| ImageMagick, ffmpeg, ffprobe | Thumbnails, webp conversion and video posters. |
davinci |
CLI kernel: listing, applying, state, search, slideshow. |
| Quickshell picker | SUPER + W, card grid with filters and transitions. |
The daemon is started from Hyprland's autostart.lua (or niri's
autostart.kdl) and restarted by the shell after theme changes. The wallpaper
stack is compositor-agnostic: it runs the same on Hyprland and
niri.
The wallpaper directory
The collection defaults to ~/.config/hypr/wallpapers and is scanned
recursively. Nested files are flattened into their thumbnail name using __
as separator (sub/dir/pic.jpg becomes sub__dir__pic.jpg). A directory
containing scene.js is an interactive scene; its thumbnail is named
scn_<name>.jpg, while videos use the 000_ prefix.
CLI
davinci set <file|url|scene-dir> [--video] [--monitors all|A,B] \
[--transition name] [--thumb <poster>] [--notify] [--dry-run]
davinci set ~/.config/hypr/wallpapers/astro-palette --transition decrypt
davinci fetch --name <n> --map <f> --dest <f>
davinci current
davinci current --thumb-name
davinci thumbs
davinci search "mountains" --source wallhaven
davinci search --continue "mountains"
davinci search --clear
davinci stop
davinci rm ~/.config/hypr/wallpapers/nord.png
davinci import ~/Downloads/*.jpg
davinci slideshow start|stop|status [interval]
davinci keys list
davinci keys set PIXABAY_KEY <value>
davinci paths
davinci --version
set accepts a file, an URL or a scene directory and resolves the target
itself; --monitors, --thumb, --notify and --dry-run refine the apply.
--transition accepts the xwww set (fade, wipe, glitch, decrypt, and
more) plus random; empty means random. fetch is the downloader the picker
calls after picking a search result, and keys manages the provider keys in
keys.conf. The picker resolves the CLI through $DAVINCI_CLI, then a
sibling ../kernel/davinci.sh, so other frontends only need the path.
Environment overrides
| Variable | Default | Use |
|---|---|---|
DAVINCI_WALLPAPER_DIR |
$WALLPAPER_DIR or ~/.config/hypr/wallpapers |
Source directory. |
DAVINCI_CACHE_DIR |
~/.cache/quickshell/wallpaper_picker |
Thumbs, current wallpaper, search. |
DAVINCI_STATE_DIR |
~/.local/state/quickshell/wallpaper_picker |
Persistent flags and current_scene. |
DAVINCI_RUN_DIR |
$XDG_RUNTIME_DIR/quickshell/wallpaper_picker |
Control files, locks and PIDs. |
DAVINCI_LOG_DIR |
$XDG_RUNTIME_DIR/quickshell/logs |
Kernel logs. |
DAVINCI_XWWW |
~/.local/bin/xwww, then PATH |
Client binary. |
DAVINCI_XWWW_DAEMON |
~/.local/bin/xwww-daemon, then PATH |
Daemon binary. |
DAVINCI_CLI |
— | Explicit path to davinci.sh consumed by the picker. |
The picker
Open with SUPER + W. The picker shows thumbnails from davinci, a transition
selector and filter controls. Cards carry a JS badge for scenes and a play
badge for videos. Applying works with a click or Return; Delete moves the
selected entry to the trash through davinci rm. The active wallpaper is
pre-selected when the picker opens (davinci current --thumb-name).
Search
Search downloads go through provider scripts under providers/:
| Source | Key | Notes |
|---|---|---|
ddg |
none | DuckDuckGo scraper, stdlib only. |
wallhaven |
none (SFW) | Native resolution filter and pagination. |
pexels |
optional PEXELS_KEY |
Stock videos; best mp4 >= 1920x1080. |
pixabay |
PIXABAY_KEY |
Stock videos; best variant >= 1920x1080. |
Keys live in $DAVINCI_STATE_DIR/keys.conf or the environment. Results are
filtered to at least 1920x1080 and validated (content-type plus mime) before
being kept. Pagination keeps a per-provider cursor under
search_cursors/<source>, and the active provider is persisted in
search_source so search --continue asks the same source.
Slideshow
davinci slideshow start [interval] runs a detached daemon that rotates
still images with a random transition and never repeats the previous one. The
state lives in slideshow.pid and slideshow_enabled under the run/state
directories. Scenes are skipped by the slideshow.
Contracts and state files
current_wallpaper.pngin the cache dir is the frame used by the lock screen and SDDM.current_scenein the state dir holds the directory of the running scene; applying an image or video removes it.thumbs/.manifestandthumbs/.source_dirindex the thumbnail cache.search_map.txtstoresname|urlfor search results.ddg_search_controlcarriesrun,pauseorstopwritten by the UI.search_cursors/<source>andsearch_sourcepersist pagination and provider.slideshow.pidandslideshow_enabledhold the slideshow daemon state.keys.conf(mode 600) stores the provider API keys.
Contributing wallpapers
The background repository hosts the wallpaper collection and the scene catalog. Images are distributed as release assets, never tracked in git:
- Submit only images you created or that are explicitly licensed for redistribution; unclear provenance is rejected.
- JPEG (optimized), 4K preferred and 2560x1440 minimum, 16:9 or wider, under about 5 MB, no watermarks.
- Open a PR or issue titled
wallpaper: <short name>, attach the image and include author, source, license and a short description. - Published releases bundle
LICENSEandCREDITS.md; images and documentation are licensed CC BY 4.0 and every author is credited.
Troubleshooting
- Wallpaper does not change: check that
xwww-daemonruns and thatxwww --versionmatches the pinned release (dots doctorreports this). davinci: xwww not found: the kernel resolvesDAVINCI_XWWW, then~/.local/bin/xwww, thenPATH; a session may not include~/.local/bin.- Video wallpaper fails:
mpvpapermust be installed (dots system). - Missing or stale thumbnails: run
davinci thumbs. - Scene appears as a plain folder: it needs a
scene.jsfile; see Interactive scenes.
Next steps
- Interactive scenes for procedural wallpapers.
- Theming and palettes for palette-reactive scenes.
- Quickshell shell for the picker and state handling.