CR-2026-03-14: Hyprland Rice Enhancement - DJ Mode & Wallpaper Management

Change Summary

Field Value

Change ID

CR-2026-03-14-HYPRLAND-RICE-DJ

System

modestus-razer (Arch Linux / Hyprland)

Current State

Basic Hyprland config, manual wallpaper setting, Adwaita GTK theme

Target State

Full rice with DJ visualizer, automated wallpaper cycling, Catppuccin theming

Requestor

Evan Rosado

Scheduled

2026-03-14

Risk Level

Low (cosmetic changes, easily reversible)

Context

Personal infrastructure / dotfiles management

Description

What

Complete Hyprland desktop rice including:

  1. Wallpaper Management System

    • Scripts for cycling wallpapers (random, next, prev)

    • Support for S-tier, anime, and general wallpaper folders

    • Integration with swww for smooth transitions

    • Wofi-based wallpaper selector

  2. DJ Mode Audio Visualizer

    • cava audio visualizer with Catppuccin rainbow gradient

    • Multiple visualization modes (single, dual, triple, matrix, ultra)

    • Animated rainbow border effects

    • Window rules for proper positioning

  3. Theme Consistency

    • GTK theme: catppuccin-mocha-mauve

    • Icons: Papirus-Dark

    • btop: Catppuccin Mocha theme

    • All components match Hyprland border colors

Why

  • Improve desktop aesthetics and daily workflow

  • Showcase Linux customization capabilities

  • Educational project for learning Hyprland configuration

  • Friendly competition with family member

Impact

  • No service impact (personal workstation only)

  • Improved visual experience

  • New keybindings for wallpaper and visualizer control

Pre-Change Checklist

Item Command/Check Status

Verify Hyprland version

hyprctl version

[x] v0.54.2

Check swww installed

which swww

[x]

Backup current config

Git version controlled

[x]

Verify GTK themes available

ls /usr/share/themes/ | grep catppuccin

[x]

Implementation Plan

Phase 1: Wallpaper Management Scripts

Created in ~/.config/hypr/scripts/:

  • wallpaper-set.sh - Set wallpaper with swww + optional wallust

  • wallpaper-cycle.sh - Cycle through wallpapers (supports "all" mode)

  • wallpaper-select.sh - Wofi picker for wallpapers

  • wallpaper-fetch.sh - Download from curated GitHub repos

Phase 2: Wallpaper Keybindings

# Wallpaper Controls
bind = $mainMod SHIFT, W, exec, ~/.config/hypr/scripts/wallpaper-cycle.sh all random
bind = $mainMod SHIFT, bracketright, exec, ~/.config/hypr/scripts/wallpaper-cycle.sh all next
bind = $mainMod SHIFT, bracketleft, exec, ~/.config/hypr/scripts/wallpaper-cycle.sh all prev
bind = $mainMod ALT, A, exec, ~/.config/hypr/scripts/wallpaper-cycle.sh ~/Pictures/wallpapers/anime random

Phase 3: DJ Mode Implementation

Created ~/.config/hypr/scripts/dj-mode.sh with modes:

  • toggle - Single bottom visualizer

  • dual - Left + right vertical strips

  • triple - Bottom + both sides

  • matrix - Matrix rain + visualizer

  • ultra - Everything + boosted blur

  • fullscreen - Full screen takeover

Phase 4: cava Configuration

Created ~/.config/cava/config with Catppuccin gradient:

gradient_color_1 = '#89b4fa'  # Blue
gradient_color_2 = '#b4befe'  # Lavender
gradient_color_3 = '#cba6f7'  # Mauve
gradient_color_4 = '#f5c2e7'  # Pink
gradient_color_5 = '#f2cdcd'  # Flamingo
gradient_color_6 = '#fab387'  # Peach
gradient_color_7 = '#f9e2af'  # Yellow
gradient_color_8 = '#a6e3a1'  # Green

Phase 5: Window Rules for Visualizers

# Bottom center visualizer
windowrule = match:class ^(cava-visualizer)$, float on
windowrule = match:class ^(cava-visualizer)$, size 60% 22%
windowrule = match:class ^(cava-visualizer)$, move 20% 76%
windowrule = match:class ^(cava-visualizer)$, pin on

# Left/Right vertical strips for dual mode
windowrule = match:class ^(cava-left)$, size 18% 45%
windowrule = match:class ^(cava-left)$, move 1% 28%

Phase 6: GTK/Icon Theme Application

gsettings set org.gnome.desktop.interface gtk-theme 'catppuccin-mocha-mauve-standard+default'
gsettings set org.gnome.desktop.interface icon-theme 'Papirus-Dark'
gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'

Phase 7: btop Catppuccin Theme

mkdir -p ~/.config/btop/themes
curl -o ~/.config/btop/themes/catppuccin_mocha.theme \
  https://raw.githubusercontent.com/catppuccin/btop/main/themes/catppuccin_mocha.theme

Phase 8: Screen Shaders

Created ~/.config/hypr/shaders/ with GLSL fragment shaders:

  • crt.frag - CRT monitor scanline effect

  • blue-light-filter.frag - Reduce blue light (night mode)

  • vibrance.frag - Enhanced color saturation

  • grayscale.frag - Black and white mode

Toggle script ~/.config/hypr/scripts/shader-toggle.sh cycles through effects.

Phase 9: eww Dashboard

Created eww widget system in ~/.config/eww/:

  • eww.yuck - Widget definitions (clock, stats, music, volume)

  • eww.scss - Catppuccin Mocha styling

Dashboard includes system stats, clock, and media controls.

Phase 10: Animated Wallpapers

Updated wallpaper-fetch.sh with animated option:

  • Uses gallery-dl to download from curated Imgur galleries

  • Sources: Hypr-live-paperlls anime and pixel collections

  • GIFs stored in ~/Pictures/wallpapers/animated/

yay -S gallery-dl
~/.config/hypr/scripts/wallpaper-fetch.sh animated

Post-Change Verification

Check Expected Result Status

Wallpaper cycling

SUPER+SHIFT+W changes wallpaper

[x]

Anime wallpaper mode

SUPER+ALT+A cycles anime folder

[x]

DJ mode toggle

SUPER+J shows/hides cava

[x]

Ultra mode

SUPER+CTRL+J launches full setup

[x]

GTK theme applied

Apps use Catppuccin Mocha

[x]

btop themed

btop shows Catppuccin colors

[x]

No Hyprland errors

hyprctl reload succeeds

[x]

Rollback Plan

All changes are git-versioned in dotfiles-optimus:

cd ~/atelier/_projects/personal/dotfiles-optimus
git log --oneline -5  # Find commit to revert to
git checkout <commit> -- wm/hyprland/.config/hypr/
stow -R hyprland -t ~
hyprctl reload

Keybindings Reference

Wallpaper Controls

Keybinding Action

SUPER + SHIFT + W

Random wallpaper (all except anime)

SUPER + SHIFT + ]

Next wallpaper

SUPER + SHIFT + [

Previous wallpaper

SUPER + ALT + W

Random from S-tier

SUPER + CTRL + W

Wofi wallpaper selector

SUPER + ALT + A

Random anime wallpaper

SUPER + ALT + SHIFT + ]

Next anime

SUPER + ALT + SHIFT + [

Previous anime

DJ Mode Controls

Keybinding Action

SUPER + J

Toggle single visualizer

SUPER + SHIFT + J

Cycle modes (single→dual→triple→matrix→off)

SUPER + CTRL + J

ULTRA MODE (maximum flex)

SUPER + ALT + J

Matrix + visualizer combo

SUPER + SHIFT + D

Fullscreen visualizer

Shader Controls

Keybinding Action

SUPER + SHIFT + S

Cycle shaders (CRT → blue-light → vibrance → grayscale → off)

SUPER + ALT + S

Disable all shaders

Widget Controls

Keybinding Action

SUPER + SHIFT + E

Toggle eww dashboard

SUPER + SHIFT + G

Random animated wallpaper

Git Commits

b9f9dc3 feat(hyprland): Add wallpaper management scripts
a125bb3 fix(hyprland): Wallpaper controls - exclude anime from all, add prev/next
194665d feat(rice): Add DJ mode visualizer + Catppuccin theming
2fdf709 feat(rice): ULTRA DJ MODE - r/unixporn destroyer
8ad5346 fix(hyprland): Remove deprecated nofocus windowrule (removed in 0.53+)

Dependencies Installed

sudo pacman -S cava cmatrix
yay -S eww-git gallery-dl

Lessons Learned

  • Hyprland 0.53+ removed nofocus, stayfocused, noinitialfocus windowrules

  • Window rules use new syntax: windowrule = match:class ^(name)$, rule on

  • swww transitions look best with --transition-type grow

  • cava gradient mode requires 8 colors for smooth rainbow effect

Sign-Off

Role Name Date

Requestor

Evan Rosado

2026-03-14

Approver

Self-approved (personal)

2026-03-14

Implementer

Evan Rosado + Claude

2026-03-14

Related