wayvid

Animated wallpaper manager for Wayland compositors.

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

功能特性

🖼️ 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)

快速开始

# Install (Arch)
yay -S wayvid

# Run
wayvid-gui

快速链接

要求

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

许可证

MIT OR Apache-2.0

安装

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

源头

Dependencies

# 拱门
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

# 软呢帽
sudo dnf install cargo mpv-libs-devel wayland-devel libxkbcommon-devel fontconfig-devel mesa-libEGL-devel

构建

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

验证

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

卸载

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

# AUR
yay -R wayvid

# Nix
nix profile remove wayvid

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

配置

配置文件：'~/.config/wayvid/config.yaml'

Basic Example

源:
  类型: 文件
  路径: ~/视频/wallpaper.mp4
layout: fill
音量: 0
循环: true
hwdec: true

源类型

File

源:
  类型: 文件
  路径: /路径/到/video.mp4

目录(播放列表)

源:
  类型: 目录
  路径: ~/视频/壁纸/
  洗牌: true
  间隔: 3600  # Change every hour

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:

源:
  类型: 文件
  路径: ~/Videos/default.mp4

per_output:
  DP-1:
    源:
      类型: 文件
      路径: ~/视频/left.mp4
  HDMI-A-1 接口:
    源:
      类型: 文件
      路径: ~/视频/right.mp4

All Options

# 视频源
source:
  类型: file|directory|workshop
  路径: string
  id: number  # For workshop

# Playback
layout: fill|contain|stretch|centre
音量: 0-100
循环: true|false
start_time: 0.0
playback_rate: 1.0
mute: false

# Performance
hwdec: true

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

# Power
power:
  battery_threshold: 20
  pause_on_battery: false

重新加载配置

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

列出输出

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

源:
  类型: 文件
  路径: ~/Videos/default.mp4

per_output:
  DP-1:
    源:
      类型: 文件
      路径: ~/视频/left.mp4
  HDMI-A-1 接口:
    源:
      类型: 文件
      路径: ~/视频/right.mp4

Same Video All Monitors

wayvid-ctl apply ~/Videos/wallpaper.mp4

Or via config:

源:
  类型: 文件
  路径: ~/视频/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.

故障排除

No monitors shown:

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

Fonts broken (Chinese):

sudo pacman -S noto-fonts-cjk  # 拱门

Thumbnails not loading:

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

Steam 创意工坊

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.

故障排除

"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

要求

支持 HDR 的显示器
支持 HDR 的合成器(Hyprland、Niri)

Formats

格式	支持
HDR10	✓
HLG的	✓
HDR10+	Tone-map only
杜比视界	Tone-map only

验证

wayvid-ctl status | grep hdr

故障排除

Washed out colors:

检查合成器 HDR 设置
Verify video is true HDR format

CLI 命令

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%

例子

# 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 创意工坊

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.)

环境变量

Variable	描述
`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 协议

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"}

地位

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"}

例子

蟒

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)

猛击

# 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

软呢帽：

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

构建

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

验证

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

贡献指南

快速开始

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

错误报告

包括：

wayvid 版本
Compositor
重现步骤
Logs: RUST_LOG=debug wayvid run

许可证

MIT OR Apache-2.0

Keyboard shortcuts

wayvid Documentation