Muro

Wallpaper generator that fits any image to any screen with blurred or averaged background.

Introduction

In Esperanto, muro means wall. The muro app converts images into well-fitted wallpapers. What makes it useful compared to other packages?

1. It displays any image without distortion as a background, regardless of size. When multiple screens with different resolutions or orientations are connected, the wallpaper image displays fully without distortion on all of them.

2. It reduces contrast between a wallpaper image and its 'empty' background. The background can be filled with either a blurred version of the image or its average color. This is especially useful when transparency is enabled for terminal windows—with reduced contrast, working inside the terminal becomes easier.

3. It supports using small images as tiles for wallpaper borders.

It is performant and can comfortably handle hundreds of thousands of images located across hundreds of subdirectories.

Many wallpaper apps work with muro: point them to the generated images in ~/.cache/muro.

Installation

Download the latest release binary file, uncompress, and place the executable muro file somewhere in the PATH.

Arch Linux AUR package

AUR package is located at https://aur.archlinux.org/packages/muro. Install it by hand, or with AUR helpers like yay or pacaur.

yay -S muro
# or
pacaur -S muro

Build as Nix package

You need to install Nix with flakes and nix-command enabled, for example using nix-installer by Determinate Systems.

In muro's root directory, run:

nix build

This creates the muro binary in the result/bin directory.

Updating Nix flake dependencies (for developers)

When Go dependencies change (after updating go.mod), you need to regenerate the Nix-specific dependency lock file:

# Install gomod2nix if not already available
nix shell nixpkgs#gomod2nix
# Regenerate gomod2nix.toml
gomod2nix
# Update flake inputs (nixpkgs, gomod2nix, etc.)
nix flake update
# Test the build
nix build .#

The gomod2nix.toml file must be regenerated whenever dependencies in go.mod or go.sum change. Without this step, the Nix build will use outdated dependencies and may fail.

Configuration

When muro runs for the first time, it creates a configuration file at ~/.config/muro/muro.yaml. Edit this file to change default options.

The most important setting is the monitors section—update it to match the order and resolution of your monitors.

Usage

To use default settings:

muro

To get help:

muro -h

To clear history:

muro -C

To change background for proportionally scaled images:

# blur image itself for the background
muro -b blur
# use average color of the image as a background
muro -b average
# use a default tile
muro -b tile
# provide a custom background image for tiling
muro -b -t /path/to/tile.png
# set a custom #AAFFAA background color
muro -b rgb --bg-color afa
muro -b rgb --bg-color aaffaa

By default, images are selected recursively in random order. Several options control how images are selected:

# Pick a specific image
muro -p ~/Pictures/wallpapers/img1.jpg
# Disable recursive selection
muro --not-recursive
# Pick the next image in ascending or descending order
muro -s name
muro -s name-desc

Setting up wallpaper for a window manager

Th muro app sets the wallpaper once and then exits. To change wallpaper regularly, run muro or muro -s name as a cron job or systemctl --user timer.

Here is an example of a systemd timer.

Changing to a random point in the wallpaper sequence

Running the muro command without flags changes the starting point to a random image. If a cronjob or timer triggers muro -s name, the images will continue sequentially from this new "seed".

Use in a Go program

import("log"muro"codeberg.org/dimus/muro/pkg""codeberg.org/dimus/muro/pkg/config")funcmain(){cfg:=config.New(config.OptImgPath("~/Pictures/wallpapers1"))mr:=muro.New(cfg)path,err:=mr.GetImagePath()iferr!=nil{log.Fatal(err)}err=mr.WallpaperImage(path)iferr!=nil{log.Fatal(err)}}

Wallpaper projects for X11 and Wayland

These projects can be used to set wallpapers generated by muro as backgrounds:

feh

swaybg

nitrogen

wallutils

License

The muro project is released under the MIT license.