mauri - Wallpaper Engine Implementation (for Linux)

Branch	Commit message	Author	Age
master	Update flake	Andrew Opalach	2 months


Age	Commit message	Author
2026-05-19	Update flakeHEAD master	Andrew Opalach
2026-05-19	Update deps	Andrew Opalach
2025-12-01	Update flake	Andrew Opalach
2025-12-01	Improve flake and build	Andrew Opalach
2025-12-01	Update flake	Andrew Opalach
2025-12-01	Update deps	Andrew Opalach
2025-10-30	Update flake	Andrew Opalach
2025-10-30	Update readme and deps	Andrew Opalach
2025-08-14	Monitor config dir for changes	Andrew Opalach
2025-07-29	Small build cleanup and tweak readme	Andrew Opalach
[...]

Clone
https://git.akon.city/mauri.git

Building

Dependencies

C++17 and C99 compiler
meson
cmake
libegl
libgl
nlohmann_json
lz4
stb_image
glm
notcurses optional (taro)
jansson optional (taro)

X11

libx11
libxext
libxrandr

Wayland

wayland
wayland-egl
wayland-protocols
wlr-protocols

Packages

debian12

# Common.
sudo apt install git meson cmake pkg-config libegl-dev nlohmann-json3-dev liblz4-dev libstb-dev libglm-dev libjansson-dev libavcodec-dev libavdevice-dev libunistring-dev libdeflate-dev libtinfo-dev
# Wayland.
sudo apt install libwayland-dev
# X11.
sudo apt install libxext-dev libxrandr-dev

archlinux

# Common.
sudo pacman -S --needed git meson cmake libegl nlohmann-json lz4 stb glm jansson ffmpeg libdeflate
# Wayland.
sudo pacman -S --needed wayland wayland-protocols wlr-protocols
# X11.
sudo pacman -S --needed libxext libxrandr

Compiling

$ meson setup build -Dwindow=(x11|wayland) -Dtaro=(enabled|disabled)
$ ninja -C build

Installing

Local

$ sudo ninja -C build install

Nix Flake

inputs = {
  mauri = {
    url = "git+https://git.akon.city/mauri";
    inputs.nixpkgs.follows = "nixpkgs";
  };
};

nixosSystem {
  system = system;
  modules = [
    ({ ... }: {
      nixpkgs.overlays = [
        (self: super: { mauri = mauri.packages.${system}.default; })
      ];
    })
  ];
};

Usage

$ mauri --help

Usage: mauri (-p, --package [path_to_scene.pkg]|-d, --directory [path_to_wallpaper]) [OPTIONS]
  -a, --assets   search path for common assets
  -w, --width    window width (default: 640)
  -h, --height   window height (default: 480)
  -o, --offset   offset of the scene camera (default: 0,0)
  -s, --scale    scale the window to the scene
  -m, --monitor  set as the background of this monitor (by name)
  -t, --target   dump the scene tree into this directory and exit

Examples

# Set as the background of DP-1.
$ ./mauri -p /mnt/hdd/SteamLibrary/steamapps/workshop/content/431960/1761287874/scene.pkg \
    -a /mnt/hdd/SteamLibrary/steamapps/common/wallpaper_engine/assets -w 2560 -h 1440 -m DP-1

# Dump the scene into ./output.
$ ./mauri -p /mnt/hdd/SteamLibrary/steamapps/workshop/content/431960/1582967473/scene.pkg \
    -a /mnt/hdd/SteamLibrary/steamapps/common/wallpaper_engine/assets -t ./output

Taro

# Run `tarod` once before anything to generate the necessary files for your setup.
$ tarod

# Open the terminal UI.
$ taro

Keybinds

←↓↑→/hjkl

Move Selection, Edit Value

Enter/Space

Confirm Selection

Tab

Cycle Between Grid and Info/Options

Goto Monitor Selection

f/b

Next/Previous Page

n/N

Set Next/Previous Wallpaper in Grid

Remove Current Wallpaper

Config

$ cat $HOME/.config/taro/config.json

{
    "directories": {
        "assets": "/mnt/hdd/SteamLibrary/steamapps/common/wallpaper_engine/assets",
        "wallpapers": [
            "/mnt/hdd/SteamLibrary/steamapps/workshop/content/431960"
        ]
    }
}

Sway Config Example

# Set wallpaper
bindsym Mod4+F1 exec printf '1633608994_p|false,100|' > $HOME/.config/taro/DP-1/selection
# Remove wallpaper
bindsym Mod4+F2 exec printf '||' > $HOME/.config/taro/DP-1/selection
# Run when starting Sway
exec tarod

Known Issues

Some gifs are incorrectly positioned.
Some objects are incorrectly scaled and/or positioned.
Some shaders fail to compile for various reasons.

Not Implemented

Particles
Mouse Paralax
Camera Shake
Animations/Puppet Warp
Javascript Scripting
3d Models
And much more...