Command Line Options

Basic Options

-v, --verbose

Enable verbose output. Use -vv for more detail.

gslapper -v DP-1 video.mp4
gslapper -vv DP-1 video.mp4  # More verbose

-f, --fork

Fork to background after starting.

gslapper -f -o "loop" DP-1 video.mp4

-d, --help-output

Display all available outputs and quit.

gslapper -d

-h, --help

Display help message.

gslapper --help

Playback Control

-p, --auto-pause

Automatically pause when wallpaper is hidden.

gslapper -p -o "loop" DP-1 video.mp4

-s, --auto-stop

Automatically stop when wallpaper is hidden.

gslapper -s -o "loop" DP-1 video.mp4

-r, --fps-cap FPS

Set frame rate cap. Available values: 30, 60, or 100 FPS.

gslapper -r 60 -o "loop" DP-1 video.mp4

Default: 30 FPS

Use Case: Higher FPS for smoother video playback, lower FPS to reduce CPU/GPU usage.

Display Options

-l, --layer LAYER

Specify shell surface layer. Options:

• background (default)
• bottom
• top
• overlay

gslapper -l overlay DP-1 video.mp4

IPC Options

-I, --ipc-socket PATH

Enable IPC control via Unix socket.

gslapper -I /tmp/gslapper.sock DP-1 video.mp4

Cache Options

--cache-size SIZE_MB

Enable image cache with specified size in MB. Caches decoded RGBA image data in RAM for instant wallpaper switching.

# 256 MB cache (recommended for ~10-30 images depending on resolution)
gslapper --cache-size 256 -I /tmp/gslapper.sock DP-1 /path/to/image.jpg

# Switch images instantly via IPC
echo "change /path/to/other.jpg" | nc -U /tmp/gslapper.sock

Default: 256 (enabled by default)

Recommended Values:

• 128 MB - For smaller image collections (~5-15 images at 4K)
• 256 MB - General purpose (~10-30 images at 4K)
• 512 MB - Large collections or many high-resolution images

Features:

• Automatic caching when images are displayed
• LRU (Least Recently Used) eviction when cache is full
• Cache hits result in near-instant wallpaper changes
• Query cache usage via IPC: cache-stats, cache-list

Notes:

• Only works with static images (JPEG, PNG, WebP, etc.)
• Videos are not cached (use GStreamer pipeline directly)
• Cache is cleared on exit

Video Options

-o, --gst-options "OPTIONS"

Pass options to GStreamer. Space-separated list:

• loop - Seamless video looping
• fill - Fill screen maintaining aspect ratio (default for images)
• panscan=X - Scale video (0.0-1.0, default 1.0)
• stretch - Stretch to fill screen (ignore aspect ratio)
• original - Display at native resolution
• no-audio - Disable audio playback

gslapper -o "loop panscan=0.8" DP-1 video.mp4

Transition Options

--transition-type TYPE

Set transition effect type. Options:

• none (default)
• fade

gslapper --transition-type fade -I /tmp/sock DP-1 image.jpg

--transition-duration SECS

Set transition duration in seconds (default: 0.5).

gslapper --transition-type fade --transition-duration 2.0 -I /tmp/sock DP-1 image.jpg

Systemd Options

-S, --systemd

Enable systemd service mode. Enables systemd readiness notifications.

gslapper -S --restore DP-1 /path/to/video.mp4

Use Case: Only needed when running as systemd user service. The service files (gslapper.service, gslapper@.service) automatically include this flag.

-R, --restore

Restore wallpaper from saved state file.

# Restore for specific output
gslapper -R DP-1

# Restore for all monitors
gslapper -R '*'

Behavior: Loads state from ~/.local/state/gslapper/state-<output>.txt (or state.txt for '*') and resumes wallpaper with saved video position and pause state.

State Management Options

--save-state

Save current wallpaper state and exit.

gslapper -o "loop" DP-1 /path/to/video.mp4
# Later, save state
gslapper --save-state

Use Case: Manual state save without stopping gSlapper. Also available via IPC: echo "save-state" | nc -U /tmp/sock.

--state-file <path>

Use custom state file path (instead of default).

gslapper --state-file /tmp/my-state.txt --restore DP-1

Default Location: ~/.local/state/gslapper/state-<output>.txt (or $XDG_STATE_HOME/gslapper/ if set).

--no-save-state

Disable automatic state saving on exit.

gslapper --no-save-state -o "loop" DP-1 /path/to/video.mp4

Use Case: Testing or temporary wallpapers where you don't want state saved.

Examples

# Basic video with looping
gslapper -o "loop" DP-1 video.mp4

# Image with fill mode and IPC
gslapper -o "fill" -I /tmp/sock DP-1 image.jpg

# Video with auto-pause and verbose output
gslapper -v -p -o "loop" DP-1 video.mp4

# Background mode with transitions
gslapper -f --transition-type fade --transition-duration 1.5 -I /tmp/sock DP-1 image.jpg