JSON-RPC API/v2

Version 2 is the first official version of the JSON-RPC API. It does not fullfil all the features, functionalities and requirements of the JSON-RPC 2.0 specification and should therefore not be used anymore.

Documentation
Using the JSONRPC.Introspect method results in a weakly formated documentation of all available methods and some of their parameters. Unfortunately not all the parameters are listed and some of them are even invalid.

Namespaces
XBMC's JSON-RPC 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.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              string     OPTIONAL: data associated with this message

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

RESULT directories       array      sub-directories in this directory files             array      files in this directory

start             number total             number end               number

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 {"albumid" : number, "fanart" : string, "label" : string, "thumbnail" : string}

start             number total             number end               number

AudioLibrary.GetSongs
Returns a list of albums in the audio library PARAMETER fields            string     OPTIONAL: fields to return information for 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 {"fanart" : string, "file" : string, "label" : string, "songid" : number, "thumbnail" : string}

start             number total             number end               number

AudioLibrary.ScanForContent
Scans file system for new audio content using ExecBuiltIn("updatelibrary(music)") command

VideoLibrary.GetMovies
Returns a list of movies in the video library

for a list of available fields look to : libjsonrpc/FileItemHandler.cpp

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 { "fanart" : string, "file" : string, "label" : string, "movieid" : number, "thumbnail" : string}

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.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     s to return information for

RESULT           array      of object string    label that field

System.GetInfoBooleans
Get info booleans about the system Available field names: PARAMETER        array      of string     s to return information for

RESULT           array      of object boolean   value of that field Example parameters:

Example result:

XBMC.GetVolume
Gets the current volume RESULT           number    volume

XBMC.SetVolume
Sets the current volume as an int percent 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