Skip to content

byteowlz/ppr

BranchesTags

Repository files navigation

ppr_banner

ppr - base16 & base24 wallpaper switcher

ppr is a cross-platform CLI tool for creating themed wallpapers from SVG templates using base16/base24 color schemes.

Features

  • Theme Support: Works with base16 and base24 color schemes
  • Color Extraction: Extract color schemes from existing SVG files to create new themes
  • Template Cycling: Cycle through preferred templates with automatic wallpaper setting
  • Custom Resolutions: Generate wallpapers at any resolution
  • Auto-Detection: Automatically detects your display resolution
  • Wallpaper Setting: Cross-platform wallpaper setting (macOS, Linux, Windows)
  • SVG Templates: Use SVG templates with color placeholders
  • Configurable: TOML-based configuration system

Installation

From Source

git clone https://github.com/byteowlz/ppr.git
cd ppr
go build -o ppr .

Binary Releases

Download the latest binary from the releases page.

Quick Start

  1. Initialize ppr:

    ppr init

  2. List available themes:

    ppr list-themes

  3. List available templates:

    ppr list-templates

  4. Generate a wallpaper:

    ppr generate --theme nord --template shapes

  5. Generate and set as wallpaper:

    ppr generate --theme gruvbox-dark --template shapes --set-wallpaper

  6. Cycle through templates:

    ppr cycle nord  # Cycles to next template and sets as wallpaper

  7. Extract colors from SVG:

    ppr extract-colors example/example.svg my-custom-theme

Usage

Commands

ppr init

Initialize ppr configuration and create necessary directories.

ppr init [--force]

ppr list-themes

List all available themes.

ppr list-themes [--details] [--variant dark|light]

ppr list-templates

List all available SVG templates.

ppr list-templates [--details]

ppr generate

Generate a themed wallpaper from an SVG template.

ppr generate --theme THEME --template TEMPLATE [OPTIONS]

Options:

  • --theme, -t: Theme name to apply (required)
  • --template, -s: Path to SVG template file (required)
  • --output, -o: Output directory (optional)
  • --resolution, -r: Output resolution (e.g., 1920x1080)
  • --set-wallpaper, -w: Set generated image as wallpaper
  • --filename, -f: Output filename (optional)

ppr cycle

Cycle through preferred templates and set as wallpaper.

ppr cycle [THEME_NAME]

Options:

  • --set-wallpaper, -w: Set generated image as wallpaper (default: true)
  • --output, -o: Output directory (optional)
  • --filename, -f: Output filename (optional)
  • --resolution, -r: Output resolution (e.g., 1920x1080)
  • --svg: Output SVG file instead of PNG

Note: The cycle command always sets the wallpaper by default, making it perfect for quick theme switching.

ppr extract-colors

Extract color scheme from SVG file and create a new theme.

ppr extract-colors <svg-file> <theme-name>

This command analyzes an SVG file containing color swatches labeled with base00-base0F and creates a new theme file. Perfect for converting visual color palettes into usable themes.

ppr set-wallpaper

Set an existing image as wallpaper.

ppr set-wallpaper IMAGE_PATH

Examples

# List available templates
ppr list-templates

# List templates with details
ppr list-templates --details

# Generate wallpaper with specific resolution
ppr generate --theme tokyo-night-storm --template shapes --resolution 2560x1440

# Generate and immediately set as wallpaper
ppr generate --theme catppuccin-mocha --template shapes --set-wallpaper

# Cycle through templates with Nord theme
ppr cycle nord

# Extract colors from a custom SVG and create new theme
ppr extract-colors my-colors.svg my-custom-theme

# List only dark themes with details
ppr list-themes --details --variant dark

# Generate with custom filename
ppr generate --theme nord --template shapes --filename my-wallpaper.png

Configuration

ppr uses a TOML configuration file located at ~/.config/ppr/config.toml:

themes_path = "/path/to/themes"
templates_path = "/path/to/templates"
output_path = "/path/to/output"
default_theme = "nord"
default_template = "shapes.svg"
default_width = 1920
default_height = 1080
auto_set_wallpaper = false
current_theme = "nord"
current_template = "shapes.svg"
last_output_path = "/path/to/last/generated/image.png"
preferred_templates = ["all"]  # or ["shapes", "horizontal_bar", "vertical_bar"]
on_wallpaper_set = ""  # Custom script to run after setting wallpaper

Custom Scripts

You can configure custom scripts to run automatically after setting a wallpaper with ppr cycle or ppr generate -w. This is useful for integrating with other wallpaper managers like hyprpaper, swaybg, etc.

Note: Custom scripts run regardless of whether ppr's built-in wallpaper setter succeeds or fails, allowing you to use your preferred wallpaper manager.

Example Usage

# For hyprpaper
on_wallpaper_set = "hyprctl hyprpaper wallpaper \",$(cat ~/.cache/current_wallpaper_path.txt)\""

# For swaybg
on_wallpaper_set = "swaybg -i ~/.config/wallpaper/current.png -m fill"

# For uwsm + swaybg (background process)
on_wallpaper_set = "setsid uwsm app -- swaybg -i ~/.config/wallpaper/current.png -m fill >/dev/null 2>&1 &"

# Multiple commands
on_wallpaper_set = "notify-send 'Wallpaper changed' && hyprctl hyprpaper reload"

Troubleshooting

If your script isn't working:

  1. Check the path: Use the same path as your output_path + /current.png
  2. Test manually: Run your script directly in terminal first
  3. Check permissions: Ensure the script commands are executable
  4. TOML syntax: Keep the entire script on one line in quotes
  5. Debug output: ppr will show "Executing custom script:" and success/failure messages

The script runs with /bin/bash -c and has access to your environment variables.

Creating SVG Templates

SVG templates use placeholder colors that get replaced with theme colors:

<rect fill="{{base00}}" />  <!-- Background -->
<circle fill="{{base08}}" /> <!-- Red accent -->
<path stroke="{{base0D}}" /> <!-- Blue accent -->

Base16 Color Placeholders

  • {{base00}} - Default Background
  • {{base01}} - Lighter Background
  • {{base02}} - Selection Background
  • {{base03}} - Comments, Invisibles
  • {{base04}} - Dark Foreground
  • {{base05}} - Default Foreground
  • {{base06}} - Light Foreground
  • {{base07}} - Light Background
  • {{base08}} - Red
  • {{base09}} - Orange
  • {{base0A}} - Yellow
  • {{base0B}} - Green
  • {{base0C}} - Cyan
  • {{base0D}} - Blue
  • {{base0E}} - Purple
  • {{base0F}} - Brown

Base24 Extensions

Base24 themes include additional colors {{base10}} through {{base17}}.

Creating Custom Color Schemes

ppr provides tools to easily create your own color schemes:

Method 1: Extract from Visual SVG

  1. Start with the example: Copy example/example.svg and modify the colors to your liking
  2. Extract the colors: Use ppr extract-colors to create a theme file
  3. Use your theme: Generate wallpapers with your custom color scheme
# Copy and edit the example
cp example/example.svg my-colors.svg
# Edit my-colors.svg with your preferred colors

# Extract the color scheme
ppr extract-colors my-colors.svg my-theme

# Use your new theme
ppr generate --theme my-theme --template shapes --set-wallpaper

Method 2: Use the Color Template

Generate a color reference sheet with any existing theme:

# Generate a color reference using the base16-colors-template
ppr generate --theme nord --template base16-colors-template --filename nord-colors.png

This creates a visual reference showing all 16 colors with their labels, perfect for:

  • Understanding color relationships in a theme
  • Creating color documentation
  • Sharing color palettes visually

Supported SVG Formats for Extraction

The extract-colors command supports various SVG formats:

  • Simple format: Direct fill attributes with <text> labels
  • Complex format: CSS classes with <tspan> text elements
  • Mixed format: Combination of both approaches

The command automatically detects base colors (base00-base0F) from text labels and matches them with corresponding fill colors.

Example Files Included

ppr includes several example files to get you started:

  • example/example.svg: Nord color palette in simple format - perfect for copying and modifying
  • example/dmg_dark.svg: Same Nord colors in complex CSS format - demonstrates compatibility
  • example/base16-colors-template.svg: Template that displays all 16 colors with labels for any theme

Try them out:

# Extract from the simple example
ppr extract-colors example/example.svg my-nord-copy

# Extract from the complex example  
ppr extract-colors example/dmg_dark.svg another-nord-copy

# Generate a color reference sheet
ppr generate --theme catppuccin-mocha --template base16-colors-template --filename mocha-colors.png

Themes

ppr supports themes from the base16 and base24 projects. Place theme YAML files in:

~/.config/ppr/themes/
├── base16/
│   ├── nord.yaml
│   ├── gruvbox-dark.yaml
│   ├── my-custom-theme.yaml  # Your extracted themes
│   └── ...
└── base24/
    ├── catppuccin-mocha.yaml
    └── ...

Theme File Format

Extracted themes follow the standard Base16 YAML format:

system: "base16"
name: "my-theme"
author: "extracted"
variant: "dark"
palette:
  base00: "#2E3440"  # Background
  base01: "#3B4252"  # Lighter Background
  # ... (base02-base0F)
  base0F: "#5E81AC"  # Brown

Template Cycling

The cycle command allows you to easily rotate through your favorite templates:

Configuration

Set your preferred templates in config.toml:

# Cycle through all available templates
preferred_templates = ["all"]

# Or specify a custom list
preferred_templates = ["shapes", "horizontal_bar", "vertical_bar", "shapes_overlap"]

Usage

# Cycle to next template with current theme
ppr cycle

# Cycle with specific theme
ppr cycle nord

# Cycle without setting wallpaper
ppr cycle --set-wallpaper=false

The cycle command:

  • Automatically moves to the next template in your preferred list
  • Sets the wallpaper by default (can be disabled)
  • Remembers the current position for seamless cycling
  • Wraps around to the first template after the last one

Platform Support

Wallpaper Setting

  • macOS: Uses AppleScript
  • Linux: Supports GNOME, KDE, XFCE, i3/sway, and generic setters
  • Windows: Uses PowerShell and Windows API

Resolution Detection

  • macOS: system_profiler
  • Linux: xrandr with xdpyinfo fallback
  • Windows: wmic

Development

Project Structure

ppr/
├── cmd/                 # CLI commands
│   ├── extract-colors.go  # Color extraction from SVG
│   ├── cycle.go           # Template cycling
│   └── ...
├── pkg/
│   ├── config/         # Configuration management
│   ├── theme/          # Theme parsing and management
│   ├── svg/            # SVG template processing
│   ├── image/          # PNG generation
│   ├── resolution/     # Display resolution detection
│   └── wallpaper/      # Cross-platform wallpaper setting
├── example/            # Example SVG files for color extraction
│   ├── example.svg     # Nord color palette example
│   ├── dmg_dark.svg    # Complex SVG format example
│   └── base16-colors-template.svg  # Color reference template
├── pkg/templates/      # Built-in SVG templates
└── themes/            # Base16/Base24 theme files

Building

go build -o ppr .

Testing

go test ./...

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

  • tinty this project gave me the idea for ppr
  • Base16 project for the color scheme specification
  • Base24 project for extended color schemes
  • oksvg for SVG rendering
  • Cobra for CLI framework

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 6

Release 1.2.0 Latest
Dec 19, 2025
+ 5 releases

Packages

 
 
 

Contributors

Languages