Needs Expansion
This article is incomplete, and needs to be expanded. More info...


Content Cleanup Required
This article should be cleaned-up to follow the content standards in the Wiki Guide. More info...

#title Multimedia Keys

Keyboard Shortcuts Editor

In Ubuntu 5.10 (Breezy Badger), Ubuntu 5.04 (Hoary Hedgehog) and later Ubuntu versions, please go to System menu -> Preferences -> Keyboard Shortcuts to find the keyboard shortcut editor. Many of the common multimedia and control keys should be predefined, and if they are not you should be able to assign functions to them through Keyboard Shortcuts easily.

If after assigning as described above, your VolumeUp/VolumeDown/Mute keys seem to work (i.e. you see a popup window with a slider in the middle of the screen that reacts on those key presses), but the playback volume actually remains unchanged, you may also have to setup what mixer tracks (channels) these keys should be bound to. Refer to this section below.

For Kubuntu, see KDEMultimediaKeys. For Xubuntu, see XfceMultimediaKeys.

Please note that if you are using this guide with laptops that have a button to switch off bluetooth/wireless, you must not assign them anything in order for these switches to work. You may also need acerhk if xev does not recognize you keys.

The recommended approach

The easiest way to configure you multimedia keys is to use keyTouch. KeyTouch is the first and only program of its kind that works perfectly together with recent kernels (2.6.24+). If your keyboard is not supported yet, you can easily get it supported. You can do this by using keytouch-editor (documentation: http://keytouch.sourceforge.net/keytouch_editor/).

You can install keyTouch on Ubuntu Maverick 10.10 with

  • sudo apt-get install keytouch keytouch-editor

You can find keyTouch (and keytouch-editor) in System->Preferences->Keytouch (Editor)

You should first run keyTouch Editor and after you finish the configuration file for you keyboard make sure you share it with other users (upload) when the programs asks.

Another autosetup program found at http://lineak.sourceforge.net/

Failing that, see below.

Quick recipe

  1. See if your key works with gnome-keybinding-properties, it is under the menu: Desktop/Preferences/Keyboard Shortcuts. If it does not work:
  2. Go to System Log Viewer and press your multimedia keys one by one.

  3. Look at the output in kern.log or syslog to discover which scancodes are generated, you should see something like this:

            atkbd.c: Unknown key pressed (translated set 2, code 0x9e on isa0060/serio0).
            atkbd.c: Use 'setkeycodes e01e <keycode>' to make it known.

    you should find the same information with:

  4. Use setkeycodes to set your keycodes as suggested. (but first use dumpkeys to see which keycodes are free to use).
  5. Put those commands in /etc/init.d/bootmisc.sh or /etc/rc.local.

  6. Open an X terminal:

            xmodmap -pke > xmodmap.conf

    Then edit this file adding the missing keysyms to the right keycodes (use xev to see the keycodes, read the file /usr/lib/X11/XKeysymDB to see which keysyms are available).

  7. From the same terminal:

            sudo cp xmodmap.conf /etc 
            cd /etc/gdm/PostLogin 
            sudo cp Default.sample Default

    then open the file /etc/X11/gdm/PostLogin/Default with your editor of choice and add this line to it:

            xmodmap /etc/xmodmap.conf
  8. Use gnome keybindings or metacity keybindings to bind actions to your fresh configured keys.

In-depth instructions

IconsPage/note.png A little background note: When you hit a key on your keyboard, the linux kernel generates a raw scancode for it (if it is assigned). Each scancode can be mapped to a keycode. This is at kernel level. X has a (quasi) total independent way of mapping keys: X reads the kernel keycode table at startup, then maps the keycode to its independent keycode table (it is the same as the kernel keycodes but different :)). Then each keycode can be mapped to a keysym, i.e. a string which represent a key or suggest an action. Thus to have our keys fully functional, they need a kernel scancode/keycode plus a X keycode/keysym. It may seem weird, but X developers have their reason to keep a separate keyboard mapping from the kernel. It is not difficult at all, just a quite tedious procedure.

  1. Use gnome-keybinding-properties:
    • Try to see if your key works with gnome-keybinding-properties, it is under the menu: Desktop/Preferences/Keyboard Shortcuts. If it does not work, or if gnome-keybinding-properties does not have a nice default action for your key, you have to read the whole howto.
  2. Assigning kernel keycodes:
    • We are trying to see which keys have already a kernel scancode/keycode and which do not.
    • Go to a real console by pressing <ctrl><alt>F1.

    • Now if you press your multimedia keys one by one, you should see an output message like this:

              atkbd.c: Unknown key pressed (translated set 2, code 0x9e on isa0060/serio0).
              atkbd.c: Use 'setkeycodes e01e <keycode>' to make it known.
    • The same informations can be found typing:

    • This is all you need, but before assigning the missing keycode, you need to check which keycodes are available, to avoid conflicts. Type:

              sudo dumpkeys | grep ^keycode
    • The command returns a list of used scancodes. Just pick the ones without an unassigned keycode (usually from 120 to 255).
    • Now you know:
      • which keys have missing keycodes
      • how to map the missing scancode/keycode to make it known
      • which keycodes are available to use
    • So it is time to actually set up these codes, type:

              setkeycodes e01e 120
      where e01e is the scancode suggested in dmesg, and 120 is a free keycode you have to choose.
    • Repeat this passage for all your keys which do not generate a scancode/keycode.
    • If you want these commands executed at system startup (you want it), add all those setkeycodes statements at the end of the file /etc/init.d/bootmisc.sh, or before the exit 0 in /etc/rc.local.

      Note that though the startup methods with bootmisc.sh or rc.local may still be supported, they are deprecated. Now the preferred method would be to use an Upstart job. To do so, as root create /etc/init/something.conf (e.g. kb-keys-customize.conf) with content like this:

      # kb-keys-customize
      # Map key codes to the scan codes emitted by Fn-F4, Fn-F5, Fn-F12
      description "Map Fn-F4, Fn-F5 and Fn-F12 kernel scancodes to kernel keycodes"
      start on local-filesystems
          setkeycodes e017 128 e016 129 e018 130
      end script
    • Now that you have all your kernel scancodes well generated, move on to:
  3. Assigning X keysyms
    • This time you can stay under X Wink ;)

    • X keysyms are a sort of descriptive string like: XF86AudioMedia, XF86WWW etc. but we can not use random names. A list of X keysyms can be found in the files /usr/lib/X11/XKeysymDB or /usr/share/X11/XKeysymDB

    • We are going to set up these keys. Open a terminal and type:

    • Then press a multimedia key. If you are lucky it already has a keysym boundto it, so the output of xev for that key will be something like this:

              KeyRelease event, serial 28, synthetic NO, window 0x3200001,
              root 0xb7, subw 0x0, time 137010761, (693,138), root:(705,256),
              state 0x10, keycode 136 (keysym 0x1008ff27, XF86Forward), same_screen YES,
              XLookupString gives 0 bytes:
    • The third row is the one of interest: it says that you have a keycode for that key (136) as well as keysym (XF86Forward). If you have a keysym then you can use that string to represent your key and use gnome keybindings or metacity keybindings to bind the relevant action to it. (See below).
    • But probably, you will find that the key does not have any keysym assigned to it, like this:

              KeyRelease event, serial 28, synthetic NO, window 0x3200001,
              root 0xb7, subw 0x0, time 137355697, (401,146), root:(413,264),
              state 0x10, keycode 136 (keysym 0x0, NoSymbol), same_screen YES,
              XLookupString gives 0 bytes:
    • In this case you have to assign your keysym to the relevant keycode (136) (it does not match the kernel keycode for that keys, but it does not matter, it is by design). This is done with xmodmap.
    • First, create a file with your current X keyboard map, in a terminal type:

              xmodmap -pke > xmodmap.conf
    • Then you are going to add all the missing keysyms to this file: use xev to see which keycode to use, look in the /usr/lib/X11/XKeysymDB or /usr/share/X11/XKeysymDB to find keysym names, open the xmodmap.conf file and fill in the missing keysym using a name which makes sense (i.e. if you have a button with a calculator printed on it, use XF86Calculator as keysym).

    • Repeat this passage for all your multimedia keys.
    • When finished, you can apply the changes with:

              xmodmap xmodmap.conf
    • Now you want to load your new xmodmap.conf when X starts. I have found that the better way is to put the command in the PostLogin script of gdm. (if you use gdm, of course) Type:

              sudo cp xmodmap.conf /etc/xmodmap.conf 
              cd /etc/gdm/PostLogin 
              sudo cp Default.sample Default
    • Now open the Default file with your favourite editor and at the end add this line:

              xmodmap /etc/xmodmap.conf
    • This way you should have all your scancodes/keycodes/keysyms assigned at system and X startup.
    • With Ubuntu 5.04 (Hoary Hedgehog), it seems that GNOME uses xkb and overwrites these changes. Instead, you can copy your xmodmap.conf file into ~/.xmodmap.

    • Now you can make something useful with them like:
  4. Using gnome keybindings or metacity to bind commands to keys
    • First, try to bind keys with gnome-keybinding-properties: it is quicker and it has some nice default action, so launch it from the terminal or from the menu.
    • The utility is self-explanatory, but probabily you will find that some actions do not work (like sleep for example), they do the wrong thing, or there is no suitable action at all for your key.
    • You can address those problems using metacity to bind keys to commands which is a lot more flexible. Open a terminal and type:

      or launch it from the menu under Applications/System Tools/Configuration Editor.
    • Go under apps/metacity or /apps/gnome_settings_daemon/keybindings in gconf-editor. You will see 2 rows (among others): global_keybindings and keybinding_commands.

    • If you click on global_keybindings, on the right pane you will find some entry for commands, like: run_command_1, run_command_2, etc. These have to be filled up with the relevant keysym for your key (like: XF86Play, XF86MyComputer, etc. use xev to see).

    • Then you can assign the matching command (or script) on the other row, under keybinding_commands. You have a lot of useful commands at your disposal like:totem --fullscreen or rhythmbox --next etc.

    • Use the command line help of those applications to discover which parameters are available, (e.g. totem --help or rhythmbox --help etc.) For firefox, take a look here: http://www.mozilla.org/unix/remote.html

  5. Additional hints
    • The actions you want to execute after a key press are limited only by your imagination: bash provides a very powerful scripting language and with hundreds of useful programs out there, there is virtually no limit.
    • For example an app you may find useful is xmacro (sudo apt-get install xmacro): it lets you play a mouse or a keyboard macro with a command. I use it to bind my Forward and Back multimedia keys to <Alt>Right and <Alt>Left respectively: this way I can control forward and back in epiphany which does not provide a command line option for this task. (it works with every app which takes <Alt>Right and <Alt>Left shortcuts). This is my xmacro script:

      case "$1" in
      sleep .3
      echo -e "KeyStrPress Alt_L \n
              KeyStrPress Right \n
              KeyStrRelease Right \n
              KeyStrRelease Alt_L" | xmacroplay :0 ;;
      sleep .3
      echo "KeyStrPress Alt_L \n
              KeyStrPress Left \n
              KeyStrRelease Left \n
              KeyStrRelease Alt_L" | xmacroplay :0  ;;
      exit 0
    • Another hint is that if you have a sleep key, and it does not work with gnome-keybinding-properties, you can use it at least to shut off your monitor. Just assign it to the command:

              xset dpms force off
      with metacity.
    • If you have a scroll wheel on your keyboard, you can even assign a keybinding to the button under the wheel. Assign it to the "Return" keysym, it will act like a return key.\

Assigning mixer tracks to multimedia keys

This UI can be found in the System -> Preferences -> Sound dialog. On the Devices page of this dialog, select the desired device and mixer tracks in the Default Mixer Tracks section. The corresponding GConf keys for these settings are /desktop/gnome/sound/default_mixer_device and /desktop/gnome/sound/default_mixer_tracks.

Those who are interested in details, can take a look at the function acme_volume_gstreamer_open() in acme-volume-gstreamer.c which defines the logic used to select mixer tracks.

MultimediaKeys (last edited 2014-05-05 20:39:56 by john.hupp)