Skip to content
ExecornPublic

About

The last wallpaper engine your Linux desktop will ever need — replaces swww/awww, mpvpaper, linux-wallpaperengine, glpaper, wpaperd & matugen/pywal in one absurdly fast C23 daemon.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

WayWal (wwal)

CI Release License: GPL-3.0-or-later

WayWal Demo

Most Wayland setups are held together with duct tape. You end up installing five or six separate tools (swww or awww, mpvpaper, linux-wallpaperengine, glpaper, wpaperd, plus matugen or pywal) just to get wallpapers, video loops, Steam Workshop scenes, music bars, and matching system colors.

WayWal replaces the whole pile with tiny C23 binaries (2.91 MiB total stripped). Drop in a photo, a 4K video, a live shader, or a Steam Wallpaper Engine scene, and your whole desktop updates its color theme in half a millisecond. And the instant a window covers your screen, WayWal drops to 0.0% CPU and GPU so your battery stays untouched.


Why use WayWal?

  • One command for everything (wwal img): Point wwal img at a picture, a GIF, a 4K video, a Shadertoy file, a Steam Workshop ID, or a folder. WayWal detects the format on its own. Then it blends the new wallpaper onto your screen at your monitor's full refresh rate.
  • Native Steam Wallpaper Engine: Run your Steam Workshop scenes straight on Wayland. Puppet meshes with 240 Hz spring-bone physics and 3D curl-noise wind, 3D perspective cameras and dynamic multi-light rigs, 50 built-in stock effects with automatic HLSL-to-GLSL translation, particles, scripts, clocks, and sound layers all work natively. No Wine, no Proton, and no heavy wrapper.
  • Whole-desktop colors in 0.5 ms: Change your wallpaper and your whole system shifts colors to match in half a millisecond. WayWal builds dark and light palettes at once and updates your terminal, bar, browser, and lockscreen right away. Existing matugen, wallust, and pywal templates work as-is.
  • Built-in shaders, visual node graph & audio visualizers: Ships with 10 procedural GPU shader presets, 50 stock post-processing and distortion effects, live PipeWire audio bars and rings that move to your music, and a visual .wwgraph node-graph shader compiler.
  • Sun-tracked day and night wallpapers: Give it your location (or a GNOME timed wallpaper) and your desktop shifts from dawn to noon to night with the real sun, flipping your apps between light and dark mode along the way.
  • Zero wasted battery (0.0% when covered): Still images use 0.0% CPU and 0.0% GPU once drawn. Videos use hardware VA-API decoding (~0.3% CPU). Open a window full screen or launch a game, and WayWal pauses right away. It mutes background sound too, then wakes back up when you can see your desktop again.
  • Drop-in replacement for swww, awww, and wpaperd: Keep your old scripts and keybinds. WayWal reads swww and awww CLI flags directly, loads wpaperd configs, and includes wwal pick so you can browse thumbnails in rofi, fuzzel, or walker in under 1 ms.
  • WayWal Studio GUI (wwal-studio): Includes an optional Wayland GUI workstation across 7 workspace perspectives (Default, Shader Coding, Scene Composer, Particle & Audio, Rigging & Animation, Theme Studio, Multi-Monitor) and 22 dockable panels to browse local wallpapers, Steam Workshop (431960), and WayWal Open Hub packages; compose WYSIWYG layers with SceneLayerTreeWidget and interactive viewport gizmos; paint GPU masks, flow maps, blur, and smudge via we_gpu_brush; generate 2D puppet meshes via Constrained Delaunay Triangulation (we_mesh_cdt), bind bones with harmonic heat-diffusion skinning and a GLES 3.1 GPU weight brush, pose 2-bone IK & Aim constraints, and keyframe animations in DopeSheetTimelineWidget with studio_rig_<id>.json sidecars; author particle emitters and PipeWire audio bindings; edit GLSL ES 3.10 and SceneScript with live we_script_lint diagnostics; compose multi-pass shaders in a visual node graph editor with 50 drag-and-drop effects; tune 3D cameras, lights, and spring-bone physics; preview Material You color themes; arrange multi-monitor spans; and export MDLV0023 puppets, PKGV0022/TEXV0005 scenes, or Ed25519-signed .wwpkg packages.

Speed & Resource Use

WayWal is written in C23 and talks directly to Wayland, DRM/KMS, and your GPU:

  • Binary size: 2.50 MiB (2,623,592 B) daemon (wwald) + 414 KiB (424,000 B) client (wwal), 2.91 MiB total stripped.
  • Still pictures: 0.00% CPU and 0.00% GPU once the frame is on screen.
  • Covered by a window: 0.00% CPU, 0.00% GPU, and 0 wakeups/sec.
  • 4K video loops: ~0.3% CPU via hardware VA-API decoding.
  • Theme extraction + template render: 0.49 ms end-to-end (0.44 ms palette + 0.05 ms templates).
  • Wallpaper picker (wwal pick): 0.93 ms warm cache (61.2 ms first-run thumbnail build).
  • Lockscreen frame export (1280×720): 13.0 ms ready for hyprlock or swaylock.
  • 4K GPU transitions: 1,668 – 2,734 FPS at 3840×2160.

See Technical Architecture & Full CLI Reference for the full benchmark suite and internals.


Install

Arch Linux (AUR)

# Prebuilt binary (fast install)
yay -S wwal-bin

# Or build latest from source
yay -S wwal-git

Fedora (Copr)

sudo dnf copr enable execorn/wwal
sudo dnf install wwal

openSUSE Tumbleweed (Copr)

sudo zypper addrepo https://download.copr.fedorainfracloud.org/results/execorn/wwal/opensuse-tumbleweed-\$basearch/ execorn-wwal
sudo zypper --gpg-auto-import-keys refresh
sudo zypper install wwal

Ubuntu / Debian (.deb)

curl -LO https://github.com/Execorn/wwal/releases/latest/download/wwal_3.0.0_amd64.deb
sudo apt install ./wwal_3.0.0_amd64.deb

NixOS / Nix (flake.nix)

nix profile install github:Execorn/wwal

Build from Source (Ubuntu, Fedora, Debian, Arch, Void, Alpine)

  1. Install your system build tools (meson, ninja, gcc or clang, pkg-config) and base libraries (wayland, wayland-protocols, libdrm, mesa, libva, liburing, libseccomp, libpng, libjpeg-turbo, plus optional qt6-base and sqlite3 for wwal-studio).
  2. Build and install (pass -Dstudio=disabled for a headless/CLI-only build):
git clone https://github.com/Execorn/wwal.git
cd wwal
meson setup build --prefix="$HOME/.local" --buildtype=release -Doptimization=3 -Db_lto=true -Dstudio=auto
meson compile -C build
meson install -C build

Popular Commands

Start the background daemon once (or add wwald & / swww-daemon & to your compositor startup file):

wwald &

1. Set Any Wallpaper & Extract Colors

# Set a wallpaper with a ripple effect starting at your mouse cursor
wwal img ~/Pictures/Wallpapers/mountain.jpg --transition-type ripple --transition-pos cursor

# Frame portrait art from the top and pick the secondary accent color (0..3)
wwal img ~/Pictures/Wallpapers/portrait.png --crop-gravity top --theme --source-color-index 1

# Pass a photo, video, shader, Workshop ID, GNOME .xml, or folder to `wwal img`
wwal img 2841902341

2. Built-In Wallpaper Picker & Studio GUI

# Open Rofi / Fuzzel / Walker with thumbnails for images, videos, shaders & Workshop items
wwal pick

# Output JSON metadata + thumbnail paths for Quickshell / Eww / AGS widgets
wwal pick --menu json

# Launch the WayWal Studio GUI (library browser, shader/scene sliders, theme studio & monitor canvas)
wwal-studio

# Launch Studio scanning specific wallpaper folders while excluding subfolders
wwal-studio -d ~/Pictures/Wallpapers -x Screenshots

3. Play a Video or GIF

# Play a looping 4K video wallpaper
wwal video ~/Videos/rain.mp4

# Play a video at 40% volume, and auto-duck it when other apps play sound
wwal video ~/Videos/scenic.mp4 --volume 0.4 --mute-on-audio

4. Use Steam Wallpaper Engine

If you own Wallpaper Engine on Steam, wwal finds and runs your Workshop library natively:

# List your installed Steam Workshop wallpapers
wwal workshop list

# Apply a Workshop wallpaper by its ID or folder path
wwal workshop apply 2841902341

# Create preview symlinks (~/.cache/wwal/workshop-previews/) for GUI pickers like Waypaper
wwal workshop sync-previews

5. Built-In Shaders & Slideshows

# List all 10 built-in shaders and launch one with live PipeWire audio reactivity
wwal shader list
wwal shader preset audio_bars --audio

# Run a mixed-media slideshow and step forward or backward
wwal slideshow ~/Pictures/Wallpapers --interval 30m --sort mtime
wwal next
wwal prev

6. Everyday Controls

wwal restore       # Restore your last wallpaper on login
wwal pause         # Pause active video, shader, or Workshop animation
wwal toggle        # Toggle pause and play
wwal clear 1e1e2e  # Set a zero-RAM solid color background
wwal status        # Show current wallpaper, screen info, and active colors

Configuration

WayWal works out of the box with no setup. If you want to save default transitions, app color templates, battery rules, or sun schedules, copy the example file to ~/.config/wwal/config.toml:

mkdir -p ~/.config/wwal
cp contrib/config.toml.example ~/.config/wwal/config.toml

More Docs

About

The last wallpaper engine your Linux desktop will ever need — replaces swww/awww, mpvpaper, linux-wallpaperengine, glpaper, wpaperd & matugen/pywal in one absurdly fast C23 daemon.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages