Using an MCE remote control in Windows

From Official Kodi Wiki
Jump to: navigation, search
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.

Most IR Kodi remote controls fall into two classes, remotes compatible with the Microsoft remote (also known as RC6 or eHome remotes) and remotes that send Media Centre keyboard shortcuts. If you have a Microsoft remote (or a compatible such as the Asrock, HP or Mediagate)see the article Using a Microsoft remote control in Windows. This article discusses the remotes that send MCE keyboard shortcuts. If you haven't already done so, you might want to look at the article Using an MCE remote for some general notes on remote controllers.

The good news is that from v10.0 Dharma onwards most MCE remotes will just work with Kodi without needing any tweaking. The only reason for continuing with this article is if you find that some of the buttons on your remote don't work or don't do what you want.


1 How MCE remotes work

The article Using an MCE remote describes the four ways that MCE remotes work in Windows. There are few standards in the world of MCE remotes, so your remote might work in any combination of three ways:

  1. The remote can send the Windows message WM_APPCOMMAND. This message is used to send a multimedia application messages like "Play", "Pause", "Stop" etc.
  2. The remote can simulate multimedia key presses when you press a button. Multimedia keys were introduced with the Microsoft multimedia keyboard, which has extra keys for multimedia functions like "Play" etc.
  3. Finally the remote can simulate the standard MS Media Center keyboard shortcuts. Many cheap MCE remotes simulate these keyboard shortcuts e.g. when you press the Play button they simulate the key press control-shift-P. To use this type of remote an application has to process the Media Center key presses.

Kodi handles all the common APPCOMMAND messages, and it handles all the Media Center keyboard shortcuts. Kodi handles some multimedia keyboard keypresses, but in any case Windows has a tendancy to convert multimedia keypresses into APPCOMMAND messages.

The only option available to you for configuring an MCE remote is to modify the Kodi key mapping to make the key do what you want. For example this remote, Remote Control Reviews#Unbranded MCE remote, helpfully sends a control-alt-F1 keypress when you press the My Music button, and this conforms to no standard that I know of! The remainder of this article describes how to work out what keypress your remote is sending and how to configure Kodi to respond to it.

2 Configuring your MCE remote

There are two steps required:

  1. Work out what keypress your remote sends when you press a button
  2. Configure the Kodi keymapping to respond to that keypress

Step 1 is easy because there is an applet available to display keypresses. Grab a copy of the Showkey applet from On Linux, you can skip the grab part and run showkey program as root. Use your favorite package manager to find the right package to install.

Run this application. You should find that ShowKey reports any key you press e.g. press the Q key on the keyboard and ShowKey will report:

KeyID  81 (0x51) - VK_Q

Press control-Q and you'll see:

KeyID  81 (0x51) - VK_Q
Mod    Ctrl

The ShowKey applet also gives you the line of XML you need in your keyboard.xml file, and this brings us to Step 2.

3 Configuring your keyboard.xml

Editing the keyboard.xml is described in Modifying keyboard.xml. The remainder of this article specifically addresses creating entries for MCE remotes. The article describes using Notepad to modify keyboard.xml, but there is a keymap editor available from or it's included in the MCERemote addon.

Kodi uses a key mapping file called keyboard.xml to determine how it should respond to key presses. There is a system keyboard.xml in C:\Program Files\Kodi\system\keymaps, and you should normally leave this alone. You need to create a personal keyboard.xml in your userdata folder and update this file with your customised key mappings.

The quickest way to edit your userdata keyboard.xml is to press Windows-R to open the Run dialog then type:

notepad %appdata%\Kodi\userdata\keymaps\keyboard.xml

If you are prompted to create a new file answer "Yes".

If you don't already have a keyboard.xml file copy and paste in this template:

      <!-- Put your key mappings here -->

As an example let's take the control-Q keystroke I mentioned above. When you press control-Q ShowKey generates the XML:

<q mod="ctrl">Notification(Key, q, 3)</q>

Copy and paste this into your keyboard.xml, so it looks like:

      <!-- Put your key mappings here -->
      <q mod="ctrl">Notification(Key, q, 3)</q>

Now start Kodi and press control-Q, and a little message should pop up saying you've pressed "q".

The key mappings are fairly obvious: in our example above the <q> means the mapping is for the key "q". The mapping starts with <q> and ends with </q>. If you want to specify control, shift or alt you use mod="ctrl,shift,alt" or any combination. For example:

<q mod="ctrl,alt">

means the key control-alt-Q.

The bit in between <q> and </q> is the action Kodi should take. In this example the "Notification" action pops up a message, which is useful only for debugging.

A quick way to check what keys and actions are available is to open (but don't modify!) C:\Program Files\Kodi\system\keymaps\keyboard.xml as this has lots of useful examples.

There is a list of all the Kodi key names that you can use in keyboard.xml in List of Kodi keynames.

There is a list of all the actions that you can use in keyboard.xml in the articles Action IDs and List of Built In Functions.

4 Troubleshooting

About the only thing that can go wrong is if you make a mistake in your keyboard.xml. The easy way to check this is to turn on debug logging and check your log file. To turn on debug logging go to the settings and select System, then Debugging, then enable Enable debug logging. When you turn on debug logging you'll see some text at the top of the screen showing various info such as CPU usage. This is a quick way to tell if debug logging is on.

As an example suppose I make a deliberate mistake in my keyboard.xml:

      <!-- Put your key mappings here -->
      <q mod="ctrl">Notification(Key, q, 3)<q>

in the <q mod="ctrl"> line i've omitted the "/" in the closing </q>. Now start Kodi and close it again, and examine the Kodi.log by pressing Windows-R and typing:


and search for the text "ERROR:". A few dozen lines down I find:

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

which tells me what my mistake is.

You can also the debug log to tell you how Kodi is processing keypresses. Sticking with my example above of mapping control-Q, start Kodi, turn on debugging and press control-Q a few times. Close Kodi and open the debug log and search for the text SDLKeyboard. You should see:

DEBUG: SDLKeyboard: scancode: 16, sym: 113, unicode: 17, modifier: 40
DEBUG: CApplication::OnKey: 127057 pressed, action is Notification(Key, q, 3)

The SDLKeyboard line reports the keypress while the CApplication::OnKey line tells you what action Kodi took.

5 And finally

That's about it. If your remote is one of those reviewed in the article Remote Control Reviews many of the reviews give you example key mappings for the extra buttons on the remotes.

Personal tools

Wiki help