Ultra-lightweight, low-resource video wallpaper for Linux, designed for low-end and old hardware.
A minimal Bash script around mpv, with automatic pausing when the wallpaper is not visible.

Install  ·  Usage  ·  Requirements  ·  How it works  ·  Measured

• Lightweight, low resource. About 2% of one CPU core while playing, 0% when covered. See Measured.
• Runs on low-end, old hardware. Tested on a Core2 Duo with no hardware video decoding.
• Minimal. One Bash script. No daemon, no GUI, no Electron.
• Built on mpv. A mature, light player does the decoding; lowpaper only places it and pauses it.
• Video wallpaper, image or slideshow. mp4, webm, gif, jpg, png, or a whole folder.
• X11 and Wayland. XFCE, MATE, Cinnamon, Sway, Hyprland, KDE.
• Pauses itself when a fullscreen or maximized window covers the desktop.

sudo apt install mpv
mkdir -p ~/.local/bin
curl -Lo ~/.local/bin/lowpaper https://github.com/Meinianda-L/lowpaper-live-wallpaper/releases/latest/download/lowpaper
chmod +x ~/.local/bin/lowpaper

lowpaper is a single file, so that is the whole install. The same script handles X11 and Wayland. To remove it, run lowpaper stop and delete the file.

lowpaper ~/Videos/rain.mp4
lowpaper ~/Pictures/sky.jpg
lowpaper -i 600 -s ~/Pictures     # folder = slideshow; -i image interval in seconds, -s shuffle
lowpaper -f fit video.mp4         # fill (default, crop) | fit (letterbox) | stretch
lowpaper -o HDMI-1 video.mp4      # one monitor only
lowpaper                          # show what is playing
lowpaper pause | resume | toggle | next | stop | status | restore
lowpaper fit fill|fit|stretch     # change scaling live
lowpaper autopause on|off         # pause while the wallpaper is covered (default on)
lowpaper startup on|off           # start at login, restoring the last wallpaper

Settings live in ~/.config/lowpaper/config (FIT, INTERVAL, AUTOPAUSE, CACHE_MB, ICONS, HWDEC).

Optional: gcc also keeps XFCE desktop icons above the video. OpenBSD nc (default on Debian and Ubuntu) is used for mpv IPC, about 3 ms per call; without it lowpaper falls back to python, which is much slower on old CPUs.

GNOME on Wayland has no layer-shell; use the Hanabi extension there. Bare window managers (i3, openbox) without a desktop window are not supported.

X11. A one-shot python call creates a desktop-type window and exits. mpv draws into it with --wid, using Xv where available, which is the cheapest path on old GPUs. A small Bash watcher follows focus and window-state changes through xprop -spy, so it sleeps until something actually changes, and pauses mpv while a fullscreen or maximized window is on top or the monitor is off.

Wayland. lowpaper builds a small C helper the first time it is needed and keeps it in ~/.cache/lowpaper. The helper speaks the wlr-layer-shell protocol directly, places one background surface per output, and renders through libmpv. It declares the few Wayland, EGL and libmpv functions it uses itself, so no -dev packages are needed: only gcc and the libraries mpv already depends on. A compositor stops sending frame callbacks to a surface nobody can see; the helper uses that to pause.

Short clips are decoded once and replayed from RAM, which takes the decoder out of the loop. Longer videos fall back to normal decoding. CACHE_MB sets the limit.

Linux Mint 22.3 XFCE/X11, Core2 Duo P8600, GeForce 320M (nouveau, no usable hwdec), 1080p display, 1280×962 10 fps H.264 clip (3 s).

• After a resolution or monitor change, or if xfdesktop restarts on its own, run lowpaper restore.
• On Wayland, lowpaper autopause on|off applies from the next start.