nixpkgs/docs/packages/hyprpaper-random.md

# hyprpaper-random

Minimal random wallpaper setter for Hyprpaper.

## Description

hyprpaper-random is a shell script that randomly selects and applies a wallpaper from a configured directory for use with Hyprpaper on Hyprland. It's designed to be minimal and fast.

## Features

- 🎲 **Random Selection**: Picks a random wallpaper from directory
- 🖼️ **Multi-Monitor Support**: Applies wallpaper to all monitors
- 📁 **Flexible Directory**: Configurable via environment variable
- 🔍 **Format Support**: jpg, jpeg, png, webp, avif
- ⚡ **Fast**: Uses `fd` for quick file searching
- 🔄 **Safe**: Null-safe handling and error checking

## Installation

### Via Overlay

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    hyprpaper-random
  ];
}
```

### Direct Reference

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.hyprpaper-random
  ];
}
```

### Run Directly

```bash
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#hyprpaper-random
```

## Usage

### Basic Usage

```bash
# Use default directory ($XDG_CONFIG_HOME/hypr/wallpapers or ~/.config/hypr/wallpapers)
hyprpaper-random

# Use custom directory
WALLPAPER_DIR=~/Pictures/wallpapers hyprpaper-random

# Or set directory permanently
export WALLPAPER_DIR=~/Pictures/wallpapers
hyprpaper-random
```

### With Hyprpaper

Make sure Hyprpaper is running and loaded:

```bash
# Start Hyprpaper
hyprpaper &

# Set random wallpaper
hyprpaper-random
```

### Automate with Keybinding

Add to Hyprland config:

```nix
{pkgs, ...}: {
  wayland.windowManager.hyprland.settings = {
    bindm = [
      "SUPER, mouse, movewindow"
    ];

    bind = [
      # Set random wallpaper on SUPER + W
      "SUPER, W, exec, ${pkgs.hyprpaper-random}/bin/hyprpaper-random"
    ];
  };
}
```

### Automate with Cron

```bash
# Change wallpaper every hour
0 * * * * hyprpaper-random
```

## Configuration

### Directory Setup

Default wallpaper directory:

```
$XDG_CONFIG_HOME/hypr/wallpapers/
# or
~/.config/hypr/wallpapers/
```

Custom directory:

```bash
# Temporary
WALLPAPER_DIR=~/Pictures/my-wallpapers hyprpaper-random

# Permanent (add to shell config)
export WALLPAPER_DIR=~/Pictures/my-wallpapers
```

### Environment Variables

- `WALLPAPER_DIR`: Path to wallpaper directory (default: `$XDG_CONFIG_HOME/hypr/wallpapers`)
- `XDG_CONFIG_HOME`: Config directory base (default: `~/.config`)

## Requirements

- `hyprland`: Hyprland window manager (for `hyprctl`)
- `hyprpaper`: Wallpaper utility for Hyprland
- `fd`: Fast file search
- `coreutils`: For `shuf` command
- `gawk`: Text processing

## Platform Support

- Linux (primary, requires Hyprland)
- macOS (not supported)
- Windows (not supported)

## Build Information

- **Version**: 0.1.1
- **Type**: Shell script
- **License**: MIT

## Troubleshooting

### No Wallpapers Found

Error: `No wallpapers found in: /path/to/dir`

**Solution**: Ensure wallpaper directory exists and contains images:

```bash
ls -la $WALLPAPER_DIR  # Check directory exists
ls -la $WALLPAPER_DIR/*.jpg  # Check for images
```

### Hyprctl Not Found

Error: `hyprctl: command not found`

**Solution**: Ensure Hyprland is installed:

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    hyprland
    hyprpaper
  ];
}
```

### Wallpaper Not Changing

**Solution**: Check if Hyprpaper is running:

```bash
# Check status
hyprctl hyprpaper listloaded

# Check for errors
journalctl -u hyprpaper -f
```

## Related

- [Adding Packages](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide