# linux-wallpaperengine-kde A fork of [Almamu/linux-wallpaperengine](https://github.com/Almamu/linux-wallpaperengine), reworked for KDE Plasma and Wayland. It plays Wallpaper Engine (Steam app 431960) live wallpapers on Linux: scene/parallax backgrounds, video (via mpv), and web/HTML backgrounds (via CEF), rendered with a from-scratch OpenGL reimplementation of Wallpaper Engine's renderer. No GUI. This is a command-line tool driven entirely by flags - see Usage below. ## What's different from upstream - Native Wayland output via `wlr-layer-shell`, in addition to the original X11 path. - KDE-specific fullscreen-pause detection over the `plasma-shell` protocol, since KWin doesn't implement `wlr-foreign-toplevel-management` like other wlroots compositors. Still experimental (see Limitations). - Multi-monitor handling: per-screen backgrounds (`--screen-root`), one wallpaper spanning several monitors (`--screen-span`), per-screen scaling/clamping/zoom/corner color, and Workshop playlists (`--playlist`). - A global playback speed multiplier (`--speed`), separate from the FPS cap. - More granular audio: restrict sound to a single screen (`--audio-screen`), a separate ambient volume for non-video backgrounds (`--ambient-volume`), per-object sound volume (`--sound-volume`), and a tunable multiplier on audio-reactive properties (`--audio-sensitivity`, with `--list-audio-objects` to see what's wired up). - Live hotswap of the running wallpaper via `SIGUSR1`, no process restart. - Layer introspection/toggling (`--list-objects`, `--disable-object`, `--enable-object`) for layers the wallpaper author didn't expose as a configurable property. ## Requirements - OpenGL 3.3 - CMake - LZ4, Zlib - SDL2 - FFmpeg - X11 or Wayland (Xrandr on X11) - GLFW3, GLEW, GLUT, GLM - MPV - PulseAudio - FFTW3 - FreeType, HarfBuzz - D-Bus (for the KDE integration, see Build) ### Ubuntu 22.04 ```bash sudo apt-get update sudo apt-get install build-essential cmake libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl-dev libglew-dev freeglut3-dev libsdl2-dev liblz4-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libxxf86vm-dev libglm-dev libglfw3-dev libmpv-dev mpv libmpv1 libpulse-dev libpulse0 libfftw3-dev libfreetype-dev libharfbuzz-dev libdbus-1-dev ``` ### Ubuntu 24.04 ```bash sudo apt-get update sudo apt-get install build-essential cmake libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl-dev libglew-dev freeglut3-dev libsdl2-dev liblz4-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libxxf86vm-dev libglm-dev libglfw3-dev libmpv-dev mpv libmpv2 libpulse-dev libpulse0 libfftw3-dev libfreetype-dev libharfbuzz-dev libdbus-1-dev ``` ### Fedora 42 ```bash sudo dnf update sudo dnf install gcc g++ cmake libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel mesa-libGL-devel glew-devel freeglut-devel SDL2-devel lz4-devel ffmpeg ffmpeg-free-devel libXxf86vm-devel glm-devel glfw-devel mpv mpv-devel pulseaudio-libs-devel fftw-devel freetype-devel harfbuzz-devel gmp-devel dbus-devel ``` ### ALT Linux ```bash sudo epm update sudo epm install gcc-c++ make cmake libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel libGL-devel libGLEW-devel freeglut-devel libSDL2-devel liblz4-devel libavcodec-devel libavformat-devel libavutil-devel libswscale-devel libXxf86vm-devel libglm-devel libglfw3-devel libmpv-devel mpv libpulseaudio-devel libpulseaudio libfftw3-devel libpng-devel libffi-devel libswresample-devel libgmpxx-devel libfreetype-devel libharfbuzz-devel libdbus-devel ``` ## Prebuilt downloads Tagged releases on the [releases page](https://github.com/WallpaperEngineLover/linux-wallpaperengine-kde/releases) have ready-to-run builds for Ubuntu 24.04, Fedora 44 and Arch, each with (`kde`) and without (`generic`) the KDE Plasma integration. They use the distro's own ffmpeg, mpv, GLFW and so on, so pick the one for your distro and install the runtime packages from the list above (the non `-dev`/`-devel` ones). Arch builds follow the rolling release and can break after big library updates, rebuild from source then. ```bash tar xzf linux-wallpaperengine-kde-fedora-44-x86_64.tar.gz ./linux-wallpaperengine-kde-fedora-44-x86_64/linux-wallpaperengine --help ``` The folder can live anywhere, the binary finds its libraries next to itself. ## Build ```bash git clone --recurse-submodules cd linux-wallpaperengine-kde mkdir build && cd build cmake -DCMAKE_BUILD_TYPE='Release' .. make ``` The binary and support files end up in `build/output`. The KDE Plasma integration (plasma-shell desktop surfaces, cursor tracking through KWin, fullscreen detection) is built in by default and only kicks in inside a Plasma session, other desktops use the generic Wayland/X11 paths. It needs the D-Bus development files. To build without it: ```bash cmake -DCMAKE_BUILD_TYPE='Release' -DDISABLE_KDE_FEATURES=ON .. ``` The "pause on fullscreen" feature on KDE Plasma also needs the [KWin Maximize Detector](https://github.com/LS-FCEFyN/Maximize-Detector) script installed separately. ## Assets You need Wallpaper Engine installed through Steam - this is where the backgrounds and shared assets come from. The binary looks for it automatically under: ``` ~/.steam/steam/steamapps/common ~/.local/share/Steam/steamapps/common ~/.var/app/com.valvesoftware.Steam/.local/share/Steam/steamapps/common ~/snap/steam/common/.local/share/Steam/steamapps/common ``` If it isn't found there, either copy the `assets` folder from Wallpaper Engine's install directory (Steam -> Wallpaper Engine -> Manage -> Browse local files) next to the `linux-wallpaperengine` binary, or point at it directly: ```bash linux-wallpaperengine --assets-dir /path/to/assets ``` ## Usage ```bash linux-wallpaperengine [options] ``` The background can be a Steam Workshop ID (`1845706469`) or a path to a background folder. ### Options | Option | Description | |--------|-------------| | `--silent` | Mute background audio | | `--volume ` | Set audio volume | | `--automute` | Mute when other apps play audio | | `--noautomute` | Don't mute when other apps play audio (default) | | `--no-audio-processing` | Disable audio reactive features | | `--fps ` | Limit frame rate | | `--window ` | Run in windowed mode with custom size/position | | `--screen-root ` | Set as background for a specific screen | | `--screen-span ,,...` | Stretch a single wallpaper across multiple screens | | `--bg ` | Assign a background to a screen (used after `--screen-root`/`--screen-span`) | | `--playlist ` | Cycle through a Wallpaper Engine playlist from `config.json` | | `--scaling ` | `stretch`, `fit`, `fill`, `center`, or `default` | | `--zoom ` | Manual zoom on top of `--scaling`, e.g. `1.5` in, `0.5` out | | `--clamp ` | Texture clamping: `clamp` (edge), `border`, `repeat`. Default `border` | | `--corner-color ` | Color outside the wallpaper's bounds when `--clamp border`, as `RRGGBB`/`RRGGBBAA`. Default `000000` | | `--layer ` | Wayland only: `wlr-layer-shell` layer (`background`, `bottom`, `top`, `overlay`) | | `--speed ` | Global playback speed multiplier | | `--assets-dir ` | Custom assets path | | `--screenshot ` | Save a screenshot (PNG/JPEG/BMP) | | `--screenshot-delay ` | Frames to wait before the screenshot (default 5) | | `--list-properties` | List a wallpaper's customizable properties | | `--set-property name=value` | Override a property | | `--list-objects` | List every object/layer, with id, name and type | | `--disable-object ` | Hide an object/layer, repeatable | | `--enable-object ` | Force an object/layer to show, repeatable | | `--disable-particles` | Disable particles | | `--disable-mouse` | Disable mouse interaction | | `--disable-parallax` | Disable parallax | | `--no-fullscreen-pause` | Don't pause while an app is fullscreen | | `--fullscreen-pause-only-active` | Wayland only: pause only when the fullscreen window is active | | `--fullscreen-pause-ignore-appid ` | Wayland only: ignore fullscreen windows whose app_id contains ``, repeatable | | `--audio-screen ` | Only this screen's background produces audio | | `--ambient-volume ` | Separate volume for non-video backgrounds; video keeps using `--volume` | | `--sound-volume =` | Per-object volume (0-1), repeatable, `*` for unmatched objects | | `--audio-sensitivity =` | Scale an object's audio-reactive swing; `0` disables it, `1` is default; repeatable, `*` for unmatched objects | | `--list-audio-objects` | List objects whose script reacts to music | ### Examples Run by Workshop ID: ```bash linux-wallpaperengine 1845706469 ``` Run from a local folder: ```bash linux-wallpaperengine ~/backgrounds/1845706469/ ``` Different background per monitor: ```bash linux-wallpaperengine \ --scaling stretch --screen-root eDP-1 --bg 2667198601 \ --scaling fill --screen-root HDMI-1 --bg 2667198602 ``` One wallpaper across multiple monitors: ```bash linux-wallpaperengine --scaling fill --screen-span HDMI-A-1,DP-2,DP-3 --bg 1845706469 ``` Windowed: ```bash linux-wallpaperengine --window 0x0x1280x720 1845706469 ``` Capped FPS: ```bash linux-wallpaperengine --fps 30 1845706469 ``` Screenshot (useful as input for pywal-style color extraction): ```bash linux-wallpaperengine --screenshot ~/wallpaper.png 1845706469 ``` Inspect and override properties: ```bash linux-wallpaperengine --list-properties 2370927443 ``` ``` barcount - slider Description: Bar Count Value: 64 Minimum value: 16 Maximum value: 64 Step: 1 bloom - boolean Description: Bloom Value: 0 ``` ```bash linux-wallpaperengine --set-property bloom=1 2370927443 ``` List and toggle layers (not every wallpaper exposes a property for each one): ```bash linux-wallpaperengine --list-objects 2370927443 ``` ``` Objects for default: 1 - Background (image) 2 - Clock (text) 3 - Rain (particle) ``` ```bash linux-wallpaperengine --disable-object Clock --disable-object 3 2370927443 ``` ## Wayland and X11 - Wayland: needs a compositor with `wlr-layer-shell-unstable` and `xdg-output-unstable-v1` (the latter for accurate monitor positioning with `--screen-span`). - X11: needs XRandr; target monitors with `--screen-root ` as reported by `xrandr`. Doesn't work if something else (GNOME, KDE, Nautilus) is already drawing the desktop background/compositing it. ## Limitations - Light and VolumeLight scene objects are parsed but not rendered - wallpapers that depend on them for lighting will look different from the Windows original. - Passthrough image effects aren't implemented. - Text objects can't sample the background behind them (no copybackground-style effects on `Text`). - KDE fullscreen-pause detection is experimental and requires the separate KWin Maximize Detector script. - On X11, a compositor or DE drawing its own background will block the wallpaper. Disabling the compositor is currently the only fix. - Some NVIDIA setups hit GLFW/OpenGL init failures; try `__GL_THREADED_OPTIMIZATIONS=0 linux-wallpaperengine` if you run into this. ## Credits - [RePKG](https://github.com/notscuffed/repkg) - texture flag insights - [RenderDoc](https://github.com/baldurk/renderdoc) - OpenGL debugging