DOCSEARCHbyAlgolia
Submit Docs

aether

repository·main·Indexed 20 days ago

https://github.com/bjarneo/aether

A visual theming application for Linux desktops and Omarchy that extracts cohesive color palettes from wallpapers to apply across applications such as Hyprland, Waybar, Neovim, and VS Code. It includes a headless CLI for automation, QML widgets for Quickshell, and integration with Wallhaven.cc for wallpaper discovery.

Tokens
49.8K
Snippets
188
Records
255
Agent score
67%

What's inside aether

  1. Base16 color mapping and extended colors

    main

    Aether maps Base16 semantic colors to ANSI terminal colors and derives several extended UI colors automatically.

    ANSI Color Mapping

    ANSI ColorBase16 Source
    0 (Black)base00
    1 (Red)base08
    2 (Green)base0B
    3 (Yellow)base0A
    4 (Blue)base0D
    5 (Magenta)base0E
    6 (Cyan)base0C
    7 (White)base05
    8 (Bright Black)base03
    9 (Bright Red)base08
    10 (Bright Green)base0B
    11 (Bright Yellow)base0A
    12 (Bright Blue)base0D
    13 (Bright Magenta)base0E
    14 (Bright Cyan)base0C
    15 (Bright White)base07

    Derived Extended Colors

    Upon import, Aether derives the following extended colors, which can be manually adjusted in the Extended Colors section of the GUI:

    • accent: derived from color4 (Blue)
    • cursor: derived from color7 (White / Default Foreground)
    • selection_foreground: derived from color0 (Black/Background)
    • selection_background: derived from color7 (White / Default Foreground)

  2. Manage color extraction caching

    main

    Extracted palettes are cached at ~/.cache/aether/color-cache/ to allow for instant re-extraction of unchanged images.

    • Cache Key: MD5(path + mtime + mode)
    • Bypassing Cache: Editing a wallpaper within the Wallpaper Editor will bypass the cache to ensure fresh extraction.

  3. What are Blueprints in Aether

    main
    Blueprints are saved theme configurations that allow you to restore specific visual setups at any time. A blueprint captures a complete snapshot of your theme, including the color palette, wallpaper, color adjustments, and application-specific overrides.

  4. Control Aether via Remote Control (IPC)

    main

    Aether can be controlled from a terminal, shell script, or AI assistant using a Unix domain socket. When the Aether GUI is running, it listens on ~/.config/aether/aether.sock. CLI subcommands connect to this socket to send commands and receive real-time state updates. This allows you to manipulate the running editor's palette, sliders, and wallpaper preview instantly.

    # Example: Load a wallpaper and extract colors into the running editor
aether extract ~/Wallpapers/forest.jpg

# Example: Adjust the palette sliders in real time
aether adjust --vibrance 20 --contrast 10

# Example: Apply the current theme to the system
aether apply

  5. Understand Aether's standalone theme output

    main

    When running Aether on non-Omarchy Linux or macOS systems, clicking "Apply Theme" generates theme files locally but does not automatically apply them system-wide.

    Output Locations:

    • Linux: ~/.config/aether/theme/
    • macOS: ~/Library/Application Support/aether/theme/

    Directory Structure (~/.config/aether/theme/):

    • backgrounds/: Contains the wallpaper.jpg copy.
    • hyprland.conf: Hyprland color configuration.
    • kitty.conf: Kitty terminal theme.
    • waybar.css: Waybar stylesheet.
    • gtk.css: GTK theme (if enabled).
    • colors.toml: The palette source used by the Aether UI.
    • neovim.lua: Neovim colorscheme (if enabled).
    • vscode.json: VSCode color theme (if enabled).
    • aether.zed.json: Zed editor theme (if enabled).

  6. Understanding the Svelte + TS + Vite template structure

    main

    This project uses a Svelte + TypeScript + Vite template designed for a lightweight developer experience.

    Key architectural decisions include:

    • Routing: Uses its own routing solution rather than SvelteKit's file-based routing.
    • Type Definitions: Uses global.d.ts with triple-slash references instead of compilerOptions.types in tsconfig.json. This ensures svelte and vite/client types are added without restricting the TypeScript compiler from seeing other types in the workspace.
    • JavaScript Interop: allowJs is enabled in the TypeScript configuration to allow for mixed JavaScript/TypeScript codebases and to ensure better typechecking for existing .js files and JavaScript syntax within .svelte files.
    • Migration Path: The project structure is designed to be similar to SvelteKit to facilitate easy migration if you require SvelteKit's extended capabilities later.

  7. Remote Control via IPC

    main

    When the Aether GUI is running, you can control the editor in real time using bare subcommands (without the -- prefix). These commands communicate via a Unix domain socket.

    Available Remote Commands:

    • aether status: Show editor state.
    • aether extract [path]: Load a wallpaper into the editor.
    • aether set-color [index] [hex]: Change a specific palette color.
    • aether adjust [flag] [value]: Move sidebar sliders (e.g., aether adjust --vibrance 20).
    • aether set-mode [mode]: Change extraction mode.
    • aether toggle-light-mode: Flip between light and dark modes.
    • aether apply: Apply the current theme.
    • aether load-blueprint [name]: Load a blueprint into the editor.
    • aether apply-blueprint [name]: Apply a blueprint directly.
    • aether set-wallpaper [path]: Set the wallpaper path.

    All commands support the --json flag for machine-readable output.

  8. How light and dark modes affect color anchors

    main

    Toggling between light and dark modes swaps the color anchors for the background and brightest colors:

    • Dark mode: color0 is the darkest color, color15 is the lightest color.
    • Light mode: color0 is the lightest color, color15 is the darkest color.

  9. Wallpaper Editor Preview Features

    main

    The editor includes several features for managing the preview experience:

    • Real-time preview: Changes are visible immediately as you adjust sliders.
    • Click and hold: Temporarily view the original, unedited image.
    • Debounced updates: Updates are debounced by 75ms to ensure smooth performance during adjustments.

  10. Understand the Aether file system layout

    main
    Aether follows the XDG Base Directory Specification, organizing files into three primary locations: ~/.config/aether/ for settings and templates, ~/.cache/aether/ for temporary files, and ~/.local/share/aether/ for permanent assets like downloaded wallpapers.

  11. Understand the Aether color extraction algorithm

    main

    Aether uses a pure Go median-cut algorithm to extract 16 ANSI-compatible colors from any wallpaper. The process follows these steps:

    1. Image Sampling: The image is scaled to 300x300 (preserving aspect ratio) using bilinear interpolation, and pixels are sampled.
    2. Median-Cut Quantization: Sampled pixels are processed via a median-cut algorithm that recursively splits the color space along its longest axis to identify dominant color clusters.
    3. Palette Mode: Dominant colors are processed through a generator to define the color scheme.
    4. ANSI Color Mapping: Colors are mapped to a 16-color ANSI palette (indices 0-15).
    5. Readability Normalization: Colors are adjusted to ensure they remain readable against the background.

  12. How light/dark mode precedence works in Aether

    main

    Aether determines whether to use light or dark mode based on a specific hierarchy of settings:

    1. URL Parameter: The mode=light|dark parameter in an aether:// link has the highest priority.
    2. colors.toml definition: If no URL parameter is set, Aether looks for the mode or light_mode field within the colors.toml file itself.
      • mode = "light" or mode = "dark"
      • light_mode = true (for light) or false (for dark)
    3. Current Setting: If neither of the above is specified, Aether falls back to the user's current active setting.