JSON-RPC API/v2

Development

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.

1 JSON-RPC 2.0 compatibility

Version	Method calls	Notifications (server-side)	Notifications (client-side)	Parameters by-name	Parameters by-position	Batch requests
Version 2	Yes	Yes	No	Yes	No	No

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

3 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

4 Methods

4.1 JSONRPC

4.1.1 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

4.1.2 JSONRPC.Version

Returns the version of this API (not JSONRPC version). An even number refers to a stable version while odd number is development.

4.1.3 JSONRPC.Permission

Returns a list of client permissions

4.1.4 JSONRPC.Ping

Returns pong!

4.1.5 JSONRPC.GetAnnouncementFlags

Returns what announcements the client is listening for

4.1.6 JSONRPC.SetAnnouncementFlags

Sets what announcements the client is listening for

4.1.7 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

4.2 Player

4.2.1 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

4.3 AudioPlayer

4.3.1 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

4.3.2 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

4.3.3 AudioPlayer.Stop

Stops playback

4.3.4 AudioPlayer.SkipPrevious

Skips to the previous item in the playlist

4.3.5 AudioPlayer.SkipNext

Skips to the next item in the playlist

4.3.6 AudioPlayer.BigSkipBackward

Skips backward in the current track by a big amount

4.3.7 AudioPlayer.BigSkipForward

Skips forward in the current track by a big amount

4.3.8 AudioPlayer.SmallSkipBackward

Skips backward in the current track by a small amount

4.3.9 AudioPlayer.SmallSkipForward

Skips forward in the current track by a small amount

4.3.10 AudioPlayer.Rewind

Rewind current track

4.3.11 AudioPlayer.Forward

Play current track forwards (Fast Forwards? unknown)

4.3.12 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

4.3.13 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

4.3.14 AudioPlayer.GetPercentage

Gets a percentage, of what is not obviously documented, presumably Position/Duration*100

RESULT             number     Percentage

4.3.15 AudioPlayer.SeekTime

Seek to a position in the track defined by position in seconds

PARAMETER          number     Position to seek to

4.3.16 AudioPlayer.SeekPercentage

Seek to a position in the track defined by a percentage (of total duration?)

PARAMETER          number     Percentage to seek to

4.4 VideoPlayer

VideoPlayer contains exactly the same methods as AudioPlayer, see method in that namespace.

4.5 PicturePlayer

4.5.1 PicturePlayer.PlayPause

Pauses or unpauses slideshow.

4.5.2 PicturePlayer.Stop

Stops playback.

4.5.3 PicturePlayer.SkipPrevious

Skips to the previous item in the slideshow.

4.5.4 PicturePlayer.SkipNext

Skips to the next item in the slideshow.

4.5.5 PicturePlayer.MoveLeft

In a zoomed view, pans the viewport to the left.

4.5.6 PicturePlayer.MoveRight

In a zoomed view, pans the viewport to the right.

4.5.7 PicturePlayer.MoveDown

In a zoomed view, pans the viewport downwards.

4.5.8 PicturePlayer.MoveUp

In a zoomed view, pans the viewport upwards.

4.5.9 PicturePlayer.ZoomOut

Zooms the viewport out.

4.5.10 PicturePlayer.ZoomIn

Zooms the viewport in.

4.5.11 PicturePlayer.Zoom

Zoom to a defined level

PARAMETER          number     Zoom level to seek to, as a whole number between 1-10

4.5.12 PicturePlayer.Rotate

Rotate the current picture (clockwise or anticlockwise?)

4.6 AudioPlaylist

4.6.1 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

4.6.2 AudioPlaylist.SkipPrevious

Skips to the previous track in the playlist

4.6.3 AudioPlaylist.SkipNext

Skips to the next track in the playlist

4.6.4 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

4.6.5 AudioPlaylist.Add

Adds a track to the current audio playlist

PARAMETER         
file              string            uri of the file to add

4.6.6 AudioPlaylist.Clear

Clears the current audio playlist

4.6.7 AudioPlaylist.Shuffle

Shuffles the current audio playlist

4.6.8 AudioPlaylist.UnShuffle

Removes the shuffle from the current audio playlist

4.7 VideoPlaylist

Contains exact the same methods as AudioPlaylist, except it affects the current video playlist, see AudioPlaylist method calls

4.8 Playlist

4.8.1 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

4.8.2 Playlist.Destroy

Destroys (deletes) a virtual playlist

PARAMETER      string     id of virtual playlist to delete

4.8.3 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

4.8.4 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)

4.8.5 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

4.8.6 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

4.8.7 Playlist.Shuffle

Shuffles the playlist

PARAMETER
playlist-file      string     OPTIONAL: id of file playlist
playlist-virtual   string     OPTIONAL: id of virtual playlist

4.8.8 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

4.9 Files

Many functions in this namespace allow filtering by type, valid types are the following:

video
music
pictures
files
programs

4.9.1 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

4.9.2 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

4.9.3 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

4.10 AudioLibrary

4.10.1 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

4.10.2 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

4.10.3 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

4.10.4 AudioLibrary.ScanForContent

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

4.11 VideoLibary

4.11.1 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}

4.11.2 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

4.11.3 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

4.11.4 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

4.11.5 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

4.11.6 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

4.11.7 VideoLibrary.GetRecentlyAddedEpisodes

Returns a list of recently added episodes to the library

PARAMETER

RESULT
episodes          array      seasons for the tv show

4.11.8 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

4.11.9 VideoLibrary.ScanForContent

Scans file system for new video content

4.12 System

4.12.1 System.Shutdown

Shuts down the system

4.12.2 System.Suspend

Suspends the system

4.12.3 System.Hibernate

Hibernates the system

4.12.4 System.Reboot

Reboots the system

4.12.5 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   

4.12.6 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 }]

4.13 XBMC

4.13.1 XBMC.GetVolume

Gets the current volume

RESULT            number    volume  

4.13.2 XBMC.SetVolume

Sets the current volume as an int percent

PARAMETER         number     volume to set to

4.13.3 XBMC.ToggleMute

Toggle volume mute on/off, returns same as XBMC.GetVolume

4.13.4 XBMC.Play

Starts playback

4.13.5 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

4.13.6 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"

4.13.7 XBMC.Quit

Exits XBMC

5 See also

• JSON-RPC API
• JSON-RPC API v3 (pre Eden)