Official Kodi Wiki - User contributions [en]

HOW-TO:Debug Python Scripts with Web-PDB

2022-01-12T00:40:30Z

Fbacher:

{{mininav|[[Development]]|[[Add-on development]]|[[Python development]]}}

[https://github.com/romanvm/kodi.web-pdb Web-PDB] is a remote web-interface to Python's built-in [https://docs.python.org/3/library/pdb.html PDB] debugger with additional convenience features. It is not tied to any IDE or other software, all you need is a common web-browser, e.g. Chrome or Firefox. Web-PDB is compatible with both Python 2 and 3, so you can use it to debug your Python 3 compatible addons.

[[File:web-pdb.png]]

Web-PDB for Kodi is available as an addon in the official Kodi addons repo.

== How To Use Web-PDB for Kodi ==

1. Install Web-PDB addon: '''Kodi Add-on repository > Program add-ons > Web-PDB'''.

2. Add <code>script.module.web-pdb</code> to [[addon.xml]] as a dependency:
<syntaxhighlight lang="xml" enclose="div">
<requires>
...
<import addon="script.module.web-pdb" version="1.5.6"/>
<requires>
</syntaxhighlight>

3. Restart Kodi so that it re-reads addon dependencies.

4. Insert the following line into your addon code at the point where you want to start debugging:
<syntaxhighlight lang="python" enclose="div">
import web_pdb; web_pdb.set_trace()
</syntaxhighlight>

The <code>set_trace()</code> call will suspend your addon and open a web-UI at the default port 5555 (port value can be changed). At the same time a notification will be displayed in Kodi, indicating that a debug session is active. The notification also shows web-UI host/port.

5. Enter in your the address bar of your browser: <code>http://<your Kodi machine hostname or IP>:5555</code>, for example <code>http://monty-python:5555</code>. Use <code>localhost</code> as a hostname if you are connecting from the same machine that runs Kodi. If everything is OK, you should see the Web-PDB UI. Now you can use all PDB commands and features. Additional '''Current file''', '''Globals''' and '''Locals''' information boxes help you better track your program runtime state.

== More Information ==

* [https://github.com/romanvm/kodi.web-pdb Web-PDB for Kodi on GitHub].
* [https://docs.python.org/2/library/pdb.html PDB debugger documentation].

[[Category:Development]]
[[Category:Python]]

Python Problems

2022-01-11T18:18:29Z

Fbacher:

This page is meant to document Python issues of general interest to Kodi addon developers.
== datetime.strptime ==
There is an old Python bug (https://bugs.python.org/issue27400) which ONLY impacts embedded python applications, such as the Kodi Python environment. The issue is that datetime.strptime is only initialized once per process and not every time the embedded environment is reinitialized. This causes datetime.strptime to return None and perhaps other strange behavior.

One option is for you to replace every reference to datetime.strptime to use a strptime_patch attached to this page. This is less voodoo, but there is always the possibility that some library code uses strptime and there will still be potential for incorrect results or a Kodi crash (script.module.youtube.dl crashed Kodi for a while).

The other option is to monkey-patch datetime.strptime so that any user of the python runtime will use it. It is voodoo like, but that is why Python supports Monkey patching. See Python documentation on datetime.strptime (https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior). It discusses some of the differences between datetime.strptime and time.strptime.

This patch simply replaces datetime.strptime with time.strptime. They are nearly identical in function. For more information, see: https://github.com/fbacher/script.module.kutils/blob/master/lib/kutils/strptime_patch.py. Essentially the patch is:

@staticmethod
def monkey_patch_strptime():
# Check if problem exists (don't want to stomp on patch applied earlier)
try:
datetime.datetime.strptime('0', '%H')
except TypeError:
# Globally replace Python's datetime.datetime.strptime with
# the version here.
datetime.datetime = StripTimePatch.strptime
@staticmethod
def strptime(date_string: str, date_format: str) -> datetime.datetime:
result: datetime.datetime
result = datetime.datetime(*(time.strptime(date_string, date_format)[0:6]))
return result

Python Problems

2022-01-11T18:14:58Z

Fbacher:

This page is meant to document Python issues of general interest to Kodi addon developers.
== datetime.strptime ==
There is an old Python bug (https://bugs.python.org/issue27400) which ONLY impacts embedded python applications, such as the Kodi Python environment. The issue is that datetime.strptime is only initialized once per process and not every time the embedded environment is reinitialized. This causes datetime.strptime to return None and perhaps other strange behavior.

One option is for you to replace every reference to datetime.strptime to use a strptime_patch attached to this page. This is less voodoo, but there is always the possibility that some library code uses strptime and there will still be potential for incorrect results or a Kodi crash (script.module.youtube.dl crashed Kodi for a while).

The other option is to monkey-patch datetime.strptime so that any user of the python runtime will use it. It is voodoo like, but that is why Python supports Monkey patching. See Python documentation on datetime.strptime (https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior). It discusses some of the differences between datetime.strptime and time.strptime.

This patch simply replaces datetime.strptime with time.strptime. They are nearly identical in function. For more information, see: https://github.com/fbacher/script.module.kutils/blob/master/lib/kutils/strptime_patch.py. Essentially the patch is:

<nowiki> @staticmethod
def monkey_patch_strptime():
# Check if problem exists (don't want to stomp on patch applied earlier)
try:
datetime.datetime.strptime('0', '%H')
except TypeError:
# Globally replace Python's datetime.datetime.strptime with
# the version here.

datetime.datetime = StripTimePatch.strptime

@staticmethod
def strptime(date_string: str, date_format: str) -> datetime.datetime:
result: datetime.datetime
result = datetime.datetime(*(time.strptime(date_string, date_format)[0:6]))
return result
</nowiki>

Python Problems

2022-01-11T15:22:41Z

Fbacher: Created page with "This page is meant to document Python issues of general interest to Kodi addon developers. == datetime.strptime == There is an old Python bug (https://bugs.python.org/issue274..."

Unicode Concerns

2022-01-09T16:40:19Z

Fbacher:

This page highlights some of the Unicode Issues beyond simply enabling your addon or Kodi runtime for basic Unicode support. Here are a few:

* The good news is that for the bulk of your work, it is fairly simple to read and display translated messages. The basic plumbing is in place.
* Side effects of Kodi issue 19883: Turkish locale set via LANG / LC_CTYPE / LC_ALL or by SetGlobalLocale breaks skin loading on any Linux. (github.com/xbmc/xbmc/issues/19883)
* Handling text from multiple locales (i.e complications with foreign movies or actors)
* How to handle internal programming keywords along with other text
* Quirks of some languages
* Searching multilingual text
* Unicode file names
* Unicode in XML
* Unicode file names in a zip file
* Json or XML processing of Unicode with keywords
* Lower/Upper case does not take you very far
* String length != number of Unicode 'letters'
* The same character (both visually and logically) can sometimes be represented by more than one sequence of Unicode 'letters'
* Minimal support in Python and C++
* Other Unicode libs exist, but non-trivial to use

A good source of information can be found at: [https://www.unicode.org/versions/Unicode14.0.0/ch05.pdf Unicode.org]. This same organization provides a good (but not the easiest to learn) and free library that performs advanced Unicode processing.

== Details: ==

=== Side effects of Kodi issue 19883 ===
Kodi was unusable with Locale = tr_TR (Turkish). A quick fix was made, but it has some undesirable side-effects on the Python addons:
* The default locale cannot be read, making it impossible to determine the country code ('US')
* The encoding for filenames is ASCII instead of UTF-8. Trying to open a file with a non-ASCII name throws exceptions. You have to explicitly encode the filename (ex: io.open(self.path.encode('utf-8'))).

On closer inspection, the Kodi C++ application has multiple problems:
As is common with many programs, keywords are caseless and the code normalized all keywords to lower case. However, there are multiple problems with this:
* ToLower works with most, but not all locales/character sets since in almost all languages ToUpper(ToLower(char)) == char. However Turkish (and others) have several characters that do not obey this rule. In addition, several of these characters are in common with English. The letter 'i' is one of the characters.
* Kodi uses the same locale for processing external text as well as internal keywords. This caused any keyword containing an 'I' to be unrecognized because ToLower would change the 'I' to a Turkish, 'dotless lower case i'

In addition, ToLower and ToUpper modifies the passed string in-place. However, there is no guarantee in Unicode that the number of bytes, or Unicode characters will be the same. This means that junk can be left at the end of the string array, or memory could be clobbered at the end of the array.

The proper solution is to create methods which handle the different ways that characters are used. Instead of using in-line calls to toLower, etc. you need methods which:
* Creates a setting keyword from a string
** Frequently keywords are looked up in a 'caseless' manner. But with the possibility of text being in any language things get more complicated.
** One approach is to restrict the keyword characters in some way and then to use a specific locale just when handling the keywords. You run into trouble if you process some English characters using Turkish locale (the infamous 'i' problem).
** Another approach is to "case fold" the characters. In simplistic terms the string is stripped of all accents, etc. and made lower-case. It is not meant for human consumption but generally works well for matching keywords. It has the advantage of being locale agnostic.
* Creates a filename from a string
** Some Operating Systems (Windows) internally identify the files with a caseless filename. Generally you want to compare filenames in a caseless manner (not sure if it should be done in a folded manner or not).
* Compares strings to see if string matches one of a list of keywords. You may need different methods for different keyword types
* Search and sort methods customized for the purpose and volume of searching

In C++ you have to worry about allocating and freeing memory for toLower, normalized, caseless or other forms of the original strings. More correctly, they are transformations on the string which can change the number of bytes that the strings take up, requiring a copy. Your method signatures frequently need to pass a pointer to this temporary string around until it is finally freed.

=== Setting names in Settings.xml ===
Although not widely documented, setting names are considered caseless, and are all mapped to lower case, as keywords are, above. The same problems exist. Addon programmers may be unaware of this. This means that in addition to the Kodi back-end treating setting names as keywords, Python addonss must do the same thing when comparing or manipulating these setting names.
=== Searching Text ===
Kodi provides the ability to search for movie title within the current playlist by simply (quickly) typing the first few characters [in upper case] of the title to search for.
This won't work properly for several reasons:
# The above ToLower/ToUpper problem
# Character collation rules vary for different locales. If the user is searching for a foreign language movie title, it may not be processed/sorted as expected. Some common way of searching/sorting needs to converged on.

There are several approaches to solving the second problem. One is to do a caseless, accentless comparison. It looks like SQLLite and MySQL both support these. Extra columns or tables (for caseless, accentless copies of the search data) may be needed to improve performance. For some discussion on the topic see: https://www.unicode.org/versions/Unicode14.0.0/ch05.pdf

Python libraries

2022-01-09T13:23:14Z

Fbacher: URL changed

Kodi Python comes with all the standard modules from Python 3.8 or later. See https://docs.python.org/3.8/library/ for reference.

== Built-in modules ==
In addition to the standard libraries, Kodi Python uses a handful of custom modules to expose Kodi functionality to Python.

Up to date documentation about these modules can be found at https://xbmc.github.io/docs.kodi.tv/master/kodi-dev-kit/

{| border=1 cellspacing=0 cellpadding=5
| '''Module'''
| '''Description'''
|-
| xbmc
| Offers classes and functions that provide information about the media currently playing and that allow manipulation of the media player (such as starting a new song). You can also find system information using the functions available in this library.
|-
| xbmcgui
| Offers classes and functions that manipulate the Graphical User Interface through windows, dialogs, and various control widgets.
|-
| xbmcplugin
| Offers classes and functions that allow a developer to present information through XBMC's standard menu structure. While plugins don't have the same flexibility as scripts, they boast significantly quicker development time and a more consistent user experience.
|-
| xbmcaddon
| Offers classes and functions that manipulate the add-on settings, information and localization.
|-
| xbmcvfs
| Offers classes and functions offers acces to the Virtual File Server (VFS) which you can use to manipulate files and folders.
|}

== Third-party modules ==
Numerous python modules are already packages as add-ons that can be imported by other add-on. See [[:Category:Add-on_libraries/modules]] for a list of available modules. To use any of these modules with your add-on, add the relevant line to [[Addon.xml#.3Crequires.3E|Addon.xml]]

== Installing additional modules ==
Additional modules may be installed by simply adding the module to the root folder of your add-on.

A common way to organized third-party modules that are not part of add-on source code itself, is to add a <code>lib</code> directory and place an <code>__init__.py</code> file and other third-party modules inside it. These modules may then normally be imported using <code>from lib import somemodule</code>.

[[Category:Add-on development]]

Unicode Concerns

2022-01-04T02:54:45Z

Fbacher: Created page with "This page addresses Unicode Issues beyond simply enabling your addon or Kodi runtime for basic Unicode support.Some of the issues are: Side effects of Kodi issue 19883: Turki..."

This page addresses Unicode Issues beyond simply enabling your addon or Kodi runtime for basic Unicode support.Some of the issues are:

Side effects of Kodi issue 19883: Turkish locale set via LANG / LC_CTYPE / LC_ALL or by SetGlobalLocale breaks skin loading on any Linux. (github.com/xbmc/xbmc/issues/19883)

Handling text from multiple locales (i.e complications with foreign movies or actors)

How to handle internal programming keywords along with other text.

Quirks of some languages

Searching multilingual text

Unicode file names

Unicode in XML

Unicode file names in a zip file

Json or XML processing of Unicode with keywords

Details:

Side effects of Kodi issue 19883
Kodi is unusable with Locale = tr_TR (Turkish). A quick fix was made, but it has some undesirable side-effects on the Python addons:
The default locale cannot be read, making it impossible to determine the country code ('US').
The encoding for filenames is ASCII instead of UTF-8. Trying to open a file with a non-ASCII name throws exceptions.

On closer inspection, the Kodi C++ application has multiple problems:
As is common with many programs, keywords are caseless and the code normalized all keywords to lower case. however, there are multiple problems with this:
ToLower works with most, but not all locales/character sets since in almost all languages ToUpper(ToLower(char)) == char. However Turkish has several characters that do not obey this rule. In addition, several of these characters are in common with English. The letter 'i' is one of the characters.
Kodi used the same locale for processing external text as well as internal keywords. This caused any keyword containing an 'I' to be unrecognized because ToLower would change the 'I' to a Turkish, 'dotless lower case i'

In addition, ToLower and ToUpper modifies the passed string in-place. However, there is no guarantee in Unicode that the number of bytes, or Unicode characters will be the same. This means that junk can be left at the end of the string array, or memory could be clobbered at the end of the array.

The proper solution is to pass the locale to the ToLower/ToUpper methods and for the caller to use a locale which is known to be stable for all of the keywords (such as en_GB or en_US, since the code was originally developed using those locales). Callers processing just normal [Turkish] text, should pass the Turkish locale.

Setting names in Settings.xml
Although not widely documented, setting names are considered caseless, and are all mapped to lower case, as keywords are, above. The same problems exist. Addon programmers may be unaware of this. This means that in addition to the Kodi back-end treating setting names as keywords, Addon Python (or other) code must do the same thing when comparing or manipulating these setting names: the addon must do any manipulation (lower/upper) using a safe locale (i.e. en_GB).

Searching Text
Kodi provides the ability to search for movie title within the current playlist by simply (quickly) typing the first few characters [in upper case] of the title to search for.
This won't work properly for several reasons:
1- The above ToLower/ToUpper problem
2- Character collation rules vary for different locales. If the user is searching for a foreign language movie title, it may not be processed/sorted as expected. [This problem may not exist]

There are several approaches to solving the second problem. One is to do a caseless, accentless comparison. It looks like SQLLite and MySQL both support these. Extra columns or tables (for caseless, accentless copies of the search data) may be needed to improve performance.

Python libraries

2021-07-02T12:42:22Z

Fbacher: Update link to python 3.8

Kodi Python comes with all the standard modules from Python 3.8 or later. See https://docs.python.org/3.8/library/ for reference.

== Built-in modules ==
In addition to the standard libraries, Kodi Python uses a handful of custom modules to expose Kodi functionality to Python.

Up to date documentation about these modules can be found at https://codedocs.xyz/xbmc/xbmc/group__python.html

{| border=1 cellspacing=0 cellpadding=5
| '''Module'''
| '''Description'''
|-
| xbmc
| Offers classes and functions that provide information about the media currently playing and that allow manipulation of the media player (such as starting a new song). You can also find system information using the functions available in this library.
|-
| xbmcgui
| Offers classes and functions that manipulate the Graphical User Interface through windows, dialogs, and various control widgets.
|-
| xbmcplugin
| Offers classes and functions that allow a developer to present information through XBMC's standard menu structure. While plugins don't have the same flexibility as scripts, they boast significantly quicker development time and a more consistent user experience.
|-
| xbmcaddon
| Offers classes and functions that manipulate the add-on settings, information and localization.
|-
| xbmcvfs
| Offers classes and functions offers acces to the Virtual File Server (VFS) which you can use to manipulate files and folders.
|}

== Third-party modules ==
Numerous python modules are already packages as add-ons that can be imported by other add-on. See [[:Category:Add-on_libraries/modules]] for a list of available modules. To use any of these modules with your add-on, add the relevant line to [[Addon.xml#.3Crequires.3E|Addon.xml]]

== Installing additional modules ==
Additional modules may be installed by simply adding the module to the root folder of your add-on.

A common way to organized third-party modules that are not part of add-on source code itself, is to add a <code>lib</code> directory and place an <code>__init__.py</code> file and other third-party modules inside it. These modules may then normally be imported using <code>from lib import somemodule</code>.

[[Category:Add-on development]]

JSON-RPC API

2019-08-23T18:50:16Z

Fbacher: Need to find correct information about JSON-RPC for Leia, since prior note says that it is v10.

{{mininav|[[Development]]}}

{{JSON-RPC API nav}}
<br />

{{cleanup}}

JSON-RPC is a HTTP- and/or raw TCP socket-based interface for communicating with Kodi. It replaces the deprecated [[HTTP API]], and offers a more secure and robust mechanism in the same format. It is based upon the [http://jsonrpc.org/spec.html JSON-RPC 2.0 specification].

Each method in the interface can have different security needs which means one client may be allowed to only control playback while another can only read and manipulate the library. In version 2 (first stable) and 4 all clients are granted full authority but will later be forced to ask for privileges and the user of Kodi will have to grant said client access. The design of JSON-RPC is that most methods should behave roughly the same and maintain consistency while hiding the mechanics of Kodi from the client creator.

In Kodi JSON-RPC can be accessed over a variety of transports and has been designed from the ground up to be flexible to allow control over new transports easily. Some of the transports have different limitations which will be enforced upon the interaction over that transport. As an example HTTP transports allow response and downloading of files while the raw TCP transport allows response and notifications (events and information Kodi sends to its clients). Depending on the client's needs it will choose one (or many) of the available transports.<br />

== Enabling JSON-RPC ==
Since the interface is available on many transports enabling it depends on the transport.
* Python: Always enabled
* HTTP: In System/Settings/Network/Services activate ''Allow control of Kodi via HTTP'' (see [[Webserver#Enabling the webserver|Enabling the webserver]])
* TCP: In System/Settings/Network/Services activate ''Allow programs on this system to control Kodi'' for localhost access only and ''Allow programs on other systems to control Kodi'' for access from other computers as well

Note: The [[EventServer]] is a different interface for sending remote keypresses to Kodi, and must be enabled separately, some programs may use both interfaces.

== Transports & Functionalities ==
=== Transports ===
==== Python ====
The ''Python'' transport can only be used by Kodi addons through the '''executeJSONRPC''' method provided by the '''xbmc''' python library. As it must be available to every addon in an Kodi installation it must not be enabled or disabled by the user.

==== HTTP ====
The ''HTTP'' transport can be used by third-party applications running on the same machine as Kodi or on a different machine which can access the machine running Kodi using the [http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] protocol. Because this transport allows applications outside Kodi to control Kodi, it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user.

===== POST =====
Third-party applications can access Kodi's JSON-RPC API by sending JSON-RPC requests embedded in HTTP [http://en.wikipedia.org/wiki/POST_(HTTP) POST] requests to the following URL
<pre>http://<your-ip>:<your-port>/jsonrpc</pre>

Starting with Frodo nightly builds it is mandatory to set the HTTP header field '''Content-Type: application/json'''

===== GET =====
Third-party application can access Kodi's JSON-RPC API by sending JSON-RPC requests embedded in a HTTP GET parameter called ''request''. The JSON-RPC request must be URL encoded and sent to the following URL
<pre>http://<your-ip>:<your-port>/jsonrpc?request=<url-encoded-request></pre>

==== TCP ====
The ''TCP'' transport can be used by third-party applications running on the same machine as Kodi or on a different machine which can access the machine running Kodi using the [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] protocol. Because this transport allows applications outside Kodi to control Kodi it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user. Once enabled, third-party applications can access Kodi's JSON-RPC API by opening a TCP [http://en.wikipedia.org/wiki/Internet_socket socket] on port 9090 (this port can be configured in the [[Advancedsettings.xml#<jsonrpc>|advanced settings]] file) and sending raw JSON-RPC requests over that socket. Please note that no delimiters are provided in between notifications and/or responses. As such, your client needs to be able to deal with this, eg. by counting and matching curly braces ({}).

==== WebSocket ====
The ''WebSocket'' transport has been added since Version 5 and can be used by third-party applications running on the same machine as Kodi or on a different machine which can access the machine running Kodi using the [http://en.wikipedia.org/wiki/WebSocket Websocket] protocol. The supported versions are 8 (draft [http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10 hybi-10]) and 13 ([http://tools.ietf.org/html/rfc6455 RFC 6455]). Because this transport allows applications outside Kodi to control Kodi it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user. Once enabled, third-party applications can access Kodi's JSON-RPC API by sending a WebSocket protocol handshake to the following URI
<pre>ws://<your-ip>:<configured tcp port>/jsonrpc</pre>
It is important to send the handshake on the port of Kodi's TCP server (by default 9090, but this port can be configured in the [[Advancedsettings.xml#<jsonrpc>|advanced settings]] file). After having successfully finished the handshake third-party applications can send WebSocket protocl messages over that connection.

=== Functionalities ===
==== Response ====
The ''Response'' functionality is the only functionality that should be present in every transport available as it describes the functionality to respond to a JSON-RPC request with a valid JSON-RPC response (be it an error message or an actual response).

==== Notifications ====
The ''Notifications'' functionality includes both server-side (from the server to clients) and client-side (from clients to the server) notifications. A JSON-RPC notification is a valid JSON-RPC request with no ''id'' property. Following the JSON-RPC 2.0 specification any JSON-RPC request with no ''id'' must be considered as a notification and the receiver must not send a response upon a notification.

In the specific case of Kodi, server-side notifications are used to inform clients about certain events to relieve clients of the need to periodically poll for certain events. Furthermore there are two ways of client-side notifications. Using [[/#JSONRPC.NotifyAll|JSONRPC.NotifyAll]] it is possible to ask Kodi to relay the message in the JSON-RPC request to all other connected clients. The second way is to send JSON-RPC requests without an ''id'' property in case the client does not care about the response (e.g. the method [[/#Player.Stop|Player.Stop]] does not return any useful information to the client).

==== Direct file download ====
The ''Direct file download'' functionality is the ability to directly download files from Kodi by calling [[/#Files.Download|Files.Download]]. In this case the term ''direct'' means that the download happens within the JSON-RPC response of the [[/#Files.Download|Files.Download]] request.

==== Redirected file download ====
The ''Redirected file download'' functionality is the ability to indirectly download files from Kodi by calling [[/#Files.PrepareDownload|Files.PrepareDownload]] and using the data received in the response to download the file over a different protocol (like HTTP, FTP ...) or another socket. As the ''Redirected file download'' is very transport specific, it must be handled separately for every transport supporting it.

=== Comparison ===
The following table shows all the available transports and what functionalities they support
{| class="prettytable" style="margin-right: 0;"
!style="padding-left: 5px; padding-right: 10px;" colspan="2"|Transport
!style="padding-left: 10px; padding-right: 10px;"|Response
!style="padding-left: 10px; padding-right: 10px;"|Notifications
!style="padding-left: 10px; padding-right: 10px;"|Direct file<br />download
!style="padding-left: 10px; padding-right: 10px;"|Redirected file<br />download
|-
|style="padding-left: 5px;" colspan="2"|[[Python Development|Python]]
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px;" colspan="2"|[http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP]
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right:5px;" rowspan="2"|[http://en.wikipedia.org/wiki/HTTP HTTP]
|style="padding-left: 5px; padding-right:5px;"|POST
|{{yes}}
|{{no}}
|{{no}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right:5px;"|GET<sup>1</sup>
|{{yes}}
|{{no}}
|{{no}}
|{{yes}}
|-
|style="padding-left: 5px;" colspan="2"|[http://en.wikipedia.org/wiki/WebSocket WebSocket]<sup>1</sup>
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|}
<sup>1</sup> Added in Version 5

== API versions ==
The JSON-RPC API exposed by Kodi is constantly extended to provide better and more functionality to third party applications. For that reason Kodi provides a version information through the '''JSONRPC.Version''' method. The rule is that odd version numbers describe an API state, that is not stable and under heavy development whereas even version numbers describe a stable API. Therefore the version number can be used by third-party clients to check if their application might not be fully compatible with the JSON-RPC API exposed by a user's Kodi installation.

Starting with XBMC v12 (Frodo) we started using a new versioning system (<major>.<minor>.<patch>) for the JSON-RPC API. Frodo stable is version 6.0.0 and from now on with every bugfix the <patch> part of the version is increased, with every feature addition to the API, the <minor> version is increased (and the <patch> version reset to 0) and with every backwards incompatible change, the <major> version is increased.

{| class="prettytable" style="margin-right: 0;"
!colspan="3"|Release
!colspan="6"|JSON-RPC 2.0 specification
!colspan="5"|Transports
|-
!style="padding-left: 5px; padding-right: 5px; width: 6em; text-align: left;"|API Version
!style="padding-left: 10px; padding-right: 10px; width: 5em;"|Version
!style="padding-left: 10px; padding-right: 10px; width: 4em;"|Name
!style="padding-left: 10px; padding-right: 10px;"|Method calls
!style="padding-left: 10px; padding-right: 10px;"|Notifications<br />(server-side)
!style="padding-left: 10px; padding-right: 10px;"|Notifications<br />(client-side)
!style="padding-left: 10px; padding-right: 10px;"|Parameters<br />by-name
!style="padding-left: 10px; padding-right: 10px;"|Parameters<br />by-position
!style="padding-left: 10px; padding-right: 10px;"|Batch requests

!style="padding-left: 10px; padding-right: 10px;"|Python
!style="padding-left: 10px; padding-right: 10px;"|TCP
!style="padding-left: 10px; padding-right: 10px;"|HTTP POST
!style="padding-left: 10px; padding-right: 10px;"|HTTP GET
!style="padding-left: 10px; padding-right: 10px;"|WebSocket
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v2|Version 2]]
|style="padding-left: 5px; padding-right: 5px;"|10.0
|style="padding-left: 5px; padding-right: 5px;"|Dharma
|{{yes}}
|{{yes}}
|{{no}}
|{{yes}}
|{{no}}
|{{no}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v3|Version 3]] / [[/v4|4]]
|style="padding-left: 5px; padding-right: 5px;"|pre-11 / 11.0
|style="padding-left: 5px; padding-right: 5px;"|Eden
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v5|Version 5]] / [[/v6|6]]
|style="padding-left: 5px; padding-right: 5px;"|pre-12 / 12.0
|style="padding-left: 5px; padding-right: 5px;"|Frodo
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|13.0
|style="padding-left: 5px; padding-right: 5px;"|Gotham
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|13.1
|style="padding-left: 5px; padding-right: 5px;"|Gotham
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|13.2
|style="padding-left: 5px; padding-right: 5px;"|Gotham
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|14.0
|style="padding-left: 5px; padding-right: 5px;"|Helix
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|14.1
|style="padding-left: 5px; padding-right: 5px;"|Helix
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|14.2
|style="padding-left: 5px; padding-right: 5px;"|Helix
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|15.0
|style="padding-left: 5px; padding-right: 5px;"|Isengard
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|15.1
|style="padding-left: 5px; padding-right: 5px;"|Isengard
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|15.2
|style="padding-left: 5px; padding-right: 5px;"|Isengard
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|16.0
|style="padding-left: 5px; padding-right: 5px;"|Jarvis
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|16.1
|style="padding-left: 5px; padding-right: 5px;"|Jarvis
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v8|Version 8]]
|style="padding-left: 5px; padding-right: 5px;"|17.0
|style="padding-left: 5px; padding-right: 5px;"|Krypton
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}<sup>1</sup>
|{{yes}}
|-
|}
<sup>1</sup>For information requests only, actions require POST

{| class="prettytable" style="margin-right: 0;"
!colspan="3"|Release
!|JSONRPC.Version
|-
!style="padding-left: 10px; padding-right: 10px;"|Date
!style="padding-left: 10px; padding-right: 10px;"|Version
!style="padding-left: 10px; padding-right: 10px;"|Codename
!style="padding-left: 10px; padding-right: 10px;"|["version"]
|-
|18 December 2010
|10.0
|Dharma
|2
|-
|10 March 2011
|10.1
|Dharma
|2
|-
| style="background:#eee;" |24 March 2012
| style="background:#eee;" |11.0
| style="background:#eee;" |Eden
| style="background:#eee;" |4
|-
|29 January 2013
|12.0
|Frodo
|{"major":6,"minor":0,"patch":0}
|-
|18 March 2013
|12.1
|Frodo
|{"major":6,"minor":0,"patch":3}
|-
|03 May 2013
|12.2
|Frodo
|{"major":6,"minor":0,"patch":3}
|-
|24 December 2013
|12.3
|Frodo
|{"major":6,"minor":0,"patch":3}
|-
| style="background:#eee;" | 04 May 2014
| style="background:#eee;" | 13.0
| style="background:#eee;" | Gotham
| style="background:#eee;" | {"major":6,"minor":14,"patch":3}
|-
| style="background:#eee;" | 05 June 2014
| style="background:#eee;" | 13.1
| style="background:#eee;" | Gotham
| style="background:#eee;" | {"major":6,"minor":14,"patch":3}
|-
| style="background:#eee;" | 17 August 2014
| style="background:#eee;" | 13.2
| style="background:#eee;" | Gotham
| style="background:#eee;" | {"major":6,"minor":14,"patch":3}
|-
|23 December 2014
|14.0
|Helix
|{"major":6,"minor":21,"patch":2}
|-
|30 January 2014
|14.1
|Helix
|{"major":6,"minor":21,"patch":2}
|-
|26 March 2014
|14.2
|Helix
|{"major":6,"minor":21,"patch":2}
|-
| style="background:#eee;" | 21 July 2015
| style="background:#eee;" | 15.0
| style="background:#eee;" | Isengard
| style="background:#eee;" | {"major":6,"minor":25,"patch":2}
|-
| style="background:#eee;" | 16 August 2015
| style="background:#eee;" | 15.1
| style="background:#eee;" | Isengard
| style="background:#eee;" | {"major":6,"minor":25,"patch":2}
|-
| style="background:#eee;" | 19 October 2015
| style="background:#eee;" | 15.2
| style="background:#eee;" | Isengard
| style="background:#eee;" | {"major":6,"minor":25,"patch":2}
|-
|21 February 2016
|16.0
|Jarvis
|{"major":6,"minor":32,"patch":4}
|-
|24 April 2016
|16.1
|Jarvis
|{"major":6,"minor":32,"patch":5}
|-
| style="background:#eee;" | 5 February 2017
| style="background:#eee;" | 17.0
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 20 March 2017
| style="background:#eee;" | 17.1
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 23 May 2017
| style="background:#eee;" | 17.2
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 24 May 2017
| style="background:#eee;" | 17.3
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 22 August 2017
| style="background:#eee;" | 17.4
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 23 October 2017
| style="background:#eee;" | 17.5
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 14 November 2017
| style="background:#eee;" | 17.6
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
|}

== Documentation ==
Kodi's JSON-RPC API has been designed to be self-documented i.e. a call to [[/#JSONRPC.Introspect|JSONRPC.Introspect]] results in a JSON-RPC response containing a documentation for all the available methods and data types. While this documentation is very incomplete and partly wrong for [[/v2|version 2]] it is provided as a full [http://tools.ietf.org/html/draft-zyp-json-schema-03 JSON schema] starting with [[/v3|version 3]]. As the documentation retrieved in that way is always specific to the used version of Kodi, it is (especially for development versions) the best documentation available and should be preferred over the wiki documentation as the latter always documents the API of the latest development.

== Debugging ==
=== Output format ===
To be able to support easier debugging of (third-party) development using the JSON-RPC API, the JSON output generated by Kodi can be pretty-printed by setting
<syntaxhighlight lang="xml" enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
</jsonrpc>
</syntaxhighlight>
in the [[Advancedsettings.xml#.3Cjsonrpc.3E|advancedsettings.xml]]. Default JSON output will be in compact format to minimize sent data (especially useful for mobile devices).

=== Direct interaction ===
To be able to test some methods of Kodi's JSON-RPC API, it can be of great help to be able to send a single hand-written JSON-RPC request to Kodi to see its effect and the generated response. Depending on the transport protocol used there are different possibilities to do that:

==== TCP ====
With a [http://en.wikipedia.org/wiki/Telnet telnet] connection (using [http://en.wikipedia.org/wiki/PuTTY PuTTY] on Windows or telnet on Linux) to port 9090 of the machine running Kodi it is possible to send and receive raw json data to/from Kodi. {{see also|SSH}}

==== HTTP ====
A simple way of manually sending HTTP requests containing a JSON-RPC request to Kodi is using the [http://chrome.google.com/extensions/detail/fhjcajmcbmldlhcimfajhfbgofnpcjmb Simple REST Client] extension for Google's Chrome/Chromium browser. It allows defining a URL and the HTTP request type ('''POST''' is what we need). The actual JSON-RPC request can be defined in the '''Data''' field and then sent to Kodi.

== See also ==
* [[/v2|JSON-RPC API v2 (Dharma)]]
* [[/v4|JSON-RPC API v4 (Eden)]]
* [[/v6|JSON-RPC API v6 (Frodo - Jarvis)]]
* [[/v8|JSON-RPC API v8 (Krypton)]]

== External links ==
* [http://jsonrpc.org/spec.html JSON-RPC 2.0 specification]
* [http://tools.ietf.org/html/draft-zyp-json-schema-03 A JSON Media Type for Describing the Structure and Meaning of JSON Documents (Draft 03)]

== Examples ==
These examples take their base from v4. Any that require a higher version will be marked.

[[JSON-RPC API/Examples]]

[[Category:Manual]]
[[Category:Development]]

JSON-RPC API

2019-08-23T18:44:04Z

Fbacher: Added basic info and link to JSON-RPC 18

{{mininav|[[Development]]}}

{{JSON-RPC API nav}}
<br />

{{cleanup}}

JSON-RPC is a HTTP- and/or raw TCP socket-based interface for communicating with Kodi. It replaces the deprecated [[HTTP API]], and offers a more secure and robust mechanism in the same format. It is based upon the [http://jsonrpc.org/spec.html JSON-RPC 2.0 specification].

Each method in the interface can have different security needs which means one client may be allowed to only control playback while another can only read and manipulate the library. In version 2 (first stable) and 4 all clients are granted full authority but will later be forced to ask for privileges and the user of Kodi will have to grant said client access. The design of JSON-RPC is that most methods should behave roughly the same and maintain consistency while hiding the mechanics of Kodi from the client creator.

In Kodi JSON-RPC can be accessed over a variety of transports and has been designed from the ground up to be flexible to allow control over new transports easily. Some of the transports have different limitations which will be enforced upon the interaction over that transport. As an example HTTP transports allow response and downloading of files while the raw TCP transport allows response and notifications (events and information Kodi sends to its clients). Depending on the client's needs it will choose one (or many) of the available transports.<br />

== Enabling JSON-RPC ==
Since the interface is available on many transports enabling it depends on the transport.
* Python: Always enabled
* HTTP: In System/Settings/Network/Services activate ''Allow control of Kodi via HTTP'' (see [[Webserver#Enabling the webserver|Enabling the webserver]])
* TCP: In System/Settings/Network/Services activate ''Allow programs on this system to control Kodi'' for localhost access only and ''Allow programs on other systems to control Kodi'' for access from other computers as well

Note: The [[EventServer]] is a different interface for sending remote keypresses to Kodi, and must be enabled separately, some programs may use both interfaces.

== Transports & Functionalities ==
=== Transports ===
==== Python ====
The ''Python'' transport can only be used by Kodi addons through the '''executeJSONRPC''' method provided by the '''xbmc''' python library. As it must be available to every addon in an Kodi installation it must not be enabled or disabled by the user.

==== HTTP ====
The ''HTTP'' transport can be used by third-party applications running on the same machine as Kodi or on a different machine which can access the machine running Kodi using the [http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] protocol. Because this transport allows applications outside Kodi to control Kodi, it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user.

===== POST =====
Third-party applications can access Kodi's JSON-RPC API by sending JSON-RPC requests embedded in HTTP [http://en.wikipedia.org/wiki/POST_(HTTP) POST] requests to the following URL
<pre>http://<your-ip>:<your-port>/jsonrpc</pre>

Starting with Frodo nightly builds it is mandatory to set the HTTP header field '''Content-Type: application/json'''

===== GET =====
Third-party application can access Kodi's JSON-RPC API by sending JSON-RPC requests embedded in a HTTP GET parameter called ''request''. The JSON-RPC request must be URL encoded and sent to the following URL
<pre>http://<your-ip>:<your-port>/jsonrpc?request=<url-encoded-request></pre>

==== TCP ====
The ''TCP'' transport can be used by third-party applications running on the same machine as Kodi or on a different machine which can access the machine running Kodi using the [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] protocol. Because this transport allows applications outside Kodi to control Kodi it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user. Once enabled, third-party applications can access Kodi's JSON-RPC API by opening a TCP [http://en.wikipedia.org/wiki/Internet_socket socket] on port 9090 (this port can be configured in the [[Advancedsettings.xml#<jsonrpc>|advanced settings]] file) and sending raw JSON-RPC requests over that socket. Please note that no delimiters are provided in between notifications and/or responses. As such, your client needs to be able to deal with this, eg. by counting and matching curly braces ({}).

==== WebSocket ====
The ''WebSocket'' transport has been added since Version 5 and can be used by third-party applications running on the same machine as Kodi or on a different machine which can access the machine running Kodi using the [http://en.wikipedia.org/wiki/WebSocket Websocket] protocol. The supported versions are 8 (draft [http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10 hybi-10]) and 13 ([http://tools.ietf.org/html/rfc6455 RFC 6455]). Because this transport allows applications outside Kodi to control Kodi it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user. Once enabled, third-party applications can access Kodi's JSON-RPC API by sending a WebSocket protocol handshake to the following URI
<pre>ws://<your-ip>:<configured tcp port>/jsonrpc</pre>
It is important to send the handshake on the port of Kodi's TCP server (by default 9090, but this port can be configured in the [[Advancedsettings.xml#<jsonrpc>|advanced settings]] file). After having successfully finished the handshake third-party applications can send WebSocket protocl messages over that connection.

=== Functionalities ===
==== Response ====
The ''Response'' functionality is the only functionality that should be present in every transport available as it describes the functionality to respond to a JSON-RPC request with a valid JSON-RPC response (be it an error message or an actual response).

==== Notifications ====
The ''Notifications'' functionality includes both server-side (from the server to clients) and client-side (from clients to the server) notifications. A JSON-RPC notification is a valid JSON-RPC request with no ''id'' property. Following the JSON-RPC 2.0 specification any JSON-RPC request with no ''id'' must be considered as a notification and the receiver must not send a response upon a notification.

In the specific case of Kodi, server-side notifications are used to inform clients about certain events to relieve clients of the need to periodically poll for certain events. Furthermore there are two ways of client-side notifications. Using [[/#JSONRPC.NotifyAll|JSONRPC.NotifyAll]] it is possible to ask Kodi to relay the message in the JSON-RPC request to all other connected clients. The second way is to send JSON-RPC requests without an ''id'' property in case the client does not care about the response (e.g. the method [[/#Player.Stop|Player.Stop]] does not return any useful information to the client).

==== Direct file download ====
The ''Direct file download'' functionality is the ability to directly download files from Kodi by calling [[/#Files.Download|Files.Download]]. In this case the term ''direct'' means that the download happens within the JSON-RPC response of the [[/#Files.Download|Files.Download]] request.

==== Redirected file download ====
The ''Redirected file download'' functionality is the ability to indirectly download files from Kodi by calling [[/#Files.PrepareDownload|Files.PrepareDownload]] and using the data received in the response to download the file over a different protocol (like HTTP, FTP ...) or another socket. As the ''Redirected file download'' is very transport specific, it must be handled separately for every transport supporting it.

=== Comparison ===
The following table shows all the available transports and what functionalities they support
{| class="prettytable" style="margin-right: 0;"
!style="padding-left: 5px; padding-right: 10px;" colspan="2"|Transport
!style="padding-left: 10px; padding-right: 10px;"|Response
!style="padding-left: 10px; padding-right: 10px;"|Notifications
!style="padding-left: 10px; padding-right: 10px;"|Direct file<br />download
!style="padding-left: 10px; padding-right: 10px;"|Redirected file<br />download
|-
|style="padding-left: 5px;" colspan="2"|[[Python Development|Python]]
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px;" colspan="2"|[http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP]
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right:5px;" rowspan="2"|[http://en.wikipedia.org/wiki/HTTP HTTP]
|style="padding-left: 5px; padding-right:5px;"|POST
|{{yes}}
|{{no}}
|{{no}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right:5px;"|GET<sup>1</sup>
|{{yes}}
|{{no}}
|{{no}}
|{{yes}}
|-
|style="padding-left: 5px;" colspan="2"|[http://en.wikipedia.org/wiki/WebSocket WebSocket]<sup>1</sup>
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|}
<sup>1</sup> Added in Version 5

== API versions ==
The JSON-RPC API exposed by Kodi is constantly extended to provide better and more functionality to third party applications. For that reason Kodi provides a version information through the '''JSONRPC.Version''' method. The rule is that odd version numbers describe an API state, that is not stable and under heavy development whereas even version numbers describe a stable API. Therefore the version number can be used by third-party clients to check if their application might not be fully compatible with the JSON-RPC API exposed by a user's Kodi installation.

Starting with XBMC v12 (Frodo) we started using a new versioning system (<major>.<minor>.<patch>) for the JSON-RPC API. Frodo stable is version 6.0.0 and from now on with every bugfix the <patch> part of the version is increased, with every feature addition to the API, the <minor> version is increased (and the <patch> version reset to 0) and with every backwards incompatible change, the <major> version is increased.

{| class="prettytable" style="margin-right: 0;"
!colspan="3"|Release
!colspan="6"|JSON-RPC 2.0 specification
!colspan="5"|Transports
|-
!style="padding-left: 5px; padding-right: 5px; width: 6em; text-align: left;"|API Version
!style="padding-left: 10px; padding-right: 10px; width: 5em;"|Version
!style="padding-left: 10px; padding-right: 10px; width: 4em;"|Name
!style="padding-left: 10px; padding-right: 10px;"|Method calls
!style="padding-left: 10px; padding-right: 10px;"|Notifications<br />(server-side)
!style="padding-left: 10px; padding-right: 10px;"|Notifications<br />(client-side)
!style="padding-left: 10px; padding-right: 10px;"|Parameters<br />by-name
!style="padding-left: 10px; padding-right: 10px;"|Parameters<br />by-position
!style="padding-left: 10px; padding-right: 10px;"|Batch requests

!style="padding-left: 10px; padding-right: 10px;"|Python
!style="padding-left: 10px; padding-right: 10px;"|TCP
!style="padding-left: 10px; padding-right: 10px;"|HTTP POST
!style="padding-left: 10px; padding-right: 10px;"|HTTP GET
!style="padding-left: 10px; padding-right: 10px;"|WebSocket
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v2|Version 2]]
|style="padding-left: 5px; padding-right: 5px;"|10.0
|style="padding-left: 5px; padding-right: 5px;"|Dharma
|{{yes}}
|{{yes}}
|{{no}}
|{{yes}}
|{{no}}
|{{no}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v3|Version 3]] / [[/v4|4]]
|style="padding-left: 5px; padding-right: 5px;"|pre-11 / 11.0
|style="padding-left: 5px; padding-right: 5px;"|Eden
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v5|Version 5]] / [[/v6|6]]
|style="padding-left: 5px; padding-right: 5px;"|pre-12 / 12.0
|style="padding-left: 5px; padding-right: 5px;"|Frodo
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|13.0
|style="padding-left: 5px; padding-right: 5px;"|Gotham
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|13.1
|style="padding-left: 5px; padding-right: 5px;"|Gotham
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|13.2
|style="padding-left: 5px; padding-right: 5px;"|Gotham
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|14.0
|style="padding-left: 5px; padding-right: 5px;"|Helix
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|14.1
|style="padding-left: 5px; padding-right: 5px;"|Helix
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|14.2
|style="padding-left: 5px; padding-right: 5px;"|Helix
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|15.0
|style="padding-left: 5px; padding-right: 5px;"|Isengard
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|15.1
|style="padding-left: 5px; padding-right: 5px;"|Isengard
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|15.2
|style="padding-left: 5px; padding-right: 5px;"|Isengard
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|16.0
|style="padding-left: 5px; padding-right: 5px;"|Jarvis
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|16.1
|style="padding-left: 5px; padding-right: 5px;"|Jarvis
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v8|Version 8]]
|style="padding-left: 5px; padding-right: 5px;"|17.0
|style="padding-left: 5px; padding-right: 5px;"|Krypton
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v9|Version 9]]
|style="padding-left: 5px; padding-right: 5px;"|18.0
|style="padding-left: 5px; padding-right: 5px;"|Leia

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}<sup>1</sup>
|{{yes}}
|-
|}
<sup>1</sup>For information requests only, actions require POST

{| class="prettytable" style="margin-right: 0;"
!colspan="3"|Release
!|JSONRPC.Version
|-
!style="padding-left: 10px; padding-right: 10px;"|Date
!style="padding-left: 10px; padding-right: 10px;"|Version
!style="padding-left: 10px; padding-right: 10px;"|Codename
!style="padding-left: 10px; padding-right: 10px;"|["version"]
|-
|18 December 2010
|10.0
|Dharma
|2
|-
|10 March 2011
|10.1
|Dharma
|2
|-
| style="background:#eee;" |24 March 2012
| style="background:#eee;" |11.0
| style="background:#eee;" |Eden
| style="background:#eee;" |4
|-
|29 January 2013
|12.0
|Frodo
|{"major":6,"minor":0,"patch":0}
|-
|18 March 2013
|12.1
|Frodo
|{"major":6,"minor":0,"patch":3}
|-
|03 May 2013
|12.2
|Frodo
|{"major":6,"minor":0,"patch":3}
|-
|24 December 2013
|12.3
|Frodo
|{"major":6,"minor":0,"patch":3}
|-
| style="background:#eee;" | 04 May 2014
| style="background:#eee;" | 13.0
| style="background:#eee;" | Gotham
| style="background:#eee;" | {"major":6,"minor":14,"patch":3}
|-
| style="background:#eee;" | 05 June 2014
| style="background:#eee;" | 13.1
| style="background:#eee;" | Gotham
| style="background:#eee;" | {"major":6,"minor":14,"patch":3}
|-
| style="background:#eee;" | 17 August 2014
| style="background:#eee;" | 13.2
| style="background:#eee;" | Gotham
| style="background:#eee;" | {"major":6,"minor":14,"patch":3}
|-
|23 December 2014
|14.0
|Helix
|{"major":6,"minor":21,"patch":2}
|-
|30 January 2014
|14.1
|Helix
|{"major":6,"minor":21,"patch":2}
|-
|26 March 2014
|14.2
|Helix
|{"major":6,"minor":21,"patch":2}
|-
| style="background:#eee;" | 21 July 2015
| style="background:#eee;" | 15.0
| style="background:#eee;" | Isengard
| style="background:#eee;" | {"major":6,"minor":25,"patch":2}
|-
| style="background:#eee;" | 16 August 2015
| style="background:#eee;" | 15.1
| style="background:#eee;" | Isengard
| style="background:#eee;" | {"major":6,"minor":25,"patch":2}
|-
| style="background:#eee;" | 19 October 2015
| style="background:#eee;" | 15.2
| style="background:#eee;" | Isengard
| style="background:#eee;" | {"major":6,"minor":25,"patch":2}
|-
|21 February 2016
|16.0
|Jarvis
|{"major":6,"minor":32,"patch":4}
|-
|24 April 2016
|16.1
|Jarvis
|{"major":6,"minor":32,"patch":5}
|-
| style="background:#eee;" | 5 February 2017
| style="background:#eee;" | 17.0
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 20 March 2017
| style="background:#eee;" | 17.1
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 23 May 2017
| style="background:#eee;" | 17.2
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 24 May 2017
| style="background:#eee;" | 17.3
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 22 August 2017
| style="background:#eee;" | 17.4
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 23 October 2017
| style="background:#eee;" | 17.5
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 14 November 2017
| style="background:#eee;" | 17.6
| style="background:#eee;" | Krypton
| style="background:#eee;" | {"major":8,"minor":0,"patch":0}
|-
| style="background:#eee;" | 28 January 2018
| style="background:#eee;" | 18.0
| style="background:#eee;" | Leia
| style="background:#eee;" | {"major":9,"minor":0,"patch":0}
|-
| style="background:#eee;" | 11 February 2018
| style="background:#eee;" | 18.1
| style="background:#eee;" | Leia
| style="background:#eee;" | {"major":9,"minor":0,"patch":0}
|-
| style="background:#eee;" | 22 April 2018
| style="background:#eee;" | 18.2
| style="background:#eee;" | Leia
| style="background:#eee;" | {"major":9,"minor":0,"patch":0}
|-
| style="background:#eee;" | 28 June 2018
| style="background:#eee;" | 18.3
| style="background:#eee;" | Leia
| style="background:#eee;" | {"major":9,"minor":0,"patch":0}
|-
|}

== Documentation ==
Kodi's JSON-RPC API has been designed to be self-documented i.e. a call to [[/#JSONRPC.Introspect|JSONRPC.Introspect]] results in a JSON-RPC response containing a documentation for all the available methods and data types. While this documentation is very incomplete and partly wrong for [[/v2|version 2]] it is provided as a full [http://tools.ietf.org/html/draft-zyp-json-schema-03 JSON schema] starting with [[/v3|version 3]]. As the documentation retrieved in that way is always specific to the used version of Kodi, it is (especially for development versions) the best documentation available and should be preferred over the wiki documentation as the latter always documents the API of the latest development.

== Debugging ==
=== Output format ===
To be able to support easier debugging of (third-party) development using the JSON-RPC API, the JSON output generated by Kodi can be pretty-printed by setting
<syntaxhighlight lang="xml" enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
</jsonrpc>
</syntaxhighlight>
in the [[Advancedsettings.xml#.3Cjsonrpc.3E|advancedsettings.xml]]. Default JSON output will be in compact format to minimize sent data (especially useful for mobile devices).

=== Direct interaction ===
To be able to test some methods of Kodi's JSON-RPC API, it can be of great help to be able to send a single hand-written JSON-RPC request to Kodi to see its effect and the generated response. Depending on the transport protocol used there are different possibilities to do that:

==== TCP ====
With a [http://en.wikipedia.org/wiki/Telnet telnet] connection (using [http://en.wikipedia.org/wiki/PuTTY PuTTY] on Windows or telnet on Linux) to port 9090 of the machine running Kodi it is possible to send and receive raw json data to/from Kodi. {{see also|SSH}}

==== HTTP ====
A simple way of manually sending HTTP requests containing a JSON-RPC request to Kodi is using the [http://chrome.google.com/extensions/detail/fhjcajmcbmldlhcimfajhfbgofnpcjmb Simple REST Client] extension for Google's Chrome/Chromium browser. It allows defining a URL and the HTTP request type ('''POST''' is what we need). The actual JSON-RPC request can be defined in the '''Data''' field and then sent to Kodi.

== See also ==
* [[/v2|JSON-RPC API v2 (Dharma)]]
* [[/v4|JSON-RPC API v4 (Eden)]]
* [[/v6|JSON-RPC API v6 (Frodo - Jarvis)]]
* [[/v8|JSON-RPC API v8 (Krypton)]]

== External links ==
* [http://jsonrpc.org/spec.html JSON-RPC 2.0 specification]
* [http://tools.ietf.org/html/draft-zyp-json-schema-03 A JSON Media Type for Describing the Structure and Meaning of JSON Documents (Draft 03)]

== Examples ==
These examples take their base from v4. Any that require a higher version will be marked.

[[JSON-RPC API/Examples]]

[[Category:Manual]]
[[Category:Development]]

JSON-RPC API/Examples

2019-03-07T21:35:41Z

Fbacher: Add complex query that took me a long time to figure out

{{mininav|[[Development]]|[[JSON-RPC API]]}}

== Examples ==
These examples take their base from v4. Any that require a higher version will be marked.

=== Introspect ===
If you require more detailed information about an API method use:
<syntaxhighlight lang="javascript" enclose="div">
{ "jsonrpc": "2.0", "method": "JSONRPC.Introspect", "params": { "filter": { "id": "AudioLibrary.GetAlbums", "type": "method" } }, "id": 1 }
</syntaxhighlight>
"AudioLibrary.GetAlbums" being the method in this example.
=== What is playing? ===
Commands to control the players in Kodi will only work if that player is currently in use.
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "Player.GetActivePlayers", "id": 1}
</syntaxhighlight><br />
<syntaxhighlight lang="javascript" enclose="div">
{"id": 1, "jsonrpc": "2.0", "result": [ { "playerid": 0, "type": "audio" } ]}
</syntaxhighlight>
In the above we can see that the audio player is active. It is possible for more than one player to be active: picture and audio.

Now we know which player is active we can query the current item with:
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "Player.GetItem", "params": { "properties": ["title", "album", "artist", "duration", "thumbnail", "file", "fanart", "streamdetails"], "playerid": 0 }, "id": "AudioGetItem"}
</syntaxhighlight>
or
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "Player.GetItem", "params": { "properties": ["title", "album", "artist", "season", "episode", "duration", "showtitle", "tvshowid", "thumbnail", "file", "fanart", "streamdetails"], "playerid": 1 }, "id": "VideoGetItem"}
</syntaxhighlight>

GetItem will ignore any properties that don't make sense for the specific player.

=== Player play/pause ===
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "Player.PlayPause", "params": { "playerid": 0 }, "id": 1}
</syntaxhighlight>

=== Get Properties ===
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "Application.GetProperties", "params": {"properties": ["volume"]}, "id": 1}
</syntaxhighlight>

=== Query the libraries ===
Artists
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "AudioLibrary.GetArtists", "params": { "limits": { "start" : 0, "end": 75 }, "properties": [ "thumbnail", "fanart", "born", "formed", "died", "disbanded", "yearsactive", "mood", "style", "genre" ], "sort": { "order": "ascending", "method": "artist", "ignorearticle": true } }, "id": 1}
</syntaxhighlight>
Albums
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "AudioLibrary.GetAlbums", "params": { "limits": { "start" : 0, "end": 50 }, "properties": ["playcount", "artist", "genre", "rating", "thumbnail", "year", "mood", "style"], "sort": { "order": "ascending", "method": "album", "ignorearticle": true } }, "id": "libAlbums"}
</syntaxhighlight>
Songs
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "AudioLibrary.GetSongs", "params": { "limits": { "start" : 0, "end": 25 }, "properties": [ "artist", "duration", "album", "track" ], "sort": { "order": "ascending", "method": "track", "ignorearticle": true } }, "id": "libSongs"}
</syntaxhighlight>
Movies
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "VideoLibrary.GetMovies", "params": { "filter": {"field": "playcount", "operator": "is", "value": "0"}, "limits": { "start" : 0, "end": 75 }, "properties" : ["art", "rating", "thumbnail", "playcount", "file"], "sort": { "order": "ascending", "method": "label", "ignorearticle": true } }, "id": "libMovies"}
</syntaxhighlight>

Movie With Multiple Filters
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "VideoLibrary.GetMovies", "params": { "properties": [ "title", "lastplayed", "studio", "cast", "plot", "writer", "director", "fanart", "runtime", "mpaa", "thumbnail", "file","year", "genre", "tag", "trailer" ], "filter": { "or": [ { "field": "genre", "operator": "contains", "value": [ "Film-Noir" ] }, { "field": "tag", "operator": "contains", "value": [ "classic noir", "film noir", "french noir", "brit noir" ] } ] } }, "id": 1 }
</syntaxhighlight>

TV Shows
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "VideoLibrary.GetTVShows", "params": { "filter": {"field": "playcount", "operator": "is", "value": "0"}, "limits": { "start" : 0, "end": 75 }, "properties": ["art", "genre", "plot", "title", "originaltitle", "year", "rating", "thumbnail", "playcount", "file", "fanart"], "sort": { "order": "ascending", "method": "label" } }, "id": "libTvShows"}
</syntaxhighlight>
Music Videos
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "VideoLibrary.GetMusicVideos", "params": { "properties": [ "title", "thumbnail", "artist", "album", "genre", "lastplayed", "year", "runtime", "fanart", "file", "streamdetails" ], "sort": { "order": "ascending", "method": "artist", "ignorearticle": true } }, "id": "libMusicVideos"}
</syntaxhighlight>
Audio Playlist
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "Playlist.GetItems", "params": { "properties": ["title", "album", "artist", "duration"], "playlistid": 0 }, "id": 1}
</syntaxhighlight>
Video Playlist
<syntaxhighlight lang="javascript" enclose="div">
{"jsonrpc": "2.0", "method": "Playlist.GetItems", "params": { "properties": [ "runtime", "showtitle", "season", "title", "artist" ], "playlistid": 1}, "id": 1}
</syntaxhighlight>

[[Category:Manual]]
[[Category:Development]]

Keymap

2018-09-13T13:19:17Z

Fbacher:

{{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:
{{#lsth:userdata|Location of 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:

* ''' 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>XBMC.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 ''TranslateKeyboardString()'' method in [https://github.com/xbmc/xbmc/blob/master/xbmc/input/ButtonTranslator.cpp ButtonTranslator.cpp]
* or in [[List of Kodi 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 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 ===
Custom joysticks are defined using the following syntax:
<syntaxhighlight lang=xml enclose="div">
<joystick name="JOYSTICK NAME">
<button id="BUTTON ID">action</button>
</joystick>
</syntaxhighlight>

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:'''
<syntaxhighlight lang=xml enclose="div">
<joystick name="PLAYSTATION(R)3 Controller (00:1B:FB:F6:E0:F2)">
<button id="15">Select</button>
<button id="14">PreviousMenu</button>
</joystick>
</syntaxhighlight>

== 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/ActionTranslator.cpp ActionTranslator.cpp].

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:Custom keymaps}}

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

{{Updated|16}}

[[Category:Development]]
[[Category:Manual]]
[[Category:Remotes]]
[[Category:Settings]]
[[Category:Controls]]

Keymap

2018-09-13T12:48:43Z

Fbacher: Updated reference to up-to-date list of available Actions.

{{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:
{{#lsth:userdata|Location of 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:

* ''' 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>XBMC.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 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().

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/ActionTranslator.cpp ActionTranslator.cpp]. See the definition of ActionMappings.

{{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 ''TranslateKeyboardString()'' method in [https://github.com/xbmc/xbmc/blob/master/xbmc/input/ButtonTranslator.cpp ButtonTranslator.cpp]
* or in [[List of Kodi 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 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 ===
Custom joysticks are defined using the following syntax:
<syntaxhighlight lang=xml enclose="div">
<joystick name="JOYSTICK NAME">
<button id="BUTTON ID">action</button>
</joystick>
</syntaxhighlight>

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:'''
<syntaxhighlight lang=xml enclose="div">
<joystick name="PLAYSTATION(R)3 Controller (00:1B:FB:F6:E0:F2)">
<button id="15">Select</button>
<button id="14">PreviousMenu</button>
</joystick>
</syntaxhighlight>

== 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/ActionTranslator.cpp ActionTranslator.cpp].

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:Custom keymaps}}

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

{{Updated|16}}

[[Category:Development]]
[[Category:Manual]]
[[Category:Remotes]]
[[Category:Settings]]
[[Category:Controls]]

Keymap

2018-09-13T12:44:21Z

Fbacher: Add reference to master list of remote button names

{{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:
{{#lsth:userdata|Location of 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:

* ''' 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>XBMC.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 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().

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 ''TranslateRemoteString()'' (NOTE: not existing anymore) function does the work.

{{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 ''TranslateKeyboardString()'' method in [https://github.com/xbmc/xbmc/blob/master/xbmc/input/ButtonTranslator.cpp ButtonTranslator.cpp]
* or in [[List of Kodi 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 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 ===
Custom joysticks are defined using the following syntax:
<syntaxhighlight lang=xml enclose="div">
<joystick name="JOYSTICK NAME">
<button id="BUTTON ID">action</button>
</joystick>
</syntaxhighlight>

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:'''
<syntaxhighlight lang=xml enclose="div">
<joystick name="PLAYSTATION(R)3 Controller (00:1B:FB:F6:E0:F2)">
<button id="15">Select</button>
<button id="14">PreviousMenu</button>
</joystick>
</syntaxhighlight>

== 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/ActionTranslator.cpp ActionTranslator.cpp].

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:Custom keymaps}}

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

{{Updated|16}}

[[Category:Development]]
[[Category:Manual]]
[[Category:Remotes]]
[[Category:Settings]]
[[Category:Controls]]

HOW-TO:Set up an MCE remote control in Linux

2018-08-21T20:33:36Z

Fbacher:

This guide will help to configure an MCE Remote on a linux HTPC, even if all the commands are specific to Ubuntu, the main steps are the same on any modern linux distribution.

MCE remotes are IR remotes that split into two main categories:
* MCE remotes that send keystrokes
* Windows remotes also known as RC6 or eHome remotes

Most remotes work out of the box through the kernel input event subsystem. However they are often unusable in this state due to laggy/buggy behavior.
On Linux it is often easier to use the [http://www.wikipedia.org Lirc] package.

== Install the remote ==
=== Simple Installation method with Lircd ===

The easiest way is to use the lircd daemon shipped with lirc package.
Most likely you will also want lirc-compat-remotes which are put in /usr/share/lirc/remotes.

In terminal, use the following command:
<pre>apt-get install -y lirc lirc-compat-remotes</pre>

After the installation a configuration dialog will appear on Ubuntu.
Choose the correct values corresponding to your receiver (and eventually transmitter)

you can now test if the correct value are send by the remote buttons by using the <code>irw</code> command tool and then launch XBMC and check if the main button are responding correctly.

You can always reconfigure the lirc package with the dpkg-reconfigure command:
<pre>dpkg-reconfigure lirc</pre>

If the remote don't work it is always a good idea to reconfigure lirc package by choosing one of those 2 generic value for the receiver option :
* Windows Media Center Transceivers/Remotes (all)
* Linux input layer (/dev/input/eventX)

a more complete guide is available here : [[HOW-TO:Setup_Lirc|HOW-TO: Setup Lirc]]

=== Alternative Installation method using InputLirc ===

In some cases the simple method will work in a buggy way (keys pressed twice, key burst, laggy key, ... ).
If this is the case or you want deeper control over the configuration then use inputlirc.
Inputlirc is a small LIRC-compatible daemon that reads from /dev/input/eventX devices and sends the received keycodes to connecting LIRC clients.

* It is important to disable lircd daemon from lirc package, On ubuntu launch the lirc reconfiguration process with :
<pre>dpkg-reconfigure lirc</pre>
Then choose twice none for receiver and transmitter.

Make sure that lircd is not running. The START_LIRCD parameter should be now set to false in /etc/lirc/hardware.conf configuration file.

* Install now inputlirc :
sudo apt-get install inputlirc

* Before proceeding we need to know the eventX number corresponding to our remote :
<pre>cat /proc/bus/input/devices</pre>

For instance on my xtreamer ultra V1, the nuvoton receiver remote correspond to event4
<pre>cI: Bus=0019 Vendor=1050 Product=00c3 Version=0033
N: Name="Nuvoton w836x7hg Infrared Remote Transceiver"
P: Phys=nuvoton/cir0
S: Sysfs=/devices/pnp0/00:09/rc/rc0/input4
U: Uniq=
H: Handlers=kbd event4
...</pre>

* As the eventX number may sometimes varry upon reboot, one need to know a unique id value corresponding to our remote to further create a udev rule :
<pre>udevadm info -a -p $(udevadm info -q path -n /dev/input/event4)</pre>
For the nuvoton, the ATTRS(id) will be used from the following output
<pre>looking at device '/devices/pnp0/00:09/rc/rc0/input4/event4':
KERNEL=="event4"
SUBSYSTEM=="input"
DRIVER==""

looking at parent device '/devices/pnp0/00:09/rc/rc0/input4':
KERNELS=="input4"
SUBSYSTEMS=="input"
DRIVERS==""
ATTRS{name}=="Nuvoton w836x7hg Infrared Remote Transceiver"
ATTRS{phys}=="nuvoton/cir0"
ATTRS{uniq}==""
ATTRS{properties}=="0"

looking at parent device '/devices/pnp0/00:09/rc/rc0':
KERNELS=="rc0"
SUBSYSTEMS=="rc"
DRIVERS==""
ATTRS{protocols}=="rc-5 nec [rc-6] jvc sony mce_kbd lirc"

looking at parent device '/devices/pnp0/00:09':
KERNELS=="00:09"
SUBSYSTEMS=="pnp"
DRIVERS=="nuvoton-cir"
ATTRS{options}=="
ATTRS{id}=="NTN0530"

looking at parent device '/devices/pnp0':
KERNELS=="pnp0"
SUBSYSTEMS=="
DRIVERS=="</pre>

* One can now create a permanent symbolic link to our eventX device by creating a custom udev rule :
<pre>echo 'KERNEL=="event*",ATTRS{id}=="NTN0530",SYMLINK="input/myremote"' > /etc/udev/rules.d/10-persistent-ir.rules</pre>

Reload the udev configuration and trigger these changes :
<pre>
/etc/init.d/udev reload
udevadm trigger</pre>
Aternatively, reboot in order to apply the udev changes.

There should now be a symbolic link in /dev/input/myremote

* Configure inputlirc by editing /etc/default/inputlirc like this :
<pre>EVENTS="/dev/input/myremote"
OPTIONS="-g -m 0 -c"</pre>

* Restart inputlirc
<pre>/etc/init.d/inputlirc stop
/etc/init.d/inputlirc start</pre>

* Copy the LircMap configuration file into the personal directory
<pre>cp /usr/share/xbmc/system/Lircmap.xml ~/.xbmc/userdata/Lircmap.xml</pre>

* Edit the linux-input-layer remote section to add the remote link name, one should have something like this :
<pre><remote device="linux-input-layer">
<altname>cx23885_remote</altname>
<altname>devinput</altname>
<altname>/dev/input/myremote</altname>
<left>KEY_LEFT</left>
...</pre>

* Launch xbmc and test the working remote

Based on : [http://www.mobidyc.net/2012/09/xtreamer-ultra-ubuntu-12-04/]

== Configure the remote buttons ==
=== Edit the driver table ===

If you are using inputlirc or lircd with the <code>Linux input layer (/dev/input/eventX)</code> value for the receiver parameter, you can tweak the driver keycode/scancode table with the ir-keytable command line tool.
In the following example one will make some changes on the driver table used by the nuvoton remote shipped with the Xtreamer Ultra V1. This example can be adapted to any remote.

By default, after using the inputlirc method on ubuntu 13.04, the subtitle, tilte and enter button are mapped like this for this remote on this HTPC :
<pre>subtitle => KEY_TITLE
title => no key code sent
enter => no key code sent</pre>

One will change the driver table to map those 3 buttons like this :
<pre>subtitle => KEY_SUBTITLE
title => KEY_TITLE
enter => KEY_SELECT</pre>

* First install the ir-keytable package
<pre>apt-get install ir-keytable</pre>

* Stop or kill any lirc daemon (inputlircd or lircd)
<pre>pkill lirc</pre>

* Launch ir-keytable in test mode for the remote and read the scancode sent by pressing the buttons :
<pre>ir-keytable -t --device=/dev/input/myremote</pre>

The output looks like this :
<pre>
Testing events. Please, press CTRL-C to abort.
1378830829.479887: event MSC: scancode = 800f044d
1378830829.479887: event sync
1378830829.728814: event key up: KEY_TITLE (0x0171)
1378830829.728814: event sync
1378830833.290068: event MSC: scancode = 800f0451
...
1379288588.428518: event MSC: scancode = 800f0437
1379288588.428518: event sync
...</pre>

By analyzing the ouput, one can determine the the button/scancode association :
<pre>subtitle => 800f044d
title => 800f0451
enter =>800f0437</pre>

* Dump the driver table into /etc/lirc/myirtable.cfg
<pre>ir-keytable -r --device=/dev/input/myremote > /etc/lirc/myirtable.cfg</pre>

* Analyse the table file and grep the line corresponding to KEY_TITLE, KEY_SUBTITLE and KEY_SELECT
<pre>scancode 0x800f044d = KEY_TITLE (0x171)
scancode 0x800f045a = KEY_SUBTITLE (0x172)</pre>

As you can see, KEY_SELECT is not associated to any scancode, KEY_TITLE is associated to the subtitle button scancode and KEY_SUBTITLE is associate to a non existent scancode.

* Before procedding, it is necessary to know the key hex value associated to KEY_SELECT

Those are located in the kernel source code in include/uapi/linux/input.h file.
One can browse the source code here : [https://github.com/torvalds/linux/blob/master/include/uapi/linux/input.h]

<pre>#define KEY_SELECT 0x161</pre>

* Edit the table file dumped before to have this button key association :
<pre>subtitle => 800f044d => KEY_SUBTITLE (0x172)
title => 800f0451 => KEY_TITLE (0x171)
enter =>800f0437 => KEY_SELECT (0x161)</pre>

after modifying the KEY_TITLE,KEY_SUBTITLE lines and adding the KEY_SELECT line the edited part should look like this :
<pre>scancode 0x800f044d = KEY_SUBTITLE (0x172)
scancode 0x800f0451 = KEY_TITLE (0x171)
scancode 0x800f0437 = KEY_SELECT (0x161)</pre>

* Make sure with your favorite tool that there isn't two lines with the same scancode fot those buttons in the file and save it.

* Clear the driver table and update it with the table file :
<pre>ir-keytable -c --device=/dev/input/myremote
ir-keytable --device=/dev/input/myremote --write=/etc/lirc/myirtable.cfg
Wrote 63 keycode(s) to driver</pre>

* To make the changes persistent upon reboot add those 2 last command above to /etc/rc.local

* One can now test if everything works correctly with ir-keytable test mode, then restart inputlirc or lircd and launch xbmc

=== Edit LircMap.xml and Keyboard.xml ===

First thing to do is to check the LircMap.xml located in ~/.xbmc/userdata/Lircmap.xml.

One can acquire the button key values with the help of irw and then edit this file to better suits our needs.
This can even be mandatory sometimes.

For instance some remotes will send KEY_NUMERIC_1 instead of KEY_1 for the numeric pad. It is then necessary to edit the file at the correponding remote section from
<pre><one>KEY_1</one></pre>
to
<pre><one>KEY_NUMERIC_1</one></pre>

A complete guide is available here : [[Userdata/lircmap.xml]]

For further tweaking it is necessary to edit the Keyboard.xml file.
A complete guide is available here : [[Keymap]]

[[Category:Remotes]]
[[Category:Manual]]

Archive:HP Pavilion HDX Remote

2014-12-26T17:04:22Z

Fbacher: /* HP Pavilion HDX Remote */

<section begin="summary" />
== HP Pavilion HDX Remote ==
[[File:HPPavilionHDXRemote.jpg|thumb]]

This is a newer version of the HP remote. An important difference from the older HP remotes is that it has a unified Play/Pause button instead of separate Play and Pause buttons. Like the older remotes it uses the Microsoft eHome drive so the buttons can be configured by modifying the registry. The Play/Pause button is number 6E. To configure this to send a VK_MEDIA_PLAY_PAUSE multimedia keypress use:

<pre>6e,00,00,00,01,cd,00</pre>

There is also a version of this newer HP remote with red / green / yellow / blue buttons as the top row of four. On that (and I assume the one pictured) the button numbers for the replay button (top-middle) and the TV button (top-right) are 80 and 39 respectively. Hope that helps

If using this one or the newer HP remote such as:

* RC2234302/01B
* 3139 228 54651
* HP PN: 464961-001
* HP SPS: 465541-001
* HP RMN: HSTNN-PR18

in combination with OVU400102/71 HP usb IR receiver on a Ubuntu system, then the Play/Pause button will need a special code 0x00007b91 in the /usr/share/lirc/remotes/mceusb/lircd.conf.mceusb

Note that the HP IR USB receiver OVU400102/71 uses a Fintek chipset. There have been various problems reported with using this device on XP. In some cases, it is recognized as an eHome device, but then does not send keys as an HID device, (however it worked with the EventGhost MCE Remote plugin). In other cases, it was not recognized as a Microsoft eHome device (a patch from HP may be required), but as a FinTek eHome device (after getting the (hacked) Fintek driver). The FinTek driver does not work on some XP configurations (cause unknown).

HP IR Receiver TSGI-IR01 apparantly has several implementations. The TopSeed (vendor id 1784 Product 0006) implementation does NOT support USB3. Plug into a USB2 port, otherwise, you will get 'random' data whenever a keys is pressed, or worse (hangs, etc.). Note that on some systems even the USB2 port will not work. This may be due to newer chipsets or firmware (z97, ASRock).
{{-}}
<section end="summary" />

[[Category:Remotes]]

Archive:HP MCE Remote

2014-12-26T16:58:42Z

Fbacher: /* HP MCE Remote */

<section begin="summary" />
== HP MCE Remote ==
[[File:HPRemotenewer.jpg{{!}}newer version|thumb]]

[[File:hpremote.jpg|thumb|older version]]
Both versions are compatible with the Microsoft remote, and the .reg files used to reconfigure the MS remote will also work with the HP remote.

With the Remote-XBMC.reg config all the buttons work in XBMC except for the "T" and "Print" buttons. To configure these buttons add the following to the .reg file:

<pre> 4E,00,00,00,04,01,22,\ ; Print button on HP remote - sends ctrl-5
5A,00,00,00,04,01,23,\ ; T button on HP remote - sends ctrl-6</pre>
{{-}}
<section end="summary" />

[[Category:Remotes]]

Archive:HP Pavilion HDX Remote

2014-01-08T01:23:59Z

Fbacher:

{{Remote
|Name= HP Pavilion HDX Remote
|Image= HPPavilionHDXRemote.jpg
|Description= This is a newer version of the HP remote. An important difference from the older HP remotes is that it has a unified Play/Pause button instead of separate Play and Pause buttons. Like the older remotes it uses the Microsoft eHome drive so the buttons can be configured by modifying the registry. The Play/Pause button is number 6E. To configure this to send a VK_MEDIA_PLAY_PAUSE multimedia keypress use:

<pre>6e,00,00,00,01,cd,00</pre>

There is also a version of this newer HP remote with red / green / yellow / blue buttons as the top row of four. On that (and I assume the one pictured) the button numbers for the replay button (top-middle) and the TV button (top-right) are 80 and 39 respectively. Hope that helps

If using this one or the newer HP remote such as:

* RC2234302/01B
* 3139 228 54651
* HP PN: 464961-001
* HP SPS: 465541-001
* HP RMN: HSTNN-PR18

in combination with OVU400102/71 HP usb IR receiver on a Ubuntu system, then the Play/Pause button will need a special code 0x00007b91 in the /usr/share/lirc/remotes/mceusb/lircd.conf.mceusb

Note that the HP IR USB receiver OVU400102/71 uses a Fintek chipset. There have been various problems reported with using this device on XP. In some cases, it is recognized as an eHome device, but then does not send keys as an HID device, (however it worked with the EventGhost MCE Remote plugin). In other cases, it was not recognized as a Microsoft eHome device (a patch from HP may be required), but as a FinTek eHome device (after getting the (hacked) Fintek driver). The FinTek driver does not work on some XP configurations (cause unknown).

HP IR Receiver TSGI-IR01 apparantly has several implementations. The TopSeed (vendor id 1784 Product 0006) implementation does NOT support USB3. Plug into a USB2 port, otherwise, you will get 'random' data whenever a keys is pressed, or worse (hangs, etc.).

}}