ACTION corresponds to a sequence of keyboard keys that will be pressed virtually. For example,

map <Up> Hello<Enter>

will type "Hello" with a newline at the end. Simulated keys are pressed in succession as quickly as possible. There is no way to wait or sleep between keys.

ACTION must be a shell command. In:

cmd <Down> say "Good morning"

the /usr/bin/say command will be executed, playing "Good morning" in audible speech.

This map type is useful for running arbitrary code that can’t be expressed by simulating keyboard keys with a map.

Commands are executed with $SHELL -c ACTION. If $SHELL isn’t set, /bin/sh is used instead.

You can think of modes like Vim modes. They enable you to map the same trigger more than once. Let’s look at an example:

cmd <Play> open -a Firefox

mode <Up> {
        map <Play> <Space>
}

Here, the <Play> headphone button will open Firefox. But when the mode is active, pressing <Play> instead simulates the Space key.

Modes are both activated and deactivated by pressing the TRIGGER sequence written after the mode keyword. The trigger functions as a toggle. In our example, pressing <Up> activates the mode. If the mode is active, pressing <Up> will deactivate the mode, causing top-level mappings to become available again.

Any number of maps and commands can be defined inside a mode. These are enclosed by curly braces. Mode mappings should not use the same trigger as the mode’s. Mappings with the same trigger are ignored:

mode <Play> {
        # The following mapping is ignored:
        map <Play> Hello
}

Modes cannot be nested.

Special keys are enclosed in ‘<’ ‘>’ brackets (e.g. <Play>). These are used in map actions to simulate a key press.

Home, End, PageUp, PageDown

CapsLock, NumLock

Tab, Space

BrightnessUp, BrightnessDown, ContrastUp, ContrastDown

Help

Power, Eject

Modifiers can be applied to any key used in map actions. Modifiers can also be chained. Modifiers must be prefixed to the key they’re modifying, both of which are surrounded by ‘<’ ‘>’ brackets.