Matugen Integration

Matugen Integration

Language: English · 简体中文

Matugen generates a Material You color palette from a single wallpaper image. Seekey can pick up those colors at startup by referencing them in seekey.ini.

Generate colors.json

Matugen does not create Seekey's JSON file unless a template asks for it. Create ~/.config/matugen/templates/seekey-colors.json:

{
  "colors": {
    "surface": "{{colors.surface.default.hex}}",
    "on_surface": "{{colors.on_surface.default.hex}}",
    "outline": "{{colors.outline.default.hex}}",
    "outline_variant": "{{colors.outline_variant.default.hex}}"
  }
}

Register it in ~/.config/matugen/config.toml. Replace /home/you with the real home directory; absolute paths avoid differences in path expansion:

[config]

[templates.seekey]
input_path = '/home/you/.config/matugen/templates/seekey-colors.json'
output_path = '/home/you/.cache/matugen/colors.json'

Generate the palette from a wallpaper:

matugen image /path/to/wallpaper.jpg --mode dark --source-color-index 0

Usage

When colors.json is available, choose Use Matugen colors from the GUI root menu. The same preset is available as matugen in the GUI/TUI theme picker and with --theme matugen.

The preset is equivalent to referencing Matugen roles with @matugen:<role> in the color fields:

[style]
foreground=@matugen:on_surface
background=@matugen:surface@0.86
border-color=@matugen:outline
placeholder-foreground=@matugen:on_surface@0.74

The @matugen:<role> syntax is resolved to the hex value from matugen's colors.json. The optional @<float> suffix wraps the result in alpha(<hex>, <float>):

@matugen:surface         → #1a1a1a
@matugen:surface@0.86    → alpha(#1a1a1a, 0.86)
@matugen:missing_key     → static theme fallback before rendering

An unknown role is left unresolved by the parser. Before rendering, Seekey replaces unresolved color references with the active theme's static fallback, so malformed or incomplete palettes cannot produce invalid GTK CSS.

GUI/TUI saves preserve the original @matugen: references rather than writing the currently resolved hex values. This remains true if colors.json changes while an editor is open or the configuration is saved to a new path. A color changed manually in the editor is intentionally saved as a static override.

Where seekey looks for colors.json

Resolution order (first match wins):

1. --matugen <path> on the command line
2. $MATUGEN_COLORS environment variable
3. $XDG_CACHE_HOME/matugen/colors.json (matugen's default)
4. ~/.cache/matugen/colors.json (fallback)

The explicit CLI path is also forwarded to GUI/TUI previews and to an overlay started with Start key overlay in the GUI.

Reload after a wallpaper change

Seekey does not auto-watch the JSON. After running matugen on a new wallpaper, restart seekey to apply the new palette:

pkill seekey && seekey &

If the JSON can't be loaded

If the implicit default file is missing or invalid, Seekey prints one warning to stderr and uses its static default colors. An explicit --matugen path is strict and causes startup to fail when it cannot be loaded. The integration is fully optional — Seekey runs without Matugen installed.