Wallpaper by Workspace

A DankMaterialShell daemon plugin that sets a different wallpaper per workspace on the niri compositor.

When you switch workspaces, DMS regenerates the Material theme (matugen) from the new wallpaper, keeping each workspace visually distinct.

Demo

Switching niri workspaces applies the per-workspace wallpaper and regenerates the theme, while OpenRGB Theme Sync pushes the theme color to the RGB hardware live. Chapters: 0:00 neutral · 0:04 green → green RGB · 0:06 warm · 0:08 snow → white RGB.

Features

• Per-workspace wallpapers: each niri workspace uses its own ~/Wallpapers/workspace_N folder.
• Fixed or alternate mode: keep the last chosen wallpaper for a workspace, or pick a random one (without repeating the previous) each time you switch.
• Periodic rotation: optionally rotate the active workspace's wallpaper every N minutes.
• "Show desktop" transition (optional): while the theme regenerates, windows briefly lower their opacity (optional background blur) so the new wallpaper and desktop appear behind them, then return to normal.
• Chrome sync (optional): after regenerating the theme, update Google Chrome's toolbar color to match the Dank bar.

Install

1. Copy the wallpaperByWorkspace/ folder into your DMS plugins directory:

   cp -r wallpaperByWorkspace "${XDG_CONFIG_HOME:-$HOME/.config}/DankMaterialShell/plugins/"
   

2. In Dank Material Shell Settings → Plugins, Scan for Plugins, then enable Wallpaper by Workspace.

Requirements

• niri compositor.
• DMS managing your wallpaper (dms matugen/wallpaper management enabled).
• A ~/Wallpapers/ directory with one workspace_N folder per workspace (workspace_1, workspace_2, …), each containing image files (jpg, jpeg, png, webp).

Niri window-rule include (for the "show desktop" transition)

The transition controls window opacity by writing to a dedicated niri window-rules file that your config.kdl must include. This file is required even if you plan to keep the transition disabled, so the plugin can manage it safely.

Add to ~/.config/niri/config.kdl:

include "dms/dank-hide.kdl"

The plugin only ever writes/clears that file and reloads niri config; it never touches config.kdl itself. If the file does not exist when the transition is used, the plugin recreates it.

Chrome sync (optional)

Chrome sync runs ~/.local/bin/dank-chrome-theme.sh if present. This is an optional helper: if the script does not exist, the plugin silently skips Chrome sync, so it is safe on machines that don't have it. Install your own script there to customize the behavior.

Obsidian sync (optional)

Obsidian sync runs ~/.local/bin/dank-obsidian-theme.sh if present. The script regenerates the dank-theme CSS snippet in every known Obsidian vault with the theme colors (backgrounds, text, accent for both dark and light modes) and sets accentColor + enables the snippet in appearance.json. Obsidian applies snippet edits live, no restart needed (on the very first run you may need to open Settings → Appearance → CSS snippets once). Same portability rule as Chrome sync: missing script = silent no-op.

Configuration

Settings live in DMS Settings → Plugins → Wallpaper by Workspace:

Setting	Default	Description
Alternar al cambiar de workspace	On	On: random wallpaper per switch. Off: keep the last chosen per workspace
Rotación periódica	Off	Automatically rotate the active workspace's wallpaper
Intervalo de rotación	10 min	Minutes between periodic rotations
Sincronizar color de Chrome	On	Update Chrome toolbar color after regenerating the theme
Sincronizar tema de Obsidian	On	Regenerate the dank-theme snippet in Obsidian vaults after regenerating the theme
Mostrar escritorio al cambiar	On	Lower window opacity during the transition ("show desktop")
Difuminar fondo al ocultar ventanas	On	Add background blur during the transition
Opacidad de las ventanas	50%	Window opacity during the transition (lower = more see-through)

How it works

• On workspace switch (NiriService.focusedWorkspaceIndex), the plugin lists images in ~/Wallpapers/workspace_N and applies an image in fixed or alternate mode.
• The per-workspace "fixed" choice (latch) and the last chosen wallpaper are persisted via the plugin state API, so they survive restarts.
• Changing the wallpaper triggers DMS theme regeneration; the plugin listens for Theme.matugenCompleted to end the transition and run Chrome/Obsidian sync.
• The periodic timer only acts on the active workspace.

Troubleshooting

• No wallpaper applied: make sure the workspace_N folder exists (matching the niri workspace index) and contains images, and that the plugin is enabled.
• Said workspace has no images: check the folder name/number matches the niri workspace index.
• Transition never restores windows: the plugin also has a ~10s safety timeout that always restores window opacity.
• Check plugin status with dms ipc plugin-scan status wallpaperByWorkspace.

License

Distributed under the MIT license.