Keymap

Keymaps are XML base files that define the mappings of keys (keyboard keys, mouse/remote/joysticks buttons and more) to Kodi actions.

Customizing keymaps through the GUI
Users can customize keymaps for remotes in GUI by using the community Keymap Editor add-on.

Location of keymaps
User modified keymap files are stored in the "keymaps" folder in the userdata folder:

Defaults
Default keymaps are included when Kodi is installed, but users should not edit those install files directly. Instead, place user modified keymaps in the userdata/keymaps/ directory.

Kodi can process multiple keymap files and does so like this:


 * All *.xml files from the default install settings and userdata/kemaps/ folders are applied as keymaps.
 * All *.xml files are processed in alphabetical order.
 * Keymaps defined in an .xml file add to or override mappings in previous .xml file.
 * Keymaps defined in the userdata folder add to or override mappings in the global keymap.

By default there will be no files in these locations, so grab one from the link below to make a new one/over-ride: Default keymaps shipped with Kodi

Structure
There is one global keymap and several window-specific keymaps.

Kodi falls back to the global map when the window-specific map hasn't bound the key being pressed.

The format of keymapping files is as follows:

As you can see, it's divided into a section, and a number of window sections (such as ).

A list of the available window names can be seen here. The WINDOW can also be a custom window formatted as  (e. g. ).

Each of these sections can contain Gamepad, Remote, Keyboard, Universal Remote, and custom Joystick sections.

The format for mapping a particular key under one of these device types is as follows:

Keynames
Depending on your device you will need to use a specific "keyname".

Gamepads
An up to date list of the available actions can be found in the source code of Kodi in ButtonTranslator.cpp where the TranslateGamepadString function does the work.

Example:

Remotes
An up to date list of the available actions can be found in the source code of Kodi in ButtonTranslator.cpp where the TranslateRemoteString function does the work.

Example:

Universal Remotes
To map Universal Remote buttons using the RCA infrared protocol, you may add   sections to keymap.xml.

In this case, the tags used are  where # is the original button code (OBC) of the button.

You would put it inside a section in the or sections.

Example:


 * Will map Stop Playback to the RCA DVD repeat button, which is not used by Kodi by default.


 * Note: ensure that the section is NOT added 'within' the section - it can appear before or after. Otherwise it will not be recognised and produces errors in the logfile.

Remote keys can be observed in the kodi.log file (~/.kodi/temp/kodi.log on Linux) when debugging is enabled in the GUI (Settings -> debugging ). The list of pre-defined OBC codes can be found at XBIRRemote.h.

Keyboards
Valid keyboard keymap syntax includes, , and.

Mapping for arbitrary key codes can be configured using the following syntax: where "123" is replaced by the key code.

A full list of valid keynames can be found in
 * the TranslateKeyboardString method in ButtonTranslator.cpp
 * or in List of Kodi keynames.

Example:


 * Modifiers
 * shift
 * alt
 * ctrl

Custom Joystick Configuration
Custom joysticks are defined using the following syntax:

Getting the joystick name:
 * On linux: 'cat /proc/bus/input/devices'
 * or see your Kodi log file

Getting the button ids:
 * 'id' is the button ID used by SDL. Joystick button ids of connected joysticks appear in kodi.log when they are pressed. Use your log to map custom buttons to actions.

Example:

Commands
The most recent available actions can be found in the TranslateActionString method in in ButtonTranslator.cpp.

For those debugging integer action codes from the debug log, the mapping of action codes to constants is in Key.h

In addition to the following actions, you can also use Built-in scripting in Kodi.

Additional keys
Other keys that can be mapped to actions.

Media keyboards/remotes

 * browser_back
 * browser_forward
 * browser_refresh
 * browser_stop
 * browser_search
 * browser_favorites
 * browser_home
 * volume_mute
 * volume_down
 * volume_up
 * next_track
 * prev_track
 * stop
 * play_pause
 * launch_mail
 * launch_media_select
 * launch_app1
 * launch_app2
 * play
 * pause
 * fastforward
 * rewind
 * channelup
 * channeldown

Mouse actions

 * leftclick
 * rightclick
 * middleclick
 * doubleclick
 * wheelup
 * wheeldown
 * mousemove
 * mousedrag
 * mousedragstart
 * mousedragend
 * mouserdrag
 * mouserdragstart
 * mouserdragend