nosignal/Motion-Wallpaper-Omarchy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
Animated video wallpapers for Omarchy using mpvpaper (Hyprland/Wayland)
6 commits 1 branch 0 tags 166 KiB
Find a file
28allday f31ff2b152 v2: gum TUI, autostart, auto-pause watcher, Omarchy fixes 
Major rewrite of the runtime so the entry point is a proper gum TUI
instead of zenity dialogs, plus a handful of correctness fixes that
make it work on real Omarchy setups.

Runtime (motion-wallpaper-toggle, extracted from the installer heredoc):
  * Full gum TUI: status header, monitor picker (with All monitors),
    library / filesystem pickers, change-video, autostart toggle.
  * State file at ~/.config/motion-wallpaper/state remembers last
    video, target monitor, and last-used directory so Browse reopens
    where the user was.
  * Actions: toggle | start | stop | change | status.

Autostart:
  * Ships a systemd user unit (motion-wallpaper.service).
  * First fresh start prompts the user via gum confirm to enable it.
  * Running-state menu offers a Turn autostart ON/OFF entry.
  * Header shows the current autostart state.

Auto-pause:
  * mpvpaper's -p is unreliable on Hyprland 0.54.x, so a small
    motion-wallpaper-watcher subscribes to Hyprland's socket2 and
    toggles mpv pause/resume via --input-ipc-server on fullscreen
    enter/exit. Started/stopped alongside mpvpaper.

Omarchy compatibility:
  * Stop path now respawns swaybg pointed at
    ~/.config/omarchy/current/background via setsid uwsm-app (the way
    Omarchy autostarts it), instead of execing hyprpaper which isn't
    present. Falls back to hyprpaper on non-Omarchy Hyprland setups.
  * mpvpaper is launched under setsid uwsm-app so it survives the
    Walker-spawned terminal closing.

Install / UX:
  * Installer only invokes sudo/yay when packages are actually
    missing, so reinstall is quiet.
  * Dropped zenity; added gum + socat + libnotify.
  * Custom SVG icon in the hicolor theme so Walker shows a proper
    tile. Installer restarts elephant.service so the new entry/icon
    appear without logout.
  * .desktop flipped to Terminal=true so launchers spawn a terminal
    for the TUI.
  * Watcher lookup falls back to the script's own dir when PATH is
    minimal (launcher-spawned terminals).

Bug fixes:
  * Monitor picker was sending row-major data to zenity as one cell;
    fixed (kept the correct form for the new gum picker).
  * load_state / action_status no longer leak a non-zero exit code
    from trailing test expressions.
  * Stop path cleans up stray hyprpaper that would otherwise win the
    background layer.
2026-04-23 20:33:02 +01:00
icons v2: gum TUI, autostart, auto-pause watcher, Omarchy fixes 2026-04-23 20:33:02 +01:00
motion-wallpaper-toggle v2: gum TUI, autostart, auto-pause watcher, Omarchy fixes 2026-04-23 20:33:02 +01:00
motion-wallpaper-watcher v2: gum TUI, autostart, auto-pause watcher, Omarchy fixes 2026-04-23 20:33:02 +01:00
motion-wallpaper.service v2: gum TUI, autostart, auto-pause watcher, Omarchy fixes 2026-04-23 20:33:02 +01:00
README.md v2: gum TUI, autostart, auto-pause watcher, Omarchy fixes 2026-04-23 20:33:02 +01:00
wallpaper.sh v2: gum TUI, autostart, auto-pause watcher, Omarchy fixes 2026-04-23 20:33:02 +01:00

README.md

Motion Wallpaper - Omarchy

Video Title

Animated video wallpapers for Omarchy (Arch Linux + Hyprland).

Uses mpvpaper to play any video file as your desktop wallpaper. Features a gum-powered TUI with Stop / Change-video options, a quick-pick library folder, optional systemd autostart so the wallpaper survives reboots, and pause-on-fullscreen so games and full-screen video don't pay the decode cost.

Quick Start

git clone https://git.no-signal.uk/nosignal/Motion-Wallpaper-Omarchy.git
cd Motion-Wallpaper-Omarchy
chmod +x wallpaper.sh
./wallpaper.sh

The installer handles all dependencies automatically.

Requirements

  • OS: Omarchy (Arch Linux)
  • Compositor: Hyprland
  • AUR Helper: yay or paru (for mpvpaper)

What It Installs

Packages

Package Source Purpose
mpv Official repos Video player engine (decodes and renders video)
jq Official repos Parses monitor info from Hyprland
gum Official repos TUI toolkit (action menus, monitor picker, file browser)
libnotify Official repos notify-send for post-action desktop notifications
mpvpaper AUR Wayland wallpaper daemon that uses mpv as its backend

Files Created

Path Purpose
~/.local/bin/motion-wallpaper-toggle Runtime script (toggle / start / stop / change / status)
~/.local/share/applications/motion-wallpaper-toggle.desktop App launcher entry
~/.config/systemd/user/motion-wallpaper.service Optional autostart unit (not enabled by default)
~/.config/motion-wallpaper/state Last-used video + target monitor
~/.cache/motion-wallpaper.log Runtime log

Usage

From App Launcher

Search for "Motion Wallpaper" in Walker or your app launcher. Because the entry is a TUI, your launcher spawns a terminal window (Terminal=true in the .desktop entry) and runs the gum interface inside it. The terminal closes automatically when the action finishes.

From Terminal

motion-wallpaper-toggle            # interactive — toggle, or Stop/Change if running
motion-wallpaper-toggle change     # pick a new video without stopping first
motion-wallpaper-toggle stop       # stop and restore the normal wallpaper
motion-wallpaper-toggle status     # print current state
motion-wallpaper-toggle start      # non-interactive start from saved state (used by systemd)

With a Keybind

Add this to ~/.config/hypr/bindings.conf:

bind = SUPER ALT, W, exec, ~/.local/bin/motion-wallpaper-toggle

Note

: SUPER+W is already bound to "Close window" in Omarchy. Use SUPER ALT+W or another free combination.

Video library folder

Drop videos in ~/Videos/Wallpapers/ and the picker shows that folder as a quick list instead of opening the full filesystem browser. A Browse… entry is always available for picking something outside the library.

Persist across reboots (autostart)

Enable the bundled systemd user unit — it calls motion-wallpaper-toggle start, which loads the last video and target monitor from state and starts mpvpaper non-interactively:

systemctl --user enable --now motion-wallpaper.service

Disable with systemctl --user disable --now motion-wallpaper.service. If no state has been saved yet, the unit exits cleanly without error.

How It Works

Toggle — not running

  1. Detects monitors via hyprctl monitors -j.
  2. If multiple monitors, offers a picker with an All monitors option (passes * to mpvpaper).
  3. Shows the video library (if any) or a file picker.
  4. Stops the current wallpaper daemon (swaybg on Omarchy, or hyprpaper on generic Hyprland) so mpvpaper is visible, then starts mpvpaper -f with --auto-pause, --loop, --vo=gpu, --profile=high-quality.
  5. Verifies mpvpaper is alive after 0.5s; surfaces failures inline in the TUI and holds the terminal open until you press enter.
  6. Saves the video path and target to ~/.config/motion-wallpaper/state.

Toggle — already running

Shows a radiolist with two choices:

  • Stop motion wallpaper — kill mpvpaper and restore the previous static wallpaper. On Omarchy this respawns swaybg -i ~/.config/omarchy/current/background -m fill via uwsm-app, matching how Omarchy autostarts it; on generic Hyprland it re-execs hyprpaper.
  • Change video — pick a new video, keep the same target, swap in place.

Supported Video Formats

Any format mpv supports, including:

  • .mp4 (H.264, H.265)
  • .mkv (Matroska)
  • .webm (VP9, AV1)
  • .mov (QuickTime)
  • .avi

Finding Video Wallpapers

Search for "live wallpaper" or "motion desktop" videos. Good sources include:

  • YouTube (download with yt-dlp)
  • Wallpaper Engine workshop (some can be extracted)
  • Free stock video sites (Pexels, Pixabay)

Tips for best results:

  • Match your monitor resolution (e.g. 3840x2160 for 4K)
  • Seamless loops look best (no visible cut at the loop point)
  • Shorter videos (10-30 seconds) use less memory
  • H.264 .mp4 has the best hardware decode support

Performance

mpvpaper uses GPU-accelerated rendering (--vo=gpu) so CPU usage is minimal. --auto-pause also pauses playback whenever a fullscreen window covers the wallpaper, so games and full-screen video don't pay the decode cost.

  • Higher resolution videos use more VRAM.
  • Shorter seamless loops (10–30s) use less memory.
  • If you still notice impact, toggle the wallpaper off or disable autostart.

Troubleshooting

First stop: ~/.cache/motion-wallpaper.log — both the toggle script and mpvpaper write there.

Video wallpaper doesn't appear / shows black

  • Check the log. Codec issues and "no such monitor" errors both show up there.
  • Make sure hyprpaper and swaybg are not running: pgrep hyprpaper && pkill hyprpaper

TUI fails with "gum is not installed"

  • sudo pacman -S gum

Launcher runs it but no terminal opens

  • Make sure your default terminal is XDG-registered. Omarchy's alacritty works out of the box.
  • As a fallback, run motion-wallpaper-toggle directly from any terminal.

"No monitors detected" error

  • Make sure you're running Hyprland: echo $XDG_CURRENT_DESKTOP
  • Check hyprctl works: hyprctl monitors

Autostart unit fails

  • journalctl --user -u motion-wallpaper.service
  • If the saved video was moved or deleted, the unit exits non-zero. Run the toggle interactively once to save fresh state.

Normal wallpaper doesn't come back after toggling off

  • Omarchy: pkill -x swaybg; setsid uwsm-app -- swaybg -i ~/.config/omarchy/current/background -m fill &
  • Or just cycle the background: omarchy-theme-bg-next then back with SUPER CTRL SPACE.
  • Generic Hyprland: hyprctl dispatch exec hyprpaper.

Uninstalling

# Stop and disable autostart if enabled
systemctl --user disable --now motion-wallpaper.service 2>/dev/null || true

# Remove installed files
rm -f ~/.local/bin/motion-wallpaper-toggle
rm -f ~/.local/share/applications/motion-wallpaper-toggle.desktop
rm -f ~/.local/share/icons/hicolor/scalable/apps/motion-wallpaper.svg
rm -f ~/.config/systemd/user/motion-wallpaper.service
rm -rf ~/.config/motion-wallpaper
rm -f ~/.cache/motion-wallpaper.log
systemctl --user daemon-reload

# Optionally remove packages
sudo pacman -Rns mpvpaper zenity

Credits

  • Omarchy - The Arch Linux distribution this was built for
  • mpvpaper - Wayland video wallpaper daemon
  • mpv - The video player engine
  • Hyprland - Wayland compositor

License

This project is provided as-is for the Omarchy community.