AI Background Generator for Hyprland

An automatic AI-powered background generator and manager for Hyprland and other wlroots-based compositors. This application runs as a background service, periodically generating new wallpapers using multiple AI backends and cycling through them.

🌟 Features

• Automatic Background Cycling: Changes the wallpaper at a user-defined interval.
• Multiple AI Backends: Supports various image generation providers.
  • Google Gemini: Generate images using Google's Gemini family of models.
  • Stability AI: Generate images using Stable Diffusion models.
  • Local Generation (Experimental): Future support for on-device generation.
• Dynamic Prompt Engineering: Creates unique, high-quality prompts by combining different styles and subjects.
• Smart Installation: A user-friendly install.sh script automates the entire setup.
• Systemd Service: Runs as a systemd user service for seamless integration with your graphical session.
• Flexible Configuration: Easily switch backends, manage API keys, and customize prompts.
• Full-featured CLI: A bg-gen command to control the daemon, list models, and more.

🚀 Installation

1. Clone the Repository:

   git clone https://github.com/your-username/your-repo.git # Replace with your repo URL
   cd background-gen
   

2. Run the Installer:

   bash scripts/install.sh
   

   The script handles everything: dependency checks, creating a Python virtual environment, installing packages, and setting up the systemd service.

3. Reload Your Shell: After installation, you must restart your shell or source your shell's configuration file for the bg-gen command to become available.

   # For bash users
   source ~/.bashrc
   
   # For zsh users
   source ~/.zshrc
   

⚙️ Configuration

The main user configuration file is located at ~/.config/background-gen/config.ini. The installer creates this file for you on the first run.

Selecting the Image Generation Backend

To choose which AI provider to use, edit the [generation] section in your config.ini:

[generation]
# Select the backend to use for generating images.
# Options: placeholder, google_api, stability_api
backend = google_api

API Key Management (Most Important)

You must provide an API key for the selected backend. There are three ways to do this, listed by precedence (method 1 overrides 2, etc.):

1. Environment Variable (Recommended for Services): Set the appropriate variable in your shell's environment. This is the most secure method, especially for a background service.

   export GOOGLE_API_KEY="your-google-api-key"
   export STABILITY_API_KEY="your-stability-api-key"
   

   To make this permanent, add the line to your ~/.bashrc, ~/.zshrc, or ~/.profile.

2. .env File (Recommended for Ease of Use): Create a file named .env inside the configuration directory: ~/.config/background-gen/.env. Add your keys to this file.

   # In ~/.config/background-gen/.env
   GOOGLE_API_KEY="your-google-api-key"
   STABILITY_API_KEY="your-stability-api-key"
   

   The application will automatically load these at startup.

3. Directly in config.ini (Not Recommended): You can paste your key directly into the config.ini file, but this is less secure.

Customizing Prompts

You can customize the prompts used for generation by editing the [prompts] section in config.ini. The generator creates new prompts by randomly combining one line from each of the lists.

[prompts]
base_prompts =
    a futuristic cityscape at night
    a tranquil forest scene
    an epic fantasy landscape

style_keywords =
    photorealistic, 8k, detailed
    vaporwave, retro, nostalgic
    impressionist painting, soft light

artist_keywords =
    in the style of Greg Rutkowski
    by Artgerm
    by Hayao Miyazaki

🛠️ Usage

The application runs as a background systemd service, but you can control it with the bg-gen command-line tool.

Command-Line Interface (bg-gen)

• Force Next Background: Immediately switch to the next wallpaper in the sequence.

  bg-gen --force-next
  

• Generate a New Image: Force the generation of a new image using the configured backend.

  bg-gen --generate-new
  

• List Available Models: See which models are available from your configured API providers.

  bg-gen --list-models
  

• Show Status: Display the current status of the daemon, including the current wallpaper and image count.

  bg-gen --show-info
  

• Stop the Daemon:

  bg-gen --stop
  

• Uninstall the Application:

  bg-gen --uninstall
  

Managing the Service

You can also manage the service directly with systemctl:

# Check the status and see recent logs
systemctl --user status background-gen.service

# Restart the service after making config changes
systemctl --user restart background-gen.service

Hotkeys

You can bind these commands to hotkeys in your hyprland.conf for easy access.

Example:

# In ~/.config/hypr/hyprland.conf
bind = $mainMod, B, exec, bg-gen --force-next
bind = $mainMod SHIFT, B, exec, bg-gen --generate-new

📂 Project Structure

• src/background_gen/: The main Python source code for the application.
• ~/.config/background-gen/: The installed location for the application, configuration (config.ini, .env), and virtual environment.
• ~/Pictures/background-gen/: The default directory where generated images are stored.
  • originals/: Full-resolution generated images.
  • compressed/: Compressed versions used for wallpapers.
• ~/.config/systemd/user/: Where the background-gen.service file is installed.

🗑️ Uninstallation

Run the uninstall command. This will prompt you before deleting files and will remove the application, configuration, and systemd service.

bg-gen --uninstall