actkbd

actkbd is a keyboard shortcut daemon that works at the system level. It does so through reading the events directly from the input devices, thus working whether a graphical session is running or not.

Do note that this causes issues if it is expected to be used for user-level shortcuts. actkbd is better used to provide global user-agnostic shortcuts like volume or brightness control.

With NixOS, actkbd can be configured using the services.actkbd configuration options.

Finding key codes

The key codes used by actkbd when binding commands will not match with the key code events xev reports.

Obtaining key codes with xev

While logged into an X session, using nix-shell -p xorg.xev --run "xev -event keyboard" will run xev, with filtering for keyboard events.

In the following example output, the line with the key code event is prefixed with an arrow. The keycode for that particular key is 41 with xev.

 |KeyRelease event, serial 28, synthetic NO, window 0x2a00001,
 |    root 0x526, subw 0x0, time 263244557, (457,417), root:(1561,950),
→|    state 0x10, keycode 41 (keysym 0x66, f), same_screen YES,
 |    XLookupString gives 1 bytes: (66) "f"
 |    XFilterEvent returns: False

Tip

While the previous statement may be true, it has been observed that for some, if not all, key code events, subtracting 8 to the xev key code will give the expected actkbd event.

Obtaining key codes with actkbd

First enable the actkbd service (see below).
To read key codes via actkbd, you need to select the right input event provider from /dev/input/. Each input device generating input events has it's own entry there, enumerated with an number. To find out which one generates the events from the hotkeys, it is viable (if tedious) to run the below command with each available entry, and see which one generates event notifications when pressing the brightness hotkeys:
actkbd -n -s -d /dev/input/event#
Once you discover the right one, it will report key presses like so:
Event: <number>:key
Event: <number>:rel
Those represent the key-press and key-release actions. The number is the key code to use for mapping.