JSON-RPC API
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.GetTimeMS
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.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 (This result is optional) an item: {"fanart":"", "file":"", "label":"", "thumbnail":""} current number? (id? of) current song (This result is optional) playing boolean whether currently playing (This result is optional) paused boolean whether currently paused (This result is optional) start number total number end number
AudioPlaylist.Add
Adds a track to the current audio playlist
PARAMETER file string uri of the file to add
AudioPlaylist.Clear
Clears the current audio playlist
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 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
PARAMETER playlist-file string OPTIONAL: id of file playlist playlist-virtual string OPTIONAL: id of virtual playlist RESULT items array a list of items in the playlist name string name of the playlist playing boolean whether currently playing (This result is optional) paused boolean whether currently paused (This result is optional) start number total number end number
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 file string the file to add (path)
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.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, media entry not included if no data RESULT shares array a list of file items in the directory {"fanart":"", "file":"","label":""} start number total number end number
Files.Download
Returns information about how to download a file (does not return the file itself)
PARAMETER string URI to a file (not a folder) RESULT path string
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 OPTIONAL: TRUE if data about subdirectories should be included REM it's seems "recursive" TRUE or FALSE return the same result ?????!!!! RESULT directories array sub-directories in this directory files array files in this directory start number total number end number
AudioLibrary
AudioLibrary.GetArtists
Returns a list of artists in the audio library
PARAMETER genreid number filters by this genre id, -1 means all. RESULT artists array artists in the library { "artistid" : number ,"fanart":string,"label":string, "thumbnail" :stringORnotpresent} start number total number end number
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 {"albumid" : number, "fanart" : string, "label" : string, "thumbnail" : string}
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
Debugging
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
<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 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:
TCP
With a telnet connection (using 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.
HTTP
A simple way of manually sending HTTP requests containing a JSON RPC request to XBMC is using the 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.
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
- Default JSON output in compact format (Advanced Settings option to disable compact json output) 20e18ee556b324da8f83
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