4. Extensions

Extensions can be acquired through either of the following two methods:

• Download Pre-written extensions.
• Write your own extensions.

1. Pre-written extensions

Wallpaper daemon handlers

• Download it from here, and put it in ~/.config/WallRizz/.
• Or, run

  WallRizz -w

Theme extension scripts

• Download it from here, and put it in ~/.config/WallRizz/themeExtensionScripts/.
• Or, run

  WallRizz -t

Extension Download UI:

Note: curl and fzf are required to download and filter script from command line.

---

2. User defined extensions

WallRizz's functionality can be extended through user-defined JavaScript ES2023 scripts:

• Run WallRizz --test and select 'Yes' to create an extension template.
• After writing your extension, run WallRizz --test to test it.

Extension Structure

Theme Extension Scripts

Located in ~/.config/WallRizz/themeExtensionScripts/, these scripts are responsible for generating and applying themes. Each script must export the following functions:

• async function setTheme(filepath):
  Receives the file path to the cached theme configuration file and applies the theme using the specified configuration.

• async function getLightThemeConf(colorHexArray)
  and async function getDarkThemeConf(colorHexArray):
  Generate theme configuration files from an array of up to 16 hex color codes, derived (using the default color backend) from the selected wallpaper, and return them as strings. These functions are invoked only when the cached theme configuration file does not exist or has changed.

Example Array:

// Array of up to 16 colors (by default color backend) derived from the wallpaper, ordered by frequency in the wallpaper.
[
  "#1a1a1a", "#2e2e2e", "#424242", "#565656", 
  "#6a6a6a", "#7e7e7e", "#929292", "#a6a6a6", 
  "#bababa", "#cecece", "#e2e2e2", "#f6f6f6",
  "#ff0000", "#ff7f00", "#ffff00"
];

Wallpaper Daemon Handler

A single script located in ~/.config/WallRizz/ must export a setWallpaper function for applying wallpapers.

Example:

export function setWallpaper(wallpaperPath) {
  OS.exec(["hyprctl", "-q", "hyprpaper unload all"]);
  OS.exec(["hyprctl", "-q", `hyprpaper preload ${wallpaperPath}`]);
  OS.exec(["hyprctl", "-q", `hyprpaper wallpaper eDP-1,${wallpaperPath}`]);
}

Global Variables and Methods

QuickJS's OS and STD modules, along with a built-in Color library and several helper methods, are available in the global scope, allowing direct use in extension scripts.

Examples:

// Executing commands asynchronously
const activeWallpaper = await execAsync("hyprctl hyprpaper listactive");

// Using an array for command arguments
const activeWallpaper = await execAsync([
  "hyprctl",
  "hyprpaper",
  "listactive",
]);

Wallpaper Application Example:

export function setWallpaper(wallpaperPath) {
  OS.exec(["hyprctl", "-q", "hyprpaper unload all"]);
  OS.exec(["hyprctl", "-q", `hyprpaper preload ${wallpaperPath}`]);
  OS.exec(["hyprctl", "-q", `hyprpaper wallpaper eDP-1,${wallpaperPath}`]);
}

---