# wallswitch
Random Wallpaper for Multiple Monitors
```
#-----------#-----------# ... ... #-----------#
| | | | |
#-----------#-----------# ... ... #-----------#
```
### 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.
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).V
* 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|star|aurora|fractal|random>`:
* **Julia Sets (`julia`)**: 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.
* *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: `f(z) = z^2 + c`, where the initial `z` is zero and `c` varies.*
* **Starfield / Bokeh (`star`)**: Projects glowing, organic circular stars and light orbs of varying sizes, intensities, and neon colors with smooth Gaussian light falloffs.
* **Cosmic Aurora (`aurora`)**: Generates glowing atmospheric wave filaments using high-contrast wave mathematics.
* **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
```
Apply a Burning Ship fractal overlay:
```
wallswitch -e ship
```
### 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, julia, mandelbrot, star, aurora, fractal, 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 a random choice of Julia or Mandelbrot fractal overlays
wallswitch --effect fractal
# Apply randomized procedural overlays (fractals, 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
### 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.