Home

Introduction

WallRizz is a terminal-based tool designed to make wallpaper and theme management simple, customizable, and efficient.

Wallpaper Selection

Choose your wallpaper from a grid or list menu in the terminal, making it easy to find and apply your favorite backgrounds.

1. Grid View:

• Run WallRizz -e to enable grid mode for browsing wallpapers in a fixed-size grid.
• Example:

  WallRizz -e -d ~/Pictures

  This will display wallpapers in a 4x4 grid layout from the specified directory.

2. List View:

• Use the -z or --preview-mode flag to set the mode to list.
• Example:

  WallRizz -z list -d ~/Pictures

  This displays wallpapers in a list format, offering quick navigation.

---

Theme Generation and Application

Automatically generates themes based on your selected wallpaper and applies them to supported applications for a cohesive look.

1. Apply a Light Theme:

• Use the -l or --light-theme flag.
• Example:

  WallRizz -l -d ~/Pictures/wallpapers

  Applies a wallpaper and enables a light theme.

2. Automate Theme Changes:

• Create conditions using JavaScript.
• Example:

  WallRizz -v 3600000 -f "(globalThis.USER_ARGUMENTS ??= {})['enableLightTheme'] = ((h) => h >= 6 && h < 18)(new Date().getHours())"

  Automatically applies a light or dark theme based on the time of day.

---

Online Wallpaper Browsing

Browse wallpapers from popular repositories directly in the terminal and download them to your designated wallpaper directory.

1. Browse and Download:

• Use the -b or --browse flag along with repository URLs.
• Example:

  WallRizz -b -u https://github.com/5hubham5ingh/WallRizz/tree/wallpapers

  Fetches wallpapers from the specified repository.

2. Multiple Repositories:

• Provide multiple URLs separated by ;.
• Example:

  WallRizz -b -u https://github.com/D3Ext/aesthetic-wallpapers/tree/main/images;https://github.com/5hubham5ingh/WallRizz/tree/wallpapers

---

Extensible with Scripts

Write or edit theming scripts for various applications. Quickly create an extension template to streamline the process.

Download pre-written extensions

1. For downloading theme extensions WallRizz -t

2. For wallpaper daemon handler extensions WallRizz -w

Write your own extension script

1. Create a Template:

• Use the --test flag to test new extensions.
• Example:

  WallRizz --test

  Generates a basic extension template, if it does not exists, for customization.

2. Add Custom Scripts:

• Edit the generated script to include specific theming logic and wallpaper application options for your applications and wallpaper daemon, respectively.

See extensions section for more.

---

Finest Level of Control Over Colors and Themes

WallRizz offers unparalleled customization with its built-in ColorJs library and support for custom color generation backends. These tools enable seamless creation of gradients, palettes, and highly refined themes tailored to individual preferences.

Features:

• Generate palettes directly from your wallpapers for cohesive theming.
• Define a custom color extraction back-end using the -c or --color-backend flag to suit your specific needs.

1. Set a Custom Color Back-end:

• Customize color extraction with your preferred tool or command.
• Example:

  WallRizz -c "magick {} -format %c -define histogram:method=kmeans -colors 16 histogram:info:"

  Extracts 16 dominant colors from the wallpaper using ImageMagick.

2. Refine Theme Colors:

• Use the built-in ColorJs library for precise adjustments and fine-tuning in the theme extension scripts. This ensures your themes are both aesthetically pleasing and harmonized with your wallpaper.

These features empower you to have complete control over your application's theme aesthetics.

---

Additional Examples

1. Random Wallpaper Selection:

WallRizz -r -d ~/Pictures

Applies a random wallpaper from the specified directory.

2. Enable Pagination:

WallRizz -e -g 5x5 -d ~/Pictures

Displays wallpapers in a 5x5 grid with pagination.

3. Set Interval for Wallpapers:

WallRizz -v 60000 -d ~/Pictures

Changes the wallpaper every 60 seconds.

4. Disable Notifications:

WallRizz -n -d ~/Pictures

Suppresses desktop notifications for a distraction-free experience.

See Usage for more.

---

Workflow Overview

graph TD
  A[Input: Wallpapers Directory Path] 
  A --> B[Cache Wallpapers using ImageMagick]

  %% Parallel Wallpaper Caching
  B --> C1[Cache Wallpaper 1]
  B --> C2[Cache Wallpaper 2]
  B --> C3[Cache Wallpaper 3]
  C1 --> D1[Cached Wallpaper 1 Ready for Processing]
  C2 --> D2[Cached Wallpaper 2 Ready for Processing]
  C3 --> D3[Cached Wallpaper 3 Ready for Processing]

  %% Parallel Color Extraction
  D1 --> E1[Extract and Cache Colors from Cached Wallpaper 1]
  D2 --> E2[Extract and Cache Colors from Cached Wallpaper 2]
  D3 --> E3[Extract and Cache Colors from Cached Wallpaper 3]
  E1 --> F[Load List of Extension Scripts from ~/.config/WallRizz/themeExtensionScripts/]
  E2 --> F
  E3 --> F

  %% Parallel Theme Configuration Generation
  F --> G[Generate Theme Configurations using getDarkThemeConf and getLightThemeConf with Cached Hex Colors]
  G --> H1[Call Functions from Theme Extension Script 1]
  G --> H2[Call Functions from Theme Extension Script 2]
  G --> H3[Call Functions from Theme Extension Script 3]
  H1 --> I1[Functions Return Theme Configurations for Application 1]
  H2 --> I2[Functions Return Theme Configurations for Application 2]
  H3 --> I3[Functions Return Theme Configurations for Application 3]

  %% Cache and Display Grid
  I1 --> J[Cache All Theme Configurations]
  I2 --> J
  I3 --> J
  J --> K[Display UI with Cached Wallpapers in Terminal]

  %% User Selection
  K --> L[User Interacts with UI and Selects Wallpaper]

  %% Set Wallpaper
  L --> M[Set Wallpaper using setWallpaper Function from ~/.config/WallRizz/]
  M --> N[System's Wallpaper Updated with Selected File Path]

  %% Parallel Theme Application
  L --> O[Apply Themes by Calling setTheme Functions with Corresponding Cached Theme Configuration Paths]
  O --> P1[Call setTheme for Application 1]
  O --> P2[Call setTheme for Application 2]
  O --> P3[Call setTheme for Application 3]
  P1 --> Q1[Theme Applied for Application 1]
  P2 --> Q2[Theme Applied for Application 2]
  P3 --> Q3[Theme Applied for Application 3]

  %% Finish
  N --> R[Wallpaper and Themes Updated]
  Q1 --> R
  Q2 --> R
  Q3 --> R

Loading