Archive: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.
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 |
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
Methods
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 string 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.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
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 (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
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
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
VideoLibary
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
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 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