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