Linux Wallpaper Engine

A lightweight Rofi-based wallpaper selector for Linux.

It can use three kinds of wallpaper sources:

• Steam Workshop wallpapers through Wallpaper Engine + linux-wallpaperengine
• Local images through swaybg
• Local videos/animated files through mpvpaper

The same selector, thumbnail gallery, last-wallpaper restore, and muted-audio behavior are shared across all three backends.

How it works

Wallpaper source
      │
      ├── Steam Workshop URL ──> linux-wallpaperengine
      │
      ├── Local image ─────────> swaybg
      │
      └── Local video ─────────> mpvpaper
                    │
                    ▼
             Rofi thumbnail gallery
                    │
                 select
                    │
                    ▼
             Wallpaper changes
                    │
                    ▼
          Last selection is saved
                    │
                    ▼
              Restore on login

The core scripts are not tied to Hyprland. Hyprland is only one integration example included in this repository. On another compositor or desktop environment, the same scripts can be started from that environment's autostart and keyboard-shortcut mechanism.

Features

• One wallpaper entry per line.
• Paste a Steam Workshop URL directly; no need to type the numeric Workshop ID.
• Use local image and video paths alongside Steam wallpapers.
• Rofi thumbnail gallery instead of a list of long URLs.
• Automatic support for common Steam preview files: jpg, jpeg, png, webp, and gif.
• Automatic thumbnails for local videos when ffmpeg is installed.
• Duplicate handling is preserved for Steam entries through the normal list behavior.
• Changes wallpaper immediately after selection.
• Remembers the last selected wallpaper and restores it on the next session.
• Wallpaper audio is muted by default.
• Monitor name and paths can be overridden with environment variables.
• Downloaded Steam Workshop assets are not stored in this repository.

Requirements

Core

• Linux
• Bash
• Rofi with icon support

Steam Workshop wallpapers

• Wallpaper Engine on Steam
• At least one subscribed/downloaded Workshop wallpaper
• linux-wallpaperengine

Local images

• swaybg

Local videos

• mpvpaper
• ffmpeg is recommended for generating video thumbnails in the Rofi gallery

You only need the backends for the wallpaper types you plan to use.

Arch Linux

Install the core selector requirements:

sudo pacman -S rofi-wayland

For Steam Workshop wallpapers, install the Linux renderer from AUR, for example with paru:

paru -S linux-wallpaperengine-git

For local images:

sudo pacman -S swaybg

For local videos, install mpvpaper from your preferred Arch package/AUR source and install ffmpeg for thumbnail generation.

Installation

Clone the repository:

git clone https://github.com/ilhamfirmansyahhub/linux-wallpaper-engine.git
cd linux-wallpaper-engine

Install the scripts:

mkdir -p ~/.local/bin ~/.config/wallpaperengine

cp wallpaper-engine-select ~/.local/bin/
cp wallpaper-engine-start ~/.local/bin/

chmod +x ~/.local/bin/wallpaper-engine-select
chmod +x ~/.local/bin/wallpaper-engine-start

Create your personal wallpaper list:

cp wallpapers.conf ~/.config/wallpaperengine/wallpapers.conf

Then edit:

$EDITOR ~/.config/wallpaperengine/wallpapers.conf

Wallpaper list format

Use one entry per line. Empty lines and lines beginning with # are ignored.

Steam Workshop

Paste the Workshop URL:

https://steamcommunity.com/sharedfiles/filedetails/?id=2458916637

The script extracts the Workshop ID automatically and looks for the wallpaper in the local Steam Workshop directory.

Local image

Use an absolute path or a path beginning with ~/:

/home/your-user/Pictures/wallpapers/example.jpg
~/Pictures/wallpapers/example.png

Supported image extensions include jpg, jpeg, png, webp, and bmp.

Local video

/home/your-user/Videos/wallpapers/example.mp4
~/Videos/wallpapers/example.webm

Common video formats such as mp4, mkv, webm, mov, avi, m4v, mpg, mpeg, and gif are recognized.

Steam Workshop location

The default native-Steam Workshop directory used by the script is:

~/.local/share/Steam/steamapps/workshop/content/431960

431960 is the Steam App ID for Wallpaper Engine.

If your Steam library is installed somewhere else, override it with:

export WALLPAPER_ENGINE_STEAM_WORKSHOP="/path/to/workshop/content/431960"

or edit the value directly in the script.

Selecting a wallpaper

Run:

~/.local/bin/wallpaper-engine-select

Rofi opens a thumbnail grid. Select an item and the appropriate backend is started automatically:

Steam Workshop URL → linux-wallpaperengine
Image path          → swaybg
Video path          → mpvpaper

The selected entry is stored in:

~/.config/wallpaperengine/current

Restoring the last wallpaper

Run:

~/.local/bin/wallpaper-engine-start

The script reads ~/.config/wallpaperengine/current, detects the source type again, and starts the matching backend.

You can put this command in your desktop/compositor autostart configuration.

Monitor selection

The default target is:

DP-4

Set another output without editing the scripts:

export WALLPAPER_ENGINE_SCREEN=HDMI-A-1

This variable is used for Steam wallpapers, mpvpaper, and swaybg.

For Hyprland, find monitor names with:

hyprctl monitors

For setups with multiple outputs, adjust the scripts or launch additional backend instances as needed.

Audio

Wallpaper audio is disabled by default.

• Steam wallpapers use linux-wallpaperengine --silent.
• Local videos use mpvpaper -o 'no-audio --loop'.

The video continues to play; only its background audio is muted.

Hyprland integration

Hyprland integration is provided as examples in:

hyprland/
├── startup.lua.example
└── keybinds.lua.example

Startup:

hl.exec_cmd("~/.local/bin/wallpaper-engine-start")

Shortcut:

hl.bind("SUPER + W", hl.dsp.exec_cmd("~/.local/bin/wallpaper-engine-select"))

Add these to your existing Hyprland Lua configuration using the syntax required by your installed Hyprland Lua API.

Other compositors and desktops

The scripts themselves do not require Hyprland. For another Wayland compositor or desktop environment, connect them to that environment's startup and shortcut facilities:

autostart  → ~/.local/bin/wallpaper-engine-start
shortcut   → ~/.local/bin/wallpaper-engine-select

For example, Sway, River, Wayfire, labwc, KDE Plasma Wayland, and other environments can use the same core scripts when their session provides the required Wayland protocols and backend support.

The repository does not require Waypaper. Waypaper can still be used separately as a wallpaper manager; this project directly invokes swaybg or mpvpaper for local files and linux-wallpaperengine for Steam Workshop items.

Configuration environment variables

WALLPAPER_ENGINE_CONFIG
WALLPAPER_ENGINE_STATE
WALLPAPER_ENGINE_SCREEN
WALLPAPER_ENGINE_STEAM_WORKSHOP
WALLPAPER_ENGINE_THUMB_CACHE

Example:

export WALLPAPER_ENGINE_SCREEN=HDMI-A-1
export WALLPAPER_ENGINE_STEAM_WORKSHOP="$HOME/.steam/steam/steamapps/workshop/content/431960"

Troubleshooting

Wallpaper does not appear in Rofi

For a Steam wallpaper, confirm that Steam has downloaded the Workshop item and that its directory exists below the configured 431960 directory.

For a local file, verify that the path in wallpapers.conf exists:

ls -l /path/to/wallpaper

Local video has no thumbnail

Install ffmpeg. The selector uses it to generate and cache a preview frame under:

~/.cache/wallpaperengine/thumbs

Local video does not start

Check that mpvpaper is installed and that the file can be opened normally with mpv.

Local image does not start

Check that swaybg is installed and that the image format is supported by your build.

Wallpaper works manually but not at login

Test the restore script directly:

~/.local/bin/wallpaper-engine-start

If that works, the remaining problem is the autostart configuration for your compositor or desktop environment.

Wrong monitor

Set the correct output name with:

export WALLPAPER_ENGINE_SCREEN=YOUR_OUTPUT

Or edit the persistent environment used by your session.

What is stored in this repository

linux-wallpaper-engine/
├── wallpaper-engine-select
├── wallpaper-engine-start
├── wallpapers.conf
├── hyprland/
│   ├── startup.lua.example
│   └── keybinds.lua.example
├── .gitignore
└── README.md

This project stores scripts and examples only. Do not commit downloaded Steam Workshop videos, GIFs, scene files, or other large wallpaper assets.

Credits

• Almamu/linux-wallpaperengine — Linux renderer for Wallpaper Engine content
• Wallpaper Engine — Workshop library and content distribution
• Rofi — thumbnail selector UI
• swaybg — local image backend
• mpvpaper — local video backend

This repository is an integration and automation layer around these projects; it does not replace them.