How to, and everything else
How to
Set a wallpaper
apolline-wall set ~/Pictures/dunes.jpg # every monitor
apolline-wall set ~/Videos/rain.mp4 --output DP-1 # one monitor; `apolline-wall status` lists their names
apolline-wall set ~/shaders/hills.frag --transition 0 # no crossfade
apolline-wall set ~/Videos/wide.mp4 --fit blur # whole, edges filled with a blurred copy; also cover, contain
set waits until the wallpaper shows and says why if it can't. A sample shader is installed at /usr/share/apolline-wall/wallpapers/hills.frag.
Use Wallpaper Engine's Workshop
- Buy Wallpaper Engine on Steam and install it with Proton (Steam → its Properties → Compatibility). Scenes need its
assetsfolder, so keep it installed. - Subscribe to wallpapers in the Workshop, in Steam or from the app's Steam Workshop tab.
- They show up in the app's library, in Apolline's Settings → Appearance, and as folders named by ID under
steamapps/workshop/content/431960in each Steam library:
apolline-wall set ~/.local/share/Steam/steamapps/workshop/content/431960/1234567890
Without the Steam client, sign in once under Steam account in the app's Settings and use Download; items land in ~/.local/share/apolline-wall/steamcmd. Assets in an unusual place can be pointed at with APOLLINE_WALL_ASSETS.
Limit how hard it works
apolline-wall limits --fps 20 --scale 0.5 # shaders and scenes: frames per second (1–240) and share of resolution (0.1–1)
apolline-wall policy --battery reduce # on battery: keep, reduce or pause
apolline-wall policy # print the current rules
The default is 30 fps at about a 1080p screen's worth of pixels.
Pause and resume
apolline-wall pause # everything
apolline-wall pause --output HDMI-A-1 # one monitor
apolline-wall resumeRotate through a playlist
In the app, filter the library to what you want, pick a monitor or all of them, choose an interval and Rotate these wallpapers. The daemon keeps rotating after the window closes and after a login. From a terminal:
apolline-wall next # also previous, stop-playlist; each takes --output NAME
Or play a folder: whatever pictures, videos, shaders and Wallpaper Engine project folders it holds, in name order. It is read again at every step, so files you add join and files you remove leave, and the one showing keeps its place:
apolline-wall playlist ~/Pictures/Walls --every 600 --output DP-1 # --fit too; every 300 s by default
To start a list of your own without the app, send the playlist command to the socket:
echo '{"playlist":{"sources":["/home/me/Videos/a.mp4","/home/me/Pictures/b.jpg"],"interval_secs":600}}' \
| socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/apolline-wall/control.sockUse it under niri, Hyprland or sway without Apolline
Add the daemon to your startup (or use the systemd unit), and the tray if you want one:
// niri, config.kdl
spawn-at-startup "apolline-wall" "daemon"
spawn-at-startup "apolline-wallpapers" "--tray"# Hyprland
exec-once = apolline-wall daemon
exec-once = apolline-wallpapers --tray# sway
exec apolline-wall daemon
exec apolline-wallpapers --tray
Remove hyprpaper, swww or swaybg lines first: two programs on the background layer fight over it. If your shell locks the screen without updating logind's LockedHint, have it run apolline-wall session locked and apolline-wall session unlocked so wallpapers pause.
Troubleshooting
- What does it show, and is it paused?
apolline-wall status: each monitor's wallpaper, pause state and reason, playlist position, limits and power state. - Why didn't it show?
setprints the reason. The daemon writes every event, errors included, to stdout, which the journal keeps:journalctl --user -u apolline-wall -f. Under Apolline the events go to the shell. The journal also says why a scene went to linux-wallpaperengine. - A scene looks wrong.
APOLLINE_WALL_SCENES=externalhands every scene to linux-wallpaperengine, to compare. Without either renderer able to draw it, the app says what to install. - A wallpaper took the daemon down. One that does so twice in a row is skipped at the next start with an error saying so, until you set it again.
- Report it. "Not working? Report it" in the app's inspector saves a plain-text report to Downloads: the wallpaper and what it is, the distribution and session, which of mpv, ffmpeg, linux-wallpaperengine, steamcmd and Steam are installed, what the daemon shows and its last errors, with your home folder and user name taken out. Attach it to an issue.
The rest is reference.
- The app in full
- Monitors and state
- Talking to it
- Videos · Shaders · Scenes
- Playlists
- Preview, looks and properties
- Automatic playback rules
- Limits and safeguards
- Trying it
The app in full
- Library. Pictures, videos and shaders from the folders above and any you add in Settings, and Wallpaper Engine's Workshop subscriptions and its own projects. Its videos and scenes play here; anything that needs linux-wallpaperengine says what to install if it's missing. Application wallpapers say they are Windows programs.
- Steam Workshop. Collections open to what they hold, and More from the author lists the rest of an author's work. Items rated Questionable show only if you turn them on in Settings; Mature ones never do. Collections have no rating, so one shows only if its first four wallpapers pass.
apolline-wallpapers --page workshopopens on this tab (--page settingson Settings).- With the Steam client, Subscribe in Steam opens the item there; the app watches for the download only while one is pending, and the item appears in the library ready to set.
- Without it, Download goes through
steamcmdwith a Steam account that owns Wallpaper Engine. steamcmd asks for the password and the Steam Guard code; the app shows its question and hands your answer straight to it, and keeps only the account name. Signing in checks that the account owns Wallpaper Engine. Downloads go one at a time into a staging folder and move into place when done; each time the tab opens the app asks the Workshop which have a newer version, for an Update button.
- Favorites. From the inspector; the filter combines with search, and favorites survive a rescan and a restart.
- Now playing. A card per monitor with what it shows, pause, and its playlist's position with previous, next and stop.
- Tray. A StatusNotifierItem that waits for the bar at login. Settings can start it at login through XDG autostart; on niri or Hyprland add the command to your startup. Every client gets a fresh status after any change, so the tray, the window and the shell agree.
Thumbnails are cached in ~/.cache/apolline-wall: videos get theirs from ffmpeg, shaders once the daemon has shown them, animated Workshop previews a frame from their middle. Workshop previews are kept under 150 MB, oldest out first.
Monitors and state
Each monitor's wallpaper follows the monitor, not the port: plug it into another one, or into a dock, and it comes back with the same wallpaper, look and playlist. The daemon recognises a monitor by what the compositor calls it on Wayland (its description, usually with a serial) and by its EDID on X11; two identical monitors without serials can't be told apart and don't move.
What each monitor shows, the limits and the rules are kept in ~/.config/apolline-wall/state.toml, so a login comes back to the same desktop. A wallpaper that fails is not written there; the last one that showed stays. Under Apolline the shell decides instead.
Talking to it
The daemon listens on $XDG_RUNTIME_DIR/apolline-wall/control.sock: one JSON command per line in, one event per line out. Apolline starts it without arguments and talks over stdin and stdout instead; then it exits when stdin closes, so it never outlives the shell. The CLI, the app and Apolline all speak the same lines.
| Command | Does |
|---|---|
{"show":{"source":"/abs/path.jpg"}} | every monitor; a folder is a Wallpaper Engine project; also "output":"DP-1", "fit":"cover"|"contain"|"blur", "transition_ms":400, "look", and a scene's "properties" |
{"pause":{"paused":true}} | no animation, videos and shaders stop, changes land at once; "output" for one monitor |
{"limits":{"fps":30,"scale":0.5}} | frames per second (1–240) and share of resolution (0.1–1) for shaders and scenes; either can be left out |
{"uniforms":{"accent":"#86bdf0"}} | the shell's accent, which shaders read as iAccent |
{"adjust":{"look":{"brightness":-0.2,"contrast":1,"saturation":1,"flip":false,"speed":1},"draft":true}} | the look of what is shown now; fields left out keep their defaults; "output" for one monitor; a draft shows but isn't remembered |
{"playlist":{"sources":[...],"interval_secs":600}} | rotate through absolute paths every 10–86400 s; also "output", "fit", "settings"; or "folder" instead of "sources" for what a folder holds, read again at every step; empty sources and no folder stops it |
{"step":{"previous":false}} | next or previous entry; "output" for one monitor, otherwise every active playlist once |
{"policy":{...}} | pause_on_lock, pause_on_sleep, pause_on_fullscreen, battery (keep/reduce/pause), battery_fps, battery_scale |
{"session":{"locked":true}} | the shell's lock state, for shells that don't update logind |
{"feed":{"output":"DP-1"}} | Plasma's wallpaper plugin asking for a monitor's frames as a PipeWire stream instead of a surface of its own, until the daemon restarts |
{"status":{}} | answered to whoever asked with a status event |
Events go to stdout and to every socket client:
{"ready":{"output","source","poster"}}once a monitor shows the new wallpaper;posteris a still image of it, for the shell's accent and the lock screen.{"error":{"output","source","message"}}when a file can't be shown or a line isn't a command. A file that failed is not retried until the nextshow.{"status":{...}}: each monitor'sname,source, effectivepaused,manual_paused, an optionalpause_reason,native_sceneandanimated_scenefor scenes,feed(its PipeWirenode, andstream, which unlike node ids is never reused) while Plasma's plugin shows it, andplaylist_status(position,total,skipped,shared,suspended,can_step); the requestedfpsandscale, and apowerobject with what logind and UPower report and the effective fps. Afterpause,limits,uniformsandadjustevery client gets a fresh one.
Videos
A source ending in .mp4, .webm, .mkv, .mov, .gif and the like plays muted and looping through libmpv, with hardware decoding where the driver offers it. libmpv is opened only when the first video is shown, so pictures work without mpv installed, and a video then answers with an error saying so.
- One decode feeds every monitor showing the same file, at the size the most demanding monitor needs and never above the video's own. Monitors showing the same video share its clock and speed.
- A frame is rendered only when a monitor showing the video is ready for one, so decoding stops while a fullscreen window covers it.
- mpv runs in its simplest rendering mode: no HDR tone mapping or fancy scalers, which a wallpaper doesn't need and a battery would pay for.
- The poster is read back from the video's own canvas and written to
$XDG_RUNTIME_DIR/apolline-wall/poster-*.pngbeforereadyis sent. A poster that can't be saved is a warning, not a failed video.
Shaders
A source ending in .frag or .glsl is a fragment shader written for Shadertoy: a mainImage(out vec4 fragColor, in vec2 fragCoord) with iTime, iTimeDelta, iFrame, iFrameRate, iResolution, iDate and iChannel0–iChannel3, which all hold a tiling noise texture since there is nowhere to pick another yet. iAccent is the shell's accent as RGB in 0–1, so a wallpaper can follow the mode you're in. Most single-pass shaders paste in as they are; multi-pass buffers, sound and keyboard input are not supported. Mind their licenses: Shadertoy's default is CC BY-NC-SA. tests/shaders/hills.frag is one of ours.
- A shader draws into a canvas of its own per monitor, about a 1080p screen's worth of pixels unless
limitssays otherwise, stretched over the monitor, at mostfpstimes a second and only when the compositor asks for a frame. - A paused shader keeps its clock still and resumes where it stopped; a new accent shows at once, on paused shaders too.
- A shader that doesn't compile comes back as an
errorwith the compiler's message, its line numbers pointing into your file. A drawing error at run time stops it, frees its GL resources and reports it once. - The poster is its first frame.
Scenes
The daemon prepares each scene with apolline-scene on its loading thread, off the event loop, before any GL work. Shared assets are found in every Steam library, Flatpak Steam included, or through APOLLINE_WALL_ASSETS.
- A scene with nothing moving is drawn once at the monitor's resolution and keeps no timer.
- A moving scene shares the shader scheduler:
fpsandscalelimits, manual and automatic pause, crossfades. On several monitors it runs once into a shared canvas, sized for the most demanding monitor within the pixels separate canvases would have taken. - Crossfades, cover, contain and blur, brightness, contrast, saturation, mirror and speed apply. Status marks these monitors with
native_scene: true, and moving ones withanimated_scene: true. - Scenes that follow the pointer draw only when it moves them. Wayland reports the pointer when it is over the desktop; X11 is asked only while such a scene shows.
- The author's properties are resolved before drawing. Changing them keeps the scene's animation phase.
- Each scene may use up to 1 GiB of textures and render targets. Posters are read back at most 640×360.
A project apolline-scene refuses, and every web wallpaper, goes to linux-wallpaperengine (linux-wallpaperengine-git in the AUR), which runs as a process of its own on that monitor while ours steps aside. Video projects don't need it.
- It starts silent and ignoring the mouse, at the
fpsfromlimitswhen it starts (a new limit reaches it the next time it starts), andfitbecomes its scaling:coverfills,containshows whole. Looks and speed don't apply, and changes to and from it don't crossfade. - Pause stops the process and resume continues it. It goes when the daemon goes, however the daemon goes.
readycomes once it has lasted a moment, with the project's preview as the poster. If it stops on its own, theerrorcarries its last words and the monitor goes back to what it showed before.- A scene with edited properties is never handed to it, since it would ignore them: the edit is refused and the previous wallpaper stays. An unedited scene falls back as usual.
APOLLINE_WALL_SCENE_RENDERERnames another program that takes the same arguments; the tests usetests/scenes/stand-in.sh.APOLLINE_WALL_SCENES=externalsends every scene there, even ones the daemon could draw.- It needs Linux 5.3 or later: the process is watched through a pidfd as well as its stderr, so a descendant holding stderr open can't delay noticing that it died. Its diagnostics keep at most three 4096-byte fragments.
Playlists
A playlist rotates through wallpapers on one monitor, or on all of them on a shared clock. It persists across restarts. Setting a wallpaper by hand ends that monitor's own playlist, and excludes it from a shared one even if the file is the same.
- Shared clock. Pausing any participating monitor pauses the clock, and stopping it stops it for all. Paused or disconnected playlists keep no timer; resuming starts a fresh interval. Pick monitors one by one for independent rotation.
- Failed entries. An entry that fails to load or play, or whose external renderer exits, is skipped for the life of the running playlist, in Next and Previous too, and for every monitor of a shared one. One healthy entry left stays on screen without a timer; if every entry fails, rotation stops and says how to recover. Starting the list again or choosing a wallpaper by hand allows a retry. Duplicate paths are dropped, order kept.
- Per-wallpaper settings. Starting rotation in the app captures each wallpaper's saved look and scene properties into the playlist's
settings(paths mapped to{"properties":{...},"look":{...}}), and every transition and restart uses that snapshot. Apply editor changes before starting; start it again to pick up later ones. The playlist's fit applies to every entry. The tray's random wallpaper uses saved settings too. - Editing during shared rotation. Changing one monitor's look keeps it in the shared playlist, and the edit belongs to the current entry: the next one uses its own snapshot.
- Controls. Each playback card and the tray show position, skipped entries, whether the clock is paused, and previous, next and stop; a shared playlist is labelled as such, since its controls affect every monitor in it.
apolline-wall statusprints the same summary.
Preview, looks and properties
Preview before applying opens an isolated picture preview with brightness, contrast, saturation, mirror and fit. Nothing reaches the desktop until Set as wallpaper; Close or Esc discards it. Pictures are decoded with size limits and reduced to 1280×720 on a worker. Video, shader and scene entries show a labelled still; full animated preview is still to come. Look presets can be saved by name, which does not apply them.
Looks are drawn in the final shader, so they cost nothing: brightness, contrast, saturation and mirror for everything apolline-wall draws itself, and speed for videos, shaders and moving scenes. In the inspector each change shows on the chosen monitor at once as a draft; Apply keeps it, Revert goes back, and each wallpaper remembers its look per monitor.
Scene entries show the controls their author declared: checkboxes, sliders, colors, text and dropdowns. Edits apply with Set as wallpaper, are remembered per wallpaper and in daemon state, and Reset properties returns to the author's defaults. Values can be saved as named presets and copied to and pasted from the clipboard as JSON. Loading the editor reads only the project's metadata. Property conditions, file pickers and unsupported kinds are not offered, and the still preview does not show the edits; the desktop does.
Automatic playback rules
Settings → Automatic playback (or apolline-wall policy) decides what happens on lock, before sleep, on battery and under windows that hide the desktop: fullscreen ones on X11, maximized or fullscreen ones on Plasma through its wallpaper plugin. Lock and sleep pause by default; battery defaults to keep running. Reduce caps shaders and scenes at 15 fps and 50 % resolution without raising a lower limit of yours; videos keep their quality, so choose Pause to stop them instead. Rules belong to the daemon and survive a restart; conditions themselves don't.
- System state comes from logind (or elogind) and UPower over D-Bus signals, with no polling while connected. A service not on the bus is waited for through
NameOwnerChanged; what it said last is cleared when it goes. Settings shows which integrations are available. No D-Bus service is needed for manual controls. - A sleep delay inhibitor, when permitted, holds sleep until the pause is processed, for at most a second.
- Lock detection needs logind's LockedHint, or the shell's own
apolline-wall session locked|unlocked(child mode:{"session":{"locked":...}}), sent at start and on each change. The two are separate reasons; an unlocked hint doesn't cancel a shell-reported lock. - Manual pause per monitor, global manual pause and each automatic reason are independent; unplugging AC or unlocking never clears a manual pause, and an automatic cap never overwrites your limits.
- Fullscreen on X11. A monitor covered entirely by one EWMH fullscreen window pauses, driven by window-manager events with no periodic scan; leaving fullscreen, moving, minimizing or switching workspace reevaluates it. Desktop windows, the daemon's own and the external renderer are excluded; hidden, other-workspace and translucent windows don't count, and partial windows aren't combined. Turn it off with
apolline-wall policy --fullscreen false. Native Wayland fullscreen detection isn't done; there the compositor's frame callbacks already stop drawing under a covering window.
Limits and safeguards
- Runtime directory. Private (0700), checked for ownership and symlinks. Without
XDG_RUNTIME_DIR, a privateapolline-wall-UIDdirectory under the temporary folder. A daemon left on the old$XDG_RUNTIME_DIR/apolline-wall.sockis still found after an upgrade, and a new one won't start next to it. Several graphical sessions of one user aren't kept apart yet. - IPC. Commands are capped at 2 MiB and subscriptions at 64; a closed client releases its subscription at once. Decoding has a two-result queue, so a busy event loop pushes back instead of piling up full-sized images.
- Child mode. Events go out off the render loop through a short queue: a slow parent gets every event in order, and while the queue is full only the newest status waits. A broken output stream ends the child session; the parent restarts it and asks for the status again. A standalone daemon's stdout going away doesn't stop it.
- Metadata.
project.jsonup to 8 MiB, regular files only; video and preview paths outside the project folder, absolute or through symlinks, are ignored. This is a path check, not a sandbox for the external renderer. - Thumbnails. Two jobs at a time, shared by the library and the Workshop; inputs up to 32 MiB, 16384 pixels a side and a 128 MiB decode budget. GIFs sample the middle of their first 48 frames in two bounded passes. Video thumbnails come from ffmpeg with one thread, fitted within 640×400, and an eight-second deadline after which the process is killed and reaped. Files appear by atomic rename only when complete. The full picture preview has a 256 MiB limit.
- Shaders. Sources are regular UTF-8 files up to 1 MiB. Time accumulates in f64 on the CPU (the GPU still sees f32); gaps are capped at the larger of 250 ms and two frame intervals, so a long interruption doesn't jump;
iFramesaturates instead of overflowing. Timers carry the wallpaper's generation and are cleared on pause, replacement and redraw, so a callback from a replaced shader can't drive its successor. - Posters. Encoded on a worker to a temporary file, flushed and renamed; a failed write keeps the previous PNG and is a warning, not a failure. Readiness is tied to the monitor's current wallpaper, so a late poster never announces one the monitor has already left.
Trying it
cargo build --release
cargo test --workspace
tools/headless.sh shots/ # under a throwaway headless sway, a screenshot per step
tools/headless.sh needs sway and grim. It shows the pictures in tests/pictures, crossfades, pauses, and checks that a missing file and an unknown command come back as errors. With ffmpeg and mpv it plays a generated clip, checks that it moves and that a paused one doesn't, and fades back to a picture. It runs tests/shaders/hills.frag the same way, checking that a new accent shows on a paused shader. With swaybg a stand-in plays linux-wallpaperengine's part: a scene shows, its process stops while paused and is gone after the next wallpaper, and one that crashes leaves the desktop as it was. With apolline-scene beside this repository it draws a synthetic scene in the daemon and checks that nothing went to the external renderer. steamcmd is checked against tests/steamcmd/stand-in.sh.
CI formats, lints with clippy -D warnings and tests on Ubuntu 22.04, x86_64 and arm64, and builds the .deb.
What is stable
Run on real hardware (Arch, niri, an NVIDIA RTX 4070 Ti, two monitors, one turned): pictures, videos, shaders, native scenes, Workshop videos, folder playlists, pausing one monitor of a shared scene, parec for scenes that listen, and Apolline's integration. On the same machine, in sway and labwc (headless, two outputs, one turned) and in X11 sessions under openbox and i3 (Xephyr, one and two monitors): pictures, videos, shaders and scenes draw, fit, pause and play folders, and on X11 the wallpaper stays under every window, takes no focus and pauses under a fullscreen window. The app opens and drives the daemon under X11 too.
Written and tested only against stand-ins or synthetic input so far: GNOME through the extension, real steamcmd downloads, linux-wallpaperengine as the fallback, real sleep and battery transitions, and Mesa (AMD and Intel) on real Workshop scenes. KDE Plasma is written but not yet run, and how scenes move to music hasn't been judged by ear. Not done: Fedora and Flatpak packages. Reports are welcome; docs/ROADMAP.md has the plan and docs/STATUS.md where things stand.