wayvid

Animated wallpaper manager for Wayland compositors.

v0.5 introduces a GUI-first design — just open the app, pick a wallpaper, and apply.

Features

🖼️ GUI wallpaper browser - Thumbnails, search, and one-click apply
🖥️ Multi-monitor support - Independent wallpapers per display
⚡ Hardware accelerated - VA-API/NVDEC via mpv
🎮 Steam Workshop - Import video wallpapers from Wallpaper Engine
🌈 HDR support - 10-bit HDR with tone-mapping
🔧 CLI tools - wayvid-ctl for scripting and automation

Tested Compositors

Hyprland ✓
Niri ✓
Sway (should work)
River (should work)

Quick Start

# Install (Arch)
yay -S wayvid

# Run
wayvid-gui

Quick Links

Requirements

Linux with Wayland
Compositor with wlr-layer-shell support
libmpv, libEGL, libwayland-client

License

MIT OR Apache-2.0

Installation

Arch Linux (AUR)

yay -S wayvid

Nix / NixOS

Direct run (no installation)

# Run wayvid-gui directly from GitHub
nix run github:YangYuS8/wayvid

# Run wayvid-ctl
nix run github:YangYuS8/wayvid#wayvid-ctl -- status

Install to profile

nix profile install github:YangYuS8/wayvid

NixOS configuration

Add to your flake.nix:

{
  inputs.wayvid.url = "github:YangYuS8/wayvid";
  
  # In your system configuration:
  environment.systemPackages = [
    inputs.wayvid.packages.${system}.default
  ];
}

Home Manager

home.packages = [
  inputs.wayvid.packages.${system}.default
];

AppImage

# Download
wget https://github.com/YangYuS8/wayvid/releases/latest/download/wayvid-x86_64.AppImage
chmod +x wayvid-x86_64.AppImage

# Run
./wayvid-x86_64.AppImage

From Source

Dependencies

# Arch
sudo pacman -S rust mpv wayland wayland-protocols libxkbcommon fontconfig mesa

# Ubuntu/Debian
sudo apt install cargo libmpv-dev libwayland-dev libxkbcommon-dev libfontconfig-dev libegl-dev

# Fedora
sudo dnf install cargo mpv-libs-devel wayland-devel libxkbcommon-devel fontconfig-devel mesa-libEGL-devel

Build

git clone https://github.com/YangYuS8/wayvid
cd wayvid
cargo build --release

Install (User)

Using the installation script (recommended):

./scripts/install.sh --user

This installs to ~/.local/bin/ and adds a desktop entry.

Install (System)

sudo ./scripts/install.sh --system

Manual Install

# User install
install -Dm755 target/release/wayvid-gui ~/.local/bin/wayvid-gui
install -Dm755 target/release/wayvid-ctl ~/.local/bin/wayvid-ctl
install -Dm644 packaging/wayvid-gui.desktop ~/.local/share/applications/wayvid.desktop
install -Dm644 logo.svg ~/.local/share/icons/hicolor/scalable/apps/wayvid.svg

# System install
sudo install -Dm755 target/release/wayvid-gui /usr/local/bin/wayvid-gui
sudo install -Dm755 target/release/wayvid-ctl /usr/local/bin/wayvid-ctl

Verify

wayvid-gui --version
wayvid-ctl --version

Autostart Configuration

Method 1: GUI Settings (Recommended)

Enable "Autostart" in Settings > General. This creates an XDG autostart entry at ~/.config/autostart/wayvid.desktop.

Method 2: niri spawn-at-startup

For niri users, add to ~/.config/niri/config.kdl:

spawn-at-startup "wayvid-gui" "--minimized"

Note: niri's systemd session also supports XDG autostart, so Method 1 works too.

Method 3: Hyprland exec-once

For Hyprland users, add to ~/.config/hypr/hyprland.conf:

exec-once = wayvid-gui --minimized

Method 4: Sway exec

For Sway users, add to ~/.config/sway/config:

exec wayvid-gui --minimized

Uninstall

# Using uninstall script
./scripts/uninstall.sh --user

# AUR
yay -R wayvid

# Nix
nix profile remove wayvid

# Manual cleanup
rm -rf ~/.config/wayvid ~/.cache/wayvid

Configuration

Config file: ~/.config/wayvid/config.yaml

Basic Example

source:
  type: file
  path: ~/Videos/wallpaper.mp4
layout: fill
volume: 0
loop: true
hwdec: true

Source Types

File

source:
  type: file
  path: /path/to/video.mp4

Directory (Playlist)

source:
  type: directory
  path: ~/Videos/wallpapers/
  shuffle: true
  interval: 3600  # Change every hour

Workshop

source:
  type: workshop
  id: 1234567890

Layout Modes

fill - Cover screen, crop if needed (default)
contain - Fit inside, may letterbox
stretch - Fill exactly, may distort
centre - Original size, centered

layout: fill

Per-Output Config

Different video per monitor:

source:
  type: file
  path: ~/Videos/default.mp4

per_output:
  DP-1:
    source:
      type: file
      path: ~/Videos/left.mp4
  HDMI-A-1:
    source:
      type: file
      path: ~/Videos/right.mp4

All Options

# Video source
source:
  type: file|directory|workshop
  path: string
  id: number  # For workshop

# Playback
layout: fill|contain|stretch|centre
volume: 0-100
loop: true|false
start_time: 0.0
playback_rate: 1.0
mute: false

# Performance
hwdec: true

# HDR
hdr_mode: auto|force|disable
tone_mapping: auto

# Power
power:
  battery_threshold: 20
  pause_on_battery: false

Reload Config

wayvid-ctl reload-config

Multi-Monitor

Using GUI (Recommended)

Open wayvid-gui
Select monitor from the bottom bar
Browse wallpapers in Library tab
Double-click to apply to selected monitor

List Outputs

wayvid-ctl outputs
# eDP-1: 1920x1080 @ (0, 0)
# DP-1: 2560x1440 @ (1920, 0)

Different Video Per Monitor

Via CLI

wayvid-ctl apply ~/Videos/left.mp4 --output DP-1
wayvid-ctl apply ~/Videos/right.mp4 --output HDMI-A-1

Via Config File

source:
  type: file
  path: ~/Videos/default.mp4

per_output:
  DP-1:
    source:
      type: file
      path: ~/Videos/left.mp4
  HDMI-A-1:
    source:
      type: file
      path: ~/Videos/right.mp4

Same Video All Monitors

wayvid-ctl apply ~/Videos/wallpaper.mp4

Or via config:

source:
  type: file
  path: ~/Videos/wallpaper.mp4

Control Per Output

wayvid-ctl pause --output DP-1
wayvid-ctl resume --output DP-1
wayvid-ctl stop --output DP-1
wayvid-ctl apply ~/Videos/new.mp4 --output DP-1

Hotplug

Monitors are detected automatically. No restart needed.

GUI

wayvid v0.5 introduces a GUI-first experience. Just run:

wayvid-gui

Interface

The GUI has a sidebar navigation with four main views:

┌─────────────────────────────────────────────────┐
│  📁 Library    │                                │
│  📂 Folders    │   ┌─────┐ ┌─────┐ ┌─────┐    │
│  ⚙️ Settings   │   │ 🎬  │ │ 🎬  │ │ 🎬  │    │
│  ℹ️ About      │   │ vid │ │ vid │ │ vid │    │
│                │   └─────┘ └─────┘ └─────┘    │
│                │                                │
│                │   🔍 Search...                 │
├────────────────┴────────────────────────────────┤
│  Monitors: [DP-1 ✓] [HDMI-A-1] [eDP-1]         │
└─────────────────────────────────────────────────┘

Views

Library

Browse your wallpaper collection with thumbnails. Click to preview, double-click to apply.

Folders

Manage source folders for wallpapers. Add/remove folders to scan.

Settings

Autostart: Launch wayvid-gui at login
Minimize to tray: Keep running in background when window is closed
Start minimized: Start directly to tray without showing window
Power management: Pause on battery or fullscreen apps
Performance: FPS limits, hardware decode options

About

Version info and links.

Usage

Browse - View wallpapers in Library tab
Select monitor - Click monitor in bottom bar
Apply - Double-click a wallpaper

Wallpaper Persistence

wayvid automatically saves your wallpaper settings and restores them on restart:

Per-monitor wallpapers: Each monitor remembers its wallpaper
Engine state: Engine auto-starts if it was running before
Settings location: ~/.config/wayvid/settings.yaml

To enable full persistence:

Enable "Start with system" in Settings
Enable "Minimize to tray"
Enable "Start minimized"

Now wayvid will start automatically on login, restore your wallpapers, and run quietly in the tray.

System Tray

The GUI minimizes to system tray when closed. Right-click tray icon for:

Show/hide window
Pause/resume playback
Quit

Autostart

Enable in Settings → Autostart, or manually:

# niri: ~/.config/niri/config.kdl
spawn-at-startup "wayvid-gui"

# hyprland: ~/.config/hypr/hyprland.conf
exec-once = wayvid-gui

Note: Use the "Start minimized" option in Settings to control whether wayvid opens in tray or shows the window on startup.

Troubleshooting

No monitors shown:

Check Wayland session is running
Ensure compositor supports wlr-layer-shell

Fonts broken (Chinese):

sudo pacman -S noto-fonts-cjk  # Arch

Thumbnails not loading:

Check ~/.cache/wayvid/thumbnails/ permissions
Ensure ffmpeg is installed for video thumbnails

Steam Workshop

Import video wallpapers from Wallpaper Engine.

Using GUI (Recommended)

The easiest way to use Workshop wallpapers is through the GUI:

Open wayvid-gui
Go to Folders tab

Add your Workshop content folder:

~/.steam/steam/steamapps/workshop/content/431960/

Browse Workshop wallpapers in Library tab
Double-click to apply

Using CLI

Apply Workshop wallpapers directly with wayvid-ctl:

# Find workshop items
ls ~/.steam/steam/steamapps/workshop/content/431960/

# Apply a workshop wallpaper
wayvid-ctl apply ~/.steam/steam/steamapps/workshop/content/431960/<id>/video.mp4

Find Workshop ID

From URL:

https://steamcommunity.com/sharedfiles/filedetails/?id=1234567890
                                                        ^^^^^^^^^^

The workshop content is typically at:

~/.steam/steam/steamapps/workshop/content/431960/<workshop_id>/

Compatibility

Supported:

Video wallpapers (.mp4, .webm, .mkv)

Not supported:

Web/HTML wallpapers
Scene wallpapers with effects
Interactive wallpapers

Look for "Video" tag in Workshop.

Troubleshooting

"No video file found":

The wallpaper may not be a video type
Check the folder for actual video files: ls ~/.steam/.../431960/<id>/

Workshop folder not found:

Ensure Steam and Wallpaper Engine are installed
Workshop content downloads to: ~/.steam/steam/steamapps/workshop/content/431960/

HDR

HDR10 support with automatic tone-mapping.

Enable

hdr_mode: auto  # auto, force, disable

Requirements

HDR-capable display
Compositor with HDR support (Hyprland, Niri)

Formats

Format	Support
HDR10	✓
HLG	✓
HDR10+	Tone-map only
Dolby Vision	Tone-map only

Verify

wayvid-ctl status | grep hdr

Troubleshooting

Washed out colors:

Check compositor HDR settings
Verify video is true HDR format

CLI Commands

wayvid-gui

Main GUI application with integrated playback engine.

wayvid-gui                    # Open GUI
wayvid-gui --minimized        # Start minimized to system tray
wayvid-gui --version          # Show version
wayvid-gui --help             # Show help

When running, wayvid-gui:

Displays wallpapers via Wayland layer-shell
Provides a graphical interface for browsing and applying wallpapers
Starts an IPC server for wayvid-ctl communication
Minimizes to system tray when closed

wayvid-ctl

CLI control tool for scripting and automation. Communicates with wayvid-gui via IPC.

Note: wayvid-ctl requires wayvid-gui to be running.

Status Commands

wayvid-ctl status             # Show current status
wayvid-ctl status --json      # JSON output for scripts
wayvid-ctl outputs            # List available monitors
wayvid-ctl ping               # Check if daemon is running

Example output:

Wayvid Daemon Status
====================
Status:  Running
Version: 0.5.0

Active Outputs:
  eDP-1 [Playing]
    Wallpaper: /home/user/Videos/wallpaper.mp4

Wallpaper Control

wayvid-ctl apply <path>                    # Apply to all monitors
wayvid-ctl apply <path> --output DP-1      # Apply to specific monitor
wayvid-ctl pause                           # Pause all playback
wayvid-ctl pause --output DP-1             # Pause specific monitor
wayvid-ctl resume                          # Resume all playback
wayvid-ctl stop                            # Stop and clear all wallpapers
wayvid-ctl stop --output DP-1              # Clear specific monitor

Volume Control

wayvid-ctl volume 50 --output eDP-1        # Set volume to 50%

Examples

# Apply wallpaper to all monitors
wayvid-ctl apply ~/Videos/wallpaper.mp4

# Apply different wallpapers per monitor
wayvid-ctl apply ~/Videos/left.mp4 --output DP-1
wayvid-ctl apply ~/Videos/right.mp4 --output HDMI-A-1

# Check status in scripts
if wayvid-ctl ping 2>/dev/null; then
  echo "wayvid is running"
else
  echo "wayvid is not running"
fi

# Get JSON status for scripting
wayvid-ctl status --json | jq '.outputs[].name'

Steam Workshop

Apply Workshop wallpapers directly:

# Find workshop video
ls ~/.steam/steam/steamapps/workshop/content/431960/

# Apply workshop wallpaper
wayvid-ctl apply ~/.steam/steam/steamapps/workshop/content/431960/<id>/video.mp4

Or use the GUI's Library tab for a better browsing experience.

Exit Codes

Code	Meaning
0	Success
1	Error (connection failed, invalid arguments, etc.)

Environment Variables

Variable	Description
`RUST_LOG`	Logging level (`error`, `warn`, `info`, `debug`, `trace`)
`XDG_RUNTIME_DIR`	IPC socket directory (default: `/run/user/$UID`)
`XDG_CONFIG_HOME`	Config directory (default: `~/.config`)
`XDG_CACHE_HOME`	Cache directory (default: `~/.cache`)

IPC Protocol

wayvid uses JSON over Unix socket for inter-process communication.

Socket path: $XDG_RUNTIME_DIR/wayvid.sock (typically /run/user/1000/wayvid.sock)

Request Format

All requests are JSON objects with a type field indicating the command.

Ping

Check if daemon is alive.

{"type": "ping"}

Response:

{"type": "pong"}

Status

Get current daemon status.

{"type": "status"}

Response:

{
  "type": "status",
  "running": true,
  "version": "0.5.0",
  "outputs": [
    {
      "name": "eDP-1",
      "wallpaper": "/home/user/Videos/wallpaper.mp4",
      "paused": false,
      "volume": 1.0
    }
  ]
}

Outputs

List available monitors.

{"type": "outputs"}

Response:

{
  "type": "outputs",
  "outputs": [
    {
      "name": "eDP-1",
      "width": 1920,
      "height": 1080,
      "refresh": 60,
      "primary": true,
      "x": 0,
      "y": 0
    }
  ]
}

Apply

Apply wallpaper to output(s).

{
  "type": "apply",
  "path": "/path/to/video.mp4",
  "output": "eDP-1",
  "mode": "fill"
}

output: Optional. If omitted, applies to all outputs.
mode: Optional. One of fill, contain, stretch, centre. Default: fill.

Response:

{"type": "ok", "message": "Wallpaper applied"}

Pause/Resume

{"type": "pause", "output": "eDP-1"}
{"type": "resume", "output": "eDP-1"}

output: Optional. If omitted, affects all outputs.

Stop

Stop playback and clear wallpaper.

{"type": "stop", "output": "eDP-1"}

Set Volume

{
  "type": "set_volume",
  "output": "eDP-1",
  "volume": 0.5
}

volume: Float from 0.0 to 1.0.

Quit

Request daemon shutdown.

{"type": "quit"}

Response Format

Success

{"type": "ok", "message": "Operation completed"}

Error

{"type": "error", "error": "Error description"}

Examples

Python

import socket
import json

def send_ipc(request):
    sock = socket.socket(socket.AF_UNIX)
    sock.connect('/run/user/1000/wayvid.sock')
    sock.send((json.dumps(request) + '\n').encode())
    response = sock.recv(4096).decode()
    sock.close()
    return json.loads(response)

# Check status
status = send_ipc({"type": "status"})
print(f"Running: {status['running']}")
for output in status.get('outputs', []):
    print(f"  {output['name']}: {output.get('wallpaper', 'None')}")

# Apply wallpaper
result = send_ipc({
    "type": "apply",
    "path": "/home/user/Videos/wallpaper.mp4"
})
print(result)

Bash

# Check status
echo '{"type":"status"}' | nc -U $XDG_RUNTIME_DIR/wayvid.sock

# Apply wallpaper
echo '{"type":"apply","path":"/home/user/Videos/wallpaper.mp4"}' | \
  nc -U $XDG_RUNTIME_DIR/wayvid.sock

# Pause all
echo '{"type":"pause"}' | nc -U $XDG_RUNTIME_DIR/wayvid.sock

Using wayvid-ctl

For most use cases, the wayvid-ctl CLI tool is recommended:

wayvid-ctl status
wayvid-ctl apply ~/Videos/wallpaper.mp4
wayvid-ctl pause

Building

Dependencies

Arch:

sudo pacman -S rust mpv wayland wayland-protocols libxkbcommon fontconfig mesa

Ubuntu/Debian:

sudo apt install cargo libmpv-dev libwayland-dev libxkbcommon-dev libfontconfig-dev libegl-dev

Fedora:

sudo dnf install cargo mpv-libs-devel wayland-devel libxkbcommon-devel fontconfig-devel mesa-libEGL-devel

Build

git clone https://github.com/YangYuS8/wayvid
cd wayvid

# Release build
cargo build --release

# Install using script (recommended)
./scripts/install.sh --user

# Or manual install
sudo install -Dm755 target/release/wayvid-gui /usr/local/bin/
sudo install -Dm755 target/release/wayvid-ctl /usr/local/bin/

Binaries

v0.5 produces two binaries:

wayvid-gui - Main GUI application with embedded playback engine
wayvid-ctl - CLI control tool for scripting

Test

cargo test --workspace
cargo clippy --workspace

Verify

wayvid-gui --version
wayvid-ctl --version

Contributing

Quick Start

git clone https://github.com/YangYuS8/wayvid
cd wayvid
cargo build --all-features
cargo test
cargo clippy

Before PR

cargo fmt
cargo clippy --all-features -- -D warnings
cargo test --all-features
Update CHANGELOG.md if user-facing

Commit Format

type(scope): description

feat(gui): Add video source browser
fix(mpv): Fix memory leak
docs: Update installation

Types: feat, fix, docs, refactor, perf, test, chore

Bug Reports

Include:

wayvid version
Compositor
Steps to reproduce
Logs: RUST_LOG=debug wayvid run

License

MIT OR Apache-2.0

Keyboard shortcuts

wayvid Documentation