wallswitch 0.56.0

# 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": "gnome",
  "directories": [
    "/home/user_name/Pictures",
    "/usr/share/wallpapers",
    "/usr/share/backgrounds"
  ],
  "extensions": ["avif", "jpg", "jpeg", "png", "svg", "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 }
    }
  ],
  "monitor_orientation": "Horizontal",
  "path_feh": "/usr/bin/feh",
  "path_magick": "/usr/bin/magick",
  "sort": false,
  "verbose": 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.