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.
Contents
- 1 JSON-RPC 2.0 compatibility
- 2 Documentation
- 3 Namespaces
- 4 Methods
- 4.1 JSONRPC
- 4.2 Player
- 4.3 AudioPlayer
- 4.3.1 AudioPlayer.State
- 4.3.2 AudioPlayer.PlayPause
- 4.3.3 AudioPlayer.Stop
- 4.3.4 AudioPlayer.SkipPrevious
- 4.3.5 AudioPlayer.SkipNext
- 4.3.6 AudioPlayer.BigSkipBackward
- 4.3.7 AudioPlayer.BigSkipForward
- 4.3.8 AudioPlayer.SmallSkipBackward
- 4.3.9 AudioPlayer.SmallSkipForward
- 4.3.10 AudioPlayer.Rewind
- 4.3.11 AudioPlayer.Forward
- 4.3.12 AudioPlayer.GetTime
- 4.3.13 AudioPlayer.GetTimeMS
- 4.3.14 AudioPlayer.GetPercentage
- 4.3.15 AudioPlayer.SeekTime
- 4.3.16 AudioPlayer.SeekPercentage
- 4.4 VideoPlayer
- 4.5 PicturePlayer
- 4.5.1 PicturePlayer.PlayPause
- 4.5.2 PicturePlayer.Stop
- 4.5.3 PicturePlayer.SkipPrevious
- 4.5.4 PicturePlayer.SkipNext
- 4.5.5 PicturePlayer.MoveLeft
- 4.5.6 PicturePlayer.MoveRight
- 4.5.7 PicturePlayer.MoveDown
- 4.5.8 PicturePlayer.MoveUp
- 4.5.9 PicturePlayer.ZoomOut
- 4.5.10 PicturePlayer.ZoomIn
- 4.5.11 PicturePlayer.Zoom
- 4.5.12 PicturePlayer.Rotate
- 4.6 AudioPlaylist
- 4.7 VideoPlaylist
- 4.8 Playlist
- 4.9 Files
- 4.10 AudioLibrary
- 4.11 VideoLibary
- 4.11.1 VideoLibrary.GetMovies
- 4.11.2 VideoLibrary.GetTVShows
- 4.11.3 VideoLibrary.GetSeasons
- 4.11.4 VideoLibrary.GetEpisodes
- 4.11.5 VideoLibrary.GetMusicVideos
- 4.11.6 VideoLibrary.GetRecentlyAddedMovies
- 4.11.7 VideoLibrary.GetRecentlyAddedEpisodes
- 4.11.8 VideoLibrary.GetRecentlyAddedMusicVideos
- 4.11.9 VideoLibrary.ScanForContent
- 4.12 System
- 4.13 XBMC
- 5 See also
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