JSON-RPC API: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Montellese
(update of the list of methods and types)
No edit summary
 
(124 intermediate revisions by 21 users not shown)
Line 1: Line 1:
<div style="float:right;padding-left:10px">__TOC__</div>
{{JSON-RPC_API_nav}}
{{mininav|[[Development]]}}


== Overview ==
JSON RPC is a HTTP-based or raw TCP Socket interface for communicating with XBMC. It replaces the soon-to-be-depreceated HTTP API, and offers a more secure and robust mechanism in the same format. It is based upon the [http://groups.google.com/group/json-rpc/web/json-rpc-2-0?pli=1 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) all clients are granted full authority but will later be forced to ask for privileges and the user of XBMC 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 XBMC from the client creator.


In XBMC 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 simply. 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 announcements (events and information XBMC sends to its clients). Depending on the clients needs it will choose one (or many) of the transports.
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].


== Enabling JSON RPC ==
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.
Since the interface is available on many transports enabling it will depends on the transport.
* Python. Always enabled
* HTTP. Enable webserver
* TCP. "Allow External Control of XBMC" for localhost control and "Allow Control from other computers" for access from outside localhost.


Note: The EventServer is a different interface for sending remote keypresses to XBMC, and must be enabled separately, some programs may use both interfaces.
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 />


== XBMC API ==
The XBMC JSON api is split up into namespaces, which contain methods that can be called. These namespaces are:
<pre>
JSONRPC          A variety of standard JSONRPC calls
Player          Manages all available players
AudioPlayer      Audio playback control
VideoPlayer      Video playback control
Slideshow        Picture playback control
Playlist        Playlist modification
Files            Shares information
AudioLibrary    Audio Library information
VideoLibrary    Video Library information
Application      Application information and control
System          System controls and information
XBMC            Dumping ground for very XBMC specific operations
</pre>


==Methods==
== Enabling JSON-RPC ==
===Application===
Since the interface is available on many transports enabling it depends on the transport.
====Application.GetProperties====
* Python: Always enabled
Retrieves the values of the given properties<br />
* HTTP: In System/Settings/Network/Services activate ''Allow control of Kodi via HTTP'' (see [[Webserver#Enabling_the_webserver|Enabling the webserver]])
'''Permission:''' ReadData<br />
* 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
'''Parameters:'''
#''array'' properties
'''Returns: '''<br />
'''Type:''' ''[[#Application.Property.Value|Application.Property.Value]]''<br />
'''Optional:''' true
====Application.Quit====
Quit application<br />
'''Permission:''' ControlPower<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Application.SetVolume====
Set the current volume<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''integer'' value
'''Returns: '''<br />
'''Type:''' ''integer''<br />
'''Optional:''' true
====Application.ToggleMute====
Toggle mute/unmute<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''integer''<br />
'''Optional:''' true
===AudioLibrary===
====AudioLibrary.Clean====
Cleans the audio library from non-existent items<br />
'''Permission:''' RemoveData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioLibrary.Export====
Exports all items from the audio library<br />
'''Permission:''' WriteFile<br />
'''Parameters:'''
#[ ''boolean'' singlefile = True ]
#[ ''boolean'' images = False ]
#[ ''boolean'' overwrite = False ]
#[ ''string'' path = "" ]
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioLibrary.GetAlbumDetails====
Retrieve details about a specific album<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' albumid
#[ ''[[#Audio.Fields.Album|Audio.Fields.Album]]'' fields ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''[[#Audio.Details.Album|Audio.Details.Album]]'' albumdetails ]


====AudioLibrary.GetAlbums====
Note: The [[EventServer]] is a different interface for sending remote keypresses to Kodi, and must be enabled separately, some programs may use both interfaces.
Retrieve all albums from specified artist or genre<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]
#[ ''[[#Audio.Fields.Album|Audio.Fields.Album]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' albums ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits


====AudioLibrary.GetArtistDetails====
== Transports & Functionalities ==
Retrieve details about a specific artist<br />
=== Transports ===
'''Permission:''' ReadData<br />
==== Python ====
'''Parameters:'''
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.
#''[[#Library.Id|Library.Id]]'' artistid
#[ ''[[#Audio.Fields.Artist|Audio.Fields.Artist]]'' fields ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''[[#Audio.Details.Artist|Audio.Details.Artist]]'' artistdetails ]


====AudioLibrary.GetArtists====
==== HTTP ====
Retrieve all artists<br />
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.
'''Permission:''' ReadData<br />
'''Parameters:'''  
#[ ''[[#Optional.Boolean|Optional.Boolean]]'' albumartistsonly = null ]
#[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]
#[ ''[[#Audio.Fields.Artist|Audio.Fields.Artist]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
*[ ''array'' artists ]


====AudioLibrary.GetGenres====
===== POST =====
Retrieve all genres<br />
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
'''Permission:''' ReadData<br />
<pre>http://<your-ip>:<your-port>/jsonrpc</pre>
'''Parameters:'''
#[ ''[[#Library.Fields.Genre|Library.Fields.Genre]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''array'' genres
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits


====AudioLibrary.GetRecentlyAddedAlbums====
Starting with Frodo nightly builds it is mandatory to set the HTTP header field '''Content-Type: application/json'''
Retrieve recently added albums<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#List.Amount|List.Amount]]'' albums = -1 ]
#[ ''[[#Audio.Fields.Album|Audio.Fields.Album]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' albums ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits


====AudioLibrary.GetRecentlyAddedSongs====
===== GET =====
Retrieve recently added songs<br />
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
'''Permission:''' ReadData<br />
<pre>http://<your-ip>:<your-port>/jsonrpc?request=<url-encoded-request></pre>
'''Parameters:'''  
#[ ''[[#List.Amount|List.Amount]]'' albums = -1 ]
#[ ''[[#Audio.Fields.Song|Audio.Fields.Song]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
*[ ''array'' songs ]


====AudioLibrary.GetSongDetails====
==== TCP ====
Retrieve details about a specific song<br />
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 ({}).
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' songid
#[ ''[[#Audio.Fields.Song|Audio.Fields.Song]]'' fields ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''[[#Audio.Details.Song|Audio.Details.Song]]'' songdetails ]
 
====AudioLibrary.GetSongs====
Retrieve all songs from specified album, artist or genre<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' albumid = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]
#[ ''[[#Audio.Fields.Song|Audio.Fields.Song]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
*[ ''array'' songs ]
 
====AudioLibrary.Scan====
Scans the audio sources for new library items<br />
'''Permission:''' UpdateData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===AudioPlayer===
====AudioPlayer.BigSkipBackward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.BigSkipForward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.Forward====
Forward current playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.GetPercentage====
Retrieve current playback progress in percentage<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''number''<br />
'''Optional:''' true
====AudioPlayer.GetTime====
Retrieves the current and total time of the currently playing file<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Player.TimeValues|Player.TimeValues]]''<br />
'''Optional:''' true
====AudioPlayer.PlayPause====
Pauses or unpause playback and returns the new state<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Player.State|Player.State]]''<br />
'''Optional:''' true
====AudioPlayer.Rewind====
Rewind current playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.SeekPercentage====
Seek to a specific percentage<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Player.SeekPercentage|Player.SeekPercentage]]'' value
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.SeekTime====
Seek to a specific time<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Player.SeekTime|Player.SeekTime]]'' value
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.SkipNext====
Skips to next item on the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.SkipPrevious====
Skips to previous item on the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.SmallSkipBackward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.SmallSkipForward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlayer.State====
Returns playback state of the audio player (if it is active)<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Player.State.Extended|Player.State.Extended]]''<br />
'''Optional:''' true
====AudioPlayer.Stop====
Stops playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===AudioPlaylist===
====AudioPlaylist.Add====
Add item(s) to playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Audio.Item|Playlist.Audio.Item]]'' item
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.Clear====
Clear playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.GetItems====
Get all items from playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Audio.Fields.Song|Audio.Fields.Song]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.Items.Audio|List.Items.Audio]]'' items
*[ ''[[#Playlist.State|Playlist.State]]'' state ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====AudioPlaylist.Insert====
Insert item(s) into playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' index
#''[[#Playlist.Audio.Item|Playlist.Audio.Item]]'' item
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.Play====
Play current or a specific item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#[ ''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' songid = -1 ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''boolean'' success
 
====AudioPlaylist.Remove====
Remove item from playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.Repeat====
Set the repeat mode of the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Repeat|Playlist.Repeat]]'' state
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.Shuffle====
Shuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.SkipNext====
Skip current item and play next item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.SkipPrevious====
Skip current item and play previous item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.State====
Provides information about the current state of the playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Playlist.State|Playlist.State]]''<br />
'''Optional:''' true
====AudioPlaylist.Swap====
Swap items in the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item1
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item2
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====AudioPlaylist.UnShuffle====
Unshuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===Files===
====Files.Download====
'''Permission:''' ReadData<br />
'''Parameters:'''
#''string'' path
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''string'' path
 
====Files.GetDirectory====
'''Permission:''' ReadData<br />
'''Parameters:'''
#''string'' directory
#[ ''[[#Files.Media|Files.Media]]'' media = "files" ]
#[ ''[[#List.Fields.All|List.Fields.All]]'' fields ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.Items.Files|List.Items.Files]]'' files
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====Files.GetSources====
Get the sources of the media windows<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Files.Media|Files.Media]]'' media
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.Items.Shares|List.Items.Shares]]'' shares
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
===Input===
====Input.Back====
Goes back in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Input.Down====
Navigate down in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Input.Home====
Goes to home window in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Input.Left====
Navigate left in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Input.Right====
Navigate right in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Input.Select====
Select current item in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Input.Up====
Navigate up in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===JSONRPC===
====JSONRPC.GetConfiguration====
Get client-specific configurations<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Configuration|Configuration]]''<br />
'''Optional:''' true
====JSONRPC.Introspect====
Enumerates all actions and descriptions<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''boolean'' getdescriptions = True ]
#[ ''boolean'' getmetadata = False ]
#[ ''boolean'' filterbytransport = True ]
#[ ''object'' filter ]<br />
'''Properties:'''
*''string'' type
*''string'' id
*[ ''boolean'' getreferences = True ]
 
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true
====JSONRPC.NotifyAll====
Notify all other connected clients<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''string'' sender
#''string'' message
#[ ''any'' data = null ]
'''Returns: '''<br />
'''Type:''' ''any''<br />
'''Optional:''' true
====JSONRPC.Permission====
Retrieve the clients permissions<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''boolean'' removedata
*''boolean'' controlplayback
*''boolean'' readdata
*''boolean'' updatedata
*''boolean'' writefile
*''boolean'' controlnotify
*''boolean'' controlpower
 
====JSONRPC.Ping====
Ping responder<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====JSONRPC.SetConfiguration====
Change the client-specific configuration<br />
'''Permission:''' ControlNotify<br />
'''Parameters:'''
#[ ''object'' notifications ]<br />
'''Properties:'''
*[ ''[[#Optional.Boolean|Optional.Boolean]]'' gui = null ]
*[ ''[[#Optional.Boolean|Optional.Boolean]]'' system = null ]
*[ ''[[#Optional.Boolean|Optional.Boolean]]'' player = null ]
*[ ''[[#Optional.Boolean|Optional.Boolean]]'' audiolibrary = null ]
*[ ''[[#Optional.Boolean|Optional.Boolean]]'' other = null ]
*[ ''[[#Optional.Boolean|Optional.Boolean]]'' videolibrary = null ]
 
'''Returns: '''<br />
'''Type:''' ''[[#Configuration|Configuration]]''<br />
'''Optional:''' true
====JSONRPC.Version====
Retrieve the jsonrpc protocol version<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===PicturePlayer===
====PicturePlayer.MoveDown====
If picture is zoomed move viewport down<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.MoveLeft====
If picture is zoomed move viewport left otherwise skip previous<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.MoveRight====
If picture is zoomed move viewport right otherwise skip next<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.MoveUp====
If picture is zoomed move viewport up<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.PlayPause====
Pauses or unpause slideshow<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.Rotate====
Rotates current picture<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.SkipNext====
Skips to next picture in the slideshow<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.SkipPrevious====
Skips to previous picture in the slideshow<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.Stop====
Stops slideshow<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.Zoom====
Zooms current picture<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''integer'' value
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.ZoomIn====
Zoom in once<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====PicturePlayer.ZoomOut====
Zoom out once<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===Player===
====Player.GetActivePlayers====
Returns all active players<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''boolean'' picture
*''boolean'' audio
*''boolean'' video
 
===Playlist===
====Playlist.Add====
Add items to the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
#''[[#Playlist.Id|Playlist.Id]]'' items
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Playlist.Clear====
Clear playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Playlist.Create====
Creates a virtual playlist from a given one from a file<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''string'' playlistid
 
====Playlist.Destroy====
Destroys a virtual playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''string'' playlistid
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Playlist.GetItems====
Retrieve items in the playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
#[ ''[[#List.Fields.All|List.Fields.All]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.Items.All|List.Items.All]]'' items
*[ ''string'' name = "" ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====Playlist.Remove====
Remove item from the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
#''['string', 'integer']'' item
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Playlist.Shuffle====
Shuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Playlist.Swap====
Swap items in the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item1
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item2
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====Playlist.UnShuffle====
Unshuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===System===
====System.GetProperties====
Retrieves the values of the given properties<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''array'' properties
'''Returns: '''<br />
'''Type:''' ''[[#System.Property.Value|System.Property.Value]]''<br />
'''Optional:''' true
====System.Hibernate====
Puts the system running XBMC into hibernate mode<br />
'''Permission:''' ControlPower<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====System.Reboot====
Reboots the system running XBMC<br />
'''Permission:''' ControlPower<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====System.Shutdown====
Shuts the system running XBMC down<br />
'''Permission:''' ControlPower<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====System.Suspend====
Suspends the system running XBMC<br />
'''Permission:''' ControlPower<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===VideoLibrary===
====VideoLibrary.Clean====
Cleans the video library from non-existent items<br />
'''Permission:''' RemoveData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoLibrary.Export====
Exports all items from the video library<br />
'''Permission:''' WriteFile<br />
'''Parameters:'''
#[ ''boolean'' singlefile = True ]
#[ ''boolean'' images = False ]
#[ ''boolean'' actorthumbs = False ]
#[ ''boolean'' overwrite = False ]
#[ ''string'' path = "" ]
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoLibrary.GetEpisodeDetails====
Retrieve details about a specific tv show episode<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' episodeid
#[ ''[[#Video.Fields.Episode|Video.Fields.Episode]]'' fields ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''[[#Video.Details.Episode|Video.Details.Episode]]'' episodedetails ]
 
====VideoLibrary.GetEpisodes====
Retrieve all tv show episodes<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Id|Library.Id]]'' tvshowid = -1 ]
#[ ''integer'' season = -1 ]
#[ ''[[#Video.Fields.Episode|Video.Fields.Episode]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' episodes ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoLibrary.GetGenres====
Retrieve all genres<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''string'' type
#[ ''[[#Library.Fields.Genre|Library.Fields.Genre]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''array'' genres
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoLibrary.GetMovieDetails====
Retrieve details about a specific movie<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' movieid
#[ ''[[#Video.Fields.Movie|Video.Fields.Movie]]'' fields ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''[[#Video.Details.Movie|Video.Details.Movie]]'' moviedetails ]
 
====VideoLibrary.GetMovieSetDetails====
Retrieve details about a specific movie set<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' setid
#[ ''[[#Video.Fields.MovieSet|Video.Fields.MovieSet]]'' fields ]
#[ ''object'' movies ]<br />
'''Properties:'''
*[ ''[[#List.Sort|List.Sort]]'' sort ]
*[ ''[[#Video.Fields.Movie|Video.Fields.Movie]]'' fields ]
*[ ''[[#List.Limits|List.Limits]]'' limits ]
 
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''[[#Video.Details.MovieSet.Extended|Video.Details.MovieSet.Extended]]'' setdetails ]
 
====VideoLibrary.GetMovieSets====
Retrieve all movie sets<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Video.Fields.MovieSet|Video.Fields.MovieSet]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
*[ ''array'' sets ]
 
====VideoLibrary.GetMovies====
Retrieve all movies<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Video.Fields.Movie|Video.Fields.Movie]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' movies ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoLibrary.GetMusicVideoDetails====
Retrieve details about a specific music video<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' musicvideoid
#[ ''[[#Video.Fields.MusicVideo|Video.Fields.MusicVideo]]'' fields ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''[[#Video.Details.MusicVideo|Video.Details.MusicVideo]]'' musicvideodetails ]
 
====VideoLibrary.GetMusicVideos====
Retrieve all music videos<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' albumid = -1 ]
#[ ''[[#Video.Fields.MusicVideo|Video.Fields.MusicVideo]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' musicvideos ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoLibrary.GetRecentlyAddedEpisodes====
Retrieve all recently added tv episodes<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Video.Fields.Episode|Video.Fields.Episode]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' episodes ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoLibrary.GetRecentlyAddedMovies====
Retrieve all recently added movies<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Video.Fields.Movie|Video.Fields.Movie]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' movies ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoLibrary.GetRecentlyAddedMusicVideos====
Retrieve all recently added music videos<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Video.Fields.MusicVideo|Video.Fields.MusicVideo]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' musicvideos ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoLibrary.GetSeasons====
Retrieve all tv seasons<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' tvshowid
#[ ''[[#Video.Fields.Season|Video.Fields.Season]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''array'' seasons ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoLibrary.GetTVShowDetails====
Retrieve details about a specific tv show<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' tvshowid
#[ ''[[#Video.Fields.TVShow|Video.Fields.TVShow]]'' fields ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''[[#Video.Details.TVShow|Video.Details.TVShow]]'' tvshowdetails ]
 
====VideoLibrary.GetTVShows====
Retrieve all tv shows<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Video.Fields.TVShow|Video.Fields.TVShow]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
*[ ''array'' tvshows ]
 
====VideoLibrary.Scan====
Scans the video sources for new library items<br />
'''Permission:''' UpdateData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===VideoPlayer===
====VideoPlayer.BigSkipBackward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.BigSkipForward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.Forward====
Forward current playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.GetPercentage====
Retrieve current playback progress in percentage<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''number''<br />
'''Optional:''' true
====VideoPlayer.GetTime====
Retrieves the current and total time of the currently playing file<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Player.TimeValues|Player.TimeValues]]''<br />
'''Optional:''' true
====VideoPlayer.PlayPause====
Pauses or unpause playback and returns the new state<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Player.State|Player.State]]''<br />
'''Optional:''' true
====VideoPlayer.Rewind====
Rewind current playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.SeekPercentage====
Seek to a specific percentage<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Player.SeekPercentage|Player.SeekPercentage]]'' value
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.SeekTime====
Seek to a specific time<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Player.SeekTime|Player.SeekTime]]'' value
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.SkipNext====
Skips to next item on the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.SkipPrevious====
Skips to previous item on the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.SmallSkipBackward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.SmallSkipForward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlayer.State====
Returns playback state of the video player (if it is active)<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Player.State.Extended|Player.State.Extended]]''<br />
'''Optional:''' true
====VideoPlayer.Stop====
Stops playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===VideoPlaylist===
====VideoPlaylist.Add====
Add item(s) to playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Video.Item|Playlist.Video.Item]]'' item
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.Clear====
Clear playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.GetItems====
Get all items from playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#List.Fields.Video|List.Fields.Video]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#List.Items.Video|List.Items.Video]]'' items
*[ ''[[#Playlist.State|Playlist.State]]'' state ]
*''[[#List.LimitsReturned|List.LimitsReturned]]'' limits
 
====VideoPlaylist.Insert====
Insert item(s) into playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' index
#''[[#Playlist.Video.Item|Playlist.Video.Item]]'' item
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.Play====
Play current or a specific item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#[ ''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item = -1 ]
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''boolean'' success
 
====VideoPlaylist.Remove====
Remove item from playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.Repeat====
Set the repeat mode of the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Repeat|Playlist.Repeat]]'' state
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.Shuffle====
Shuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.SkipNext====
Skip current item and play next item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.SkipPrevious====
Skip current item and play previous item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.State====
Provides information about the current state of the playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''[[#Playlist.State|Playlist.State]]''<br />
'''Optional:''' true
====VideoPlaylist.Swap====
Swap items in the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item1
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item2
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====VideoPlaylist.UnShuffle====
Unshuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
===XBMC===
====XBMC.GetInfoBooleans====
Retrieve info booleans about XBMC and the system<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''array'' booleans
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true
====XBMC.GetInfoLabels====
Retrieve info labels about XBMC and the system<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''array'' labels
'''Returns: '''<br />
'''Type:''' ''object''<br />
'''Optional:''' true
====XBMC.Play====
Starts playback of the given file<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''string'' file
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
====XBMC.StartSlideshow====
Starts slideshow with the images from the given directory<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''string'' directory
#[ ''boolean'' random = True ]
#[ ''boolean'' recursive = True ]
'''Returns: '''<br />
'''Type:''' ''string''<br />
'''Optional:''' true
 
==Global types==
===Application===
====Application.Property.Name====
'''Type:''' ''string''<br />
'''Optional:''' true<br />
'''Default:''' "volume"
====Application.Property.Value====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''boolean'' muted = False ]
*[ ''integer'' volume = 0 ]
 
===Array===
====Array.Integer====
'''Type:''' ''array''<br />
'''Optional:''' true
====Array.String====
'''Type:''' ''array''<br />
'''Optional:''' true
===Audio===
====Audio.Details.Album====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''integer'' rating = 0 ]
*[ ''string'' style = "" ]
*[ ''string'' theme = "" ]
*[ ''string'' description = "" ]
*[ ''string'' artist = "" ]
*[ ''string'' fanart = "" ]
*[ ''string'' albumlabel = "" ]
*[ ''string'' thumbnail = "" ]
*[ ''string'' musicbrainzalbumartistid = "" ]
*''string'' label
*''[[#Library.Id|Library.Id]]'' albumid
*[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
*[ ''integer'' year = 0 ]
*[ ''string'' genre = "" ]
*[ ''string'' title = "" ]
*[ ''string'' type = "" ]
*[ ''string'' musicbrainzalbumid = "" ]
*[ ''string'' mood = "" ]
 
====Audio.Details.Artist====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''string'' style = "" ]
*[ ''string'' description = "" ]
*[ ''string'' musicbrainzartistid = "" ]
*''string'' artist
*[ ''string'' fanart = "" ]
*[ ''string'' formed = "" ]
*[ ''string'' disbanded = "" ]
*[ ''string'' born = "" ]
*''[[#Library.Id|Library.Id]]'' artistid
*[ ''string'' yearsactive = "" ]
*[ ''string'' instrument = "" ]
*[ ''string'' genre = "" ]
*''string'' label
*[ ''string'' thumbnail = "" ]
*[ ''string'' died = "" ]
*[ ''string'' mood = "" ]
 
====Audio.Details.Song====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''string'' comment = "" ]
*[ ''integer'' rating = 0 ]
*[ ''string'' lyrics = "" ]
*[ ''string'' albumartist = "" ]
*[ ''string'' file = "" ]
*[ ''integer'' year = 0 ]
*[ ''integer'' duration = 0 ]
*[ ''string'' musicbrainzalbumid = "" ]
*[ ''string'' album = "" ]
*[ ''string'' title = "" ]
*[ ''string'' fanart = "" ]
*[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
*''string'' label
*[ ''[[#Library.Id|Library.Id]]'' albumid = -1 ]
*[ ''string'' thumbnail = "" ]
*''[[#Library.Id|Library.Id]]'' songid
*[ ''integer'' track = 0 ]
*[ ''string'' musicbrainztrackid = "" ]
*[ ''string'' genre = "" ]
*[ ''string'' musicbrainzartistid = "" ]
*[ ''string'' artist = "" ]
*[ ''string'' musicbrainzalbumartistid = "" ]
*[ ''integer'' playcount = 0 ]


====Audio.Fields.Album====
==== WebSocket ====
'''Type:''' ''array''<br />
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
'''Optional:''' true
<pre>ws://<your-ip>:<configured tcp port>/jsonrpc</pre>
====Audio.Fields.Artist====
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.
'''Type:''' ''array''<br />
'''Optional:''' true
====Audio.Fields.Song====
'''Type:''' ''array''<br />
'''Optional:''' true
===Configuration===
====Configuration====
'''Type:''' ''object''<br />
'''Optional:''' false<br />
'''Properties:'''
*''[[#Configuration.Notifications|Configuration.Notifications]]'' notifications


====Configuration.Notifications====
=== Functionalities ===
'''Type:''' ''object''<br />
==== Response ====
'''Optional:''' true<br />
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).
'''Properties:'''
*''boolean'' gui
*''boolean'' system
*''boolean'' player
*''boolean'' audiolibrary
*''boolean'' other
*''boolean'' videolibrary


===Files===
==== Notifications ====
====Files.Media====
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.  
'''Type:''' ''string''<br />
'''Optional:''' true<br />
'''Default:''' "video"
===Global===
====Global.Time====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''integer'' hours
*''integer'' seconds
*''integer'' minutes
*''integer'' milliseconds


===Library===
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 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 does not return any useful information to the client).
====Library.Details.Genre====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''[[#Library.Id|Library.Id]]'' genreid
*[ ''string'' title = "" ]
*[ ''string'' thumbnail = "" ]
*''string'' label


====Library.Fields.Genre====
==== Direct file download ====
'''Type:''' ''array''<br />
The ''Direct file download'' functionality is the ability to directly download files from Kodi by calling Files.Download. In this case the term ''direct'' means that the download happens within the JSON-RPC response of the Files.Download request.
'''Optional:''' true
====Library.Id====
'''Type:''' ''integer''<br />
'''Optional:''' true<br />
'''Default:''' -1
===List===
====List.Amount====
'''Type:''' ''integer''<br />
'''Optional:''' true<br />
'''Default:''' -1
====List.Fields.All====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Fields.Video====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Items.All====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Items.Audio====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Items.Files====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Items.Shares====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Items.Video====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Limits====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''integer'' start = 0 ]
*[ ''integer'' end = -1 ]


====List.LimitsReturned====
==== Redirected file download ====
'''Type:''' ''object''<br />
The ''Redirected file download'' functionality is the ability to indirectly download files from Kodi by calling 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.
'''Optional:''' true<br />
'''Properties:'''
*''integer'' start
*''integer'' total
*''integer'' end


====List.Sort====
=== Comparison ===
'''Type:''' ''object''<br />
The following table shows all the available transports and what functionalities they support
'''Optional:''' true<br />
{| class="prettytable" style="margin-right: 0;"
'''Properties:'''
!style="padding-left: 5px; padding-right: 10px;" colspan="2"|Transport
*[ ''string'' order = "ascending" ]
!style="padding-left: 10px; padding-right: 10px;"|Response
*[ ''boolean'' ignorearticle = False ]
!style="padding-left: 10px; padding-right: 10px;"|Notifications
*[ ''string'' method = "none" ]
!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
|{{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


===Optional===
== API versions ==
====Optional.Boolean====
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.
'''Type:''' ''['null', 'boolean']''<br />
'''Optional:''' true<br />
'''Default:''' null
===Player===
====Player.SeekPercentage====
'''Type:''' ''number''<br />
'''Optional:''' true<br />
'''Default:''' 0
====Player.SeekTime====
'''Type:''' ''integer''<br />
'''Optional:''' true<br />
'''Default:''' 0
====Player.State====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''boolean'' paused
*''boolean'' playing


====Player.State.Extended====
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.
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*''boolean'' paused
*''boolean'' partymode
*''boolean'' playing


====Player.TimeValues====
{| class="prettytable" style="margin-right: 0;"
'''Type:''' ''object''<br />
!colspan="3"|Release
'''Optional:''' true<br />
!colspan="6"|JSON-RPC 2.0 specification
'''Properties:'''
!colspan="5"|Transports
*''boolean'' paused
|-
*''[[#Global.Time|Global.Time]]'' total
!style="padding-left: 5px; padding-right: 5px; width: 6em; text-align: left;"|API Version
*''boolean'' playing
!style="padding-left: 10px; padding-right: 10px; width: 5em;"|Version
*''[[#Global.Time|Global.Time]]'' time
!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


===Playlist===
!style="padding-left: 10px; padding-right: 10px;"|Python
====Playlist.Audio.Item====
!style="padding-left: 10px; padding-right: 10px;"|TCP
'''Type:''' ''object''<br />
!style="padding-left: 10px; padding-right: 10px;"|HTTP POST
'''Optional:''' true<br />
!style="padding-left: 10px; padding-right: 10px;"|HTTP GET
'''Properties:'''
!style="padding-left: 10px; padding-right: 10px;"|WebSocket
*[ ''[[#Playlist.Id|Playlist.Id]]'' playlist ]
|-
*[ ''[[#Library.Id|Library.Id]]'' songid = -1 ]
|style="padding-left: 5px; padding-right: 5px;"|Version 2
*[ ''[[#Library.Id|Library.Id]]'' albumid = -1 ]
|style="padding-left: 5px; padding-right: 5px;"|10.0
*[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
|style="padding-left: 5px; padding-right: 5px;"|Dharma
*[ ''string'' file = "" ]
|{{yes}}
*[ ''string'' directory = "" ]
|{{yes}}
*[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]
|{{no}}
|{{yes}}
|{{no}}
|{{no}}


====Playlist.Id====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{no}}
*[ ''string'' id = "" ]
|{{no}}
*[ ''string'' file = "" ]
|-
|style="padding-left: 5px; padding-right: 5px;"|Version 3 / 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}}


====Playlist.Item.Position====
|{{yes}}
'''Type:''' ''integer''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Default:''' -1
|{{no}}
====Playlist.Repeat====
|{{no}}
'''Type:''' ''string''<br />
|-
'''Optional:''' true<br />
|style="padding-left: 5px; padding-right: 5px;"|Version 5 / 6
'''Default:''' "off"
|style="padding-left: 5px; padding-right: 5px;"|pre-12 / 12.0
====Playlist.State====
|style="padding-left: 5px; padding-right: 5px;"|Frodo
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*''integer'' current
|{{yes}}
*''boolean'' paused
|{{yes}}
*''[[#Playlist.Repeat|Playlist.Repeat]]'' repeat
|{{yes}}
*''boolean'' playing
*''boolean'' shuffled


====Playlist.Video.Item====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*[ ''[[#Playlist.Id|Playlist.Id]]'' playlist ]
|{{yes}}
*[ ''[[#Library.Id|Library.Id]]'' movieid = -1 ]
|-
*[ ''[[#Library.Id|Library.Id]]'' episodeid = -1 ]
|style="padding-left: 5px; padding-right: 5px;"|Version 6
*[ ''string'' file = "" ]
|style="padding-left: 5px; padding-right: 5px;"|13.0
*[ ''string'' directory = "" ]
|style="padding-left: 5px; padding-right: 5px;"|Gotham
*[ ''[[#Library.Id|Library.Id]]'' musicvideoid = -1 ]
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}


===System===
|{{yes}}
====System.Property.Name====
|{{yes}}
'''Type:''' ''string''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Default:''' "canshutdown"
|{{yes}}
====System.Property.Value====
|-
'''Type:''' ''object''<br />
|style="padding-left: 5px; padding-right: 5px;"|Version 6
'''Optional:''' true<br />
|style="padding-left: 5px; padding-right: 5px;"|13.1
'''Properties:'''
|style="padding-left: 5px; padding-right: 5px;"|Gotham
*[ ''boolean'' canreboot = False ]
|{{yes}}
*[ ''boolean'' cansuspend = False ]
|{{yes}}
*[ ''boolean'' canhibernate = False ]
|{{yes}}
*[ ''boolean'' canshutdown = False ]
|{{yes}}
|{{yes}}
|{{yes}}


===Video===
|{{yes}}
====Video.Cast====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|{{yes}}
====Video.Details.Episode====
|{{yes}}
'''Type:''' ''object''<br />
|-
'''Optional:''' true<br />
|style="padding-left: 5px; padding-right: 5px;"|Version 6
'''Properties:'''
|style="padding-left: 5px; padding-right: 5px;"|13.2
*[ ''number'' rating = 0 ]
|style="padding-left: 5px; padding-right: 5px;"|Gotham
*[ ''[[#Library.Id|Library.Id]]'' tvshowid = -1 ]
|{{yes}}
*[ ''string'' file = "" ]
|{{yes}}
*[ ''string'' plot = "" ]
|{{yes}}
*[ ''string'' votes = "" ]
|{{yes}}
*[ ''string'' title = "" ]
|{{yes}}
*[ ''string'' fanart = "" ]
|{{yes}}
*[ ''string'' writer = "" ]
*''string'' label
*[ ''string'' thumbnail = "" ]
*[ ''[[#Video.Streams|Video.Streams]]'' streamdetails ]
*[ ''[[#Video.Resume|Video.Resume]]'' resume ]
*[ ''integer'' season = 0 ]
*[ ''string'' director = "" ]
*[ ''string'' showtitle = "" ]
*[ ''integer'' episode = 0 ]
*[ ''string'' productioncode = "" ]
*[ ''string'' lastplayed = "" ]
*''[[#Library.Id|Library.Id]]'' episodeid
*[ ''string'' originaltitle = "" ]
*[ ''[[#Video.Cast|Video.Cast]]'' cast ]
*[ ''string'' firstaired = "" ]
*[ ''integer'' playcount = 0 ]
*[ ''string'' runtime = "" ]


====Video.Details.Movie====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*[ ''number'' rating = 0 ]
|{{yes}}
*[ ''[[#Array.String|Array.String]]'' set ]
|-
*[ ''string'' tagline = "" ]
|style="padding-left: 5px; padding-right: 5px;"|Version 6
*[ ''string'' file = "" ]
|style="padding-left: 5px; padding-right: 5px;"|14.0
*[ ''integer'' year = 0 ]
|style="padding-left: 5px; padding-right: 5px;"|Helix
*[ ''[[#Array.Integer|Array.Integer]]'' setid ]
|{{yes}}
*[ ''string'' plot = "" ]
|{{yes}}
*[ ''string'' votes = "" ]
|{{yes}}
*[ ''string'' title = "" ]
|{{yes}}
*[ ''string'' fanart = "" ]
|{{yes}}
*[ ''string'' mpaa = "" ]
|{{yes}}
*[ ''string'' writer = "" ]
*''string'' label
*[ ''string'' thumbnail = "" ]
*[ ''[[#Video.Streams|Video.Streams]]'' streamdetails ]
*[ ''string'' plotoutline = "" ]
*[ ''[[#Video.Resume|Video.Resume]]'' resume ]
*[ ''string'' director = "" ]
*[ ''string'' imdbnumber = "" ]
*[ ''string'' studio = "" ]
*[ ''string'' showlink = "" ]
*[ ''string'' genre = "" ]
*''[[#Library.Id|Library.Id]]'' movieid
*[ ''string'' productioncode = "" ]
*[ ''string'' country = "" ]
*[ ''string'' lastplayed = "" ]
*[ ''string'' premiered = "" ]
*[ ''string'' originaltitle = "" ]
*[ ''[[#Video.Cast|Video.Cast]]'' cast ]
*[ ''string'' sorttitle = "" ]
*[ ''integer'' playcount = 0 ]
*[ ''string'' runtime = "" ]
*[ ''integer'' top250 = 0 ]
*[ ''string'' trailer = "" ]


====Video.Details.MovieSet====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*[ ''string'' title = "" ]
|{{yes}}
*[ ''string'' fanart = "" ]
|-
*''string'' label
|style="padding-left: 5px; padding-right: 5px;"|Version 6
*[ ''integer'' playcount = 0 ]
|style="padding-left: 5px; padding-right: 5px;"|14.1
*[ ''string'' thumbnail = "" ]
|style="padding-left: 5px; padding-right: 5px;"|Helix
*''[[#Library.Id|Library.Id]]'' setid
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}


====Video.Details.MovieSet.Extended====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*[ ''string'' title = "" ]
|{{yes}}
*[ ''string'' fanart = "" ]
|-
*''string'' label
|style="padding-left: 5px; padding-right: 5px;"|Version 6
*[ ''array'' movies ]
|style="padding-left: 5px; padding-right: 5px;"|14.2
*[ ''integer'' playcount = 0 ]
|style="padding-left: 5px; padding-right: 5px;"|Helix
*[ ''string'' thumbnail = "" ]
|{{yes}}
*''[[#Library.Id|Library.Id]]'' setid
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}


====Video.Details.MusicVideo====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*[ ''string'' album = "" ]
|{{yes}}
*[ ''string'' plot = "" ]
|-
*[ ''string'' artist = "" ]
|style="padding-left: 5px; padding-right: 5px;"|Version 6
*[ ''string'' fanart = "" ]
|style="padding-left: 5px; padding-right: 5px;"|15.0
*[ ''string'' lastplayed = "" ]
|style="padding-left: 5px; padding-right: 5px;"|Isengard
*[ ''integer'' year = 0 ]
|{{yes}}
*[ ''[[#Video.Resume|Video.Resume]]'' resume ]
|{{yes}}
*''string'' label
|{{yes}}
*[ ''string'' director = "" ]
|{{yes}}
*[ ''string'' thumbnail = "" ]
|{{yes}}
*[ ''string'' studio = "" ]
|{{yes}}
*[ ''string'' file = "" ]
*[ ''integer'' track = 0 ]
*[ ''string'' genre = "" ]
*[ ''string'' title = "" ]
*[ ''integer'' playcount = 0 ]
*[ ''string'' runtime = "" ]
*''[[#Library.Id|Library.Id]]'' musicvideoid
*[ ''[[#Video.Streams|Video.Streams]]'' streamdetails ]


====Video.Details.Season====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*[ ''[[#Library.Id|Library.Id]]'' tvshowid = -1 ]
|{{yes}}
*[ ''integer'' episode = 0 ]
|-
*[ ''string'' fanart = "" ]
|style="padding-left: 5px; padding-right: 5px;"|Version 6
*''integer'' season
|style="padding-left: 5px; padding-right: 5px;"|15.1
*''string'' label
|style="padding-left: 5px; padding-right: 5px;"|Isengard
*[ ''integer'' playcount = 0 ]
|{{yes}}
*[ ''string'' thumbnail = "" ]
|{{yes}}
*[ ''string'' showtitle = "" ]
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}


====Video.Details.TVShow====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*[ ''string'' episodeguide = "" ]
|{{yes}}
*''[[#Library.Id|Library.Id]]'' tvshowid
|-
*[ ''number'' rating = 0 ]
|style="padding-left: 5px; padding-right: 5px;"|Version 6
*[ ''string'' file = "" ]
|style="padding-left: 5px; padding-right: 5px;"|15.2
*[ ''integer'' year = 0 ]
|style="padding-left: 5px; padding-right: 5px;"|Isengard
*[ ''string'' plot = "" ]
|{{yes}}
*[ ''string'' votes = "" ]
|{{yes}}
*[ ''string'' title = "" ]
|{{yes}}
*[ ''string'' fanart = "" ]
|{{yes}}
*[ ''string'' mpaa = "" ]
|{{yes}}
*''string'' label
|{{yes}}
*[ ''string'' thumbnail = "" ]
*[ ''string'' imdbnumber = "" ]
*[ ''string'' studio = "" ]
*[ ''string'' genre = "" ]
*[ ''integer'' episode = 0 ]
*[ ''string'' lastplayed = "" ]
*[ ''string'' premiered = "" ]
*[ ''string'' originaltitle = "" ]
*[ ''[[#Video.Cast|Video.Cast]]'' cast ]
*[ ''string'' sorttitle = "" ]
*[ ''integer'' playcount = 0 ]


====Video.Fields.Episode====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|{{yes}}
====Video.Fields.Movie====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|-
====Video.Fields.MovieSet====
|style="padding-left: 5px; padding-right: 5px;"|Version 6
'''Type:''' ''array''<br />
|style="padding-left: 5px; padding-right: 5px;"|16.0
'''Optional:''' true
|style="padding-left: 5px; padding-right: 5px;"|Jarvis
====Video.Fields.MusicVideo====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|{{yes}}
====Video.Fields.Season====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|{{yes}}
====Video.Fields.TVShow====
'''Type:''' ''array''<br />
'''Optional:''' true
====Video.Resume====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''number'' position = 0 ]
*[ ''number'' total = 0 ]


====Video.Streams====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}
*[ ''array'' video ]
|{{yes}}
*[ ''array'' audio ]
|-
*[ ''array'' subtitle ]
|style="padding-left: 5px; padding-right: 5px;"|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}}


==Global types==
|{{yes}}
===Files===
|{{yes}}
====Files.Media====
|{{yes}}
'''Type:''' ''string''<br />
|{{yes}}
'''Optional:''' false
|{{yes}}
===Library===
|-
====Library.Fields.Album====
|style="padding-left: 5px; padding-right: 5px;"|Version 8
'''Type:''' ''array''<br />
|style="padding-left: 5px; padding-right: 5px;"|17.0
'''Optional:''' true
|style="padding-left: 5px; padding-right: 5px;"|Krypton
====Library.Fields.Episode====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|{{yes}}
====Library.Fields.Movie====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Fields:''' "title", "genre", "year", "rating", "director", "trailer", "tagline", "plot", "plotoutline", "originaltitle", "lastplayed", "playcount", "writer", "studio", "mpaa", "cast", "country", "imdbnumber", "premiered", "productioncode", "runtime", "set", "showlink", "streamDetails", "top250", "votes", "writingcredits", "fanart", "thumbnail", "file"


====Library.Fields.MusicVideo====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|{{yes}}
====Library.Fields.Season====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|-
====Library.Fields.Song====
|style="padding-left: 5px; padding-right: 5px;"|Version 10
'''Type:''' ''array''<br />
|style="padding-left: 5px; padding-right: 5px;"|18
'''Optional:''' true
|style="padding-left: 5px; padding-right: 5px;"|Leia
====Library.Fields.TVShow====
|{{yes}}
'''Type:''' ''array''<br />
|{{yes}}
'''Optional:''' true
|{{yes}}
====Library.Id====
|{{yes}}
'''Type:''' ''integer''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Default:''' -1
===List===
====List.Fields.All====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Fields.Video====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Limits====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''integer'' start = 0 ]
*[ ''integer'' end = -1 ]


====List.Sort====
|{{yes}}
'''Type:''' ''object''<br />
|{{yes}}
'''Optional:''' true<br />
|{{yes}}
'''Properties:'''
|{{yes}}<sup>1</sup>
*[ ''string'' order = "ascending" ]
|{{yes}}
*[ ''boolean'' ignorearticle = False ]
|-
*[ ''string'' method = "none" ]
|style="padding-left: 5px; padding-right: 5px;"|Version 12
|style="padding-left: 5px; padding-right: 5px;"|19
|style="padding-left: 5px; padding-right: 5px;"|Matrix
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}


===Player===
|{{yes}}
====Player.SeekPercentage====
|{{yes}}
'''Type:''' ''number''<br />
|{{yes}}
'''Optional:''' false
|{{yes}}<sup>1</sup>
====Player.SeekTime====
|{{yes}}
'''Type:''' ''integer''<br />
|-
'''Optional:''' false
|}
===Playlist===
<sup>1</sup>For information requests only, actions require POST
====Playlist.Audio.Item====
'''Type:''' ''object''<br />
'''Optional:''' false<br />
'''Properties:'''
*[ ''[[#Library.Id|Library.Id]]'' songid = -1 ]
*[ ''[[#Playlist.Id|Playlist.Id]]'' playlist ]
*[ ''[[#Library.Id|Library.Id]]'' albumid = -1 ]
*[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
*[ ''string'' file = "" ]
*[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]


====Playlist.Id====
{| class="prettytable" style="margin-right: 0;"
'''Type:''' ''object''<br />
!colspan="3"|Release
'''Optional:''' false<br />
!|JSONRPC.Version
'''Properties:'''
|-
*[ ''string'' id = "" ]
!style="padding-left: 10px; padding-right: 10px;"|Date
*[ ''string'' file = "" ]
!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;" | 05 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}
|-
| 29 January 2019
| 18.0
| Leia
| {"major":10,"minor":1,"patch":1}
|-
| 17 February 2019
| 18.1
| Leia
| {"major":10,"minor":1,"patch":2}
|-
| 22 April 2019
| 18.2
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 27 June 2019
| 18.3
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 01 September 2019
| 18.4
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 17 November 2019
| 18.5
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 02 March 2020
| 18.6
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 21 May 2020
| 18.7
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 01 June 2020
| 18.7.1
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 14 June 2020
| 18.7.2
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 29 July 2020
| 18.8
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| 24 October 2020
| 18.9
| Leia
| {"major":10,"minor":3,"patch":0}
|-
| style="background:#eee;" | 20 February 2021
| style="background:#eee;" | 19.0
| style="background:#eee;" | Matrix
| style="background:#eee;" | {"major":12,"minor":2,"patch":1}
|-
| style="background:#eee;" | 10 May 2021
| style="background:#eee;" | 19.1
| style="background:#eee;" | Matrix
| style="background:#eee;" | {"major":12,"minor":3,"patch":0}
|-
| style="background:#eee;" | 09 October 2021
| style="background:#eee;" | 19.2
| style="background:#eee;" | Matrix
| style="background:#eee;" | {"major":12,"minor":4,"patch":0}
|-
| style="background:#eee;" | 28 October 2021
| style="background:#eee;" | 19.3
| style="background:#eee;" | Matrix
| style="background:#eee;" | {"major":12,"minor":4,"patch":0}
|-
| style="background:#eee;" | 04 March 2022
| style="background:#eee;" | 19.4
| style="background:#eee;" | Matrix
| style="background:#eee;" | {"major":12,"minor":4,"patch":0}
|-
| TBA 2022
| 20.0
| Nexus
| {"major":12,"minor":10,"patch":2}
|-
|}


====Playlist.Item.Position====
== Documentation ==
'''Type:''' ''integer''<br />
Kodi's JSON-RPC API has been designed to be self-documented i.e. a call to 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 version 2 it is provided as a full [http://tools.ietf.org/html/draft-zyp-json-schema-03 JSON schema] starting with 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.
'''Optional:''' true<br />
'''Default:''' -1
====Playlist.Video.Item====
'''Type:''' ''object''<br />
'''Optional:''' false<br />
'''Properties:'''
*[ ''[[#Playlist.Id|Playlist.Id]]'' playlist ]
*[ ''[[#Library.Id|Library.Id]]'' movieid = -1 ]
*[ ''[[#Library.Id|Library.Id]]'' episodeid = -1 ]
*[ ''string'' file = "" ]
*[ ''[[#Library.Id|Library.Id]]'' musicvideoid = -1 ]


== Debugging ==
== Debugging ==
=== Output format ===
=== Output format ===
To be able to support easier debugging of (third party) development using the JSON RPC API, the JSON output generated by XBMC can be pretty printed by setting
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
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
<jsonrpc>
<jsonrpc>
     <compactoutput>false</compactoutput>
     <compactoutput>false</compactoutput>
</jsonrpc>
</jsonrpc>
</source>
</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).
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 ===
=== Direct interaction ===
To be able to test some methods of XBMC's JSON RPC API it can be of great help to be able to send a single hand-written JSON RPC request to XBMC to see its effect and the generated response. Depending on the transport protocol used there are different possibilities to do that:
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 ====
==== 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 XBMC it is possible to send and receive raw json data to/from XBMC.
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 ====
==== HTTP ====
A simple way of manually sending HTTP requests containing a JSON RPC request to XBMC is using the [http://chrome.google.com/extensions/detail/fhjcajmcbmldlhcimfajhfbgofnpcjmb Simple REST Client] extension for Google's Chrome/Chromium browser. It allows defining an 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 XBMC.
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.


== Development ==
=== Dharma (10.0) ===
==== Supported features of JSON RPC 2.0 ====
* Method calls (with or without parameters) over HTTP or TCP
* Server-side (XBMC) announcements (over TCP port 9090)
* by-name parameters


==== Unsupported features of JSON RPC 2.0 ====
== External links ==
* support for by-value OR by-position parameters
* [http://jsonrpc.org/spec.html JSON-RPC 2.0 specification]
* "params" must always be an array (by-position) or an object (by-value) but never a simple type
* [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)]
* Client-side announcements (XBMC returns an error response)
* Bulk requests (XBMC returns a parse error response)


=== Eden (11.0) [WIP] ===
==== Additionally supported features of JSON RPC 2.0 ====
* Client-side announcements (methods can be called without the "id" field which will result in the execution of the method without returning a response) [http://github.com/xbmc/xbmc/commit/625699dcd724b771c327b2b1d1e018b8bf91b11c 625699dcd724b771c327]
* Bulk requests (multiple method calls can be sent as an array in a single json rpc request; all methods are executed and the response contains all responses of the bulk request in an array) [http://github.com/xbmc/xbmc/commit/605dbbc542e61c888be46b0d4114ce73b00e14d0 605dbbc542e61c888be4]
* Default JSON output in compact format ([[Advancedsettings.xml#.3Cjsonrpc.3E|Advanced Settings]] option to disable compact json output) [http://github.com/xbmc/xbmc/commit/20e18ee556b324da8f836ec9eb6678840297d7d7 20e18ee556b324da8f83]
* support for by-value OR by-position parameters [http://github.com/xbmc/xbmc/commit/774b8868ee59a1778ad5eeac7d3d712bb2585aed 774b8868ee59a1778ad5]
* "params" must always be an array (by-position) or an object (by-value) but never a simple type [http://github.com/xbmc/xbmc/commit/774b8868ee59a1778ad5eeac7d3d712bb2585aed 774b8868ee59a1778ad5]


=== General improvement areas ===
Why are there 2 VideoPlayer and AudioPlayer namespaces when they are an arbitrary distinction? Both are handled by the same functions and require extra processing to check the caller used the right namespace.


Same for VideoPlaylist and AudioPlaylist, both map directly to AVPlaylist. The third Playlist namespace contains create and destroy commands, implying there is no difference between Audio and Video playlists
[[Category:JSON-RPC]]

Latest revision as of 05:47, 20 May 2022

JSON-RPC Pages
Main JSON-RPC Page
- v8 (Krypton)
- v10 (Leia)
- v12 (Matrix)
- v13 (Nexus)
- v14 (Omega)
Examples
All JSON-RPC Pages
Home icon grey.png   ▶ Development ▶ JSON-RPC API


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 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.


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 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 protocol. Because this transport allows applications outside Kodi to control Kodi, it has to be manually enabled (see 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 POST requests to the following URL 

http://<your-ip>:<your-port>/jsonrpc

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 

http://<your-ip>:<your-port>/jsonrpc?request=<url-encoded-request>

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 TCP protocol. Because this transport allows applications outside Kodi to control Kodi it has to be manually enabled (see Enabling JSON-RPC) by the user. Once enabled, third-party applications can access Kodi's JSON-RPC API by opening a TCP socket on port 9090 (this port can be configured in the 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 Websocket protocol. The supported versions are 8 (draft hybi-10) and 13 (RFC 6455). Because this transport allows applications outside Kodi to control Kodi it has to be manually enabled (see 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 

ws://<your-ip>:<configured tcp port>/jsonrpc

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 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 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 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. In this case the term direct means that the download happens within the JSON-RPC response of the Files.Download request.

Redirected file download

The Redirected file download functionality is the ability to indirectly download files from Kodi by calling 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

Transport Response Notifications Direct file
download 		Redirected file
download
Python Yes No No No
TCP Yes Yes No No
HTTP POST Yes No No Yes
GET1 Yes No No Yes
WebSocket1 Yes Yes No No

1 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.

Release JSON-RPC 2.0 specification Transports
API Version Version Name Method calls Notifications
(server-side) 		Notifications
(client-side) 		Parameters
by-name 		Parameters
by-position 		Batch requests Python TCP HTTP POST HTTP GET WebSocket
Version 2 10.0 Dharma Yes Yes No Yes No No Yes Yes Yes No No
Version 3 / 4 pre-11 / 11.0 Eden Yes Yes Yes Yes Yes Yes Yes Yes Yes No No
Version 5 / 6 pre-12 / 12.0 Frodo Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 13.0 Gotham Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 13.1 Gotham Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 13.2 Gotham Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 14.0 Helix Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 14.1 Helix Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 14.2 Helix Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 15.0 Isengard Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 15.1 Isengard Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 15.2 Isengard Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 16.0 Jarvis Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 6 16.1 Jarvis Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 8 17.0 Krypton Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Version 10 18 Leia Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes1 Yes
Version 12 19 Matrix Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes1 Yes

1For information requests only, actions require POST

Release JSONRPC.Version
Date Version Codename ["version"]
18 December 2010 10.0 Dharma 2
10 March 2011 10.1 Dharma 2
24 March 2012 11.0 Eden 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}
04 May 2014 13.0 Gotham {"major":6,"minor":14,"patch":3}
05 June 2014 13.1 Gotham {"major":6,"minor":14,"patch":3}
17 August 2014 13.2 Gotham {"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}
21 July 2015 15.0 Isengard {"major":6,"minor":25,"patch":2}
16 August 2015 15.1 Isengard {"major":6,"minor":25,"patch":2}
19 October 2015 15.2 Isengard {"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}
05 February 2017 17.0 Krypton {"major":8,"minor":0,"patch":0}
20 March 2017 17.1 Krypton {"major":8,"minor":0,"patch":0}
23 May 2017 17.2 Krypton {"major":8,"minor":0,"patch":0}
24 May 2017 17.3 Krypton {"major":8,"minor":0,"patch":0}
22 August 2017 17.4 Krypton {"major":8,"minor":0,"patch":0}
23 October 2017 17.5 Krypton {"major":8,"minor":0,"patch":0}
14 November 2017 17.6 Krypton {"major":8,"minor":0,"patch":0}
29 January 2019 18.0 Leia {"major":10,"minor":1,"patch":1}
17 February 2019 18.1 Leia {"major":10,"minor":1,"patch":2}
22 April 2019 18.2 Leia {"major":10,"minor":3,"patch":0}
27 June 2019 18.3 Leia {"major":10,"minor":3,"patch":0}
01 September 2019 18.4 Leia {"major":10,"minor":3,"patch":0}
17 November 2019 18.5 Leia {"major":10,"minor":3,"patch":0}
02 March 2020 18.6 Leia {"major":10,"minor":3,"patch":0}
21 May 2020 18.7 Leia {"major":10,"minor":3,"patch":0}
01 June 2020 18.7.1 Leia {"major":10,"minor":3,"patch":0}
14 June 2020 18.7.2 Leia {"major":10,"minor":3,"patch":0}
29 July 2020 18.8 Leia {"major":10,"minor":3,"patch":0}
24 October 2020 18.9 Leia {"major":10,"minor":3,"patch":0}
20 February 2021 19.0 Matrix {"major":12,"minor":2,"patch":1}
10 May 2021 19.1 Matrix {"major":12,"minor":3,"patch":0}
09 October 2021 19.2 Matrix {"major":12,"minor":4,"patch":0}
28 October 2021 19.3 Matrix {"major":12,"minor":4,"patch":0}
04 March 2022 19.4 Matrix {"major":12,"minor":4,"patch":0}
TBA 2022 20.0 Nexus {"major":12,"minor":10,"patch":2}

Documentation

Kodi's JSON-RPC API has been designed to be self-documented i.e. a call to 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 version 2 it is provided as a full JSON schema starting with 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 

<jsonrpc>
    <compactoutput>false</compactoutput>
</jsonrpc>

in the 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 telnet connection (using 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 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.


External links

Retrieved from "https://kodi.wiki/index.php?title=JSON-RPC_API&oldid=242055"