JSON-RPC API: Difference between revisions
>Topfs2 |
>Montellese (Minor restructuring & detailed description of (un)supported JSON RPC 2.0 features in Dharma/Eden) |
||
Line 30: | Line 30: | ||
</pre> | </pre> | ||
== JSONRPC == | === JSONRPC === | ||
=== JSONRPC.Introspect === | ==== JSONRPC.Introspect ==== | ||
Returns a list of all available method calls | Returns a list of all available method calls | ||
<pre> | <pre> | ||
Line 40: | Line 40: | ||
</pre> | </pre> | ||
=== JSONRPC.Version === | ==== JSONRPC.Version ==== | ||
Returns the version of this API (not JSONRPC version). An even number refers to a stable version while odd number is development. | Returns the version of this API (not JSONRPC version). An even number refers to a stable version while odd number is development. | ||
=== JSONRPC.Permission === | ==== JSONRPC.Permission ==== | ||
Returns a list of client permissions | Returns a list of client permissions | ||
=== JSONRPC.Ping === | ==== JSONRPC.Ping ==== | ||
Returns pong! | Returns pong! | ||
=== JSONRPC.GetAnnouncementFlags === | ==== JSONRPC.GetAnnouncementFlags ==== | ||
Returns what announcements the client is listening for | Returns what announcements the client is listening for | ||
=== JSONRPC.SetAnnouncementFlags === | ==== JSONRPC.SetAnnouncementFlags ==== | ||
Sets what announcements the client is listening for | Sets what announcements the client is listening for | ||
=== JSONRPC.Announce === | ==== JSONRPC.Announce ==== | ||
Send a message to other clients. An announcement made by a client will fall under the "Other" announcement category so a client can't pretend to send XBMC messages (which will never send on "Other"). | Send a message to other clients. An announcement made by a client will fall under the "Other" announcement category so a client can't pretend to send XBMC messages (which will never send on "Other"). | ||
<pre> | <pre> | ||
Line 65: | Line 65: | ||
</pre> | </pre> | ||
== Player == | === Player === | ||
=== Player.GetActivePlayers === | ==== Player.GetActivePlayers ==== | ||
Returns which players are active (available for querying)<br /> | Returns which players are active (available for querying)<br /> | ||
Note: AudioPlayer, VideoPlayer and Slideshow methods are only available if there respective player is active, use this function to obtain that information | Note: AudioPlayer, VideoPlayer and Slideshow methods are only available if there respective player is active, use this function to obtain that information | ||
Line 76: | Line 76: | ||
</pre> | </pre> | ||
== AudioPlayer == | === AudioPlayer === | ||
=== AudioPlayer.State === | ==== AudioPlayer.State ==== | ||
Gets the state of the audio player | Gets the state of the audio player | ||
<pre> | <pre> | ||
Line 86: | Line 86: | ||
</pre> | </pre> | ||
=== AudioPlayer.PlayPause === | ==== AudioPlayer.PlayPause ==== | ||
Pauses or unpauses playback, returns new state | Pauses or unpauses playback, returns new state | ||
<pre> | <pre> | ||
Line 94: | Line 94: | ||
</pre> | </pre> | ||
=== AudioPlayer.Stop === | ==== AudioPlayer.Stop ==== | ||
Stops playback | Stops playback | ||
=== AudioPlayer.SkipPrevious === | ==== AudioPlayer.SkipPrevious ==== | ||
Skips to the previous item in the playlist | Skips to the previous item in the playlist | ||
=== AudioPlayer.SkipNext === | ==== AudioPlayer.SkipNext ==== | ||
Skips to the next item in the playlist | Skips to the next item in the playlist | ||
=== AudioPlayer.BigSkipBackward === | ==== AudioPlayer.BigSkipBackward ==== | ||
Skips backward in the current track by a big amount | Skips backward in the current track by a big amount | ||
=== AudioPlayer.BigSkipForward === | ==== AudioPlayer.BigSkipForward ==== | ||
Skips forward in the current track by a big amount | Skips forward in the current track by a big amount | ||
=== AudioPlayer.SmallSkipBackward === | ==== AudioPlayer.SmallSkipBackward ==== | ||
Skips backward in the current track by a small amount | Skips backward in the current track by a small amount | ||
=== AudioPlayer.SmallSkipForward === | ==== AudioPlayer.SmallSkipForward ==== | ||
Skips forward in the current track by a small amount | Skips forward in the current track by a small amount | ||
=== AudioPlayer.Rewind === | ==== AudioPlayer.Rewind ==== | ||
Rewind current track | Rewind current track | ||
=== AudioPlayer.Forward === | ==== AudioPlayer.Forward ==== | ||
Play current track forwards (Fast Forwards? unknown) | Play current track forwards (Fast Forwards? unknown) | ||
=== AudioPlayer.GetTime === | ==== AudioPlayer.GetTime ==== | ||
Gets the state of the audio player, including time information, to the second | Gets the state of the audio player, including time information, to the second | ||
<pre> | <pre> | ||
Line 131: | Line 131: | ||
</pre> | </pre> | ||
=== AudioPlayer.GetTime === | ==== AudioPlayer.GetTime ==== | ||
Gets the state of the audio player, including time information, to the millisecond | Gets the state of the audio player, including time information, to the millisecond | ||
<pre> | <pre> | ||
Line 141: | Line 141: | ||
</pre> | </pre> | ||
=== AudioPlayer.GetPercentage === | ==== AudioPlayer.GetPercentage ==== | ||
Gets a percentage, of what is not obviously documented, presumably Position/Duration*100 | Gets a percentage, of what is not obviously documented, presumably Position/Duration*100 | ||
<pre> | <pre> | ||
Line 147: | Line 147: | ||
</pre> | </pre> | ||
=== AudioPlayer.GetPercentage === | ==== AudioPlayer.GetPercentage ==== | ||
Gets a percentage, of what is not obviously documented, presumably Position/Duration*100 | Gets a percentage, of what is not obviously documented, presumably Position/Duration*100 | ||
<pre> | <pre> | ||
Line 153: | Line 153: | ||
</pre> | </pre> | ||
=== AudioPlayer.SeekTime === | ==== AudioPlayer.SeekTime ==== | ||
Seek to a position in the track defined by position in seconds | Seek to a position in the track defined by position in seconds | ||
<pre> | <pre> | ||
Line 159: | Line 159: | ||
</pre> | </pre> | ||
=== AudioPlayer.SeekPercentage === | ==== AudioPlayer.SeekPercentage ==== | ||
Seek to a position in the track defined by a percentage (of total duration?) | Seek to a position in the track defined by a percentage (of total duration?) | ||
<pre> | <pre> | ||
Line 169: | Line 169: | ||
== PicturePlayer == | == PicturePlayer == | ||
=== PicturePlayer.PlayPause === | ==== PicturePlayer.PlayPause ==== | ||
Pauses or unpauses slideshow. | Pauses or unpauses slideshow. | ||
=== PicturePlayer.Stop === | ==== PicturePlayer.Stop ==== | ||
Stops playback. | Stops playback. | ||
=== PicturePlayer.SkipPrevious === | ==== PicturePlayer.SkipPrevious ==== | ||
Skips to the previous item in the slideshow. | Skips to the previous item in the slideshow. | ||
=== PicturePlayer.SkipNext === | ==== PicturePlayer.SkipNext ==== | ||
Skips to the next item in the slideshow. | Skips to the next item in the slideshow. | ||
=== PicturePlayer.MoveLeft === | ==== PicturePlayer.MoveLeft ==== | ||
In a zoomed view, pans the viewport to the left. | In a zoomed view, pans the viewport to the left. | ||
=== PicturePlayer.MoveRight === | ==== PicturePlayer.MoveRight ==== | ||
In a zoomed view, pans the viewport to the right. | In a zoomed view, pans the viewport to the right. | ||
=== PicturePlayer.MoveDown === | ==== PicturePlayer.MoveDown ==== | ||
In a zoomed view, pans the viewport downwards. | In a zoomed view, pans the viewport downwards. | ||
=== PicturePlayer.MoveUp === | ==== PicturePlayer.MoveUp ==== | ||
In a zoomed view, pans the viewport upwards. | In a zoomed view, pans the viewport upwards. | ||
=== PicturePlayer.ZoomOut === | ==== PicturePlayer.ZoomOut ==== | ||
Zooms the viewport out. | Zooms the viewport out. | ||
=== PicturePlayer.ZoomIn === | ==== PicturePlayer.ZoomIn ==== | ||
Zooms the viewport in. | Zooms the viewport in. | ||
=== PicturePlayer.Zoom === | ==== PicturePlayer.Zoom ==== | ||
Zoom to a defined level | Zoom to a defined level | ||
<pre> | <pre> | ||
Line 205: | Line 205: | ||
</pre> | </pre> | ||
=== PicturePlayer.Rotate === | ==== PicturePlayer.Rotate ==== | ||
Rotate the current picture (clockwise or anticlockwise?) | Rotate the current picture (clockwise or anticlockwise?) | ||
== AudioPlaylist == | === AudioPlaylist === | ||
=== AudioPlaylist.Play === | ==== AudioPlaylist.Play ==== | ||
Starts playing a playlist | Starts playing a playlist | ||
<pre> | <pre> | ||
Line 221: | Line 221: | ||
</pre> | </pre> | ||
=== AudioPlaylist.SkipPrevious === | ==== AudioPlaylist.SkipPrevious ==== | ||
Skips to the previous track in the playlist | Skips to the previous track in the playlist | ||
=== AudioPlaylist.SkipNext === | ==== AudioPlaylist.SkipNext ==== | ||
Skips to the next track in the playlist | Skips to the next track in the playlist | ||
=== AudioPlaylist.GetItems === | ==== AudioPlaylist.GetItems ==== | ||
Returns a list of items in the playlist, if you chose the right playlist type, also returns state information | Returns a list of items in the playlist, if you chose the right playlist type, also returns state information | ||
<pre> | <pre> | ||
Line 237: | Line 237: | ||
</pre> | </pre> | ||
=== AudioPlaylist.Add === | ==== AudioPlaylist.Add ==== | ||
Adds a track to the current audio playlist | Adds a track to the current audio playlist | ||
<pre> | <pre> | ||
Line 243: | Line 243: | ||
</pre> | </pre> | ||
=== AudioPlaylist.Clear === | ==== AudioPlaylist.Clear ==== | ||
Clears the current audio playlist | Clears the current audio playlist | ||
<pre> | <pre> | ||
Line 249: | Line 249: | ||
</pre> | </pre> | ||
=== AudioPlaylist.Shuffle === | ==== AudioPlaylist.Shuffle ==== | ||
Shuffles the current audio playlist | Shuffles the current audio playlist | ||
=== AudioPlaylist.UnShuffle === | ==== AudioPlaylist.UnShuffle ==== | ||
Removes the shuffle from the current audio playlist | Removes the shuffle from the current audio playlist | ||
== VideoPlaylist == | === VideoPlaylist === | ||
Contains exact the same methods as AudioPlaylist, except it affects the current video playlist, see AudioPlaylist method calls | Contains exact the same methods as AudioPlaylist, except it affects the current video playlist, see AudioPlaylist method calls | ||
== Playlist == | === Playlist === | ||
=== Playlist.Create === | ==== Playlist.Create ==== | ||
Creates a virtual playlist, optionally from another file or virtual playlist | Creates a virtual playlist, optionally from another file or virtual playlist | ||
Line 271: | Line 271: | ||
</pre> | </pre> | ||
=== Playlist.Destroy === | ==== Playlist.Destroy ==== | ||
Destroys (deletes) a virtual playlist | Destroys (deletes) a virtual playlist | ||
<pre> | <pre> | ||
Line 278: | Line 278: | ||
</pre> | </pre> | ||
=== Playlist.GetItems === | ==== Playlist.GetItems ==== | ||
Returns a list of items in the playlist, if you chose the right playlist type, also returns state information | Returns a list of items in the playlist, if you chose the right playlist type, also returns state information | ||
<pre> | <pre> | ||
Line 286: | Line 286: | ||
</pre> | </pre> | ||
=== Playlist.Add === | ==== Playlist.Add ==== | ||
Adds file(s) to a given playlist (file or virtual) | Adds file(s) to a given playlist (file or virtual) | ||
<pre> | <pre> | ||
Line 294: | Line 294: | ||
</pre> | </pre> | ||
=== Playlist.Remove === | ==== Playlist.Remove ==== | ||
Removes file from a given playlist (file or virtual) | Removes file from a given playlist (file or virtual) | ||
<pre> | <pre> | ||
Line 303: | Line 303: | ||
</pre> | </pre> | ||
=== Playlist.Clear === | ==== Playlist.Clear ==== | ||
Clears a given playlist | Clears a given playlist | ||
<pre> | <pre> | ||
Line 311: | Line 311: | ||
</pre> | </pre> | ||
=== Playlist.Swap === | ==== Playlist.Swap ==== | ||
Swaps the position of two items in a given playlist | Swaps the position of two items in a given playlist | ||
<pre> | <pre> | ||
Line 321: | Line 321: | ||
</pre> | </pre> | ||
==== Playlist.Shuffle ==== | |||
=== Playlist.Shuffle === | |||
Shuffles the playlist | Shuffles the playlist | ||
<pre> | <pre> | ||
Line 330: | Line 329: | ||
</pre> | </pre> | ||
=== Playlist.UnShuffle === | ==== Playlist.UnShuffle ==== | ||
Removes the shuffle from the playlist | Removes the shuffle from the playlist | ||
<pre> | <pre> | ||
Line 338: | Line 337: | ||
</pre> | </pre> | ||
== Files == | === Files === | ||
Many functions in this namespace allow filtering by type, valid types are the following: | Many functions in this namespace allow filtering by type, valid types are the following: | ||
<pre> | <pre> | ||
Line 347: | Line 346: | ||
programs | programs | ||
</pre> | </pre> | ||
=== Files.GetSources === | ==== Files.GetSources ==== | ||
Returns a list of available source directories (directories in root folder) | Returns a list of available source directories (directories in root folder) | ||
<pre> | <pre> | ||
Line 357: | Line 356: | ||
</pre> | </pre> | ||
=== Files.Download === | ==== Files.Download ==== | ||
Returns information about how to download a file (does not return the file itself) | Returns information about how to download a file (does not return the file itself) | ||
=== Files.GetDirectory === | ==== Files.GetDirectory ==== | ||
Returns a list of items in a directory, items can be filtered by type. | Returns a list of items in a directory, items can be filtered by type. | ||
<pre> | <pre> | ||
Line 373: | Line 372: | ||
</pre> | </pre> | ||
== AudioLibrary == | === AudioLibrary === | ||
=== AudioLibrary.GetArtists === | ==== AudioLibrary.GetArtists ==== | ||
Returns a list of artists in the audio library | Returns a list of artists in the audio library | ||
<pre> | <pre> | ||
Line 384: | Line 383: | ||
</pre> | </pre> | ||
=== AudioLibrary.GetAlbums === | ==== AudioLibrary.GetAlbums ==== | ||
Returns a list of albums in the audio library | Returns a list of albums in the audio library | ||
<pre> | <pre> | ||
Line 397: | Line 396: | ||
</pre> | </pre> | ||
=== AudioLibrary.GetSongs === | ==== AudioLibrary.GetSongs ==== | ||
Returns a list of albums in the audio library | Returns a list of albums in the audio library | ||
<pre> | <pre> | ||
Line 409: | Line 408: | ||
</pre> | </pre> | ||
=== AudioLibrary.ScanForContent === | ==== AudioLibrary.ScanForContent ==== | ||
Scans file system for new audio content | Scans file system for new audio content | ||
== VideoLibary == | === VideoLibary === | ||
=== VideoLibrary.GetMovies === | ==== VideoLibrary.GetMovies ==== | ||
Returns a list of movies in the video library | Returns a list of movies in the video library | ||
<pre> | <pre> | ||
Line 428: | Line 427: | ||
</pre> | </pre> | ||
=== VideoLibrary.GetTVShows === | ==== VideoLibrary.GetTVShows ==== | ||
Returns a list of tv shows in the video library | Returns a list of tv shows in the video library | ||
<pre> | <pre> | ||
Line 442: | Line 441: | ||
</pre> | </pre> | ||
=== VideoLibrary.GetSeasons === | ==== VideoLibrary.GetSeasons ==== | ||
Returns a list of seasons for a given tv show | Returns a list of seasons for a given tv show | ||
<pre> | <pre> | ||
Line 452: | Line 451: | ||
</pre> | </pre> | ||
=== VideoLibrary.GetEpisodes === | ==== VideoLibrary.GetEpisodes ==== | ||
Returns a list of episodes for a tv show and season | Returns a list of episodes for a tv show and season | ||
<pre> | <pre> | ||
Line 463: | Line 462: | ||
</pre> | </pre> | ||
=== VideoLibrary.GetMusicVideos === | ==== VideoLibrary.GetMusicVideos ==== | ||
Returns a list of Music videos in the video library | Returns a list of Music videos in the video library | ||
<pre> | <pre> | ||
Line 479: | Line 478: | ||
</pre> | </pre> | ||
=== VideoLibrary.GetRecentlyAddedMovies === | ==== VideoLibrary.GetRecentlyAddedMovies ==== | ||
eturns a list of recently added movies in the video library | eturns a list of recently added movies in the video library | ||
<pre> | <pre> | ||
Line 493: | Line 492: | ||
</pre> | </pre> | ||
=== VideoLibrary.GetRecentlyAddedEpisodes === | ==== VideoLibrary.GetRecentlyAddedEpisodes ==== | ||
Returns a list of recently added episodes to the library | Returns a list of recently added episodes to the library | ||
<pre> | <pre> | ||
Line 502: | Line 501: | ||
</pre> | </pre> | ||
=== VideoLibrary.GetRecentlyAddedMusicVideos === | ==== VideoLibrary.GetRecentlyAddedMusicVideos ==== | ||
Returns a list of Music videos in the video library | Returns a list of Music videos in the video library | ||
<pre> | <pre> | ||
Line 513: | Line 512: | ||
</pre> | </pre> | ||
=== VideoLibrary.ScanForContent === | ==== VideoLibrary.ScanForContent ==== | ||
Scans file system for new video content | Scans file system for new video content | ||
== System == | === System === | ||
=== System.Shutdown === | ==== System.Shutdown ==== | ||
Shuts down the system | Shuts down the system | ||
=== System.Suspend === | ==== System.Suspend ==== | ||
Suspends the system | Suspends the system | ||
=== System.Hibernate === | ==== System.Hibernate ==== | ||
Hibernates the system | Hibernates the system | ||
=== System.Reboot === | ==== System.Reboot ==== | ||
Reboots the system | Reboots the system | ||
=== System.GetInfoLabels === | ==== System.GetInfoLabels ==== | ||
Get info labels about the system | Get info labels about the system | ||
Line 539: | Line 538: | ||
</pre> | </pre> | ||
=== System.GetInfoBooleans === | ==== System.GetInfoBooleans ==== | ||
Get info booleans about the system | Get info booleans about the system | ||
Available field names: <code>system.canshutdown system.canpowerdown system.cansuspend system.canhibernate system.canreboot</code> | Available field names: <code>system.canshutdown system.canpowerdown system.cansuspend system.canhibernate system.canreboot</code> | ||
Line 554: | Line 553: | ||
<code>[ { 'system.canshutdown' : true }, { 'system.cansuspend' : true }]</code> | <code>[ { 'system.canshutdown' : true }, { 'system.cansuspend' : true }]</code> | ||
== XBMC == | === XBMC === | ||
=== XBMC.GetVolume === | ==== XBMC.GetVolume ==== | ||
Gets the current volume | Gets the current volume | ||
<pre> | <pre> | ||
Line 561: | Line 560: | ||
</pre> | </pre> | ||
=== XBMC.SetVolume === | ==== XBMC.SetVolume ==== | ||
Sets the current volume | Sets the current volume | ||
<pre> | <pre> | ||
Line 567: | Line 566: | ||
</pre> | </pre> | ||
=== XBMC.ToggleMute === | ==== XBMC.ToggleMute ==== | ||
Toggle volume mute on/off, returns same as XBMC.GetVolume | Toggle volume mute on/off, returns same as XBMC.GetVolume | ||
=== XBMC.Play === | ==== XBMC.Play ==== | ||
Starts playback | Starts playback | ||
=== XBMC.StartSlideshow === | ==== XBMC.StartSlideshow ==== | ||
Starts slideshow | Starts slideshow | ||
<pre> | <pre> | ||
Line 583: | Line 582: | ||
recursive boolean True if include pictures from subdirectories | recursive boolean True if include pictures from subdirectories | ||
</pre> | </pre> | ||
=== XBMC.Log === | ==== XBMC.Log ==== | ||
Logs a line in xbmc.log | Logs a line in xbmc.log | ||
<pre> | <pre> | ||
Line 593: | Line 592: | ||
</pre> | </pre> | ||
=== XBMC.Quit === | ==== XBMC.Quit ==== | ||
Exits XBMC | Exits XBMC | ||
== Development == | == 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 ==== | |||
* support for by-value OR by-position parameters | |||
* "params" must always be an array (by-position) or an object (by-value) but never a simple type | |||
* 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] | |||
==== Still unsupported features of JSON RPC 2.0 ==== | |||
* support for by-value OR by-position parameters | |||
* "params" must always be an array (by-position) or an object (by-value) but never a simple type | |||
=== General improvement areas === | |||
There are about 3 different state returns, that are subtly different, if we want to return player state just reuse State method? | There are about 3 different state returns, that are subtly different, if we want to return player state just reuse State method? | ||
Revision as of 09:05, 26 January 2011
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 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.
Enabling JSON RPC
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.
XBMC API
The XBMC JSON api is split up into namespaces, which contain methods that can be called. These namespaces are:
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 System System Controls and Information XBMC Application controls
JSONRPC
JSONRPC.Introspect
Returns a list of all available method calls
PARAMETERS getpermissions boolean OPTIONAL: return list of required permissions getdescriptions boolean OPTIONAL: return list of method descriptions filterbytransport boolean OPTIONAL: Return only methods available on this transport
JSONRPC.Version
Returns the version of this API (not JSONRPC version). An even number refers to a stable version while odd number is development.
JSONRPC.Permission
Returns a list of client permissions
JSONRPC.Ping
Returns pong!
JSONRPC.GetAnnouncementFlags
Returns what announcements the client is listening for
JSONRPC.SetAnnouncementFlags
Sets what announcements the client is listening for
JSONRPC.Announce
Send a message to other clients. An announcement made by a client will fall under the "Other" announcement category so a client can't pretend to send XBMC messages (which will never send on "Other").
PARAMETERS sender string the sender of the announcement (your client name) message string description of the announcement data object OPTIONAL: data associated with this message
Player
Player.GetActivePlayers
Returns which players are active (available for querying)
Note: AudioPlayer, VideoPlayer and Slideshow methods are only available if there respective player is active, use this function to obtain that information
RESULT video boolean True if video is available, false otherwise audio boolean True if audio is available, false otherwise picture boolean True if pictures are playing, false otherwise
AudioPlayer
AudioPlayer.State
Gets the state of the audio player
RESULT playing boolean True if audio is currently playing paused boolean True if audio is currently paused partymode boolean True if party mode is enabled
AudioPlayer.PlayPause
Pauses or unpauses playback, returns new state
RESULT playing boolean True if audio is currently playing paused boolean True if audio is currently paused
AudioPlayer.Stop
Stops playback
AudioPlayer.SkipPrevious
Skips to the previous item in the playlist
AudioPlayer.SkipNext
Skips to the next item in the playlist
AudioPlayer.BigSkipBackward
Skips backward in the current track by a big amount
AudioPlayer.BigSkipForward
Skips forward in the current track by a big amount
AudioPlayer.SmallSkipBackward
Skips backward in the current track by a small amount
AudioPlayer.SmallSkipForward
Skips forward in the current track by a small amount
AudioPlayer.Rewind
Rewind current track
AudioPlayer.Forward
Play current track forwards (Fast Forwards? unknown)
AudioPlayer.GetTime
Gets the state of the audio player, including time information, to the second
RESULT time number Position in current track in seconds total number Duration of current track in seconds playing boolean True if audio is currently playing paused boolean True if audio is currently paused
AudioPlayer.GetTime
Gets the state of the audio player, including time information, to the millisecond
RESULT time number Position in current track in milliseconds total number Duration of current track in milliseconds playing boolean True if audio is currently playing paused boolean True if audio is currently paused
AudioPlayer.GetPercentage
Gets a percentage, of what is not obviously documented, presumably Position/Duration*100
RESULT number Percentage
AudioPlayer.GetPercentage
Gets a percentage, of what is not obviously documented, presumably Position/Duration*100
RESULT number Percentage
AudioPlayer.SeekTime
Seek to a position in the track defined by position in seconds
PARAMETER number Position to seek to
AudioPlayer.SeekPercentage
Seek to a position in the track defined by a percentage (of total duration?)
PARAMETER number Percentage to seek to
VideoPlayer
VideoPlayer contains exactly the same methods as AudioPlayer, see method in that namespace.
PicturePlayer
PicturePlayer.PlayPause
Pauses or unpauses slideshow.
PicturePlayer.Stop
Stops playback.
PicturePlayer.SkipPrevious
Skips to the previous item in the slideshow.
PicturePlayer.SkipNext
Skips to the next item in the slideshow.
PicturePlayer.MoveLeft
In a zoomed view, pans the viewport to the left.
PicturePlayer.MoveRight
In a zoomed view, pans the viewport to the right.
PicturePlayer.MoveDown
In a zoomed view, pans the viewport downwards.
PicturePlayer.MoveUp
In a zoomed view, pans the viewport upwards.
PicturePlayer.ZoomOut
Zooms the viewport out.
PicturePlayer.ZoomIn
Zooms the viewport in.
PicturePlayer.Zoom
Zoom to a defined level
PARAMETER number Zoom level to seek to, as a whole number between 1-10
PicturePlayer.Rotate
Rotate the current picture (clockwise or anticlockwise?)
AudioPlaylist
AudioPlaylist.Play
Starts playing a playlist
PARAMETER number id number of a song to play OR PARAMETER songid number id number of a song to play RESULT status boolean whether method succeeded
AudioPlaylist.SkipPrevious
Skips to the previous track in the playlist
AudioPlaylist.SkipNext
Skips to the next track in the playlist
AudioPlaylist.GetItems
Returns a list of items in the playlist, if you chose the right playlist type, also returns state information
RESULT items array a list of items in the playlist current number? (id? of) current song playing boolean whether currently playing paused boolean whether currently paused
AudioPlaylist.Add
Adds a track to the current audio playlist
PARAMETER unknown
AudioPlaylist.Clear
Clears the current audio playlist
PARAMETER unknown
AudioPlaylist.Shuffle
Shuffles the current audio playlist
AudioPlaylist.UnShuffle
Removes the shuffle from the current audio playlist
VideoPlaylist
Contains exact the same methods as AudioPlaylist, except it affects the current video playlist, see AudioPlaylist method calls
Playlist
Playlist.Create
Creates a virtual playlist, optionally from another file or virtual playlist
PARAMETER playlist-virtual string OPTIONAL: id of an existing virtual playlist to copy from playlist-file string OPTIONAL: id of an existing file playlist to copy from RESULT playlist-virtual string id of the new playlist
Playlist.Destroy
Destroys (deletes) a virtual playlist
PARAMETER playlist-virtual string id of virtual playlist to delete
Playlist.GetItems
Returns a list of items in the playlist, if you chose the right playlist type, also returns state information
RESULT items array a list of items in the playlist name string name of the playlist
Playlist.Add
Adds file(s) to a given playlist (file or virtual)
PARAMETER playlist-file string OPTIONAL: id of file playlist playlist-virtual string OPTIONAL: id of virtual playlist
Playlist.Remove
Removes file from a given playlist (file or virtual)
PARAMETER playlist-file string OPTIONAL: id of file playlist playlist-virtual string OPTIONAL: id of virtual playlist item string/number id of item to remove
Playlist.Clear
Clears a given playlist
PARAMETER playlist-file string OPTIONAL: id of file playlist playlist-virtual string OPTIONAL: id of virtual playlist
Playlist.Swap
Swaps the position of two items in a given playlist
PARAMETER playlist-file string OPTIONAL: id of file playlist playlist-virtual string OPTIONAL: id of virtual playlist item1 number id of first item item2 number id of second item
Playlist.Shuffle
Shuffles the playlist
PARAMETER playlist-file string OPTIONAL: id of file playlist playlist-virtual string OPTIONAL: id of virtual playlist
Playlist.UnShuffle
Removes the shuffle from the playlist
PARAMETER playlist-file string OPTIONAL: id of file playlist playlist-virtual string OPTIONAL: id of virtual playlist
Files
Many functions in this namespace allow filtering by type, valid types are the following:
video music pictures files programs
Files.GetSources
Returns a list of available source directories (directories in root folder)
PARAMETER media string media type filter, see Files namespace documentation for details RESULT shares array a list of file items in the directory
Files.Download
Returns information about how to download a file (does not return the file itself)
Files.GetDirectory
Returns a list of items in a directory, items can be filtered by type.
PARAMETER directory string the directory to list, e.g. foo/bar media string media type filter, see Files namespace documentation for details recursive boolean TRUE if data about subdirectories should be included RESULT directories array sub-directories in this directory files array files in this directory
AudioLibrary
AudioLibrary.GetArtists
Returns a list of artists in the audio library
PARAMETER genreid number filters by this genre id RESULT artists array artists in the library
AudioLibrary.GetAlbums
Returns a list of albums in the audio library
PARAMETER genreid number filters by this genre id artistid number filters by this artist id start number integer value to start result listing from end number integer value to end result listing from RESULT albums array artists in the library
AudioLibrary.GetSongs
Returns a list of albums in the audio library
PARAMETER genreid number filters by this genre id artistid number filters by this artist id albumid number filters by this album id RESULT albums array artists in the library
AudioLibrary.ScanForContent
Scans file system for new audio content
VideoLibary
VideoLibrary.GetMovies
Returns a list of movies in the video library
PARAMETER fields string OPTIONAL: fields to return information for sortmethod string OPTIONAL: method to sort the returned list sortorder string OPTIONAL: order of sorting, "ascending" or "descending" start number OPTIONAL: index to start listing from end number OPTIONAL: index to end listing at RESULT movies array movies in the library
VideoLibrary.GetTVShows
Returns a list of tv shows in the video library
PARAMETER fields string OPTIONAL: fields to return information for sortmethod string OPTIONAL: method to sort the returned list sortorder string OPTIONAL: order of sorting, "ascending" or "descending" start number OPTIONAL: index to start listing from end number OPTIONAL: index to end listing at RESULT tvshows array movies in the library
VideoLibrary.GetSeasons
Returns a list of seasons for a given tv show
PARAMETER tvshowid number id of the tv show to get seasons for RESULT seasons array seasons for the tv show
VideoLibrary.GetEpisodes
Returns a list of episodes for a tv show and season
PARAMETER tvshowid number id of the tv show season number id of the season to get episodes for RESULT episodes array seasons for the tv show
VideoLibrary.GetMusicVideos
Returns a list of Music videos in the video library
PARAMETER artistid number id of the artist albumid number id of the album fields string OPTIONAL: fields to return information for sortmethod string OPTIONAL: method to sort the returned list sortorder string OPTIONAL: order of sorting, "ascending" or "descending" start number OPTIONAL: index to start listing from end number OPTIONAL: index to end listing at RESULT musicvideos array music videos in the library
VideoLibrary.GetRecentlyAddedMovies
eturns a list of recently added movies in the video library
PARAMETER fields string OPTIONAL: fields to return information for sortmethod string OPTIONAL: method to sort the returned list sortorder string OPTIONAL: order of sorting, "ascending" or "descending" start number OPTIONAL: index to start listing from end number OPTIONAL: index to end listing at RESULT movies array movies in the library
VideoLibrary.GetRecentlyAddedEpisodes
Returns a list of recently added episodes to the library
PARAMETER RESULT episodes array seasons for the tv show
VideoLibrary.GetRecentlyAddedMusicVideos
Returns a list of Music videos in the video library
PARAMETER fields string OPTIONAL: fields to return information for sortmethod string OPTIONAL: method to sort the returned list sortorder string OPTIONAL: order of sorting, "ascending" or "descending" start number OPTIONAL: index to start listing from end number OPTIONAL: index to end listing at
VideoLibrary.ScanForContent
Scans file system for new video content
System
System.Shutdown
Shuts down the system
System.Suspend
Suspends the system
System.Hibernate
Hibernates the system
System.Reboot
Reboots the system
System.GetInfoLabels
Get info labels about the system
PARAMETER array of string <field name>s to return information for RESULT array of object <field name> string label that field
System.GetInfoBooleans
Get info booleans about the system
Available field names: system.canshutdown system.canpowerdown system.cansuspend system.canhibernate system.canreboot
PARAMETER array of string <field name>s to return information for RESULT array of object <field name> boolean value of that field
Example parameters:
[ 'system.canshutdown', 'system.cansuspend' ]
Example result:
[ { 'system.canshutdown' : true }, { 'system.cansuspend' : true }]
XBMC
XBMC.GetVolume
Gets the current volume
RESULT number volume
XBMC.SetVolume
Sets the current volume
PARAMETER number volume to set to
XBMC.ToggleMute
Toggle volume mute on/off, returns same as XBMC.GetVolume
XBMC.Play
Starts playback
XBMC.StartSlideshow
Starts slideshow
PARAMETER string command to start slideshow with OR PARAMETER directory string directory to show pictures from random boolean True if show in random order recursive boolean True if include pictures from subdirectories
XBMC.Log
Logs a line in xbmc.log
PARAMETER string text to log OR PARAMETER message string text to log level string log level, "debug", "info", "notice", "warning", "error", "severe", "fatal", "none"
XBMC.Quit
Exits XBMC
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
- support for by-value OR by-position parameters
- "params" must always be an array (by-position) or an object (by-value) but never a simple type
- 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) 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) 605dbbc542e61c888be4
Still unsupported features of JSON RPC 2.0
- support for by-value OR by-position parameters
- "params" must always be an array (by-position) or an object (by-value) but never a simple type
General improvement areas
There are about 3 different state returns, that are subtly different, if we want to return player state just reuse State method?
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
Use objects for all parameter values, as per JSON 2.0 spec. Current functions not using an object for parameters
AVPlayerOperations.cpp CAVPlayerOperations::SeekTime CAVPlayerOperations::SeekPercentage PicturePlayerOperations.cpp CPicturePlayerOperations::Zoom AVPlaylistOperations.cpp CAVPlaylistOperations::Play PlaylistOperations.cpp CPlaylistOperations::Destroy CPlaylistOperations::Remove Remote ambiguity about parameter type AudioLibrary.cpp CAudioLibrary::GetAlbum albumid should be genreid XBMCOperations.cpp CXBMCOperations::StartSlideshow CXBMCOperations::Log