Migration Guide¶

This guide helps users migrate from other wallpaper tools to gSlapper. Whether you're coming from swww, mpvpaper, hyprpaper, swaybg, or feh, we'll show you how to make the switch smoothly.

Why Migrate to gSlapper?¶

Key Advantages: - ✅ Video + Static Support - One tool for both animated and static wallpapers - ✅ GStreamer Backend - More efficient than libmpv, better NVIDIA compatibility - ✅ Minimal Resource Usage - Smart texture management and frame rate limiting - ✅ Wayland Native - Built for wlroots compositors (Hyprland, Sway, River, Niri) - ✅ IPC Control - Runtime control via Unix sockets - ✅ Persistent State - Automatic wallpaper restoration on login - ✅ Smooth Transitions - Fade effects between static images

Migrating from swww¶

swww vs gSlapper Comparison¶

Feature	swww	gSlapper
Static Images	✅	✅
Video Wallpapers	❌ (images only)	✅
Daemon	`swww-daemon`	Optional systemd service
Transitions	✅ (fade)	✅ (fade)
Scaling	Limited	Full (fill, stretch, original, panscan)
Multi-Monitor	✅	✅
IPC Control	✅	✅
Resource Usage	Medium	Low (smart management)
Video Support	GIF only	Full GStreamer (MP4, MKV, WebM)

swww Commands → gSlapper Equivalents¶

Basic Usage¶

swww:

# Set wallpaper on all monitors
swww img /path/to/image.jpg

# Set on specific monitor
swww img -o DP-1 /path/to/image.jpg

# With transition
swww img -t fade --transition-step 90 /path/to/image.jpg

gSlapper (static images):

# Set wallpaper on all monitors
gslapper -o "fill" '*' /path/to/image.jpg

# Set on specific monitor
gslapper -o "fill" DP-1 /path/to/image.jpg

# With transition
gslapper -o "fill" --transition-type fade --transition-duration 0.5 DP-1 /path/to/image.jpg

Video Wallpapers (NEW in gSlapper)¶

# Set video wallpaper with looping
gslapper -o "loop" DP-1 /path/to/video.mp4

# Video with custom scaling
gslapper -o "loop panscan=0.8" DP-1 /path/to/video.mp4

Scaling Modes¶

swww	gSlapper	Description
`--no-resize`	`-o "original"`	Native resolution
`--cover`	`-o "fill"`	Cover screen, crop excess
`--contain`	`-o "panscan=1.0"`	Fit inside, keep aspect

Daemon/Service¶

swww:

# Start daemon manually
swww-daemon

# Or via systemd
systemctl --user enable swww-daemon.service
systemctl --user start swww-daemon.service

gSlapper:

# No daemon needed for static images (one-shot like swww init)
# But you can use systemd for persistence:

# Create environment file
echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY" > ~/.config/gslapper/environment

# Enable service
systemctl --user enable --now gslapper.service

Cache Management¶

swww:

swww clear-cache
swww img --no-cache /path/to/image.jpg

gSlapper:

# gSlapper has an in-memory image cache (default 256MB)
# Images are auto-cached on 'change' IPC command
# Adjust cache size with --cache-size MB option

swww Config → gSlapper¶

swww config (~/.config/swww/init.sh):

#!/bin/bash
swww init
swww img /path/to/wallpaper.jpg

gSlapper equivalent:

#!/bin/bash
# Method 1: One-shot (no daemon)
gslapper -o "fill" '*' /path/to/wallpaper.jpg

# Method 2: Systemd service for persistence
# See: Persistent Wallpapers guide

Migration Checklist - swww Users¶

[ ] Replace swww img commands with gslapper -o "fill" for static images
[ ] Use gslapper -o "loop" for video wallpapers (new capability)
[ ] Update compositor startup scripts
Hyprland: Change exec-once = swww img ... to exec-once = gslapper ...
Sway: Change exec swww img ... to exec gslapper ...

[ ] Disable swww-daemon if using gSlapper service:

systemctl --user disable swww-daemon.service

[ ] Update shell aliases (if any):

# Old
alias wp='swww img ~/Pictures/wallpaper.jpg'

# New
alias wp='gslapper -o "fill" ~/Pictures/wallpaper.jpg'

Migrating from mpvpaper¶

mpvpaper vs gSlapper Comparison¶

Feature	mpvpaper	gSlapper
Static Images	✅	✅
Video Wallpapers	✅	✅
Backend	libmpv	GStreamer
Memory Leaks	⚠️ Issues on NVIDIA	✅ Fixed
GPU Resource Usage	High	Optimized
Multi-Monitor	✅	✅
IPC Control	✅	✅
Transitions	❌	✅
Scaling Modes	Limited	Full (fill, stretch, original, panscan)
Persistent State	No	✅ Automatic

Why Switch from mpvpaper?¶

Known Issues Fixed in gSlapper: - ✅ NVIDIA Memory Leaks - GStreamer backend solves libmpv memory issues - ✅ GPU Resource Usage - Smart texture management reduces VRAM consumption - ✅ Static Image Transitions - Fade effects not available in mpvpaper - ✅ Persistent State - Automatic wallpaper restoration, no manual scripts needed

mpvpaper Commands → gSlapper Equivalents¶

Basic Usage¶

mpvpaper:

# Video wallpaper
mpvpaper -f --loop DP-1 /path/to/video.mp4

# Video with options
mpvpaper -f --loop --panscan=1.0 DP-1 /path/to/video.mp4

# Static image
mpvpaper DP-1 /path/to/image.jpg

gSlapper:

# Video wallpaper
gslapper -f -o "loop" DP-1 /path/to/video.mp4

# Video with options
gslapper -f -o "loop panscan=1.0" DP-1 /path/to/video.mp4

# Static image (fill mode by default)
gslapper DP-1 /path/to/image.jpg

# Or explicit fill mode
gslapper -o "fill" DP-1 /path/to/image.jpg

Scaling/Panscan¶

mpvpaper:

# Full stretch
mpvpaper -f DP-1 video.mp4

# Panscan (0.0 = fit, 1.0 = fill)
mpvpaper -f --panscan=0.5 DP-1 video.mp4

gSlapper:

# Full stretch
gslapper -f -o "stretch" DP-1 video.mp4

# Panscan (0.0 = fit, 1.0 = fill)
gslapper -f -o "panscan=0.5" DP-1 video.mp4

Auto-Pause/Stop¶

mpvpaper:

# Uses ~/.config/mpvpaper/pauselist and stoplist
# Add application names to files

gSlapper:

# Same configuration files
echo "firefox" >> ~/.config/mpvpaper/pauselist
echo "games" >> ~/.config/mpvpaper/stoplist

# Or use command-line flags
gslapper -p -o "loop" DP-1 video.mp4  # Auto-pause
gslapper -s -o "loop" DP-1 video.mp4  # Auto-stop

IPC Control¶

mpvpaper:

# No built-in IPC
# Requires external tools or scripts

gSlapper:

# Start with IPC socket
gslapper -I /tmp/gslapper.sock -o "loop" DP-1 video.mp4

# Control via IPC
echo "pause" | nc -U /tmp/gslapper.sock
echo "resume" | nc -U /tmp/gslapper.sock
echo "change /new/video.mp4" | nc -U /tmp/gslapper.sock

mpvpaper Systemd → gSlapper¶

mpvpaper service:

[Unit]
Description=mpvpaper service
After=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/mpvpaper -f --loop DP-1 /path/to/video.mp4
Restart=on-failure

[Install]
WantedBy=default.target

gSlapper equivalent:

[Unit]
Description=gSlapper Wallpaper Service
After=graphical-session.target
Wants=graphical-session.target

[Service]
Type=notify
ExecStart=/usr/bin/gslapper --systemd --restore DP-1
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
TimeoutStopSec=30

EnvironmentFile=%h/.config/gslapper/environment
Environment=XDG_RUNTIME_DIR=%t

MemoryMax=512M
CPUQuota=50%
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=default.target

Key Differences: - --systemd --restore enables state persistence - Type=notify for systemd readiness - Resource limits for better management - SIGHUP reload support for state saving

Migration Checklist - mpvpaper Users¶

[ ] Replace mpvpaper with gslapper in all scripts

[ ] Update systemd services

systemctl --user disable mpvpaper.service
systemctl --user enable gslapper.service

[ ] Create environment file for gSlapper:

mkdir -p ~/.config/gslapper
echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY" > ~/.config/gslapper/environment

[ ] Test video playback (should work better on NVIDIA)
[ ] Try fade transitions with static images
[ ] Set up IPC socket for runtime control
[ ] Update compositor startup scripts

Migrating from hyprpaper¶

hyprpaper vs gSlapper Comparison¶

Feature	hyprpaper	gSlapper
Static Images	✅	✅
Video Wallpapers	❌	✅
Hyprland Only	✅	✅ (but works on any wlroots compositor)
Daemon	✅ (`hyprpaper`)	Optional systemd service
Preloading	✅	⚠️ TODO (coming soon)
Transitions	❌	✅
Scaling	Basic	Full (fill, stretch, original, panscan)
IPC Control	❌	✅
Multi-Monitor	✅	✅

hyprpaper Commands → gSlapper Equivalents¶

Basic Usage¶

hyprpaper:

# Start daemon
hyprpaper &

# Preload images
hyprpaper preload /path/to/image1.jpg
hyprpaper preload /path/to/image2.jpg

# Set wallpaper
hyprpaper wallpaper "DP-1,/path/to/image1.jpg"
hyprpaper wallpaper "DP-2,/path/to/image2.jpg"

gSlapper:

# Set wallpaper directly (no daemon required)
gslapper -o "fill" DP-1 /path/to/image1.jpg

# For multiple monitors (different wallpapers)
gslapper -o "fill" DP-1 /path/to/image1.jpg &
gslapper -o "fill" DP-2 /path/to/image2.jpg &

# Or use systemd service for persistence
# See: Persistent Wallpapers guide

Different Wallpapers per Monitor¶

hyprpaper (~/.config/hypr/hyprpaper.conf):

wallpaper = DP-1,/path/to/image1.jpg
wallpaper = DP-2,/path/to/image2.jpg

gSlapper (systemd template services):

# Enable per-monitor services
systemctl --user enable --now gslapper@DP-1.service
systemctl --user enable --now gslapper@DP-2.service

# Each service has its own state file
# Set wallpapers manually first
gslapper -o "fill" DP-1 /path/to/image1.jpg  # Ctrl+C
gslapper -o "fill" DP-2 /path/to/image2.jpg  # Ctrl+C

hyprpaper Config → gSlapper¶

hyprpaper config (~/.config/hypr/hyprpaper.conf):

wallpaper = DP-1,/path/to/wallpaper.jpg
wallpaper = DP-2,/path/to/wallpaper2.jpg
splash = false

gSlapper equivalent (Hyprland config):

Method 1: Compositor startup (quick setup)

# ~/.config/hypr/hyprland.conf
exec-once = gslapper -o "fill" DP-1 /path/to/wallpaper.jpg

Method 2: Systemd service (recommended)

# Create environment
echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY" > ~/.config/gslapper/environment

# Enable services
systemctl --user enable --now gslapper@DP-1.service
systemctl --user enable --now gslapper@DP-2.service

Method 3: Shell script (for manual control)

#!/bin/bash
# ~/.config/hypr/set-wallpapers.sh
gslapper -o "fill" DP-1 /path/to/wallpaper.jpg &
gslapper -o "fill" DP-2 /path/to/wallpaper2.jpg &

Migration Checklist - hyprpaper Users¶

[ ] Kill hyprpaper daemon:
```
pkill hyprpaper
```

[ ] Remove from Hyprland config:

# Comment out in ~/.config/hypr/hyprland.conf
# exec-once = hyprpaper &

[ ] Set up gSlapper via systemd (recommended) or compositor config
[ ] Test with static images first
[ ] Try video wallpapers (new feature not available in hyprpaper)
[ ] Try fade transitions
[ ] Remove hyprpaper config file if not needed

Migrating from swaybg¶

swaybg vs gSlapper Comparison¶

Feature	swaybg	gSlapper
Static Images	✅	✅
Video Wallpapers	❌	✅
Sway Only	✅	✅ (but works on any Wayland compositor)
Daemon	✅ (runs in bg)	Optional systemd service
Transitions	❌	✅
Scaling	`stretch`/`fill` only	Full modes
IPC Control	❌	✅
Multi-Monitor	✅	✅

swaybg Commands → gSlapper Equivalents¶

Basic Usage¶

swaybg:

# Single monitor
swaybg -i /path/to/image.jpg -m fill

# Multiple monitors (different wallpapers)
swaybg -i /path/to/image1.jpg -o DP-1 -m fill \
         -i /path/to/image2.jpg -o DP-2 -m fill

# Scale modes
swaybg -i /path/to/image.jpg -m stretch
swaybg -i /path/to/image.jpg -m fit

gSlapper:

# Single monitor
gslapper -o "fill" DP-1 /path/to/image.jpg

# Multiple monitors
gslapper -o "fill" DP-1 /path/to/image1.jpg &
gslapper -o "fill" DP-2 /path/to/image2.jpg &

# Scale modes
gslapper -o "stretch" DP-1 /path/to/image.jpg
gslapper -o "original" DP-1 /path/to/image.jpg
gslapper -o "panscan=1.0" DP-1 /path/to/image.jpg  # Fit

Sway Config → gSlapper¶

swaybg in Sway config (~/.config/sway/config):

# Single wallpaper
output * bg /path/to/wallpaper.jpg fill

# Different per monitor
output DP-1 bg /path/to/wallpaper1.jpg fill
output DP-2 bg /path/to/wallpaper2.jpg fill

# Scale modes
output DP-1 bg /path/to/wallpaper.jpg stretch
output DP-1 bg /path/to/wallpaper.jpg fit

gSlapper equivalent:

Method 1: Exec in sway config

# Single wallpaper
exec gslapper -o "fill" '*' /path/to/wallpaper.jpg

# Different per monitor (script)
exec ~/.config/sway/set-wallpapers.sh

Method 2: Systemd service (recommended)

# Create environment
echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY" > ~/.config/gslapper/environment

# Enable services
systemctl --user enable --now gslapper.service  # Single
# Or per monitor:
systemctl --user enable --now gslapper@DP-1.service
systemctl --user enable --now gslapper@DP-2.service

Method 3: Script for sway exec

#!/bin/bash
# ~/.config/sway/set-wallpapers.sh
gslapper -o "fill" DP-1 /path/to/wallpaper1.jpg &
gslapper -o "fill" DP-2 /path/to/wallpaper2.jpg &

Migration Checklist - swaybg Users¶

[ ] Remove output * bg lines from sway config:

# Comment out in ~/.config/sway/config
# output * bg /path/to/wallpaper.jpg fill

[ ] Kill any running swaybg instances:
```
pkill swaybg
```
[ ] Set up gSlapper via systemd (recommended) or sway exec
[ ] Test static image wallpaper
[ ] Try video wallpapers (new feature)
[ ] Try fade transitions
[ ] Enable IPC socket if you want runtime control

Migrating from feh¶

feh vs gSlapper Comparison¶

Feature	feh	gSlapper
Static Images	✅	✅
Video Wallpapers	❌	✅
X11 Tool	✅	❌ (Wayland only)
Xwayland Compatible	✅	✅ (native Wayland better)
Image Browser	✅	❌
Transitions	❌	✅
Scaling	Full modes	Full modes
IPC Control	❌	✅
Multi-Monitor	✅	✅

Note: feh is an X11 tool. If you're using Wayland with Xwayland, gSlapper (native Wayland) will provide better performance and integration.

feh Commands → gSlapper Equivalents¶

Basic Usage¶

feh:

# Set wallpaper
feh --bg-fill /path/to/image.jpg

# Specific monitor (with xrandr)
feh --bg-fill /path/to/image.jpg --output-name DP-1

# Scale modes
feh --bg-scale /path/to/image.jpg    # Fit inside
feh --bg-tile /path/to/image.jpg     # Tile
feh --bg-center /path/to/image.jpg   # Center

gSlapper:

# Set wallpaper
gslapper -o "fill" DP-1 /path/to/image.jpg

# Scale modes
gslapper -o "panscan=1.0" DP-1 /path/to/image.jpg  # Fit
gslapper -o "original" DP-1 /path/to/image.jpg     # Center/native

feh Random Wallpaper Scripts¶

feh script:

#!/bin/bash
# feh random wallpaper
DIR="$HOME/Pictures/Wallpapers"
IMAGE=$(find "$DIR" -type f | shuf -n 1)
feh --bg-fill "$IMAGE"

gSlapper equivalent:

#!/bin/bash
# gSlapper random wallpaper
DIR="$HOME/Pictures/Wallpapers"
IMAGE=$(find "$DIR" -type f | shuf -n 1)
gslapper -o "fill" '*' "$IMAGE"

feh Integration in Compositors¶

Sway with feh:

# ~/.config/sway/config
exec feh --bg-fill /path/to/wallpaper.jpg

gSlapper equivalent:

# ~/.config/sway/config
exec gslapper -o "fill" '*' /path/to/wallpaper.jpg

Migration Checklist - feh Users¶

[ ] Ensure you're using Wayland (native Wayland is better than Xwayland)
[ ] Remove feh from compositor config
[ ] Kill any running feh instances:
```
pkill feh
```
[ ] Set up gSlapper (see tool-specific guides above)
[ ] Test with static images
[ ] Try video wallpapers (new feature)
[ ] Try fade transitions
[ ] Keep feh for image browsing if you like it (both can coexist)

Quick Reference: Common Commands¶

Setting Static Wallpaper¶

Tool	Command
swww	`swww img /path/to/image.jpg`
mpvpaper	`mpvpaper DP-1 /path/to/image.jpg`
hyprpaper	`hyprpaper wallpaper "DP-1,/path/to/image.jpg"`
swaybg	`swaybg -i /path/to/image.jpg -m fill -o DP-1`
feh	`feh --bg-fill /path/to/image.jpg`
gSlapper	`gslapper -o "fill" DP-1 /path/to/image.jpg`

Setting Video Wallpaper¶

Tool	Command
swww	❌ Not supported
mpvpaper	`mpvpaper -f --loop DP-1 /path/to/video.mp4`
hyprpaper	❌ Not supported
swaybg	❌ Not supported
feh	❌ Not supported
gSlapper	`gslapper -o "loop" DP-1 /path/to/video.mp4`

Fade Transition¶

Tool	Command
swww	`swww img -t fade /path/to/image.jpg`
mpvpaper	❌ Not supported
hyprpaper	❌ Not supported
swaybg	❌ Not supported
feh	❌ Not supported
gSlapper	`gslapper --transition-type fade --transition-duration 0.5 DP-1 /path/to/image.jpg`

Troubleshooting Migration Issues¶

Compositor Still Starts Old Tool¶

Problem: Old wallpaper tool still runs on startup

Solution: 1. Check compositor config files: - Hyprland: ~/.config/hypr/hyprland.conf - Sway: ~/.config/sway/config - River: ~/.config/river/init - Niri: ~/.config/niri/config.kdl

Remove or comment out old tool:

# Old
# exec-once = hyprpaper &

# New
exec-once = gslapper -o "fill" '*' /path/to/wallpaper.jpg

Kill running instances:

pkill hyprpaper
pkill swaybg
pkill swww-daemon

Multiple Wallpaper Tools Running¶

Problem: Conflicts between multiple wallpaper tools

Solution:

# Check for running tools
ps aux | grep -E "swww|mpvpaper|hyprpaper|swaybg|feh|gslapper"

# Kill old tools
systemctl --user stop swww-daemon.service
pkill -f "mpvpaper|hyprpaper|swaybg|feh"

# Start gSlapper
gslapper -o "fill" '*' /path/to/wallpaper.jpg

Wallpaper Not Showing¶

Problem: gSlapper starts but no wallpaper visible

Solutions: 1. Check output name:

gslapper -d  # List available outputs

Check if file exists and is readable:

test -f /path/to/wallpaper.jpg && echo "OK" || echo "Missing"

Check logs:

# With verbose flag
gslapper -vv DP-1 /path/to/wallpaper.jpg

# Systemd logs
journalctl --user -u gslapper.service -f

Transition Not Working¶

Problem: Fade transition doesn't appear

Cause: Transitions only work between static images, not videos

Solution:

# Correct - static image to static image
gslapper -o "fill" --transition-type fade DP-1 image1.jpg
# Then:
echo "change /path/to/image2.jpg" | nc -U /tmp/gslapper.sock

# Incorrect - video wallpaper
gslapper -o "loop" DP-1 video.mp4  # No transition

Additional Resources¶

Quick Start Guide - Get started with gSlapper
Command Line Options - Full CLI reference
Systemd Service Setup - Persistent wallpapers guide
Persistent Wallpapers - Advanced persistence methods
IPC Control - Runtime control guide
Troubleshooting - Common issues and solutions

Feature Comparison Summary¶

Feature	swww	mpvpaper	hyprpaper	swaybg	feh	gSlapper
Static Images	✅	✅	✅	✅	✅	✅
Video Wallpapers	❌	✅	❌	❌	❌	✅
Transitions	✅	❌	❌	❌	❌	✅
IPC Control	✅	❌	❌	❌	❌	✅
Preload Cache	❌	❌	✅	❌	❌	⚠️ TODO
Persistent State	✅	❌	❌	❌	❌	✅
NVIDIA Friendly	✅	⚠️	✅	✅	✅	✅
GPU Optimized	Medium	High	Low	Low	Low	Low
Backend	Custom	libmpv	Custom	Custom	X11	GStreamer
Multi-Monitor	✅	✅	✅	✅	✅	✅

gSlapper combines the best features: - Static images + videos (like mpvpaper) - Transitions (like swww) - IPC control (like swww) - Low GPU usage (better than mpvpaper) - No NVIDIA memory leaks (unlike mpvpaper) - Wayland native (unlike feh)