✨ Features

• Keyboard-first — arrow keys / hjkl / wasd to move, / to filter, Enter to apply. No mouse needed, but it works too (click to select, double-click to apply).
• Images and video wallpapers — via swww, looping video via mpvpaper.
• Smooth transitions — animated switches for both images and video
• Live previews — selecting a video plays a short looping clip right on its thumbnail.
• Audition mode — Space applies a wallpaper but keeps the picker open, so you can flip through options on your real desktop.
• Lightweight & on-demand — launches when you call it, exits cleanly, and never idles in the background. Rendering is handed to detached daemons.
• Restore on login — remembers your last wallpaper so a video survives a reboot.
• Color-scheme integration — tells noctalia / matugen / wallust / pywal to re-theme your system from the new wallpaper.
• Riced to taste — flat, borderless TUI look; the surface is transparent except the floating bar and the cards, so your desktop stays visible while you browse.

🖥️ Supported compositors

Wallfliper draws its picker as a wlr-layer-shell overlay and delegates painting to swww/mpvpaper, so it targets compositors that implement wlr-layer-shell:

Hyprland · Sway · river · Wayfire · niri

Out of scope (no layer-shell, or only partial): KDE Plasma, GNOME, X11, Windows.

🙃 Why this exists

Honestly? I just wanted to give Claude Code a try, and ended up enjoying it a little too much.

Wallfliper was built mostly "low-code" — most of the codebase was written with the help of AI tooling like Claude Code and Google Stitch, with me steering the design, scope and decisions.

📦 Installation

Install from source — works on any supported compositor:

[!IMPORTANT]
Install PySide6 from your distribution, not pip. layer-shell-qt is a compiled
Qt plugin loaded into the running process — its Qt version must match the Qt that
PySide6 uses. Distro packages are all built against the same system Qt, so they always
match. A pip install PySide6 bundles its own Qt and can mismatch the system
layer-shell plugin, causing cryptic load failures.

1. Install the dependencies

On Arch / CachyOS — copy-paste:

sudo pacman -S pyside6 layer-shell-qt swww ffmpeg

paru -S mpvpaper

On other distros — install them with your package manager (names vary, e.g.
python3-pyside6). swww and mpvpaper are usually not packaged outside Arch —
build them from source (both have simple instructions):

• swww → https://github.com/LGFae/swww (Rust)
• mpvpaper → https://github.com/GhostNaN/mpvpaper

2. Run it

git clone https://github.com/Roberth-Souza/wallfliper
cd wallfliper

python main.py --check        # ✓/✗ report of every dependency
python main.py                # launch

💡 python main.py --check prints a per-dependency report with an install hint for
whatever's missing — run it first if anything misbehaves.

⌨️ Usage

Recommended

Bind Wallfliper to a compositor hotkey. Pressing the hotkey again while it's open
closes it — it's a toggle.

-- Hyprland (Lua config) — ~/.config/hypr/modules/keybinds.lua
hl.bind("SUPER + W", hl.dsp.exec_cmd("python /path/to/wallfliper/main.py"))

# Sway — ~/.config/sway/config
bindsym $mod+w exec python /path/to/wallfliper/main.py

# niri — ~/.config/niri/config.kdl
binds { Mod+W { spawn "python" "/path/to/wallfliper/main.py"; } }

Applying an image stops any running video wallpaper — there's only ever one wallpaper at a time.

⚙️ Settings

Type /config while searching and hit Enter (keyboard-driven: j/k move · Enter
select · Esc close):

• folder — choose your wallpaper directory (via your xdg-desktop-portal file chooser)

🔁 Restore on login

Wallfliper saves the last-applied wallpaper to ~/.config/wallfliper/state.json.
wallfliper --restore reads that and re-spawns swww/mpvpaper — so a video
wallpaper survives a reboot. (Wallfliper itself doesn't stay running; it just hands
the file back to the renderer and exits — mpvpaper is stateless and dies on reboot,
so something has to re-launch it, and that's all --restore does.)

python /path/to/wallfliper/main.py --restore   # re-apply the saved wallpaper now

Run it on login from your compositor's autostart, wrapped in a short sleep so the
compositor finishes bringing up your desktop first. Without the delay a video wallpaper
can come up frozen on a low-res frame: mid-boot the wallpaper surface is briefly reported
as "hidden", which trips mpvpaper's auto-pause (a known mpvpaper quirk). A few seconds'
delay sidesteps it:

-- Hyprland (Lua config) — inside hl.on("hyprland.start", ...) in your autostart.lua
hl.exec_cmd("sh -c 'sleep 5 && python /path/to/wallfliper/main.py --restore'")

# Sway — ~/.config/sway/config
exec sh -c 'sleep 5 && python /path/to/wallfliper/main.py --restore'

# niri — ~/.config/niri/config.kdl
spawn-at-startup "sh" "-c" "sleep 5 && python /path/to/wallfliper/main.py --restore"

# Wayfire — ~/.config/wayfire.ini
[autostart]
wallfliper = sh -c 'sleep 5 && python /path/to/wallfliper/main.py --restore'

Uses system python (the same interpreter that runs the app) — no virtualenv,
no activation. Once you install via a package (e.g. AUR), a real wallfliper command
lands on PATH and every line above shortens to just wallfliper --restore.

wallfliper --install-autostart writes ~/.config/autostart/wallfliper-restore.desktop
(the freedesktop standard). It works on sessions that honor XDG autostart — GNOME/KDE,
or wlroots compositors launched via UWSM/systemd. A bare Hyprland/Sway/niri session
won't read that folder, so on a plain setup use the compositor exec line above instead.

No background daemon of our own — rendering is handled by swww-daemon / mpvpaper.

🎨 Color-scheme integration

After applying a wallpaper, Wallfliper notifies external color tools so your system
color scheme regenerates from it (best-effort, never blocks). It auto-detects
noctalia if installed — v5+ (noctalia msg) or the
older quickshell-based noctalia-shell (qs ... ipc); for everything else set
color_hook in ~/.config/wallfliper/config.json ({path} is substituted):

{
  "color_hook": "matugen image {path}"
}

Works with matugen / wallust / pywal / any command. For video wallpapers it themes from a
still frame extracted with ffmpeg.

🩹 Troubleshooting

First step, always: wallfliper --check — it tells you exactly what's missing.

The app still runs without the optional tools — missing dependencies are reported in the
terminal at startup, and --check lists them with install hints.

📄 License

GPL-3.0. PySide6 is used under the LGPL.