wallswitch 0.59.3

randomly selects wallpapers for multiple monitors
Documentation

wallswitch

Random Wallpaper for Multiple Monitors

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

Description

wallswitch randomly selects and processes wallpapers for multiple monitors.

It is designed to be exceptionally fast, and lightweight, performing all image stitching, cropping, scaling, and fractal generation in-process using pure Rust. It is compatible with both X11 and modern Wayland compositors.

Features

  • Multi-Picture Composition: Dynamically combines up to N different wallpapers per monitor across all supported desktop environments.
  • 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.
  • Procedural Overlay Effects: Adds customizable mathematical overlays over your wallpapers. Configured via -e / --effect <none|fractal|star|random>:
    • Julia Fractals: Highly detailed, randomized 360-degree rotated fractals. Uses continuous potential smooth coloring to prevent color-banding, and contrast-preserving dynamic halo blending to keep shapes visible on both light and dark backgrounds.
    • Starfield / Bokeh: projects glowing, organic circular stars and light orbs of varying sizes, intensities, and neon colors with smooth Gaussian light falloffs.
    • Randomized Mode: Automatically decides on a random overlay effect independently for each physical display.
  • Highly Optimized Parallel Processing: Core rendering routines for procedural calculations and image stitching are fully parallelized across all logical CPU cores using standard library thread scopes, maximizing execution speed.
  • Soft Vignette Shading: Seamlessly darkens and softens edges to add depth and draw focus to the center.
  • 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 (AVIF, JPG, PNG, WEBP, TIF, 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 (All desktops):

wallswitch -p N

Apply Julia fractal overlays on wallpapers:

wallswitch -e fractal

Configuration

The configuration file is located at:

  ~/.config/wallswitch/wallswitch.json

Displaying the Configuration:

wallswitch -c

The default configuration file structure:

{
  "desktop": "gnome",
  "directories": [
    "/home/user_name/Figures",
    "/home/user_name/Images",
    "/home/user_nameo/Pictures",
    "/home/user_name/Wallpapers",
    "/home/user_name/Imagens",
    "/usr/share/wallpapers",
    "/usr/share/backgrounds",
    "/tmp/teste"
  ],
  "extensions": [
    "avif",
    "jpg",
    "jpeg",
    "png",
    "tif",
    "webp"
  ],
  "interval": 1800,
  "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",
  "sort": false,
  "fractal": false,
  "wallpaper": "/home/claudio/wallswitch.jpg",
  "transition_type": "random",
  "transition_duration": 2,
  "transition_fps": 60,
  "transition_angle": 45,
  "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

randomly selects wallpapers for multiple monitors
Usage: wallswitch [OPTIONS]

Options:
  -b, --min_size <MIN_SIZE>
          Set a minimum file size (in bytes) for searching image files
  -B, --max_size <MAX_SIZE>
          Set a maximum file size (in bytes) for searching image files
  -c, --config
          Read the configuration file and exit the program
  -d, --min_dimension <MIN_DIMENSION>
          Set the minimum dimension that the height and width must satisfy
  -D, --max_dimension <MAX_DIMENSION>
          Set the maximum dimension that the height and width must satisfy
  -e, --effect <EFFECT>
          Apply a procedural overlay effect to the selected wallpapers before displaying [possible values: none, fractal, star, random]
  -g, --generate <GENERATOR>
          Generate shell completions and exit the program [possible values: bash, elvish, fish, powershell, zsh]
  -i, --interval <INTERVAL>
          Set the interval (in seconds) between each wallpaper displayed
  -l, --list <CRITERIA>
          List all found images and exit
  -m, --monitor <MONITOR>
          Set the number of monitors [default: 2]
  -o, --orientation <MONITOR_ORIENTATION>
          Inform monitor orientation: Horizontal (side-by-side) or Vertical (stacked)
      --once
          Run a single wallpaper update cycle and exit
  -p, --pictures_per_monitor <PICTURES_PER_MONITOR>
          Set number of pictures (or images) per monitor [default: 1]
  -s, --sort
          Sort the images found
      --dry-run
          Run without applying the wallpapers (simulation mode)
      --transition-type <TRANSITION_TYPE>
          Transition type for Wayland compositors using awww (e.g. wipe, wave, fade, random)
      --transition-duration <TRANSITION_DURATION>
          Duration of the transition animation in seconds
      --transition-fps <TRANSITION_FPS>
          Frames per second for transition smoothness
      --transition-angle <TRANSITION_ANGLE>
          Angle used by directional transitions (wipe, wave)
      --transition-pos <TRANSITION_POS>
          Origin position used by grow/outer transitions (e.g. center, top)
  -v, --verbose
          Show intermediate runtime messages
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version


Config file:
  /home/claudio/.config/wallswitch/wallswitch.json

Examples:
  # Start the automatic background loop using default settings
  wallswitch

  # Run a single wallpaper update cycle and exit (useful for cron jobs)
  wallswitch --once

  # Change wallpaper every 10 minutes (600 seconds)
  wallswitch --interval 600

  # Set 3 different wallpapers per monitor (Gnome desktop only)
  wallswitch --pictures_per_monitor 3

  # Filter images by dimension (min 1080px) and file size (max 5MB)
  wallswitch --min_dimension 1080 --max_size 5242880

  # Apply randomized procedural overlays (Julia fractal or starfield) onto the selected wallpapers
  wallswitch --effect random

  # Apply a specific procedural Julia fractal overlay
  wallswitch --effect fractal

  # Dry run mode to see what would be executed without applying changes
  wallswitch --dry-run --verbose

  # Wayland (awww): Use specific transition effects and duration
  wallswitch --transition-type wave --transition-duration 3

  # List all found images sorted by file size
  wallswitch --list size

  # Display all processed images (with dimensions) in JSON format
  wallswitch --list processed

  # Display all images that haven't been probed yet
  wallswitch --list unprocessed

  # Count processed images using jq
  wallswitch -l processed | jq 'length'

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 : Assembles composite backgrounds in memory, saves the final spanned file, and sets it via 'gsettings'.
  • XFCE : Assembles composite backgrounds in memory, saves separate monitor backgrounds, and applies them via 'xfconf-query'.
  • Wayland : Robust detection for Niri, Hyprland, Labwc, Mango. Assembles separate monitor backgrounds, and applies them. Backend priority: awww -> swaybg -> hyprpaper.
  • X11/Other: Fallback to 'feh'.

Dependencies

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