MPVPAPER(1)

💅 MPVPAPER — the manual, bestie edition ✨

okay so you want a video as your wallpaper? on a wlroots compositor? say less, because mpvpaper is literally that girl 🫶

---

🎀 NAME 🎀

mpvpaper — a video wallpaper player that uses mpv to do its thing, made for wlroots. that's the whole vibe, no cap.

---

✨ SYNOPSIS ✨

mpvpaper [options] <output> <url|path filename>

---

💖 DESCRIPTION 💖

so mpvpaper is a wallpaper program for wlroots-based Wayland compositors — like Sway, iykyk — and it lets you play videos with mpv as your wallpaper. yes, actual moving video. as your background. main character desktop energy, periodt. 👑

---

🌸 OPTIONS 🌸

• -h, --help — shows you the usage options. that's it. that's the whole thing 💁‍♀️
• -d, --help-output — lists out all the available outputs and then dips (quits). super handy when you're like "wait what's my monitor even called"
• -v, --verbose — be more verbose! and if you're feeling extra, -vv gives you higher verbosity. more words, more lore 🗣️
• -f, --fork — forks mpvpaper so you can close the terminal without killing your wallpaper. freedom 💅
• -p, --auto-pause — automagically pauses mpv when the wallpaper is hidden* ✨ this saves CPU usage, more or less, seamlessly
• -s, --auto-stop — automagically stops mpv when the wallpaper is hidden* ✨ this saves CPU/RAM usage, although more abruptly
• -n, --slideshow <seconds> — slideshow mode! plays the next video in a playlist every <seconds> 🎞️ and it passes mpv options "loop loop-playlist" for convenience. cute and convenient, we love a multitasker
• -l, --layer <layer> — specifies which shell surface <layer> to run on (the default is background)
• -o, --mpv-options <"options"> — forwards mpv <"options"> right on through 🫶 must be within quotes if you're passing multiple options, okurrr

---

🌈 EXAMPLES 🌈

simple example:

mpvpaper DP-2 /path/to/video

you can select the output with either a connection name or an identifier name:

mpvpaper 'DP-2 DP-1 HDMI-A-1' /path/to/video
mpvpaper 'Acer Technologies Acer H236HL LX1AA12341234' /path/to/video

to play the same video on ALL outputs:

mpvpaper ALL /path/to/video

forward mpv options by passing "--mpv-options" or "-o" like so:

mpvpaper -o "no-audio --loop-playlist shuffle" HDMI-A-1 www.url/to/playlist

and bestie, you can also control mpvpaper just like mpv in the terminal with keyboard bindings 🎹

but if you want to control mpvpaper while it's forked, you could use an mpv input-ipc-server like this:

mpvpaper -o "input-ipc-server=/tmp/mpv-socket-DP-1" DP-1 /path/to/video

then send input commands with socat. for example, to toggle pause:

echo 'cycle pause' | socat - /tmp/mpv-socket-DP-1

for more mpv commands, read this: https://mpv.io/manual/master/#command-interface ⭐

---

🧚 FILES 🧚

these files (the watch lists) contain lists of program names that, if they're found running with pidof, will cause mpvpaper to pause/stop. and you have to create them manually** 🙈

• ~/.config/mpvpaper/pauselist — list of program names that will cause mpvpaper to pause
• ~/.config/mpvpaper/stoplist — list of program names that will cause mpvpaper to stop

add programs that can be found with the pidof command into the list, and separate them by spaces or newlines.

for example, "firefox steam obs" — or:

"firefox
 steam
 obs"

---

💀 NOTES 💀

*limitations of automagic:

mpvpaper manipulates a feature of Wayland called a "surface frame callback".

this feature of Wayland is what lets mpvpaper draw/render only when it actually makes sense to do so. and one reason mpvpaper might not draw/render is if it's "hidden". that's the literal magic behind the automagic pause/stop options ✨

whatever "hidden" means is up to the compositor. as for Sway, "hidden" means there's a fullscreen window in the way of the wallpaper. mpvpaper will still draw/render even if there's a normal window blocking the wallpaper view entirely. rude, but ok.

this feature is at best a hack that works on some compositors. usability of these auto options will vary and may not work as intended or at all 😭 in such a case, other features like the "watch lists" mentioned above should be used instead.

**more on lists:

• mpvpaper will automatically resume only after all the programs in the watch lists are no longer running
• if there are programs running from both lists, stopping will always win out. stop stays undefeated 💀
• programs added into a list at runtime will be ignored, unless restarted or "stopped"

extra notes:

• when mpvpaper is resuming after "stopping", mpvpaper should begin where it left off — both in terms of time position and playlist position (if not shuffled) ⏱️
• there's a small time delay (1-2 secs.) with the automagic options, because it uses time to calculate when to act. patience, bestie 🧘‍♀️
• mpv user configs are loaded by default

---

👑 AUTHOR 👑

created by GhostNaN

based on swaybg

inspired by scoopta's glpaper

code repository: https://github.com/GhostNaN/mpvpaper/

---

🦋 SEE ALSO 🦋

mpv (1) — go read that one too, it's giving essential 💜

---

so yeah!! that's mpvpaper version 1.8, dated May 2025, bestie — go make your desktop iconic, ily, bye 🫶✨🎀