wallswitch 0.64.2

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 fast, and lightweight, performing all image stitching, cropping, scaling, and fractal generation in-process using pure Rust.

Example Wallpapers (with Julia Fractal Overlays)

Below are two examples of generated wallpapers after applying the procedural Julia set fractal overlay effect. Click on the thumbnails below to view the images in 1920x1080 resolution:

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|julia|mandelbrot|newton|nova|star|aurora|fractal|random>:
    • Julia Sets (julia): 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.
      • Generator function: f(z) = z^2 + c, where c is a fixed constant and the initial z varies.
    • Mandelbrot Set (mandelbrot): Renders structural details and high-period cardioid bulb swirls.
      • Generator function: z(n+1) = z(n)^2 + c, where the initial z is zero and c varies.
    • Newton-Raphson Basins (newton): Renders geometric, kaleidoscope-like mandala structures representing root-finding convergence fields across complex space boundaries.
      • Generator function: z(n+1) = z(n) - lambda * f(z(n)) / f'(z(n)) on the polynomial f(z) = z^p - 1.
    • Nova Julia (nova): Generates flowing, fluid-like plumes resembling liquid mercury, cosmic nebulae, or dynamic plasma current paths.
      • Generator function: z(n+1) = z(n) - R * (z(n)^p - 1) / (p * z(n)^(p-1)) + c.
    • Starfield / Bokeh (star): Projects glowing, circular stars and light orbs of varying sizes, intensities, and neon colors with smooth Gaussian light falloffs.
      • Generator function: I(d) = I_0 * exp(-d^2 / (2 * sigma^2)).
    • Cosmic Aurora (aurora): Generates glowing atmospheric wave filaments using multi-frequency wave mathematics.
      • Generator function: alpha = 0.25 * (sin(d_u * x) + cos(d_v * y) + sin(d_w * x + rho) + cos(sqrt(u^2 + v^2) * d_w4)).
    • Fractal Mode (fractal): Randomly selects between Julia or Mandelbrot fractal overlays for the cycle.
    • Polynomial Mode (polynomial): Randomly selects between Newton-Raphson Basins or Nova Julia fractal overlays for the cycle.
    • Randomized Mode (random): 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.
  • 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 a specific Julia Sets overlay on wallpapers:

wallswitch -e julia

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_name/Pictures",
    "/home/user_name/Wallpapers",
    "/home/user_name/Imagens",
    "/usr/share/backgrounds"
  ],
  "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,
  "effect": "juliaset",
  "effects": {
    "add_presets": true,
    "min_iterations": 600,
    "max_iterations": 1200,
    "julia": [ ... ],
    "mandelbrot": [ ... ],
    "newton": [ ... ],
    "nova": [ ... ]
  },
  "wallpaper": "/home/user_name/.cache/wallswitch/wallswitch.png",
  "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, julia, mandelbrot, newton, nova, star, aurora, fractal, polynomial, 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 a specific Julia Sets fractal overlay on wallpapers
  wallswitch --effect julia

  # Apply random fractal overlays [julia, mandelbrot]
  wallswitch --effect fractal

  # Apply randomized procedural overlays (fractal, polynomial, stars, auroras) on wallpapers
  wallswitch --effect random

  # 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 Background Strategies

wallswitch can be deployed using two different strategies depending on your operating system and system resource preferences.

Strategy A: Systemd User Scheduler (Recommended for Linux)

This approach triggers a single-shot cycle (wallswitch --once) at a configured interval.

  • Advantage: Guarantees 0 MB of RAM usage when idle, as the process terminates immediately after updating the background.
  • Requirements: Any standard Linux distribution using Systemd (such as Manjaro, Arch, Fedora, Debian/Ubuntu).

To build, install, and configure the Systemd timer automatically (defaults to a 5-minute / 300-second interval):

git clone https://github.com/claudiofsr/wallswitch.git
cd wallswitch
make install

To customize the rotation interval (e.g., to 10 minutes / 600 seconds):

make install INTERVAL=600

To cleanly disable and remove the timer and configuration files from your system:

make uninstall

Strategy B: Built-in Daemon Mode

This approach runs wallswitch as a persistent background loop process.

  • Advantage: Completely self-contained with zero external scheduler dependencies; ideal for non-Systemd setups, X11/Openbox sessions, or Windows environments.
  • Memory Management: Highly optimized. It leverages standard drop semantics and conditional malloc_trim FFI triggers at the end of each cycle to release unused memory arenas back to the OS kernel, keeping the idle RAM footprint constrained (~58MB to ~140MB depending on the processing of massive 4K/8K assets).

To build and install the standalone binary:

cargo b -r && cargo install --path=.

To run the persistent background loop (e.g., updating every 5 minutes):

wallswitch --interval 300

Desktops

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 Hyprland, Niri, 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.