Ubuntu Wiki

• Launchpad Entry: foo

• Created: 2008-09-07

• Status: draft

• Contributors: Otto Kekäläinen

• Packages affected:

Summary

Currently multimedia applications don't have built in support for special keys like "play", "stop", "next", "fast forward" etc which are currently found in multimedia keyboards and IR remote controls. This is an coordinated effort create good defaults that use the special key codes. Out-of-the-box -functionaliy should be the norm - setting user and installation specific key bindings and configuration files should be the exception.

Release Note

Thanks to coordinated work with special key code support in different applications, users can use the most common multimedia applications out-of-the-box with any IR remote control or multimedia keyboard which driver is based on the Linux HID inpu device model (device in /dev/input/eventX).

Rationale

Nowadays most IR remote control drivers automatically register them as /dev/input/eventX devices, just as any other human input devices (keyboards, mouses etc). The key codes these devices send are standardized within the Linux human input device system. By developing better support in how these key codes are recognized by X.org (the graphical system) they would automatically be later available in GTK+ and other applications directly, so no Lirc system in needed to control applications with a IR remote.

The problem at the moment however is, that few applications have build in support for special keys. Usually applications can only be controlled by the key codes found in a regular keyboard. For example, "space" usually make the multimedia application pause and "n" changes to next channel/item in playlist. However multimedia keyboards and IR remotes have keys that generate special key codes, like "Play", "pause" and "fast forward" etc..

Check out what Linux input devices your system has with command ls /dev/input/.

You can test what key codes you own keyboard or remote gives with the command sudo evtest /dev/inpux/eventX where X stands for the device number.

The Linux key codes should end up in Xorg as key syms. Current key syms can be viewed in Xorg's git: main list http://cgit.freedesktop.org/xorg/proto/xproto/tree/keysymdef.h, others at http://cgit.freedesktop.org/xorg/proto/xproto/tree/

From Xorg's key syms these key codes automatically propagate to GUI toolkits. For example, see the newest list of gdk key syms: http://svn.gnome.org/viewvc/gtk%2B/trunk/gdk/gdkkeysyms.h?view=markup

What we need to do:

1. recognize the most common special key codes in use in current multimedia keyboards and remotes
2. add the support of these key codes in Xorg
3. inform the GUI application developers of the newly available key codes and help developers add these new key syms into their applications
4. show in each application's documentation what key codes are supported

Use Cases

• Joe buys a IR remote control. When he comes home he plugs it into his computer, opens Rhythmbox and starts listening to music. Then he goes to his sofa and lies down. From there he presses the "next" button on his remote control and Rhythmbox changes to next item in the playlist. Joe does not at any point do any manual configuration of anything.

• Carol is watching a movie with Totem and her phone rings. She presses "pause" on her multimedia keyboard and Totem pauses.

Assumptions

Most new multimedia keyboards and IR remote control device drivers are written so, that the device goes into Linux as a linux-input-device, available through /dev/input/eventX.

Design

I've analyzed the v4l's IR remote control drivers and their keymaps with the command grep KEY_[A-Z0-9]* v4l-ir-keymaps.c -o | sort | uniq -c | sort -n -r.

These are the most common key codes are and their suggested functions in different types of applications:

<occurences> <key code> <function in audio/video player> <function in tv/radio player> <function in picture viewer>
     44 KEY_9       select channel      select channel      -
     44 KEY_8       select channel      select channel      -
     44 KEY_7       select channel      select channel      -
     44 KEY_6       select channel      select channel      -
     44 KEY_5       select channel      select channel      -
     44 KEY_4       select channel      select channel      -
     44 KEY_3       select channel      select channel      -
     44 KEY_2       select channel      select channel      -
     44 KEY_1       select channel      select channel      -
     44 KEY_0       select channel      select channel      -
     43 KEY_MUTE        mute (system wide)
     42 KEY_RECORD      -               record              -
     41 KEY_POWER       logout/power off (system wide)
     40 KEY_VOLUMEUP    volume up (system wide)
     40 KEY_VOLUMEDOWN  volume down (system wide)
     40 KEY_CHANNELUP   select next in playlist         channel up
     40 KEY_CHANNELDOWN select previous in playlist     channel down
     39 KEY_STOP        stop
     35 KEY_REWIND      rewind
     32 KEY_ZOOM        -
     31 KEY_RESERVED    -
     29 KEY_PLAY        play
     29 KEY_PAUSE       pause
     24 KEY_UP          focus up / traverse menu
     24 KEY_RIGHT       focus right / traverse menu
     24 KEY_LEFT        focus left / traverse menu
     24 KEY_DOWN        focus down / traverse menu
     20 KEY_TV          open TV app (system wide)
     20 KEY_TEXT        -   show teletext   -
     20 KEY_ENTER       enter
     19 KEY_AUDIO       change audio channel
     18 KEY_TUNER       -
     17 KEY_VIDEO       open video player app (system wide)
     17 KEY_MENU        open menu
     17 KEY_FASTFORWARD fast forward
     16 KEY_FORWARD     forward
     15 KEY_SEARCH      search / focus in search field
     15 KEY_RED         (app specific function)
     15 KEY_RADIO       open radio app (system wide)
     15 KEY_PREVIOUS    previous
     14 KEY_MODE        -
     14 KEY_GREEN       (app specific function)
     14 KEY_BLUE        (app specific function)
     13 KEY_YELLOW      (app specific function)
     13 KEY_INFO        info / properties
     12 KEY_PLAYPAUSE   play or pause
     12 KEY_AGAIN       repeat on / off
     11 KEY_OK          enter
     11 KEY_NEXT        next item in playlist
     10 KEY_SUBTITLE    change subtitle
     10 KEY_SLEEP       -
     10 KEY_SHUFFLE     suffle on / off
     10 KEY_SELECT      -
     10 KEY_EPG         show EPG

Implementation

Step 1: Done in this spec (list above)

Step 2: Some Xorg developers have been notified, but no decisions have been made. Partially some are already doing thing similar to what is suggested in this spec.

Step 3: We need to contact the developers and ask them to add more key (code) shortcuts:

• Rhythmbox
• Totem
• Me TV
• Elisa media center
• Gnome Mplayer
• Gxine
• VLC
• Kaffeine
• Amarok

UI Changes

The user documentation or interface must somehow tell the user what special key codes are supported and what they do.

Code Changes

Add new key syms in Xorg and add new key syms in applications.

Migration

Not an issue.

Test/Demo Plan

Work in progress.

Outstanding Issues

(comments copypasted out of context from different emails)

Peter Hutterer: The problem here is the design of the core protocol (in how Xorg translates linux key codes into Xorg key syms). It only allows for up to 255 keycodes and thus anything above that will be ignored. Until we get 32bit keycodes this won't change. It's planned, but I can't give you a timeframe other than maybe server-1.6 (Dec), probably server-1.7 (May).

Bastien Nocera: (Special key sym support in Totem) It's already there, see also: http://thread.gmane.org/gmane.linux.ubuntu.devel.desktop/1691/focus=6992

(Example:) GDK_Pause is the same as XK_Pause, which is for the Pause/Break key, not for audio pause keys (XF86XK_AudioPause) which we already handle. Like those ones? https://bugs.freedesktop.org/show_bug.cgi?id=16519

Also, we're working on generating more keycodes for GDK. See: http://bugzilla.gnome.org/show_bug.cgi?id=442632#c13

Wouter Stomp: Fedora just implemented this for their upcoming release. You can probably reuse most of their work.

See http://fedoraproject.org/wiki/Features/BetterLIRCSupport

And perhaps there could even be a feature freeze exception to include gnome-lirc-properties in intrepid? It seems really useful.

Otto Kekäläinen: We don't need Lirc at all for Linux input devices. Making Lirc easier to use does not help this spec's goals.

BoF agenda and discussion

Has not been discussed yet.

CategorySpec