Multimedia Keys

Most modern keyboards are equipped with a number of multimedia keys. This article explains what needs to be done in order to use those keys.

Determine the keycodes
Whenever a key is pressed on the keyboard, the kernel generates a raw scancode, which can be mapped to a keycode. X does this slightly differently and reads the kernel keycode table at startup, then maps the keycode to its own keycode table. Each keycode can be mapped to a keysym, which is a string that represents a key.

There are several applications that show the keycodes.

xev
Install the xev program:

And run it in an X terminal.

Pressing keys on the keyboard will cause their keycodes and other information to printed in the xev window. The keycodes relating to individual keys can be discovered in this way. The output of xev will look similar to this: Output of xev

The "keycode" value is what is relevant. In this example it is "160." Make note of each keycode value in respect to each extended key.

The following script can help find the keycodes in the output of xev:

Run this instead of plain xev. Press all multimedia keys in order, then close the xev window. The filtered output appears only after closing the window, for example: Output of xev after closing window

Most likely, as in this example, the first line in the output does NOT correspond to a multimedia key (it is the keycode value for the Enter key).

A single key can be identified without ending xev by:

If pressing each key produces output from xev then jump ahead to Setting up xmodmap. If pressing a key doesn't do anything at all (i.e., xev produces no output), the raw scan code will need to be found.

showkey
You can also switch to console and run

to see the scan codes, or

to see the key codes.

Using KeyTouch
KeyTouch provides an all-in-one solution for multimedia keyboards.

Start it under X and select the keyboard you have. After that, you can use it to connect functions or programs to your special keys. You should not need an xmodmap.

If your keyboard is not in the list, emerge keytouch-editor (which is masked by keyword at the time of this writing).

The official manual is available at http://keytouch.sourceforge.net/. Basically you just hit each key and assign a name. Don't forget to send the file to the keytouch project (you will be asked for that when saving the file) to help others. The manual can help you solve problems such as the following error from dmesg: keyboard.c: can't emulate rawmode for keycode XXX

lineakd
Another simple way to bring your multimedia keys to life is to use "lineakd". LinEAK is available via portage (see http://lineak.sourceforge.net for details).

Multiple application control
If you like to control more than one application you will need a command wrapper like ReMoot. ReMoot can control audacious, Rhythmbox, Amarok, Quod Libet, xine, kaffeine and some more. The command 'remoot play' will control the active application multimedia application and therefore you don't have to asign one key to one application. This is very useful together with LinEAK or Keytouch

Finding raw scan codes - PS/2 keyboards
If the above methods didn't recognise your keys and your keyboard is connected via the PS/2 connector (not USB), run the following command in an X terminal:

atkbd.c: Unknown key released (translated set 2, code 0x96 on isa0060/serio0). atkbd.c: Use 'setkeycodes e016 ' to make it known.

This means that the kernel doesn't have keycodes mapped to your keyboard's scancodes.

Mapping raw scan codes to key codes
You will have to add one line to a *.start file in for each missing key. For example:

Don't forget to make the file executable:

Where the first number (e008) is the raw scan code (what you see in dmesg, or get from getkeycodes) and the second number (136) is an unused keycode in your kernel. In general you can find a good keycode by taking the last 2 digits of this first number, converting it from hex (base-16) to decimal (base-10) and adding 128.

Here is a simple bash script that can do the conversion for you. Just press all of your multimedia keys and run this script afterwards. It will parse the output of dmesg for unknown keys and give you the lines you should add to.

This will set up the proper scancode - keycode mapping every boot. To set them up without rebooting, run the following as root:

or

After you have the proper mappings set up, restart X and try running xev again to ensure that a keycode is displayed for each multimedia key you want to use.

Finding raw scan codes - USB keyboards
atkbd.c is not used for USB keyboards, and if your kernel is configured to use full HID support you will not see any kernel messages. Instead you will need to run a user-mode program called getscancodes to read the key codes from one of the devices, as described here.

For example by this method it is possible to find out that the codes for the zoom slider on a Microsoft Natural Ergonomic Keyboard 4000 are 0x1a2 and 0x1a3. Check the Microsoft Natural Ergonomic Keyboard 4000 article for more details.

Setting up xmodmap
Once all the multimedia keys are being recognised by xev, they need to be mapped to keysyms. Create a file called in your $HOME directory.

A list of possible keysyms can be found in (!this file does not exist anymore). The following is a list of the more commonly used keysyms as found in XKeysymDB.

All you have to do now is to call xmodmap whenever your X session starts, if this doesn't already happen automatically (it should.) Usually a good place to do this is your file.

Alternatively, you can set this up in this way:

Remember to substitute $HOME for the full path of your home directory.

GDM setup If you are using GDM you can use the file as a system wide Xmodmap. You can also change the location to another Xmodmap file if you wish. Simply change sysmodmap=/etc/X11/Xmodmap in the file to whatever you would like.

KDM setup Under KDM and KDE, the proper place to load file is.

Do not forget to run "chmod +x ~/.kde/share/config/kdm/Xsession"

xfce4 setup If you are using xfce4-sessions, then you just need to place the .Xmodmap file to ${HOME}/.Xmodmap.

Disabling auto-repeat
You may find that your keyboard has autorepeat enabled for the multimedia keys, which has the undesirable effect of the "next track" button sometimes skipping ahead by too many songs or the "play/pause" button pausing and then resuming immediately, if you accidentally hold the button down for a fraction too long.

Rather than altering your whole keyboard's auto-repeat timing to fix this, you can disable auto-repeat completely for specific keys (or enable it, if you have buttons to control the volume and you'd like to be able to hold these down instead of pressing them repeatedly to adjust the volume.) This can be done by running the xset command at startup (see above for the best place to put the commands, here is being used.)

Assigning keys to special functions
Now that your multimedia keys have a keysym mapping, you can bind them to whatever function you want or your window manager allows you to. Note that some programs natively support hotkeys (especially media players) so it is more efficient (and lower latency) to use this mechanism where possible, as it doesn't rely on some other program executing a command to perform the action (see below for a list of known programs with built in hotkey support.)

Native hotkey support
These programs support hotkeys without window manager help, so they're much more responsive as a command doesn't have to be launched every time a key is pressed.

Audacious
Since Audacious version 1.4 the hotkey plugin is available in the package audacious-plugins. To use the plugin go to the Audacious preferences, under Plugins, General, enable the Global Hotkey plugin and configure it by selecting the different commands and pressing the appropriate key.

Non window manager specific - xbindkeys
If your window manager doesn't have a facility for keyboard shortcuts, or indeed if you want to switch between multiple window managers/desktop environments and keep the same keyboard shortcuts throughout, then xbindkeys may be the solution for you.

To install, a simple:

After installation you must edit the config file. If you don't have the file (you won't), you'll get it by running xbindkeys and reading). The file is well commented with examples. To use the key XF86WWW to open your webbrowser (Firefox in this case), place the following code snippet into the config file:

To use multemedia keys to control sound vulome, place the following code snippet into the config file:

You can use various modifiers (alt, shift, ctrl) to add additional shortcuts. For example, to launch a urxvt terminal with the key combination Ctrl-n, place the following code snippet in your config file:

From the xbindkey manpage, the -k flag is useful for providing a template for the key you want to map. It will load a xev-like window, that waits for a single keypress and then outputs the sample config.

When finished with your config file, simply run the command (or 'xbindkeys -n' if you do not want xbindkeys to run as a daemon). It is a good idea to add xbindkeys to your .xinitrc (before your window manager starts), and to use the '-p' flag, so that you can make changes to the config file on the fly, and have it be polled by the daemon.

If you are running xbindkeys as a daemon and edit .xbindkeysrc, it will automatically update bindings so you won't have to restart it.

Blackbox
You will need to emerge bbkeys. Once bbkeys is installed, make sure bbkeys is ran whenever you start X. Example xinitrc:

Now you will need to configure bbkeys. You can either use the global configuration file (usually /usr/share/bbkeys/bbkeysrc) or copy it to ~/.bbkeysrc and edit that instead. Example:

That's all there is to it.

Fluxbox
Open up your with your favourite editor. To control the basic XMMS functionality you append this example to your file:

For certain cards it might work if you put PCM for mute instead of Master. It might give the desired effect (Volume Up button when pressed will unmute the card):

Openbox
Open your file, search for section "keyboard" and, following the examples, add in the end of session:

For more information refer to the documentation for openbox about actions and keybindings in http://icculus.org/openbox/index.php/Help:Contents#Configuration.

IceWM
Just edit the file

And restart IceWM.

XFCE
Go to Settings > Keyboard Settings, and select the "Shortcuts" tab. To define our own key bindings, we have to create a new theme. Click "Add" to create it (note that all key bindings from the default theme are copied into the new theme). In the "Command Shortcuts" section, doubleclick on an empty slot, enter the command you would like to bind and press the according key. The keysym from your should appear next to the command if everything works as expected. Done.

KDE
With KDE you can set almost all settings through the Control Center if you have a supported keyboard. Go to Control Center -> Regional & Accessibility -> Keyboard Layout and choose your Keyboard model. In Mandriva 2009, go to Configure Desktop -> Regional & Language -> Keyboard Layout and choose Keyboard model.

If Keyboard Layout is missing:

After you have set your model, use KHotKeys to map the keys to actions. You can also use simple DCOP calls to talk to Amarok.

If your keyboard is not supported you can try the following:

If you use kdm as your login manager, kdm will source the file on each login.

Simply create the file as mentioned above, then have a line in  that has xmodmap use it.

If this does not work, simply create a file containing

and make it executable.

GNOME
Gnome-2.10: Go to Desktop > Preferences > Keyboard Shortcuts, or run gnome-keyboard-bindings, whichever suits your fancy. Make sure the Sound category in the Actions column is expanded, then click on the desired action. The entry in the Shortcut column will change to "New accelerator...." Press the desired key for the binding, and the shortcut is made. A proper entry should look similar to

If you feel more comfortable with (or are just that more adventurous), open up Gnome's Configuration Editor, either through the menus, or through the command gconf-editor, then navigate to Apps > gnome_settings_daemon > keybindings. For the even-more-adventurous, use your favorite editor, and open

A decent set to work with is:

Window Maker
Adding shortcuts to Window Maker is simple using the Window Maker Preferences Utility: WPrefs. By default WPrefs is the third icon down in the dock. If WPrefs is no longer in the dock, you can access it on most distros by running the following command in an X terminal:

You can go to the keyboard section of WPrefs to bind the extended keys to some predefined internal Window Maker commands.

Simply scroll right until the keyboard icon is visible and click on it.

You will see a list of internal commands that you can higlight. Select the command you want to bind and then click the "capture" button. Now simply hit the key and any modifiers (ctrl, alt, shift etc.) you want to bind to this function.

While binding internal Window Maker commands is useful, you can also bind external commands to keystrokes. The only way to do this is to add them to the main Window Maker menu, the same menu you can access from right clicking on the root window or hitting F12 by default.

In WPrefs you can click on the menu icon: the one next to the keyboard icon to access the menu. An editable version of the menu will pop up outside of the main WPref window. You can drag any of the sample elements from the main WPrefs window to the editable menu to create a new element of that type. Double-click on an element in the editable menu to change its name. Be sure to press Enter after completing the name change or else it will revert.

Adding a shortcut to a program entry will result in the shortcut keysym showing up in the menu; It will not show up in the editable version of the menu. Because the keysyms are a bit ugly you can tidy up the menu by sticking the programs in a submenu.

You can add a shortcut to a "Run Program" element by selecting it in the dummy menu and clicking the "Capture" button then pressing the key/keystroke you want to bind to that program.

Enlightenment DR16
Emerge the e16keyedit package. Then run 'e16keyedit' inside of enlightenment. Create a new keybinding, and press the 'Change' button to record a keystroke. Just press your new multimedia key and bind it to whatever action you'd like (use the 'Run' action to bind it to a command like aumix). Remember to press the 'Save' button when you're done.

Ion 3
Copy to  (if you did not do this already) and edit it. By using kpress(KEY, ACTION) you can bind actions to multimedia keys:

Note that in some later versions of ion3, key bindings have moved from to. Same syntax, just a different file. If you don't have an to copy, this is probably why.

FVWM and FVWM-Crystal
Add a binding in your configuration. FVWM-Crystal users can find a description of the modifiers used by Crystal in

For a system wide configuration using the Aumix mixer, modify the file, otherwise copy it in and add:

Another example with FVWM functions, parameters, external command and key modifiers:

An example with amixer:

FVWM-Crystal is using $[Mod0] which is not defined in plain FVWM. To determine the modifiers into FVWM, you can use the output of

xmodmap -pm

As $[Mod0] is defined as N (none) in Crystal and $[Mod1] as M for Meta (Alt), all that is needed is to replace all the occurrences of $[Mod0] by N and $[Mod1] by M:

Key XF86AudioLowerVolume A N Mixer-Volume-Down Key XF86AudioRaiseVolume A N Mixer-Volume-Up key XF86AudioPlay A N Music-Play key XF86AudioPlay A C Music-Pause key XF86AudioPlay A M Music-PlayPause

Twm (Timeless Window Manager)
The xmodmap step is not needed, unless the key doesn't have a keysym yet ("NoSymbol" in xev). Add any bindings you wish to .twmrc, like next example, and press Restart.

User and session independent hotkey support
The program Magmakeys can be used tie arbitrary commands to specific hotkeys independently from the user logged in or the window manager used. This is especially useful for keys directly related to the hardware (e.g. volume control, enabling wireless network devices etc.). The Magmakeys daemon hooks into the input subsystem of the kernel and intercepts key presses on a system-wide basis; commands are then globally defined in :

# volume control KEY_VOLUMEUP   1       /usr/bin/amixer set Master 2%+ KEY_VOLUMEDOWN 1       /usr/bin/amixer set Master 2%- # keep changing the volume when holding the key KEY_VOLUMEUP   2       /usr/bin/amixer set Master 2%+ KEY_VOLUMEDOWN 2       /usr/bin/amixer set Master 2%- KEY_MUTE       1       /usr/bin/amixer set Master toggle

Sample: eMachines m68xx
If you own an eMachines m68xx notebook and want to jump right to using the keys, you can use the following to setup the keys. NB: These were created on an m6809, but I assume they're the same for the other m68xx models, if you have access to one of the other models and can confirm/deny this, please update this page.

First, we update the the keysyms. On an x86_64 system the file we want is. Insert the following code:

Now, we add the required references to this keyboard layout to X11/kxb/rules/(xorg

In the X.Org file we add it to the list of $inetkbds like so:

In we add one line among the large list of models.

And finally in we give it a description, which can be localized.

Now, after all that, restart your X server and there's a fresh new m68xx keyboard waiting to be selected. In KDE this can be selected easily by opening the Keyboard Layout Control Module and choosing the newly added "Laptop/notebook eMachines m68xx" from the Keyboard Model list. Any of the specials keys can then be bound as shortcuts the way you configure any other shortcut.

Since this is at the X server level, and system wide, it should be accessible to all users in any window manager.

If key presses generate no X events
X11 only supports key codes up to 255. It is an inherent limitation and they say that the one of the easiest ways to fix it would be to switch to protocol version X12. So, don't hold your breath.

More and more keyboards (and remotes) generate key codes larger than 255. If some keys of your keyboard or a remote control do now show up in X, and xev does not show anything for them, try showkeys. If it will show key codes larger than 255 - read on.

There are different solutions to this problem. The easiest one is to remap the keys to fit into 0..255 range. For AT keyboards use showkeys -s or getkeycodes and then setkeycodes as explained above. For USB keyboards (and for AT keyboards too) you need to emerge udev with the keymap USE flag. Then, as explained in the README.keymap.txt run

where X is a number of your device. Try different numbers, if you don't see multimedia key presses from your keyboard - some keyboards report normal keys and multimedia keys on different event devices.

Once you've figured out the device, and a key to remap, find in /usr/include/linux/input.h an appropriate KEY_XXXXX constant with a code less than 255. You can try to remap the key right away, for example:

This command has an immediate effect, all running programs will see new key code without restarting.

To make your changes permanent, create a mapping file, and put it in /lib/udev/keymaps/. Name it after a model of your keyboard or remote. Such a file may look simialr to

And add an appropriate rule to /etc/udev/rules.d/ (README.keymap.txt suggests to add it to /lib/udev/rules.d/95-keymap.rules but I prefer to keep all settings and modifications in /etc). Your udev rule might look like

That's all!

Alternatives:
 * patch the kernel: Microsoft Natural Ergonomic Keyboard 4000
 * patch the xf86-input-evdev driver: http://www.mythtv.org/wiki/Remapping_remote_control_key_codes_greater_than_255
 * use a tool that reads from /dev/input/event and feeds simulated keypresses to X using XTest extension, thus bypassing xf86-input-evdev driver. One of such tools is (EvRouter). It can be installed from the sunrise overlay.
 * use a tool that read key presses from the console, pretty much like showkeys does, and feeds them to X using XTest. One of such tools is rawkeybind.

Command Line Functions to Control Common Applications
Many applications have methods to control them from command line. These are perfect for creating shortcuts to use with multimedia keys.

If you like to control all the apps below (and 20+ more apps) you will need a command wrapper like ReMoot. ReMoot can control xmms, Mplayer, Rhythmbox, Amarok, Quod Libet, xine, kaffeine and 20 more apps. The command 'remoote play' will control the active multimedia application and therefor you don't have to asign one key to one application. ReMoot works best with [/HOWTO_Use_Multimedia_Keys#Alternative:_lineakd_or_keyTouch Lineak], Keytouch or xbindkeys and has a web-frontend that works remote control with a PDA or any web enabled gadget.

Audacious
Audacious has some straightforward command line switches. You can see more by executing this command in a terminal:

Audacious command line switches from the audacious manpage

Rhythmbox
Rhythmbox can be controlled using dbus.

Dbus commands

This is not an exhaustive list of commands.

It can also be controlled using rhythmbox-client.

rhythmbox-client commands

For all options, type rhythmbox-client --help or man rhythmbox-client

amarok
amarok command line switches from "dcop amarok player" (v. 1.4.4)

Quod Libet
Quod Libet command line switches from "quodlibet --help"

MPD/MPC
If you use MPD your client may already support some keysyms. For instance gmpc correctly recognises XF86AudioNext, XF86AudioPrev, XF86AudioStop, and XF86AudioPlay. Furthermore, gmpc works with profiles, and whichever you have selected will be played, paused, stopped, next'd, or previous'd autimagically.

If you do not use gmpc, or do not want to leave gmpc running then you may want to bind these keys to short cuts to the command line MPD client, mpc. first you must install mpc by executing:

The mpc command line switches are:

mpc switches from "mpc --help"

ALSA
ALSA can be controlled using amixer. The following commands will adjust the PCM levels of your ALSA soundcard.

Controling PCM levels with amixer

Not all sound cards support mute toggling. The following script can be used on such cards. It saves the current volume to and sets it to 0. To "unmute", execute the script again and the previous value will be restored.

(Verified with amixer 1.0.13)

Banshee player
Banshee command line switches from "banshee --help"

Goggles Music Manager
As of v0.7.4, Goggles Music Manager supports the following command line options:

Goggles Music Manager command line options from "gmm --help"

Getting illumination switching to work under X
To get switching on/off the illumination of multimedia keyboard to work under X using key Scroll_Lock:

Change mapping of Scroll_lock by extending ~.Xmodmap with something like this:

keycode 78 = XF86LightBulb

Of course you could use any other key you like.

Make a little script somewere like this:

kbd-illum

and make it executable.

Of course you need xsetleds installed:

Then bind key XF86LightBulb to this command:

/usr/local/bin/kbd-illum --toggle

like explained above and you are done.

HOWTO Мультимедийные кнопки (клавиши)