WPE - Wallpaper Engine Manager 🎨

A professional command-line wrapper for linux-wallpaperengine that makes managing Steam Workshop wallpapers effortless.

✨ Features

• 🎯 Easy Management - Start, stop, and toggle wallpapers with simple commands
• ⭐ Favorites System - Save and randomly select from your favorite wallpapers
• 📜 History Tracking - Quick navigation through previously used wallpapers
• 🎨 Presets - Save and load different configurations for various scenarios
• 📊 Performance Stats - Monitor CPU, memory, and uptime of running wallpapers
• 🔄 Systemd Integration - Auto-start wallpapers on boot
• 🔒 Safe Operations - Built-in locking mechanism prevents race conditions
• 📝 Logging - Automatic log rotation and monitoring
• 🎭 Rich CLI - Colorful output with icons for better readability

📋 Requirements

Essential

• Linux operating system (any distro)
• Bash 4.0 or higher (already installed on most systems)
• linux-wallpaperengine - The core wallpaper engine (see installation below)

Installing linux-wallpaperengine

WPE is a wrapper around linux-wallpaperengine, so you need to install it first:

Arch Linux (AUR)

# Using yay
yay -S linux-wallpaperengine

# Using paru
paru -S linux-wallpaperengine

From Source

git clone https://github.com/Almamu/linux-wallpaperengine.git
cd linux-wallpaperengine
# Follow the build instructions in the repository README

Pre-built Binaries

Download from: linux-wallpaperengine releases

Note: The WPE installer will check for linux-wallpaperengine and guide you through installation if not found.

🚀 Installation

Prerequisites

First, ensure linux-wallpaperengine is installed (see Requirements above).

Install WPE

Quick Install

curl -sL https://raw.githubusercontent.com/sodops/wpe/main/install.sh | bash

Manual Install

# Clone the repository
git clone https://github.com/sodops/wpe.git

# Run the installer
cd wpe
./install.sh

The installer will:

• ✅ Check for linux-wallpaperengine (and offer to install it on Arch Linux)
• ✅ Install wpe to ~/.local/bin/
• ✅ Make it executable
• ✅ Add ~/.local/bin to PATH if needed
• ✅ Create configuration directories
• ✅ Run first-time setup

After installation, you can immediately start using WPE!

📖 Usage

Basic Commands

# Start a wallpaper (use Steam Workshop ID)
wpe start 1234567890

# Stop current wallpaper
wpe stop

# Toggle wallpaper on/off
wpe toggle

# Restart current wallpaper
wpe restart

# Show status
wpe status

# Show current wallpaper info
wpe info


# Show performance statistics
wpe stats

# List installed wallpapers
wpe list

# Select wallpaper interactively
wpe select

# Remove a wallpaper
wpe remove 1234567890

Favorites Management

# Add current wallpaper to favorites
wpe fav add 1234567890

# List all favorites
wpe fav list

# Start random favorite
wpe fav random

# Remove from favorites
wpe fav remove 1234567890

History & Navigation

# Show history (last 10)
wpe history

# Show last 20 wallpapers
wpe history 20

# Switch to previous wallpaper
wpe prev

# Switch to next wallpaper
wpe next

# Clear history
wpe clear-history

Presets

# Save current configuration as preset
wpe preset save gaming

# Load a preset
wpe preset load work

# List all presets
wpe preset list

# Delete a preset
wpe preset delete gaming

Systemd Service

# Install systemd service
wpe install-service

# Enable auto-start on boot
wpe enable

# Disable auto-start
wpe disable

Logs & Configuration

# Show last 50 log lines
wpe logs

# Follow logs in real-time
wpe logs follow

# Clear logs
wpe clear-logs

# Show current configuration
wpe config

⚙️ Configuration

WPE uses XDG-compliant directories:

• Config: ~/.config/wpe/
• Cache: ~/.cache/wpe/

Config file location

~/.config/wpe/config

Example configuration

# Display screen (use xrandr to list available screens)
WPE_SCREEN="eDP-1"

# Scaling mode: fit, fill, or stretch
WPE_SCALING="fit"

# Frame rate
WPE_FPS="30"

# Volume (0-100)
WPE_VOLUME="0"

📁 Directory Structure

~/.config/wpe/
├── config          # Main configuration file
├── favorites       # List of favorite wallpaper IDs
└── presets/        # Saved preset configurations
    ├── gaming
    ├── work
    └── ...

~/.cache/wpe/
├── current.id      # Current wallpaper ID
├── history         # Wallpaper history
├── wpe.log         # Application logs
├── wpe.pid         # Process ID file
└── wpe.lock        # Lock file for safe operations

🔍 Finding Wallpapers

1. Visit Steam Workshop - Wallpaper Engine
2. Find a wallpaper you like
3. Copy the ID from the URL: https://steamcommunity.com/sharedfiles/filedetails/?id=XXXXXXXXXX
4. Use the ID with WPE: wpe start XXXXXXXXXX

🎯 Examples

# Set up a wallpaper for gaming
wpe start 1845902173
wpe preset save gaming

# Create a work preset with low performance impact
wpe start 2459830408
wpe preset save work

# Quick random wallpaper from favorites
wpe fav add 1845902173
wpe fav add 2459830408
wpe fav add 1885286935
wpe fav random

# Check performance of current wallpaper
wpe stats

# Navigate through history
wpe prev  # Go back to previous wallpaper
wpe next  # Go forward in history

🔧 Troubleshooting

Wallpaper not starting?

# Check if linux-wallpaperengine is installed
which linux-wallpaperengine

# Check logs for errors
wpe logs

# Verify the wallpaper ID is correct
wpe info

Multiple instances running?

# Stop all instances
wpe stop

# Check status
wpe status

Clear everything and start fresh

# Stop wallpaper
wpe stop

# Clear logs and history
wpe clear-logs
wpe clear-history

# Start fresh
wpe start YOUR_WALLPAPER_ID

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• linux-wallpaperengine - The core wallpaper engine for Linux
• Wallpaper Engine - The original Windows application
• Steam Workshop community for amazing wallpapers

📮 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: GitHub Discussions
• ⭐ Star this repo if you find it useful!

🗺️ Roadmap

• GUI using rofi/dmenu for wallpaper selection
• Automatic wallpaper downloads from Steam Workshop
• Theme/category organization for wallpapers
• Multi-monitor support with different wallpapers
• Scheduled wallpaper rotation
• Integration with popular Linux desktop environments

---

Made with ❤️ for the Linux community