wallswitch

Random Wallpaper for Multiple Monitors

#-----------#-----------# ... ... #-----------#
|           |           |         |           |
| Monitor 1 | Monitor 2 |         | Monitor n |
|           |           |         |           |
#-----------#-----------# ... ... #-----------#

Description

wallswitch randomly selects wallpapers for multiple monitors.

It is designed to be fast, robust, and compatible with both X11 and modern Wayland compositors.

Features

• Random Wallpaper Selection: Dynamically chooses different wallpapers from designated directories for every monitor.

• Smart Caching & Visual Deduplication:

  • Uses BLAKE3 hashing to index files.
  • Automatically skips visual duplicates (same image, different filename).
  • Smart cache checks modification times (mtime) for instant startup.

• Configurable Filtering:

  • Dimension Control: Filter images by minimum/maximum width and height.
  • File Size Management: Exclude images based on byte size.

• Flexible Configuration:

  • Custom directories and image extensions (JPG, PNG, SVG, WEBP, AVIF, etc.).
  • Monitor-specific settings (orientation and pictures per monitor).

• Advanced Listing:

  • Sort your entire collection by size, dimensions, aspect ratio, or date.

Usage

Standard background loop:

  wallswitch

Run once and exit (useful for login scripts or cron):

  wallswitch --once

Test behavior without applying changes:

  wallswitch --dry-run

Set N different wallpapers per monitor (Gnome only):

  wallswitch -p N

Configuration

The configuration file is located at: ~/.config/wallswitch/wallswitch.json

Displaying the Configuration:

  wallswitch -c

The default configuration file structure:

{
  "desktop": "niri",
  "directories": [
    "/home/user_name/Figures",
    "/home/user_name/Images",
    "/home/user_name/Pictures",
    "/home/user_name/Wallpapers",
    "/home/user_name/Imagens",
    "/usr/share/wallpapers",
    "/usr/share/backgrounds",
    "/tmp/teste"
  ],
  "extensions": [
    "avif",
    "jpg",
    "jpeg",
    "png",
    "svg",
    "tif",
    "webp"
  ],
  "interval": 300,
  "min_dimension": 600,
  "max_dimension": 128000,
  "min_size": 1024,
  "max_size": 1073741824,
  "monitors": [
    {
      "picture_orientation": "Vertical",
      "pictures_per_monitor": 1,
      "resolution": {
        "width": 3840,
        "height": 2160
      }
    },
    {
      "picture_orientation": "Horizontal",
      "pictures_per_monitor": 1,
      "resolution": {
        "width": 3840,
        "height": 2160
      }
    }
  ],
  "monitor_orientation": "Horizontal",
  "path_feh": "/usr/bin/feh",
  "path_magick": "/usr/bin/magick",
  "sort": false,
  "wallpaper": "/home/user_name/wallswitch.jpg",
  "transition_type": "random",
  "transition_duration": 2,
  "transition_fps": 60,
  "transition_angle": 30,
  "transition_pos": "center"
}

Listing and Sorting

List images using --list <CRITERIA>.

Table sorting options:

• path: Sort by full system path.
• name: Sort by filename only.
• size: Sort by file size (ascending).
• sizedesc: Sort by file size (descending).
• width: Sort by image width.
• height: Sort by image height.
• area: Sort by total pixels (width x height).
• ratio: Sort by aspect ratio (e.g., 16:9).
• time: Sort by last modification date.

JSON state options:

• processed: List probed images with dimension metadata (JSON).
• unprocessed: List images pending dimension probing (JSON).
• cache: Full dump of the metadata cache (JSON).

Example:

  wallswitch --list ratio

Wallpaper Suggestions

• Get all gnome backgrounds:

  git clone https://github.com/zebreus/all-gnome-backgrounds.git

Help Messages

Run: wallswitch -h

Options:
  -b, --min_size <MIN_SIZE>           Min file size in bytes
  -B, --max_size <MAX_SIZE>           Max file size in bytes
  -c, --config                        Read config and exit
  -d, --min_dimension <MIN_DIM>       Min value for width/height
  -D, --max_dimension <MAX_DIM>       Max value for width/height
  -i, --interval <INTERVAL>           Seconds between changes
  -l, --list <CRITERIA>               List and sort images
  -m, --monitor <MONITOR>             Number of monitors [default: 2]
  -o, --orientation <ORIENT>          Monitor layout: Horizontal or Vertical
      --once                          Run one cycle and exit
  -p, --pictures_per_monitor <N>      Images per monitor (Gnome)
  -s, --sort                          Sort images by filename
      --dry-run                       Simulation mode
  -v, --verbose                       Show runtime messages

Installation and Desktops

Build from source:

  git clone https://github.com/claudiofsr/wallswitch.git
  cd wallswitch
  cargo b -r && cargo install --path=.

Desktop Specifics:

• Gnome : Uses 'magick' to create a spanned background and 'gsettings'.
• XFCE : Uses 'xfconf-query' to set images per monitor.
• Wayland : Robust detection for Niri, Hyprland, Labwc, Mango. Backend priority: awww -> swaybg -> hyprpaper.
• X11/Other: Fallback to 'feh'.

Dependencies

• imagemagick : Core image processing (identify/magick).
• feh : Fast viewer for X11/Openbox.
• awww : Animated daemon for Wayland (highly recommended).
• swaybg : Reliable static wallpaper tool for Wayland.
• hyprpaper : Wallpaper utility for Hyprland users.

License

Copyright (c) 2023, Claudio Fernandes de Souza Rodrigues.

All rights reserved.

Distributed under the BSD-3-Clause License.