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