xbindkeys

Related articles
Sxhkd
Xmodmap
Xorg#Automation
xbindkeys
is a program that allows to bind commands to certain keys or key combinations on the keyboard. It works with multimedia keys and is independent of the window manager and desktop environment.
Installation
Install
the
xbindkeys
package.
Configuration
Create a blank
~/.xbindkeysrc
, or you can create a sample file:
Note
This includes some bindings such as
Ctrl+f
, which you may want to edit or remove.
$ xbindkeys -d > ~/.xbindkeysrc
Now you can either edit
~/.xbindkeysrc
to set keybindings, or you can do that with the
#GUI method
.
Tip
xbindkeys
reloads the configuration file if modified.  Send a
HUP
signal to force reloading:
killall -HUP xbindkeys
. When a
HUP
signal is sent to xbindkeys, changes take effect only after moving the mouse, see
xbindkeys(1)
for more information.
Audio control
Here is an example configuration file that binds
Fn
key combos on a laptop to
pactl
commands that adjust audio, such as sound volume and mute status. Note that pound (#) symbols can be used to create comments.
~/.xbindkeysrc
# Increase volume
"pactl set-sink-volume @DEFAULT_SINK@ +1000"
   XF86AudioRaiseVolume

# Decrease volume
"pactl set-sink-volume @DEFAULT_SINK@ -1000"
   XF86AudioLowerVolume

# Mute volume
"pactl set-sink-mute @DEFAULT_SINK@ toggle"
   XF86AudioMute

# Mute microphone
"pactl set-source-mute @DEFAULT_SOURCE@ toggle"
   XF86AudioMicMute
For alternative commands to control volume, see
PulseAudio#Keyboard volume control
or
ALSA#Keyboard volume control
.
Backlight control
Keybindings for backlight control can be defined using the
XF86MonBrightnessUp
and
XF86MonBrightnessDown
keys. See
Backlight#Backlight utilities
for the available backlight control utilities.
GUI method
For graphical configuration
install
the
xbindkeys_config-gtk2
AUR
package and run:
$ xbindkeys_config
Identifying keycodes
To find the keycodes for a particular key, enter the following command:
$ xbindkeys --key
or the following to grab multiple keys:
$ xbindkeys --multikey
A blank window will pop up. Press the key(s) to which you wish to assign a command and
xbindkeys
will output a handy snippet that can be entered into
~/.xbindkeysrc
. For example, while the blank window is open, press
Alt+o
to get the following output (results may vary):
"(Scheme function)"
    m:0x8 + c:32
    Alt + o
The first line represents a command.
The second line contains the state (0x8) and keycode (32) as reported by the tool
xev
.
The third line contains the keysyms associated with the given keycodes.
To use this output, copy either one of the last two lines to
~/.xbindkeysrc
and replace "(Scheme function)" with the command you wish to perform.
To identify mouse buttons,
xev
can be used, see
[1]
.
Tip
If the multikey mode is used, press
q
to quit the window.
Note
xev
is provided within the
xorg-xev
package, see
xev(1)
for more information.
Making changes permanent
Once you are done configuring your keys, edit your
xprofile
or
xinitrc
file (depending on your window manager) and place
xbindkeys
before the line that starts your window manager or DE.
Simulating multimedia keys
The XF86Audio* and other multimedia keys (see
LQWiki:XF86 keyboard symbols
) are pretty-much well-recognized by the major DEs. For keyboards without such keys, you can simulate their effect with other keys
# Decrease volume on pressing Super-minus
"pactl set-sink-volume 0 -1000"
   m:0x50 + c:20
   Mod2+Mod4 + minus
However, to actually call the keys themselves you can use tools like
xdotool
and
xmacro
AUR
. Unfortunately since you would already be holding down some modifier key (Super or Shift, for example), X will see the result as
Super-XF86AudioLowerVolume
which will not do anything useful. Here is a script based on
xmacro
and
xmodmap
from the
xorg-xmodmap
package for doing this
[2]
.
#!/bin/sh
echo 'KeyStrRelease Super_L KeyStrRelease minus' | xmacroplay :0
xmodmap -e 'remove Mod4 = Super_L'
echo 'KeyStrPress XF86AudioLowerVolume KeyStrRelease XF86AudioLowerVolume' | xmacroplay :0
xmodmap -e 'add Mod4 = Super_L'
This works for calling
XF86AudioLowerVolume
once (assuming you are using
Super+minus
), but repeatedly calling it without releasing the
Super
key (like tapping on a volume button) does not work. If you would like it to work that way, add the following line to the bottom of the script.
echo 'KeyStrPress Super_L' | xmacroplay :0
With this modified script, if you press the key combination fast enough your
Super_L
key will remain 'on' till the next time you hit it, which may result in some interesting side-effects. Just tap it again to remove that state, or use the original script if you want things to 'just work' and do not mind not multi-tapping on volume up/down.
These instructions are valid for pretty much any one of the XF86 multimedia keys (important ones would be
XF86AudioRaiseVolume
,
XF86AudioLowerVolume
,
XF86AudioPlay
,
XF86AudioPrev
,
XF86AudioNext
).
Mouse chording
By dedicating one button on the mouse as a "chording" key (much like the
Shift
key on a keyboard), it is possible to use
xbindkeys
to configure your mouse to perform more actions than would otherwise be possible. This requires the use of Scheme rather than the simplified
xbindkeys
syntax.
.xbindkeysrc.scm
(define (define-mouse-chords chord-key . definitions)
  (define (start-mouse-chord)
    (let ((cmd #f))
      (for-each
        (lambda (definition)
          (let ((key (list-ref definition 0)) (binding (list-ref definition 1)))
            (xbindkey-function key (lambda () (set! cmd binding)))))
        definitions)
      (xbindkey-function `(release ,chord-key)
        (lambda ()
          (remove-xbindkey `(release ,chord-key))
          (for-each
            (lambda (definition)
              (let ((key (list-ref definition 0)))
                (remove-xbindkey key)))
            definitions)
          (if cmd
            (begin
              (run-command cmd)
              (set! cmd #f))
          )))))
  (xbindkey-function chord-key start-mouse-chord))
With this function defined, you can now configure some chorded commands:
(define-mouse-chords "b:10"
  (list '(release "b:1") "xdotool click 8")
  (list '(release "b:2") "xdotool click 9")
)
This defines "button 10" as as chording key on your mouse. When button 10 is pressed down, the function will create bindings for the buttons defined inside the block. When button 10 is released, those bindings will be removed. So for example: with button 10 held down, pressing and releasing button 1, and then releasing button 10, will result in a virtual "button 8" (back) event being generated.
Troubleshooting
If, for any reason, a hotkey you
already
set in
~/.xbindkeysrc
does not work, open up a terminal and type the following:
$ xbindkeys -n
By pressing the non-working key, you will be able to see any error
xbindkeys
encounter (e.g: mistyped command/keycode,...).
If the command for a keybind works via the xdotool in command line, but not when activated by the hotkey try adding "+ Release" to the hotkey (especially notable on
GNOME
):
"xdotool key --clearmodifiers XF86AudioPlay"
    Mod2 + F7 + Release
This will make the
F7
key play/pause audio. Where the "xdotool" command would work in commandline, if the "+ Release" is removed it will fail with xbindkeys.
Note
Be aware that setting two or more keyboard layouts with e.g.
setxkbmap -layout ch,dk
results in different button states for the different layouts and
xbindkeys
will not be able to handle that.