-
Notifications
You must be signed in to change notification settings - Fork 31
Configuration File
The configuration file controls the behavior of keyledsd service. It defines effects, and when to enable them. The configuration file is automatically reloaded when keyledsd detects is has changed. If the new configuration contains errors, it is not applied.
Summary:
While reading this page, keep the example configuration file handy!
keyledsd follows the XDG basedir specification. This means that when starting up, keyledsd looks for a configuration file named keyledsd.conf in the following locations:
- Your
$XDG_CONFIG_HOMEdirectory. If not set, it resolves to$HOME/.config/keyledsd.conf. - Each directory defined in
$XDG_CONFIG_DIRS, in order. - Lastly, the
/etc/keyledsd.conffile. This file is shipped in keyleds packages, including example configuration.
The first configuration file found is used. This means putting a configuration file in $HOME/.config/keyledsd.conf overrides the system-wide configuration file.
It is also possible to pass a configuration file path directly: keyledsd -c ./my-keyledsd.conf does what one would expect.
The configuration file uses YAML syntax (see below). It has five sections: global settings, devices, key groups, effects and profiles.
They live at root level an define global service behavior:
-
auto_quit: if yes or true, the service will shutdown when the last supported device is disconnected. Similar to--singlecommand-line option. Defaults to no. -
dbus: if yes or true, the service will register its DBus interface, so scripts can interact with it. Defaults to yes. -
layouts: a list of additional directory paths to look for layout files in. Defaults to empty list.
Optional. They make it possible to give a name to devices. Useful when one wants some effects to apply to some devices but not others.
It is a simple mapping of name → serial entries, for instance:
devices:
left-keyboard: 000123456789
right-keyboard: 000987654321Find out keyboard serials using keyledsctl list or looking at keyledsd's logs.
Specifies global key groups. This is a mapping of name → list-of-keys.
groups:
functions: [ESC, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12]
numpad: [KPDOT, KP0, KP1, KP2, KP3, KP4, KP5, KP6, KP7, KP8, KP9,
NUMLOCK, KPSLASH, KPASTERISK, KPMINUS, KPPLUS, KPENTER]See the detailed key group page for the full explanation with more examples.
An effect is a set of plugins, configured and glued together in a specific order. This section defines all effects, giving them a unique name for use in profiles. For instance:
effects:
nightsky: # effect name
plugins: # begins the list of plugins
- plugin: fill
color: darkblue
- plugin: stars
number: 10
color0: yellow
blackout: # another effect
plugin: # ...and its list of plugins
- plugin: fill
color: blackEffects may also have effect-specific key groups, to avoid clobbering the global key group list. See the key group page for details.
When an effect is active, all its plugins are enabled and contribute to the visual. The final key colors are obtained by compositing the output of all plugins, in order, taking into account transparency information. See the detailed effect documentation for more.
Profiles tell when effects should be activated. They are evaluated every time the environment changes, and effects are enabled and disabled as the result of this evaluation. For instance:
profiles:
__default__:
effect: blackout
video: # profile name
lookup: { class: mpv|vlc } # when to activate it
effect: nightsky # what effect to activate
video-left-keyboard:
devices: [left-keyboard] # restrict profile to those devices
lookup: { class: mpv|vlc } # when to activate it
effects: [nightsky, fancyfx] # what effect to activateEach profile defines a set of lookups that are matched against current environment status. When all its lookups match, the profile becomes candidate for activation. At the end of the evaluation, the last (bottom-most) candidate for activation is selected as active profile. TL;DR: “last matching profile wins”.
The effect(s) selected by the active profile are enabled and start playing. Note that the profile may select either a single effect with singular effect: effect-name or multiple effects with plural effects: [name1, name2, ...]. In the latter case, effects are stacked on top of each other, from left to right. See the effect documentation for details.
Two special profiles can be defined: __default__ profile is activated when no candidate for activation are found in the evaluation. And __overlay__ is always active, its effects being drawn on top of the active profile's effects.
Profiles that define a device list are only considered on matching keyboards. Even special profiles. Lastly, if no profile matches and neither __default__ nor __overlay__ are defined, keyledsd stops refreshing the keyboard.
See the shipped example configuration file.
The configuration file uses YAML1.1 syntax. It can get complex if one wants it to, but for most purposes, it boils down to:
- Indentation matters. All lines at the same indentation level are siblings, belonging to the first less-indented line above. See examples below.
- A mapping (key → value pairs) is defined by simply putting indented
key: valuelines.Short mappings may also use curly brackets:person: name: Antoine surname: Saint-Exupéry
person: {name: Antoine, surname: Saint-Exupéry}. - A list is defined by putting indented items preceded with a dash.
Short lists may also use square brackets:
vegetables: - oranges - carrots
vegetables: [oranges, carrots]. - Anything that is neither a mapping nor a list and contains no special characters is a regular value. In above examples,
Antoine,name,orangesare all regular values. - Values with special characters (colons
:, commas,, pipe|, ampersand&, asterisk*, hash#) must be quoted:"f|o&o:b*a#r".
That's about it, though it's possible to get more complicated should one need to. If you take that path, you should note that:
- Aliases support is partial for now. It works on all literal values and key groups.
- All literals are read as strings. Settings consumed as numbers are converted later on, using decimal notation. Colors are converted later on, using a specific syntax.
- Tags are not supported.