HOW-TO:Modify keymaps: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Targettio
No edit summary
No edit summary
(47 intermediate revisions by 12 users not shown)
Line 1: Line 1:
== Quick summary ==
{{mininav| [[Remote controls]] | [[Keymaps]] }}


The keyboard.xml file controls how XBMC reacts to keypresses, that is
{{bigger| {{note| You can also edit keymaps from within {{kodi}} by using '''[[Add-on:Keymap Editor]]'''. }} }}
 
{{cleanup}}
 
The keyboard.xml file controls how Kodi reacts to keypresses, that is
it determines what action is mapped to what keypress. There are two
it determines what action is mapped to what keypress. There are two
main reasons for modifying keyboard.xml:
main reasons for modifying keyboard.xml:


1. you want to change the standard key mappings because of a personal
# You want to change the standard key mappings because of a personal preference
preference
# You are configuring a Media Center remote control that sends keypresses


2. you are configuring a Media Center remote control that sends
You can edit keyboard.xml using any text editor such as Notepad++ in Windows or gedit/nano in Linux. The location where the file should be located after creation is in [[userdata]]
keypresses


You can edit keyboard.xml using any text editor such as Notepad in
There is a more detailed discussion of the keyboard.xml file at [[keymaps]], while the remainder of this article is focussed on the gory details of editing it.
Windows or gedit in Linux. The location of the file is:


Windows - %APPDATA%\xbmc\userdata\keymaps\keyboard.xml
== Introduction ==
 
Linux - $home/.xbmc/userdata/keymaps/keyboard.xml
 
There is a more detailed discussion of the keyboard.xml file at
http://wiki.xbmc.org/index.php?title=Keymap.xml, while the remainder of
this article is focussed on the gory details of editing it.


== Introduction ==
All the keypresses that Kodi responds to, for example "{{keypress|P}}" for "play" and "{{keypress|X}}" for "stop" are configured in a file called keyboard.xml.
Actually there are two keyboard.xml files. There is the system keyboard.xml that contains all the standard key mappings, and each user optionally has their own userdata keyboard.xml that contains just their customised key mappings.


All the keypresses that XBMC responds to, for example "P" for "play"
The userdata keyboard.xml only needs to contain additional key mappings, or key mappings that override the defaults in the system keyboard.xml. When Kodi is trying to decide how to respond to a keypress it first looks in the userdata keyboard.xml.
and "X" for "stop" are configured in a file called keyboard.xml.
If it doesn't find a mapping for the keypress Kodi then looks in the system keyboard.xml. This means that the userdata keyboard.xml is typically quite short because it only needs to define mappings for a few keys.
Actually there are two keyboard.xml files. There is the system
keyboard.xml that contains all the standard key mappings, and each user
optionally has their own userdata keyboard.xml that contains just their
customised key mappings.


The userdata keyboard.xml only needs to contain additional key
You can change key mappings by editing the system keyboard.xml, but we strongly recommend you don't do this.
mappings, or key mappings that override the defaults in the system
The system keyboard.xml is a big complicated file, and if you introduce an error into it you can break all the key mappings.
keyboard.xml. When XBMC is trying to decide how to respond to a
Also any changes you make risk being overwritten if you upgrade Kodi. In general you should only ever '''edit your userdata keyboard.xml'''. Even if you make a horrendous hash of this you just need to delete or rename your userdata keyboard.xml to restore the default key mappings.
keypress it first looks in the userdata keyboard.xml. If it doesn't
find a mapping for the keypress XBMC then looks in the system
keyboard.xml. This means that the userdata keyboard.xml is typically
quite short because it only needs to define mappings for a few keys.


You can change key mappings by editing the system keyboard.xml, but we
User keymaps are only processed when Kodi starts up, therfore you must restart Kodi to see any changes.
strongly recommend you don't do this. The system keyboard.xml is a big
complicated file, and if you introduce an error into it you can break
all the key mappings. Also any changes you make risk being overwritten
if you upgrade XBMC. In general you should only ever edit your userdata
keyboard.xml. Even if you make a horrendous hash of this you just need
to delete or rename your userdata keyboard.xml to restore the default
key mappings.


== Where to find keyboard.xml ==
== Where to find keyboard.xml ==


'''Windows'''
Keymap configuration files are stored in the "'''keymaps'''" folder in the [[userdata]] folder:


The userdata keyboard.xml is kept in
{{#lsth:userdata|Location of the UserData folder}}
%APPDATA%\xbmc\userdata\keymaps\keyboard.xml, where %APPDATA% is an
environment variable that varies depending on what version of Windows
you use. For example on my PC runnings Windows 7 my %APPDATA% is
C:\Users\renniej\AppData\Roaming.


Note that %APPDATA% contains the username ("renniej" in my case). This
== How to edit keyboard.xml ==
means that if several different users are using the same PC each user
has their own keyboard.xml so changes you make to one user won't affect
the others. If you really really want your changes to affect all users
you can either (carefully!) edit the system keyboard.xml or you can use
portable mode.


'''Linux'''
'''keyboard.xml''' is just a text file so you can edit it it using any text editor e.g. in Windows use Notepad++. In Windows there is a third party keymap editor available from http://xbmcmce.sourceforge.net/, or this editor is also available through the [[Add-on:MCERemote]] add-on.


The userdata keyboard.xml is kept in
<big>'''Windows'''</big>
$home/.xbmc/userdata/keymaps/keyboard.xml, where once again $home is an
enviroment variable. In most text editors like gedit the .xbmc directory
won'tbe displayed and you need to enable displaying hidden files.


== How to edit keyboard.xml ==
To use Notepad++ to edit your userdata keyboard.xml click Start then Run, or in Win7 click {{keypress|Start}} then All Programs then Accessories then Run, or press the keyboard shortcut {{keypress|Win|R}}, then when the Run dialog opens type in:


keyboard.xml is just a text file so you can edit it it using any text editor
<pre>notepad++ %APPDATA%\Kodi\userdata\keymaps\keyboard.xml</pre>
e.g. in Windows use Notepad. If you use Windows there is a third party
keymap editor available from http://xbmcmce.sourceforge.net/, or this
editor is also available through the MCERemote add-on.


'''Windows'''
* If you haven't edited your keyboard.xml before Notepad will ask "Do you want to create a new file?" and you should click '''Yes'''.


To use Notepad to edit your userdata keyboard.xml click Start then Run, or in
* If you have downloaded the KeyMapEdit applet from http://xbmcmce.sourceforge.net/ run it then select File/Open and double click "keyboard.xml".
Win7 click Start then All Programs then Accessories then Run,
or press the keyboard shortcut Windows-R, then when the Run dialog
opens type in:


<pre>notepad %APPDATA%\XBMC\userdata\keymaps\keyboard.xml</pre>
* If you use the MCERemote add-on just select the "Edit keyboard.xml" option.


If you haven't edited your keyboard.xml before Notepad will ask "Do
{{Note|that KeyMapEdit.exe isn't included in the MCERemote add-on by default (because the rules for add-ons prohibit including executable files). You need to go into the add-on settings Misc section and enable the setting "Update/install keymap editor" then select "Edit keyboard.xml".}}
you want to create a new file?" and you should click Yes.


If you have downloaded the KeyMapEdit applet from http://xbmcmce.sourceforge.net/
<big>'''Linux'''</big>
run it then select File/Open and double click "keyboard.xml".


If you use the MCERemote add-on just select the "Edit keyboard.xml" option.
Use your favourite text editor e.g. gedit. Remember that the .kodi directory is hidden so you need to show hidden files to see it.
Note that KeyMapEdit.exe isn't included in the MCERemote add-on by default
(because the rules for add-ons prohibit including executable files). You
need to go into the add-on settings Misc section and enable the setting
"Update/install keymap editor" then select "Edit keyboard.xml".
 
'''Linux'''
 
Use your favourite text editor e.g. gedit. Remember that the .xbmc
directory is hidden so you need to show hidden files to see it.


== What to put in keyboard.xml ==
== What to put in keyboard.xml ==
Line 109: Line 62:
This is an outline rather than a definitive guide.
This is an outline rather than a definitive guide.
For the full details see
For the full details see
http://wiki.xbmc.org/index.php?title=Keymap.xml.
[[keymaps]].


A keyboard.xml file will look something like:
A keyboard.xml file will look something like:
Line 127: Line 80:
&lt;/keymap&gt;</pre>
&lt;/keymap&gt;</pre>


The keyboard.xml must start with &lt;keymap&gt; and end with &lt;/keymap&gt;. In
The keyboard.xml must start with &lt;keymap&gt; and end with &lt;/keymap&gt;. In between are a number of sections; in the example above the first section is &lt;global&gt;, the second section is &lt;Home&gt;, and there can be lots of other sections as well.
between are a number of sections; in the example above the first
section is &lt;global&gt;, the second section is &lt;Home&gt;, and there can be
lots of other sections as well.


The &lt;global&gt; section defines key mappings that apply everywhere in XBMC
The &lt;global&gt; section defines key mappings that apply everywhere in Kodi unless they are overridden by a mapping in another section. The &lt;Home&gt; section defines key mappings that apply only when you're at the Kodi home screen. Other sections define mappings that apply to other screens, for example the &lt;FullScreenVideo&gt; section defines mappings that apply when you're watching a video full screen. The easiest way to get a list of all the section names is to open the system keyboard.xml in Notepad and look through it.
unless they are overridden by a mapping in another section. The &lt;Home&gt;
section defines key mappings that apply only when you're at the XBMC
home screen. Other sections define mappings that apply to other
screens, for example the &lt;FullScreenVideo&gt; section defines mappings
that apply when you're watching a video full screen. The easiest way to
get a list of all the section names is to open the system keyboard.xml
in Notepad and look through it.


The key mappings have the form:
The key mappings have the form:
Line 145: Line 88:
<pre>&lt;keyname mod="modifiers"&gt;SomeAction&lt;/keyname&gt;</pre>
<pre>&lt;keyname mod="modifiers"&gt;SomeAction&lt;/keyname&gt;</pre>


As with the section names, to see possible key names look at the
As with the section names, to see possible key names look at the system keyboard.xml. In fact copying and pasting from the system keyboard.xml is probably the easiest way to construct your custom keyboard.xml.
system keyboard.xml. In fact copying and pasting from the system
keyboard.xml is probably the easiest way to construct your custom
keyboard.xml.
 
You need only only include the mod="modifiers" if you want to combine
the key with a keyboard modifer like control, shift or alt. For
example:


You need only only include the mod="modifiers" if you want to combine the key with a keyboard modifer like control, {{keypress|shift}} or {{keypress|alt}}.
For example:
<pre>&lt;d&gt;Notification(Keypress, You pressed D!, 3)&lt;/d&gt;</pre>
<pre>&lt;d&gt;Notification(Keypress, You pressed D!, 3)&lt;/d&gt;</pre>


configures the D key to execute the action Notification(Keypress, You pressed D!, 3)
configures the {{keypress|D}} key to execute the action Notification(Keypress, You pressed D!, 3)
while:
while:


<pre>&lt;d mod="ctrl,alt"&gt;Notification(Keypress, You pressed ctrl-alt-D!, 3)&lt;/d&gt;</pre>
<pre>&lt;d mod="ctrl,alt"&gt;Notification(Keypress, You pressed ctrl-alt-D!, 3)&lt;/d&gt;</pre>


configures a control-alt-D keypress to execute the action. Incidentally
configures a {{keypress|control|alt|D}} keypress to execute the action. Incidentally the Notification action displays a little message at the bottom right of the screen. This can be useful for testing your key mappings.
the Notification action displays a little message at the bottom right
 
of the screen. This can be useful for testing your key mappings.
<pre>&lt;d mod="longpress"&gt;Notification(Keypress, You kept pressing D!, 3)&lt;/d&gt;</pre>
 
configures a '''long''' {{keypress|D}} keypress to execute the action.  


== An example ==
== An example ==


This example is going to be a bit contrived, but after all it's only
This example is going to be a bit contrived, but after all it's only intended as an example of how you might make some more useful key mapping.
intended as an example of how you might make some more useful key
mapping.


Media Center remote controls usually have a button labelled "Guide",
Media Center remote controls usually have a button labelled {{button|Guide}}, and when you press it this button usually sends a {{keypress|control|G}} keystroke.
and when you press it this button usually sends a control-G keystroke.
In this example we'll configure the Guide button to display the Info screen except when playing a video, when we'll configure it to show the OSD ('''O'''n '''S'''creen '''D'''isplay).
In this example we'll configure the Guide button to display the Info
So lets start by defining a global mapping for {{keypress|control|G}} to display Info:
screen except when playing a video, when we'll configure it to show the
On Screen Display. So lets start by defining a global mapping for
control-G to display Info:


<pre>&lt;keymap&gt;
<pre>&lt;keymap&gt;
Line 182: Line 117:
     &lt;keyboard&gt;
     &lt;keyboard&gt;
       &lt;g mod="ctrl"&gt;Info&lt;/g&gt;
       &lt;g mod="ctrl"&gt;Info&lt;/g&gt;
    &lt;/keyboard&gt;
   &lt;/global&gt;
   &lt;/global&gt;
&lt;/keymap&gt;</pre>
&lt;/keymap&gt;</pre>


From the previous section it should be obvious what this key mapping
From the previous section it should be obvious what this key mapping does so I won't dwell on it further. If you create a userdata keyboard.xml with this mapping and run Kodi you should find that whenever you press {{keypress|control|G}} it displays the Info screen.
does so I won't dwell on it further. If you create a userdata
keyboard.xml with this mapping and run XBMC you should find that
whenever you press control-G it displays the Info screen.


However this will make control-G display Info when playing a video, and
However this will make {{keypress|control|G}} display Info when playing a video, and we want it to display the OSD instead. To achieve this modify the keyboard.xml to:
we want it to display the OSD instead. To achieve this modify the
keyboard.xml to:


<pre>&lt;keymap&gt;
<pre>&lt;keymap&gt;
Line 207: Line 138:
&lt;/keymap&gt;</pre>
&lt;/keymap&gt;</pre>


The global action for control-G is still Info, but the
The global action for {{keypress|control|G}} is still Info, but the <FullScreenVideo> section overrides the global mapping when playing a video and configures {{keypress|control|G}} to display the OSD instead.
&lt;FullScreenVideo&gt; section overrides the global mapping when playing a
video and configures control-G to display the OSD instead.


== Debugging ==
== Debugging ==


It's easy to make mistakes when writing a keyboard.xml file, and if
It's easy to make mistakes when writing a keyboard.xml file, and if Kodi finds an error in your keyboard.xml it will simply stop processing it, leaving you wondering why your key mappings aren't
XBMC finds an error in your keyboard.xml it will simply stop
working. To check for errors in your keyboard.xml turn debug logging on (in the Settings screen go into System then Debugging and enable the '''Enable debug logging option'''), then close Kodi then start it and close it again. Now look in %APPDATA%\Kodi and you'll find a file called kodi.log. Open this file in Notepad and you should be able to find the error.
processing it, leaving you wondering why your key mappings aren't
working. To check for errors in your keyboard.xml turn debug logging on
(in the Settings screen go into System then Debugging and enable the
Enable debug logging option), then close XBMC then start it and close
it again. Now look in %APPDATA%\XBMC and you'll find a file called
xbmc.log. Open this file in Notepad and you should be able to find the
error.


For example, take the keymapping above but suppose I mistype:
For example, take the keymapping above but suppose I mistype:
Line 231: Line 153:
<pre>&lt;g mod="ctrl"&gt;Info&lt;/&gt;</pre>
<pre>&lt;g mod="ctrl"&gt;Info&lt;/&gt;</pre>


that is I missed the "g" in &lt;/g&gt;. If I run XBMC and then look at
that is I missed the "{{keypress|g}}" in &lt;/g&gt;. If I run Kodi and then look at kodi.log I find:
xbmc.log I find:


<pre> INFO: Loading special://masterprofile/keymaps/keyboard.xml
<pre> INFO: Loading special://masterprofile/keymaps/keyboard.xml
Line 238: Line 159:
             Error reading end tag.</pre>
             Error reading end tag.</pre>


Finally, the Notification action can useful when you're testing your key
Finally, the Notification action can useful when you're testing your key mappings as it displays a little message at the bottom right of the screen to confirm Kodi has processed the keystroke. A typical example
mappings as it displays a little message at the bottom right of the
screen to confirm XBMC has processed the keystroke. A typical example
would be:
would be:


Line 247: Line 166:
and the last argument, 3, is the number of seconds to display the message.
and the last argument, 3, is the number of seconds to display the message.


== Reference ==
== References ==


The ultimate reference for the possible keynames and actions is the
The ultimate reference for the possible keynames and actions is the Kodi source code and in particular the source file ButtonTranslator.cpp, which you can find at https://github.com/xbmc/xbmc/blob/master/xbmc/input/ButtonTranslator.cpp
XBMC source code and in particular the source file
ButtonTranslator.cpp, which you can find at
http://trac.xbmc.org/browser/trunk/xbmc/ButtonTranslator.cpp.


For the key names look for the function CButtonTranslator::TranslateKeyboardString.
For the key names look for the function CButtonTranslator::TranslateKeyboardString.
Line 260: Line 176:
For the sections look for "static const ActionMapping windows[]".
For the sections look for "static const ActionMapping windows[]".


Finally, there are four key modifiers you can use in key mappings:
Finally, there are five key modifiers you can use in key mappings:
 
* {{keypress|ctrl}} or {{keypress|control}}
* {{keypress|shift}}
* {{keypress|alt}}
* {{keypress|win}} or {{keypress|super}} (the Windows key)
* {{keypress|longpress}} (holding down the key)


<ul>
{{note|The {{keypress|shift}} modifier can't be used alone. This is because Kodi isn't case sensitive when processing keystrokes, i.e. a {{keypress|'''g'''}}is the same as a {{keypress|'''G'''}}.}}
<li>ctrl or control</li>
<li>shift</li>
<li>alt</li>
<li>win or super (the Windows key)</li>
</ul>


Note that the shift modifier can't be used alone. This is because XBMC
{{updated|16}}
isn't case sensitive when processing keystrokes, i.e. a g keypress
is the same as a G keypress.


[[category:Inner Workings]]
[[Category:Remotes]]
[[category:Customization]]
[[Category:How-to]]
[[category:Python]]
[[Category:Manual]]
[[category:Remote]]
[[category:Settings]]
[[category:Skin Development]]
[[Category:HTTP API]]

Revision as of 10:19, 28 December 2017

Home icon grey.png   ▶ Remote controls ▶ Keymaps ▶ HOW-TO:Modify keymaps

Note: You can also edit keymaps from within Kodi by using Add-on:Keymap Editor.

Cleanup.png This page or section may require cleanup, updating, spellchecking, reformatting and/or updated images. Please improve this page if you can. The discussion page may contain suggestions.


The keyboard.xml file controls how Kodi reacts to keypresses, that is it determines what action is mapped to what keypress. There are two main reasons for modifying keyboard.xml:

  1. You want to change the standard key mappings because of a personal preference
  2. You are configuring a Media Center remote control that sends keypresses

You can edit keyboard.xml using any text editor such as Notepad++ in Windows or gedit/nano in Linux. The location where the file should be located after creation is in userdata

There is a more detailed discussion of the keyboard.xml file at keymaps, while the remainder of this article is focussed on the gory details of editing it.

Introduction

All the keypresses that Kodi responds to, for example "P" for "play" and "X" for "stop" are configured in a file called keyboard.xml. Actually there are two keyboard.xml files. There is the system keyboard.xml that contains all the standard key mappings, and each user optionally has their own userdata keyboard.xml that contains just their customised key mappings.

The userdata keyboard.xml only needs to contain additional key mappings, or key mappings that override the defaults in the system keyboard.xml. When Kodi is trying to decide how to respond to a keypress it first looks in the userdata keyboard.xml. If it doesn't find a mapping for the keypress Kodi then looks in the system keyboard.xml. This means that the userdata keyboard.xml is typically quite short because it only needs to define mappings for a few keys.

You can change key mappings by editing the system keyboard.xml, but we strongly recommend you don't do this. The system keyboard.xml is a big complicated file, and if you introduce an error into it you can break all the key mappings. Also any changes you make risk being overwritten if you upgrade Kodi. In general you should only ever edit your userdata keyboard.xml. Even if you make a horrendous hash of this you just need to delete or rename your userdata keyboard.xml to restore the default key mappings.

User keymaps are only processed when Kodi starts up, therfore you must restart Kodi to see any changes.

Where to find keyboard.xml

Keymap configuration files are stored in the "keymaps" folder in the userdata folder:


How to edit keyboard.xml

keyboard.xml is just a text file so you can edit it it using any text editor e.g. in Windows use Notepad++. In Windows there is a third party keymap editor available from http://xbmcmce.sourceforge.net/, or this editor is also available through the Add-on:MCERemote add-on.

Windows

To use Notepad++ to edit your userdata keyboard.xml click Start then Run, or in Win7 click Start then All Programs then Accessories then Run, or press the keyboard shortcut  Win+R, then when the Run dialog opens type in:

notepad++ %APPDATA%\Kodi\userdata\keymaps\keyboard.xml
  • If you haven't edited your keyboard.xml before Notepad will ask "Do you want to create a new file?" and you should click Yes.
  • If you use the MCERemote add-on just select the "Edit keyboard.xml" option.

Note: that KeyMapEdit.exe isn't included in the MCERemote add-on by default (because the rules for add-ons prohibit including executable files). You need to go into the add-on settings Misc section and enable the setting "Update/install keymap editor" then select "Edit keyboard.xml".

Linux

Use your favourite text editor e.g. gedit. Remember that the .kodi directory is hidden so you need to show hidden files to see it.

What to put in keyboard.xml

This is an outline rather than a definitive guide. For the full details see keymaps.

A keyboard.xml file will look something like:

<keymap>
  <global>
    <keyboard>
      ... key mappings here
    </keyboard>
  </global>
  <Home>
    <keyboard>
      ... key mappings here
    </keyboard>
  </Home>
  ... and so on
</keymap>

The keyboard.xml must start with <keymap> and end with </keymap>. In between are a number of sections; in the example above the first section is <global>, the second section is <Home>, and there can be lots of other sections as well.

The <global> section defines key mappings that apply everywhere in Kodi unless they are overridden by a mapping in another section. The <Home> section defines key mappings that apply only when you're at the Kodi home screen. Other sections define mappings that apply to other screens, for example the <FullScreenVideo> section defines mappings that apply when you're watching a video full screen. The easiest way to get a list of all the section names is to open the system keyboard.xml in Notepad and look through it.

The key mappings have the form:

<keyname mod="modifiers">SomeAction</keyname>

As with the section names, to see possible key names look at the system keyboard.xml. In fact copying and pasting from the system keyboard.xml is probably the easiest way to construct your custom keyboard.xml.

You need only only include the mod="modifiers" if you want to combine the key with a keyboard modifer like control,  Shift or alt. For example:

<d>Notification(Keypress, You pressed D!, 3)</d>

configures the D key to execute the action Notification(Keypress, You pressed D!, 3) while:

<d mod="ctrl,alt">Notification(Keypress, You pressed ctrl-alt-D!, 3)</d>

configures a control+alt+D keypress to execute the action. Incidentally the Notification action displays a little message at the bottom right of the screen. This can be useful for testing your key mappings.

<d mod="longpress">Notification(Keypress, You kept pressing D!, 3)</d>

configures a long D keypress to execute the action.

An example

This example is going to be a bit contrived, but after all it's only intended as an example of how you might make some more useful key mapping.

Media Center remote controls usually have a button labelled Guide, and when you press it this button usually sends a control+G keystroke. In this example we'll configure the Guide button to display the Info screen except when playing a video, when we'll configure it to show the OSD (On Screen Display). So lets start by defining a global mapping for control+G to display Info:

<keymap>
  <global>
    <keyboard>
      <g mod="ctrl">Info</g>
    </keyboard>
  </global>
</keymap>

From the previous section it should be obvious what this key mapping does so I won't dwell on it further. If you create a userdata keyboard.xml with this mapping and run Kodi you should find that whenever you press control+G it displays the Info screen.

However this will make control+G display Info when playing a video, and we want it to display the OSD instead. To achieve this modify the keyboard.xml to:

<keymap>
  <global>
    <keyboard>
      <g mod="ctrl">Info</g>
    </keyboard>
  </global>
  <FullScreenVideo>
    <keyboard>
      <g mod="ctrl">OSD</g>
    </keyboard>
  </FullScreenVideo>
</keymap>

The global action for control+G is still Info, but the <FullScreenVideo> section overrides the global mapping when playing a video and configures control+G to display the OSD instead.

Debugging

It's easy to make mistakes when writing a keyboard.xml file, and if Kodi finds an error in your keyboard.xml it will simply stop processing it, leaving you wondering why your key mappings aren't working. To check for errors in your keyboard.xml turn debug logging on (in the Settings screen go into System then Debugging and enable the Enable debug logging option), then close Kodi then start it and close it again. Now look in %APPDATA%\Kodi and you'll find a file called kodi.log. Open this file in Notepad and you should be able to find the error.

For example, take the keymapping above but suppose I mistype:

<g mod="ctrl">Info</g>

as

<g mod="ctrl">Info</>

that is I missed the "g" in </g>. If I run Kodi and then look at kodi.log I find:

 INFO: Loading special://masterprofile/keymaps/keyboard.xml
ERROR: Error loading keymap: special://masterprofile/keymaps/keyboard.xml, Line 4
             Error reading end tag.

Finally, the Notification action can useful when you're testing your key mappings as it displays a little message at the bottom right of the screen to confirm Kodi has processed the keystroke. A typical example would be:

<g mod="ctrl">Notification(This is the title, This is the message, 3)</g>

and the last argument, 3, is the number of seconds to display the message.

References

The ultimate reference for the possible keynames and actions is the Kodi source code and in particular the source file ButtonTranslator.cpp, which you can find at https://github.com/xbmc/xbmc/blob/master/xbmc/input/ButtonTranslator.cpp

For the key names look for the function CButtonTranslator::TranslateKeyboardString.

For the actions look for "static const ActionMapping actions[]".

For the sections look for "static const ActionMapping windows[]".

Finally, there are five key modifiers you can use in key mappings:

  • ctrl or control
  •  Shift
  • alt
  •  Win or super (the Windows key)
  • longpress (holding down the key)

Note: The  Shift modifier can't be used alone. This is because Kodi isn't case sensitive when processing keystrokes, i.e. a gis the same as a G.