# Nix Random Wallpaper

A simple program that sets random wallpaper images as desktop backgrounds in nix based operating systems / window managers. It fetches images from a local directory or Unsplash, composes a new image to match display size and arrangement, and sets the new image as the desktop background.

This project was forked from [Gnome Random Wallpaper](https://github.com/miliarch/gnome_random_wallpaper), which while great at its original limited scope, is no longer maintained.

**Example arrangement**

![Example Arrangement](example_arrangement.png)

**Example wallpaper**

![Example Wallpaper](example_wallpaper.jpg)

## Usage

Nix Random Wallpaper (`nrw`) currently makes the following assumptions about the user:
* The user will configure some external scheduler to prompt the `nrw` command to run in the background
* The user doesn't usually want to keep the generated wallpaper images forever
  * The last image that was generated is replaced by the newly generated image
* The user won't interact directly with the program often, making command line argument support unnecessary

Simply running `nrw` will fetch images from the image directory (`images_dir`) defined in configuration, then prepare and set the wallpaper based on the configured setter. Sadly the free (unpublished) unsplash API no longer seems to work and is effectively unsupported. I haven't removed any related code, but the configuration no longer uses unsplash as default. The `$HOME/Pictures` directory is the new default configuration value for `images_dir` and `output_dir`.

In xorg, all setters resize and compose the images on a spanned canvas matching your current display arrangement, save the resulting wallpaper image to the output directory (`output_dir`), and update your desktop background. In wayland (currently only hyprland and niri via swaybg), images are placed on their own right-sized canvases, saved separately, and update the desktop background individually on each screen.

Some suggested steps to take in your environment:
* Configure a cron job or timer of some sort to run `nrw` at regular intervals (every 15 minutes works well for me - `*/15 * * * * /path/to/nrw`)
* Configure a Startup Application to run `nrw` on login

## Installation

Use the following command to install the `nrw` module from PyPi with pip:
```
pip install nrw
```

Or to install the latest version of the repository with pip:
```
pip install git+https://github.com/miliarch/nrw.git
```

After installation, a `nrw` executable link should be placed in your `$HOME/.local/bin` directory (this may vary depending on distro). If this directory is included in your PATH environment variable, the `nrw` command should be available for use without any further steps. Otherwise, you'll need to either specify the full path to run the program, or add the `$HOME/.local/bin` directory to your PATH environment variable.

Alternatively, clone this repository to your preferred installation directory and manually link `./nrw/nix_random_wallpaper.py` in the execution directory of your choice.

## Configuration

Default configuration can be found in [nrw/config.yaml](nrw/config.yaml). This file can be copied to `$HOME/.config/nix_random_wallpaper/config.yaml` and modified to override the default options.

Each configuration option in the file includes an in-line comment that details its function. If you have any questions about how existing options behave, or requests for new options, please raise an issue in this repository.

### Extra configuration required for swaybg_niri window setter

The `swaybg_niri` window_setter requires custom systemd service units to be installed for automatic image update/refresh to work. This configuration is similar to what is recommended in the [official getting started documentation](https://niri-wm.github.io/niri/Example-systemd-Setup.html).

Install the following systemd unit file at `$HOME/.config/systemd/user/swaybg@.service`:
```
[Unit]
PartOf=graphical-session.target
After=graphical-session.target
Requisite=graphical-session.target

[Service]
ExecStart=/usr/bin/swaybg --mode fill --output %i -i "%h/Pictures/wallpaper_%i.jpg"
Restart=on-failure
```

Enable one instanced service unit per display used on the system. For example, if your `niri msg outputs` output includes 2 monitors named `DP-1` and `DP-2`:
```
systemctl --user add-wants niri.service swaybg@DP-1.service
systemctl --user add-wants niri.service swaybg@DP-2.service
```

In addition, because of the hardcoded path in the systemd service file, your nrw config file needs to specify:
```
output_dir: $HOME/Pictures
output_image_name: wallpaper.jpg
output_image_format: jpeg
```

This can definitely get better if anyone is bothered by the restriction, but I'm satisfied with it for the time being.

## Supported display configurations

Any number of displays that are arranged horizontally (side-by-side) within the vertical (height) bounds of the largest display should be supported by wallpaper setters that compose images that span multiple displays.

## Unsupported display configurations

Vertical arrangements, including mixed vertical/horizontal arrangements, are currently unsupported by wallpaper setters that compose images that span multiple displays. Support may be implemented in the future.

Window setters that set display backgrounds independently should support any configuration.

## Tested configurations

### Window managers

* Cinnamon 5.0.5-5.0.7 (xorg)
* awesome v4.3 (xorg)
* hyprland v0.39.1 (wayland)
* [niri](https://github.com/niri-wm/niri) 25.11 (b35bcae)

### Wallpaper setters

* gnome (via gsettings; xorg only)
* [nitrogen](https://github.com/l3ib/nitrogen) (recommended for xorg)
* [hyprpaper](https://github.com/hyprwm/hyprpaper) (hyprland/wayland only)
* [swaybg](https://github.com/swaywm/swaybg) (niri/wayland with systemd only)

### Resolutions
* 1920x1080
* 2560x1440
* 3840x2160

### Display arrangements
* Dual monitor, landscape orientation, horizontal arrangement (side-by-side)
* With wayland wallpaper setters, images are set independently by active monitor instead of being placed on a large canvas; any arrangement should be supported
