README: catch up with watcher, autostart prompts, state parsing
Doc drift from the last two commits: * Intro mentioned "--auto-pause" — replaced with the external watcher, so rewrite to describe that instead. * Added socat to the deps table and the new motion-wallpaper-watcher binary + SVG icon to the Files Created table. * State file description updated to include LAST_DIR; mentions the atomic write + safe KEY=VALUE parser. * Autostart section replaced with the TUI-first flow (first-run prompt, menu toggle, stop-offers-disable, disable-offers-stop), with systemctl as an alternative. * How It Works expanded with the setsid + uwsm-app spawn, the flock on the stop path, and a new "Auto-pause (the watcher)" subsection describing the Hyprland socket2 + mpv IPC bridge. * Added a troubleshooting entry for auto-pause not firing (fullscreen vs full-width, watcher log check). * Uninstall removes the new watcher binary; package remove line updated to the real deps (was still listing zenity).
This commit is contained in:
parent
2ce38ce9eb
commit
48dd9b2f0a
1 changed files with 38 additions and 19 deletions
57
README.md
57
README.md
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Animated video wallpapers for [Omarchy](https://omarchy.com) (Arch Linux + Hyprland).
|
||||
|
||||
Uses [mpvpaper](https://github.com/GhostNaN/mpvpaper) to play any video file as your desktop wallpaper. Features a [gum](https://github.com/charmbracelet/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.
|
||||
Uses [mpvpaper](https://github.com/GhostNaN/mpvpaper) to play any video file as your desktop wallpaper. Features a [gum](https://github.com/charmbracelet/gum)-powered TUI with Stop / Change-video / autostart toggle, a quick-pick library folder, a systemd autostart unit so the wallpaper survives reboots, and an auto-pause watcher that subscribes to Hyprland's event socket and pauses the video whenever a fullscreen window covers the wallpaper — so games and full-screen video don't pay the decode cost.
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
|
@ -32,6 +32,7 @@ The installer handles all dependencies automatically.
|
|||
| `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) |
|
||||
| `socat` | Official repos | UNIX-socket bridge used by the auto-pause watcher |
|
||||
| `libnotify` | Official repos | `notify-send` for post-action desktop notifications |
|
||||
| `mpvpaper` | AUR | Wayland wallpaper daemon that uses mpv as its backend |
|
||||
|
||||
|
|
@ -39,10 +40,12 @@ The installer handles all dependencies automatically.
|
|||
|
||||
| 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 |
|
||||
| `~/.local/bin/motion-wallpaper-toggle` | Runtime TUI (toggle / start / stop / change / status) |
|
||||
| `~/.local/bin/motion-wallpaper-watcher` | Auto-pause watcher — pauses mpv on fullscreen |
|
||||
| `~/.local/share/applications/motion-wallpaper-toggle.desktop` | App launcher entry (Terminal=true) |
|
||||
| `~/.local/share/icons/hicolor/scalable/apps/motion-wallpaper.svg` | Launcher icon |
|
||||
| `~/.config/systemd/user/motion-wallpaper.service` | Autostart unit (not enabled by default) |
|
||||
| `~/.config/motion-wallpaper/state` | Last video, target monitor, and last-used directory |
|
||||
| `~/.cache/motion-wallpaper.log` | Runtime log |
|
||||
|
||||
## Usage
|
||||
|
|
@ -73,17 +76,20 @@ bind = SUPER ALT, W, exec, ~/.local/bin/motion-wallpaper-toggle
|
|||
|
||||
### 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.
|
||||
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. The last directory you picked from is remembered (`LAST_DIR` in the state file) — next time you **Browse…**, `gum file` opens there instead of `$HOME`.
|
||||
|
||||
### 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:
|
||||
The first time you start a wallpaper, the TUI asks whether to enable autostart. Say yes and the bundled systemd user unit is enabled — on next login it calls `motion-wallpaper-toggle start`, which loads the saved video + target and starts mpvpaper non-interactively.
|
||||
|
||||
You can flip autostart any time from the running-state menu (**Turn autostart ON / OFF**). The header always shows the current state. If you click **Stop** while autostart is still on, the TUI offers to disable it too so "stop" really means stop. If you disable autostart while the wallpaper is running, it offers to stop the current instance.
|
||||
|
||||
CLI alternative:
|
||||
```bash
|
||||
systemctl --user enable --now motion-wallpaper.service
|
||||
systemctl --user disable --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.
|
||||
If no state has been saved yet, the unit exits cleanly without error.
|
||||
|
||||
## How It Works
|
||||
|
||||
|
|
@ -91,17 +97,24 @@ Disable with `systemctl --user disable --now motion-wallpaper.service`. If no st
|
|||
|
||||
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`.
|
||||
3. Shows the video library (if any) or a `gum file` browser starting at `LAST_DIR`.
|
||||
4. Stops the current wallpaper daemon (`swaybg` on Omarchy, or `hyprpaper` on generic Hyprland) so mpvpaper is visible, then runs `setsid uwsm-app -- mpvpaper -o "..."` with `--loop --no-audio --mute=yes --vo=gpu --profile=high-quality --input-ipc-server=…` and spawns the watcher. `setsid` + `uwsm-app` detaches mpvpaper from the TUI terminal so it survives the window closing.
|
||||
5. Verifies mpvpaper is alive after 0.8s; surfaces failures inline and holds the terminal open until you press enter.
|
||||
6. Saves video, target, and last-used directory to `~/.config/motion-wallpaper/state` (atomic write, parsed back without `source` so it can't execute code from the state file).
|
||||
7. If autostart isn't already enabled, asks whether to enable it.
|
||||
|
||||
### Toggle — already running
|
||||
|
||||
Shows a radiolist with two choices:
|
||||
Shows a menu with four entries:
|
||||
|
||||
- **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.
|
||||
- **Stop motion wallpaper** — kill the watcher + 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`. Stop is `flock`-guarded, so the TUI path and systemd's `ExecStop` can't race.
|
||||
- **Change video** — pick a new video, keep the same target, swap in place (`LAST_DIR` updates if you browsed).
|
||||
- **Turn autostart ON / OFF** — toggles the systemd unit. Label reflects current state.
|
||||
- **Cancel** — bail without changes.
|
||||
|
||||
### Auto-pause (the watcher)
|
||||
|
||||
`motion-wallpaper-watcher` subscribes to Hyprland's event socket (`$XDG_RUNTIME_DIR/hypr/<instance>/.socket2.sock`) and, on `fullscreen>>1`, sends `{"command":["set_property","pause",true]}` to mpv's IPC socket (`--input-ipc-server`). On `fullscreen>>0` it resumes. The watcher is started and killed alongside mpvpaper by the toggle script. mpvpaper's own `-p` flag was flaky on Hyprland 0.54.x, hence this external approach.
|
||||
|
||||
## Supported Video Formats
|
||||
|
||||
|
|
@ -130,7 +143,7 @@ Search for "live wallpaper" or "motion desktop" videos. Good sources include:
|
|||
|
||||
## 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.
|
||||
mpvpaper uses GPU-accelerated rendering (`--vo=gpu`) so CPU usage is minimal. The watcher 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.
|
||||
|
|
@ -159,6 +172,11 @@ First stop: `~/.cache/motion-wallpaper.log` — both the toggle script and mpvpa
|
|||
- `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.
|
||||
|
||||
**Auto-pause isn't pausing on fullscreen**
|
||||
- Make sure the window is truly fullscreen (`hyprctl activewindow -j | jq '.fullscreen'` should be non-zero). On Omarchy, **SUPER+F** is true fullscreen; **SUPER+ALT+F** is only "full width" and won't trigger pause.
|
||||
- `grep watcher: ~/.cache/motion-wallpaper.log` should show `fullscreen entered — pause` / `fullscreen left — resume` lines.
|
||||
- If the watcher isn't running: `pgrep -af motion-wallpaper-watcher`. If missing, the toggle script failed to spawn it — check the log around the start time.
|
||||
|
||||
**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`.
|
||||
|
|
@ -172,6 +190,7 @@ systemctl --user disable --now motion-wallpaper.service 2>/dev/null || true
|
|||
|
||||
# Remove installed files
|
||||
rm -f ~/.local/bin/motion-wallpaper-toggle
|
||||
rm -f ~/.local/bin/motion-wallpaper-watcher
|
||||
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
|
||||
|
|
@ -179,8 +198,8 @@ rm -rf ~/.config/motion-wallpaper
|
|||
rm -f ~/.cache/motion-wallpaper.log
|
||||
systemctl --user daemon-reload
|
||||
|
||||
# Optionally remove packages
|
||||
sudo pacman -Rns mpvpaper zenity
|
||||
# Optionally remove packages (skip any you want to keep for other uses)
|
||||
sudo pacman -Rns mpvpaper gum socat
|
||||
```
|
||||
|
||||
## Credits
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue