wallpiper

A lightweight translation layer for Wallpaper Engine on x86_64 GNU/Linux based compositors without re-inventing the wheel. Proton does most of the heavy lifting, while wallpiper re-implements/patches niche portions of the PE/COFF Windows API Wallpaper Engine needs.

Wallpiper then metaphorically "pipes" your wallpaper (using zero-copy dma-buf) from an internal frame buffer to a desktop portal. No overhead.

If you find this utility/tool useful, please consider giving it a star ⭐

Why? Other projects exist?¹

It's simple. Wallpiper is a translation layer, not a re-implementation. It doesn't depend on Wallpaper Engine, or any program it could theoretically run. Think of it more like Proton itself. Other projects, such as linux-wallpaperengine, are re-implementations. This means Wallpaper Engine's private spec/codebase is being cloned/mirrorred (largely by LLM technology, which has a tendency to hallucinate). By design, its far more unstable, and not actually Wallpaper Engine.

NOTE: Wallpiper is early in development. Although backed by proper design, you may face breaking issues.

Core Dependencies²

• wallpaper-engine
• proton (>= v11.0 was tested working)
• fontconfig (optional: for local-font overrides)
• vulkan-headers
• vulkan-icd-loader
• make
• dbus
• c99 compiler

On Arch Linux:

$ pacman -S base-devel dbus vulkan-headers vulkan-icd-loader fontconfig

Packaging³

We welcome additional packaging submissions, all related packaging logic resides in .github/packages

Arch Linux (AUR)

Get it from the AUR, or compile manually below.

Building from source⁴

It is highly recommended that you have a clean, never before ran installation of Wallpaper Engine before continuing. Running it through Steam, Proton, Wine, or other compatability tools may silently break your install before you even start.

If you face any issues during install, this should be your first hunch.

Wallpiper Core

Start by building the core of wallpiper

$ make build-core

# optionally install wallpiper to `%HOME/.local/lib/wallpiper/`
$ make install-wallpiperd

Wallpiper Portals

Wallpiper supports the following DE/WM(s) through the following portals. Jump to whatever section is relevant to you. Pull requests are welcome for additional portals. You can also submit an issue report to suggest other portals.

• wallpiper-portal-gnome
• wallpiper-portal-kde
• wallpiper-portal-hyprland
• wallpiper-portal-sway
• wallpiper-portal-cosmic
• wallpiper-portal-i3

Usage⁵

When built from source, wallpiper is NOT installed to PATH automatically. All binaries live at ./build/release relative to the repository root.

# check config
$ wallpiperctl check-config

# run wallpiperd (manages proton and wallpaper engine. YOU DO NOTHING)
$ WALLPIPER_PORTAL=portal [WALLPIPER_*...] wallpiperd

Environment Variables⁶

wallpiperd has no persistent configuration, all variability is mutable through environment variables.

See docs/ENVIRONMENT_VARIABLES.md or wallpiperd --help/-h.

Command API⁷

wallpiperctl is a control process for the wallpiperd daemon, and wallpaper-engine.

See docs/COMMAND_API.md or wallpiperctl --help/-h.

Troubleshooting⁸

See TROUBLESHOOTING.md.

Contributing⁹

Issues and pull requests are welcome. See CONTRIBUTING.md. If wallpiper is useful to you, a star helps others find it!

License¹⁰

MIT see LICENSE.

Footnotes

1. Why wallpiper ↩

2. Core dependencies ↩

3. External repository packaging status ↩

4. Building wallpipers source code ↩

5. Wallpiper usage ↩

6. Environment variable documentation ↩

7. Command API documentation ↩

8. Troubleshooting wallpiper ↩

9. Contributing to the wallpiper code-base ↩

10. Licensing agreement ↩