JSON-RPC API
Overview
JSON RPC is a HTTP-based interface for communicating with XBMC. It replaces the now-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.
Enabling JSON RPC
TODO: add detail and check
To enable the JSON RPC interface in XBMC the "Allow External Control of XBMC" option must be enabled in the settings page. To control XBMC from other computers the "Allow Control from other computers" must also be enabled.
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)
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
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
Seek to a position in the track defined by a percentage (of total duration?)
PARAMETER number Zoom level to seek to, as a whole number between 1-10
Development
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 and it doesn't even check you've got the right type. 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