linux-wallpaperengine-kde

linux-wallpaperengine-kde

A fork of 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

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

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

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

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 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.

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

git clone --recurse-submodules <this repo's url>
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:

cmake -DCMAKE_BUILD_TYPE='Release' -DDISABLE_KDE_FEATURES=ON ..

The "pause on fullscreen" feature on KDE Plasma also needs the KWin 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:

linux-wallpaperengine --assets-dir /path/to/assets

Usage

linux-wallpaperengine [options] <background_id or path>

The background can be a Steam Workshop ID (1845706469) or a path to a background folder.

Options

Option	Description
--silent	Mute background audio
--volume <val>	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 <val>	Limit frame rate
--window <XxYxWxH>	Run in windowed mode with custom size/position
--screen-root <screen>	Set as background for a specific screen
--screen-span <screen-1>,<screen-2>,...	Stretch a single wallpaper across multiple screens
--bg <id/path>	Assign a background to a screen (used after --screen-root/--screen-span)
--playlist <file>	Cycle through a Wallpaper Engine playlist from config.json
--scaling <mode>	stretch, fit, fill, center, or default
--zoom <factor>	Manual zoom on top of --scaling, e.g. 1.5 in, 0.5 out
--clamp <mode>	Texture clamping: clamp (edge), border, repeat. Default border
--corner-color <hex>	Color outside the wallpaper's bounds when --clamp border, as RRGGBB/RRGGBBAA. Default 000000
--layer <layer>	Wayland only: wlr-layer-shell layer (background, bottom, top, overlay)
--speed <factor>	Global playback speed multiplier
--assets-dir <path>	Custom assets path
--screenshot <file>	Save a screenshot (PNG/JPEG/BMP)
--screenshot-delay <n>	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 <id/name>	Hide an object/layer, repeatable
--enable-object <id/name>	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 <val>	Wayland only: ignore fullscreen windows whose app_id contains <val>, repeatable
--audio-screen <screen>	Only this screen's background produces audio
--ambient-volume <val>	Separate volume for non-video backgrounds; video keeps using --volume
--sound-volume <id/name>=<val>	Per-object volume (0-1), repeatable, * for unmatched objects
--audio-sensitivity <id/name>=<mult>	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:

linux-wallpaperengine 1845706469

Run from a local folder:

linux-wallpaperengine ~/backgrounds/1845706469/

Different background per monitor:

linux-wallpaperengine \
  --scaling stretch --screen-root eDP-1 --bg 2667198601 \
  --scaling fill --screen-root HDMI-1 --bg 2667198602

One wallpaper across multiple monitors:

linux-wallpaperengine --scaling fill --screen-span HDMI-A-1,DP-2,DP-3 --bg 1845706469

Windowed:

linux-wallpaperengine --window 0x0x1280x720 1845706469

Capped FPS:

linux-wallpaperengine --fps 30 1845706469

Screenshot (useful as input for pywal-style color extraction):

linux-wallpaperengine --screenshot ~/wallpaper.png 1845706469

Inspect and override properties:

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

linux-wallpaperengine --set-property bloom=1 2370927443

List and toggle layers (not every wallpaper exposes a property for each one):

linux-wallpaperengine --list-objects 2370927443

Objects for default:
  1 - Background (image)
  2 - Clock (text)
  3 - Rain (particle)

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 <name> 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 - texture flag insights
• RenderDoc - OpenGL debugging