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

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

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