Introduction

This guide is intended to serve as a reference for users who want to modify the button behavior of their OSMC remote controls. This is not intended as a general guide on key mapping in Kodi, or a thread for general keymap questions. If you need to familiarize yourself with keymaps, or what things you can do with them your first step should be Kodi’s wiki on the subject.

OSMC Legacy Behaviour

The first two generations of the OSMC remote using OSMC prior to the March 2020 update implemented support via eventlircd maps. This method does not support long-press behavior with these remotes. If you want to modify any behavior with this system the easiest method is to install the ‘Keymap Editor’ Kodi add-on. If you find yourself confused on the mass of choices presented there I would direct you to read the first part of Kodi’s keymap wiki which will make understanding how to use the add-on much easier.

Third generation OSMC remotes started shipping in the beginning of 2020. An eventlircd map was never implemented as our intention was to always support long-press functions. We have since decided to support long press functionality on all generations of OSMC remotes.

OSMC Long press update

With the OSMC March 2020 update there have been significant changes to how the OSMC remote interacts with the operating system and Kodi. To address incompatibilities with some keyboard languages and the layouts they use, as well as to simplify support, we have modified the underlying keymapping and how these key presses are delivered to Kodi. This allows for a unified layout for all remotes. We also utilise Kodi’s peripheral input system to allow more flexibility and customisation of the remote’s operation.

Long-press action List

If you have the OSMC custom keymap enabled the most notable long-press actions are listed below along with some deviations of the stock short-press actions. Please note that these are subject to change as this is still a work in progress.

Global Fallback Actions*

  • (Home) Go to home screen
  • (Home Long-press) Toggle fullscreen audio/video playback
  • (Back Long-press) Go to home screen
  • (Menu Long-press) Slideout menu

Home Screen

  • (Home) Send CEC activate source**
  • (Home Long-press) Send CEC standby**
  • (Back Long-press) Power menu
  • (OK Long-press) Reload skin (refreshes db sync for MySQL)
  • (Play Long-press) Update video library

On Screen Keyboard

  • (Up Long-press) Shift
  • (Down Long-press) Symbols
  • (OK Long-press) Enter
  • (Back Long-press) Previous menu

File Manager

  • (Right Long-press) Highlight
  • (Left Long-press) Highlight

Fullscreen Video (Except Live TV)

  • (Home) Bookmarks
  • (Home Long-press) playerdebug overlay
  • (Info Long-press) playerprocessinfo dialog
  • (OK Long-press) Video playlist
  • (Up Long-press) Next item in video playlist***
  • (Down Long-press) Previous item in video playlist***
  • (Left Long-press) Audio delay adjustment
  • (Right Long-press) Subtitle delay adjustment
  • (Back Long-press) Stop
  • (Menu) Video settings
  • (Menu Long-press) Audio settings
  • (Play Long-press) Turn subtitles on/off
  • (Stop Long-press) Subtitle settings

Picture Slideshow

  • (Play) Pause
  • (Up Long-press) Zoom in
  • (Down Long-press) Zoom out
  • (OK Long-press) Zoom normal

Movies and TV Shows Screens

  • (OK Long-press) Toggle view between unwatched and all videos
  • (Play Long-press) Toggle watched status of selected item

Fullscreen Live TV

  • (Left Long-press) Audio delay adjustment
  • (Right Long-press) Subtitle delay adjustment
  • (OK Long-press) Record
  • (Play Long-press) Toggle subtitles
  • (Stop Long-press) Toggle teletext

TV Guide

  • (OK Long-press) Record

Visualisation (Fullscreen Music Playback)

  • (Left Long-press) Rewind
  • (Right Long-press) Fast Forward

*Global fallback actions are what happens when a button doesn’t have a different window specific function assigned to it. For example the (home) button normally takes you to the home screen, but this changes to bringing up chapters/bookmarks during full screen playback.
**CEC actions will only work when they are enabled in Settings>System>Input>Peripherals>CEC Adapter>
***Only works for videos without chapters/bookmarks. If chapters/bookmarks are present (up/down long-press) will provide the same function as (up/down short-press). To go to a previous video playlist item the first (down long-press) will take you to the start of the currently playing video and requires a second (down long-press) immediately after to actually switch to the previous video playlist item. This behavior is due to current Kodi limitations.

My remote works different and I prefer the old behavior

You can turn off the new keymap by going to Settings>System>Input>Peripherals>OSMC RF Remote>Don’t use the custom keymap for this device> [enable] and then reboot Kodi. This will fall back to a keymap that is very close to the old behavior.

My keyboard or secondary controller acts different

Because the OSMC remotes are seen by Kodi as keyboards they share a single keymap with all devices that are also seen as a keyboard. This means that in order to fully customize how our remote acts, we necessarily impact secondary controllers that are sharing the same keyboard keys.

If this poses a minor problem for you then it would probably be best fixed by putting a custom keymap in ~/.kodi/userdata/keymaps that returns the behavior of the key/s at issue.

You can alternatively disable the custom keymap entirely by going to Settings>System>Input>Peripherals>OSMC RF Remote>Don’t use the custom keymap for this device>[enable] and then reboot Kodi.

My custom keys stopped working with the update

Unfortunately there was no way around this. The remotes using eventlircd mappings are keymapped as <remote> whereas in the new system they are <keyboard>. In addition to that, some of the key names used for the remotes with eventlircd are different than what is available for keyboard input.

Hopefully the enhanced function the new setup provides outweighs the inconvenience of remaking any customisations.

How do I customize my keymap (GUI, short-press only)

The simplest method to customizing a keymap is to install the ‘Keymap Editor’ Kodi add-on. This can be found in add-ons>install from repository>Program add-ons. If you find yourself confused on the mass of choices presented there I would direct you to read the first part of Kodi’s keymap wiki which will make understanding how to use the add-on much easier.

A simple explanation of how it works is that you must first choose where you want the button to do something. If you program a button to “global" it becomes the behavior everywhere except where it is already specified to have a different action in a particular screen. If you assign a button to anywhere other than global then that action overrides what is set in global, but it only performs that action when that specific screen is active. Once you find the section and button you want to change simply click on it and you will be presented with an option to select the key you want to map.

Keymap Editor does not support long-press. If you hold down some of the buttons during recording they will come back with an erroneous key id that will not function. If it displays more than five digits, then try again without holding the key down. Additionally, if you manually add any long-press modifiers (and many other action not supported by keymap editor), to the .kodi/userdata/keymaps/gen.xml keymap it creates, they will be lost the next time you open keymap editor (that is not a typo, it happens when you open the add-on, and it happens even if you don’t tell it to save the file). If you want to add unsupported options to a keymap that won’t be affected by this, you should follow the instruction in the next section.

How do I customize my keymap long-press (advanced)

Currently long-press actions can only be mapped by manually creating/editing an xml file. For more novice users I would recommend starting by mapping with keymap editor (as explained in the previous section) which will provide most of the text you need. Map the buttons you want as long-presses temporarily as short-presses. Once you have saved your file in keymap editor it will have made a file called gen.xml in ~/.kodi/userdata/keymaps/. You will then need to make a subfolder called “osmc" and move the gen.xml file into that folder. This can be done via ssh by

cd ~/.kodi/userdata/keymaps/
mkdir osmc
mv gen.xml osmc

You would then need to edit that xml file to add the long-press modifier. To do this you would add mod="longpress" to the opening tags for every action you want it to apply to.

For example

<key id="61624">action</key>

would get changed to

<key id="61624" mod="longpress">action</key>

If you were planning on expanding in the future and wanted it a bit easier to read you can swap out the key id for the key name so it would become

<volume_down mod="longpress">action</volume_down>

The key names are found in the technical section of this guide. To edit via ssh you could type in

nano ~/.kodi/userdata/keymaps/osmc/gen.xml

The preceding only works if you have the remotes custom map enabled. If you want the custom keymap disabled but retain the ability to have a second keymap for long-press that does not get affected by keymap editor, then you would need to go to Settings>System>Input>Peripherals>OSMC RF Remote> and set Don’t use the custom keymap for this device [disable] and then change Keymap to use for this device to something other than “osmc". The name you choose dictates the folder name you will use instead of ~/.kodi/userdata/keymaps/osmc/ A reboot is required for this setting to take effect.

Other operating systems

There are plans to eventually move the peripheral input and its custom keymap from OSMC to Kodi. This would allow the second generation and newer remotes to (mostly) behave the same regardless of where they are being used. The “mostly" part is because there are issues with Kodi language support when the operating system is set to some non-English keyboard layouts. We have worked around this problem in OSMC at the operating system level, but full keyboard language compatibility will remain an issue on other systems absent some update to how Kodi works.

The mapping for this to work has already been included with the custom keymap we’re using in OSMC, but no testing has been done as of the time i’m writing this. If anyone would like to test the OSMC remote on any other operating system please send me a pm.

Technical

All versions of the OSMC remote will map as follows if being used in OSMC running March 2020 update or newer…

Home  = escape        (key id="61467")
Info  = leftbracket   (key id="61480")
Up    = up            (key id="61568")
Down  = down          (key id="61569")
Left  = left          (key id="61570")
Right = right         (key id="61571")
OK    = return        (key id="61453")
Back  = browser_back  (key id="61616")
Menu  = rightbracket  (key id="61481")
Play  = play_pause    (key id="61629")
Stop  = stop          (key id="61628")
Vol-  = volume_down   (key id="61624")
Vol+  = volume_up     (key id="61625")

In other operating system where they have not been setup to run through LIRC, they will appear as a keyboard and can be mapped in Kodi using the following key names.

First generation on other operating systems

Home  = home
Info  = N/A*
Up    = up
Down  = down
Left  = left
Right = right
OK    = return
Back  = browser_back
Menu  = N/A*
Play  = play_pause
Stop  = stop
RW    = rewind
FF    = fastforward
*Key unmappable due to Kodi limitation

Second generation on other operating systems

Home  = home
Info  = i
Up    = up
Down  = down
Left  = left
Right = right
OK    = return
Back  = browser_back
Menu  = c
Play  = play_pause
Stop  = stop
Vol-  = minus
Vol+  = equals

Third generation on other operating systems

Home  = escape
Info  = i
Up    = up
Down  = down
Left  = left
Right = right
OK    = return
Back  = browser_back
Menu  = c
Play  = play_pause
Stop  = stop
Vol-  = minus
Vol+  = equals

Keymap examples

Map first generation rewind/fast forward buttons to control volume 
<keymap>
	<global>
		<keyboard>
			<rewind>volume_down</rewind>
			<fastforward>volume_up</fastforward>
		</keyboard>
	</global>
</keymap>
Replace home button long-press CEC power off at home screen with fullscreen action 
<keymap>
	<Home>
		<keyboard>
			<escape mod="longpress">fullscreen</escape>
		</keyboard>
	</Home>
</keymap>
Disable low battery notification 
<keymap>
	<global>
		<keyboard>
			<f2>noop</f2>
		</keyboard>
	</global>
</keymap>
Make home button dedicated to CEC power control 
<?xml version="1.0" encoding="UTF-8"?>
<keymap>
	<global>
		<keyboard>
			<escape>CECActivateSource</escape>
			<escape mod="longpress">CECStandby</escape>
		</keyboard>
	</global>
	<FullscreenVideo>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</FullscreenVideo>
	<FullscreenGame>
		<keyboard>
			<escape/>
		</keyboard>
	</FullscreenGame>
	<Visualisation>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</Visualisation>
	<MusicOSD>
		<keyboard>
			<escape/>
		</keyboard>
	</MusicOSD>
	<slideshow>
		<keyboard>
			<escape/>
		</keyboard>
	</slideshow>
	<VideoOSD>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</VideoOSD>
	<VideoMenu>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</VideoMenu>
	<VideoBookmarks>
		<keyboard>
			<escape/>
		</keyboard>
	</VideoBookmarks>
	<Videos>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</Videos>
	<VideoPlaylist>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</VideoPlaylist>
	<MusicInformation>
		<keyboard>
			<escape/>
		</keyboard>
	</MusicInformation>
	<MusicPlaylist>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</MusicPlaylist>
	<SongInformation>
		<keyboard>
			<escape/>
		</keyboard>
	</SongInformation>
	<MovieInformation>
		<keyboard>
			<escape/>
		</keyboard>
	</MovieInformation>
	<PictureInfo>
		<keyboard>
			<escape/>
		</keyboard>
	</PictureInfo>
	<PVROSDChannels>
		<keyboard>
			<escape/>
		</keyboard>
	</PVROSDChannels>
	<PVRChannelGuide>
		<keyboard>
			<escape/>
		</keyboard>
	</PVRChannelGuide>
	<AddonInformation>
		<keyboard>
			<escape/>
		</keyboard>
	</AddonInformation>
	<yesnodialog>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</yesnodialog>
	<selectdialog>
		<keyboard>
			<escape/>
		</keyboard>
	</selectdialog>
	<contextmenu>
		<keyboard>
			<escape/>
		</keyboard>
	</contextmenu>
	<addonsettings>
		<keyboard>
			<escape/>
		</keyboard>
	</addonsettings>
	<addonbrowser>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</addonbrowser>
	<filemanager>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</filemanager>
	<interfacesettings>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</interfacesettings>
	<systeminfo>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</systeminfo>
	<eventlog>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</eventlog>
	<playersettings>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</playersettings>
	<mediasettings>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</mediasettings>
	<pvrsettings>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</pvrsettings>
	<servicesettings>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</servicesettings>
	<gamesettings>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</gamesettings>
	<profiles>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</profiles>
	<systemsettings>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</systemsettings>
	<music>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</music>
	<pictures>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</pictures>
	<skinsettings>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</skinsettings>
	<musicplaylisteditor>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</musicplaylisteditor>
	<games>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</games>
	<programs>
		<keyboard>
			<escape/>
			<escape mod="longpress"/>
		</keyboard>
	</programs>
</keymap>