SPEX

Dynamic wallpaper color palette generator and theming engine.

(pronounced: spex)

Installation · Changelog · CLI · Extraction · Color Roles · spex-convert · Template Engine · Transforms

〰️〰️〰️〰️〰️〰️〰️〰️〰️〰️〰️〰️〰️〰️〰️〰️

Warning

Spex is still under active development and may behave inconsistently with some wallpapers. Palette generation can occasionally produce incorrect colors while the extraction and role-mapping logic is still being improved.

Preview

spex generates terminal palette previews so you can quickly inspect extracted colors before exporting or rendering templates.

Features

• 🎨 High-quality palette extraction from wallpapers
• 🧠 LAB k-means extraction with mediancut fallback
• 🌈 Configurable palette tuning with faithful, balanced, and vivid presets
• 🌗 Dark and light theme modes
• 🧩 Config-driven template engine with loops and transformations
• ⚙️ Workflow automation with template hooks
• 🖥️ Terminal palette preview output
• 📦 Multiple export formats (json, css, terminal)
• 🔁 Companion spex-convert CLI for migrating external templates
• 🧱 Modular and extensible Rust architecture

Installation

Arch Linux (AUR)

Recommended installation method on Arch Linux.

Install with an AUR helper:

yay -S spex-bin

Build from source via AUR:

yay -S spex

Manual Install (Binary)

Download the v1.0.0 release tarball:

curl -L -o spex.tar.gz https://github.com/Grey-007/Spex/releases/download/v1.0.0/spex-linux-x86_64.tar.gz

Extract it:

tar -xvf spex.tar.gz

Install the binaries into your PATH:

sudo install -Dm755 spex /usr/local/bin/spex
sudo install -Dm755 spex-convert /usr/local/bin/spex-convert

Build From Source

cargo build --release
sudo install -Dm755 target/release/spex /usr/local/bin/spex
sudo install -Dm755 target/release/spex-convert /usr/local/bin/spex-convert

Usage

Basic usage:

spex wallpaper.jpg

Custom palette size:

spex wallpaper.jpg --colors 16

Dark theme:

spex wallpaper.jpg --theme dark

Dry run:

spex wallpaper.jpg --dry-run

Force mediancut:

spex wallpaper.jpg --extractor mediancut

Inspect extraction:

spex wallpaper.jpg --debug-extractor --debug-palette

Vivid recovery mode:

spex wallpaper.jpg --vivid

spex-convert

spex-convert is the companion migration tool in this repo. It converts templates from other theming systems into Spex-compatible placeholders so existing configs are easier to move into a Spex workflow.

What it does:

• extracts tokens from template files
• detects common source styles such as pywal, Matugen, and CSS-like variables
• classifies semantic aliases with direct and fuzzy matching
• rewrites recognized tokens into Spex syntax
• reports unknown tokens while leaving unmatched content untouched

It understands token forms such as {token}, {{token}}, ${token}, $token, and nested Matugen braces like {{{{colors.primary.default.hex}}}}, which are normalized into canonical Spex tokens like {{colors.primary.hex}}.

Examples:

spex-convert theme.css
spex-convert theme.css --analyze
spex-convert theme.css --output converted.css

Default behavior writes the converted template to converted_template.spex. --analyze prints detected tokens and suggested mappings without writing a file.

Template System

Templates are configured through config.toml and rendered with generated palette variables.

Directory layout:

~/.config/spex/
    config.toml
    templates/

Template variable examples:

{{background}}
{{primary}}
{{accent}}
{{colors.surface.hex}}

colors.* semantic role tokens are stable and map directly to generated theme roles:

• colors.background -> theme.background
• colors.surface -> theme.surface
• colors.primary -> theme.primary
• colors.secondary -> theme.secondary
• colors.accent -> theme.accent
• colors.accent2 -> theme.accent2
• colors.highlight -> theme.highlight
• colors.text -> theme.text

Role fallback is only used when a requested role is missing:

• accent2 -> accent
• surface -> background
• secondary -> primary

Theme background behavior:

• dark mode anchors the background near black and keeps only a restrained accent tint from the most expressive palette color
• light mode anchors the background near white and keeps a subtle accent tint from the same palette hint
• surface comes from the next palette color closest in theme-relative luminance while still staying perceptually distinct from the background (Delta-E > 8)
• surface_container and surface_high are then stepped away from surface to keep layered backgrounds readable without inverting the theme order
• primary, secondary, accent, and accent2 are chosen from the most saturated palette colors that stay distinct from the background and from each other
• text is chosen from the strongest-contrast endpoint so the final role order stays stable: background -> surface -> accents -> text

Low-saturation wallpaper handling:

• Spex can tune palette behavior with preset, vibrancy_strength, and background_tint_strength in config.toml
• --palette-preset vivid or --vivid pushes dull wallpapers harder toward brighter accents
• the boost raises saturation and contrast while still following the wallpaper's dominant hue family
• grayscale palettes can receive a small hue hint from the wallpaper's dominant color region

For troubleshooting template role resolution, run with:

spex generate wallpaper.jpg --debug-theme

--debug-theme now also prints the final semantic role assignments with:

• LAB values
• luminance
• saturation
• theme-relative depth
• contrast against background
• Delta-E distances between roles

For palette metrics and final role diagnostics, run with:

spex generate wallpaper.jpg --debug-colors

CLI Examples

Preview only:

spex preview wallpaper.jpg

Generate shell completions:

spex completions fish

Diagnostics:

spex doctor

Diagnostics

Use spex doctor to validate your environment before running full template workflows.

It checks:

• config file availability and parse validity
• template directories and template file readability
• template token validity (including colors.* token paths)
• hook command configuration (without executing hooks)
• Spex Color Engine token generation
• template rendering simulation with a mock palette

Example:

spex doctor

Documentation

Detailed docs are available in:

• docs/extraction.md
• docs/color_roles.md
• docs/template_engine.md
• docs/transformations.md
• docs/hooks.md
• docs/cli.md
• docs/spex-convert.md

Contributing

Issues and pull requests are welcome. If you have ideas for improvements, new template targets, or workflow enhancements, feel free to open a discussion.

Credits

Inspired by:

• pywal
• matugen

License

Licensed under the MIT License. See LICENSE.