View source for Keymap

{{mininav| [[Remote controls]] }}
<section begin="intro" />Keymaps are XML base files that define the mappings of keys (keyboard keys, mouse/remote/joysticks buttons and more) to Kodi actions.<section end="intro" />

== Customizing keymaps through the GUI ==
{{main|Add-on:Keymap Editor}}
Users can customize keymaps for remotes in GUI by using the community [[Add-on:Keymap Editor|Keymap Editor]] add-on.

== Location of keymaps ==
User modified keymap files must be stored in the "'''keymaps'''" folder in the [[userdata]] folder:
{{#lst:userdata|location all}}

=== 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/keymaps/ 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:

* ''' https://github.com/xbmc/xbmc/tree/master/system/keymaps '''
* ''' https://github.com/kodi-game/peripheral.joystick/tree/master/peripheral.joystick/resources/buttonmaps/xml '''

== Structure ==

There is one '''global''' keymap and several '''window'''-specific keymaps.<br />
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:

<syntaxhighlight lang=xml enclose="div">
<keymap>
  <global>
    <gamepad>
      <A>Select</A>
      [...]
    </gamepad>

    <remote>
      <select>Select</select>
      [...]
    </remote>

    <keyboard>
      <enter>Select</enter>
      [...]
    </keyboard>

    <mouse>
      <leftclick>Select</leftclick>
      [...]
    </mouse>

    <universalremote>
      <obc25>ActivateWindow(MyMusic)</obc25>
      [...]
    </universalremote>

    <joystick name="PLAYSTATION(R)3 Controller (00:1B:FB:F6:E0:F2)">
      <button id="15">Select</button>
      [...]
    </joystick>
  </global>

  <Home>
    [...]
  </Home>

  [...]

</keymap>
</syntaxhighlight>

As you can see, it's divided into a <global> section, and a number of window sections (such as <Home>).<br />
A list of the available window names can be seen [[Window IDs|here]]. The WINDOW can also be a custom window formatted as <windowId#> (e. g. <window1113>). <br />
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:
<syntaxhighlight lang=xml enclose="div">
  <keyname>action</keyname>
</syntaxhighlight>

== 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 [https://github.com/xbmc/xbmc/blob/master/xbmc/input/ButtonTranslator.cpp ButtonTranslator.cpp] where the ''TranslateGamepadString()'' function does the work.

'''Example:'''
<syntaxhighlight lang=xml enclose="div">
<gamepad>
  <A>Select</A>
</gamepad>
</syntaxhighlight>

=== Remotes ===
An up to  date list of IR-remote button names can be found in the source code of Kodi [https://github.com/xbmc/xbmc/blob/master/xbmc/input/IRTranslator.cpp IRTranslator.cpp]. See the method TranslateString().

The available actions are discussed in section [[Keymap#Actions|Actions]].

{{Note|Some remotes (e.g. FLIRC) are actually seen as "keyboards". Those will need to use the <keyboard> tag instead.}}

'''Example:'''
<syntaxhighlight lang=xml enclose="div">
<remote> 
  <play>Play</play>
</remote>
</syntaxhighlight>

=== Universal Remotes ===
To map Universal Remote buttons using the RCA infrared protocol, you may add '''<universalremote>''' sections to keymap.xml.<br />
In this case, the tags used are <obc#> where # is the original button code (OBC) of the button.<br />
You would put it inside a <universalremote> section in the <window> or <global> sections.

'''Example:'''
<syntaxhighlight lang=xml enclose="div">
<universalremote> 
  <obc148>Stop</obc148>
</universalremote>
</syntaxhighlight>

:Will map ''Stop Playback'' to the RCA DVD repeat button <obc148>, which is not used by Kodi by default. 

* '''Note:''' ensure that the <universalremote> section is '''NOT''' added 'within' the <remote> 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 [https://github.com/xbmc/xbmc/blob/master/xbmc/input/XBIRRemote.h XBIRRemote.h].

=== Keyboards ===
Valid keyboard keymap syntax includes <keyname>, <key id="">, and <keyname mod="">.

Mapping for arbitrary key codes can be configured using the following syntax: 
<syntaxhighlight lang=xml enclose="div">
<key id="123">
</syntaxhighlight>
where "123" is replaced by the key code.

A full list of valid keynames can be found in 
* the [https://github.com/xbmc/xbmc/blob/master/xbmc/input/keyboard/XBMC_keytable.cpp XBMC_keytable.cpp] source code file
* or in [[List_of_keynames]].<br />

'''Example:'''
<syntaxhighlight lang=xml enclose="div">
<keyboard>
  <key id="123">action</key> -- id is the keys keycode. >
  <a mod="shift,alt">action</a> -- corresponds to shift-alt-a, the mod="" syntax is enabled since build 26407. >
  <space>action</space> -- for a complete list of valid keynames, see ButtonTranslator.cpp or List of Kodi keynames above. >
</keyboard>
</syntaxhighlight>

;Modifiers
* shift
* alt
* ctrl

=== Mouse ===

As this highly depends on the mouse you are using and which kind of buttons are available, we only mention the most common buttons on a mouse:
<syntaxhighlight lang=xml enclose="div">
<keymap>
  <mouse>
    <global>
      <leftclick>...</leftclick>
      <middleclick>...</middleclick>
      <rightclick>...</rightclick>
      <wheelup>...</wheelup>
      <wheeldown>...</wheeldown>
    </global>
  </mouse>
</keymap>
</syntaxhighlight>

'''''Example for changing the volume while on MusicOSD (On Screen Display) window using the mouse wheel'''''

<syntaxhighlight lang=xml enclose="div">
<keymap>
  <MusicOSD>
    <mouse>
      <wheeldown>VolumeDown</wheeldown>
      <wheelup>VolumeUp</wheelup>
    </mouse>
  </MusicOSD>
</keymap>
</syntaxhighlight>


=== Custom Joystick Configuration ===
See [[HOW-TO:Modify_joystick.xml]].

== Long-press ==
{{note| Longpress seems to only be working on keyboard keymaps at the moment }}
Depending on the device, many remotes, keyboards, and gamepads can use the long-press modifier. This allows a button to do a separate action when held for a short period of time. The syntax for this is as follows:

<pre><button mod="longpress">action</button></pre>

Not all devices will correctly work with the longpress action, but most should. 

{{Note|Long-press will disable keyrepeat for that key/window.}}

=== Removing a long-press action from a default keymap ===
If you want to simply remove a long-press action, rather than override it, you can place an empty long-press tag in a keymap. This also has the effect of re-enabling keyrepeat for the short-press action.

For example, this will remove the context menu action from the default keyboard.xml keymap:

<pre>
<keymap>
  <global>
    <keyboard>
      <return mod="longpress"></return>
      <enter mod="longpress"></enter>
    </keyboard>
  </global>
</keymap>
</pre>

== Commands ==
The most recent available actions can be found in [https://github.com/xbmc/xbmc/blob/master/xbmc/input/actions/ActionIDs.h ActionIDs.h].

For those debugging integer action codes from the debug log, the mapping of action codes to constants is in [https://github.com/xbmc/xbmc/blob/master/xbmc/input/Key.h Key.h]

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

=== Actions ===
{{Main|Action IDs}}
{{#lst:Action IDs|Action IDs}}

=== Functions ===
{{main|List of built-in functions|Built-in scripting}}
{{#lst:List of built-in functions|functions}}

== Windows ==
{{main|Window IDs}}
{{#lst:Window IDs|main content}}

== 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 - right button drag
* mouserdragstart - start of right button drag
* mouserdragend - end of right button drag

== Examples and pre-made keymaps ==
{{see|:Category:Remotes}}

== See also ==
* [[Remote controls]]
* [[Keyboard controls]]
* [[Add-on development]]
* [[Python development]]
* [[Skinning]]

{{Updated|16}}



[[Category:Remotes]]
[[Category:Settings]]