omarchy-background-changer

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #typescript #llm #golang #deep-learning #nodejs #macos #java #windows #kubernetes #security

omarchy-background-changer

(★ 18)

No description available.

omarchy-background-changer Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Omarchy Background Listener
![Wallpapers](https://raw.githubusercontent.com/mpriem/omarchy-background-changer/main/wallpapers/wallpapers.gif)
## Overview
This repository contains the Hyprland event listener script that drives workspace-aware wallpapers for the [Omarchy](https://github.com/basecamp/omarchy) desktop (an Arch Linux derivative). The script listens for monitor and workspace events and swaps backgrounds via [`swww`](https://github.com/Horus645/swww) so each workspace can have its own image.

Out of the box the wallpaper mapping targets the **Matt Black** theme. The listener is intentionally minimal and assumes a single theme directory of wallpapers, so treat it as a starting point that you can adapt to match the structure of your own Omarchy setup.

## Requirements
All commands below assume an Arch-based system with the [`yay`](https://github.com/Jguer/yay) AUR helper installed.

### `swww`
Fast wallpaper switcher used to display images and (eventually) pre-cache them.

```bash
yay -S --needed swww
```

### `swww-daemon`
Maintains compositor state for `swww` so image transitions are smooth. This package currently lives in the AUR.

```bash
yay -S --needed swww-daemon
```

### `socat`
Streams Hyprland events from the UNIX socket into the listener script.

```bash
yay -S --needed socat
```

> ℹ️  The script also expects Hyprland's `hyprctl` binary and `jq` (both part of a standard Omarchy/Hyprland install).

## Setup
1. Copy `omarchy-background-listener.sh` somewhere in your `$PATH` (for example, `~/.config/omarchy/bin/`).
2. Make it executable:
   ```bash
   chmod +x ~/.config/omarchy/bin/omarchy-background-listener.sh
   ```
3. Place your wallpapers under `~/Pictures/wallpapers/` or adjust the `WS_IMG` map in the script to point to your preferred locations.
4. Ensure `swww-daemon` is running before starting the listener:
   ```bash
   swww-daemon &
   ~/.config/omarchy/bin/omarchy-background-listener.sh &
   ```

## Omarchy `autostart.conf`
Add the following lines to your `~/.config/omarchy/autostart.conf` so the daemon and listener start with Hyprland (update paths if you put the script elsewhere):

```
exec-once = swww-daemon
exec-once = ~/.config/omarchy/bin/omarchy-background-listener.sh
```

Comment out the default sway background line, as the listener now controls backgrounds:

```
# exec-once = uwsm app -- swaybg -i ~/.config/omarchy/current/background -m fill
```

Restart Hyprland or reload the config to activate the changes.

## Customization & Future Work
- Replace the entries in `WS_IMG` with images that match your workspace layout or, better yet, refactor the script to load mappings from a config file so it can support multiple themes beyond the current Matt Black setup.
- The move to `swww` was motivated by its ability to pre-cache images for buttery transitions—precaching hooks have not been added yet, so contributions in that direction are welcome.
- Per-monitor defaults, named workspaces, and theme profiles are all areas ready for improvement.

## Warranty & Support
This code is provided **as-is**, with no formal support. Review the script, adapt it to your environment, and test changes carefully before relying on it in production sessions.

omarchy-background-changer

omarchy-background-changer Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

omarchy-background-changer

omarchy-background-changer Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README