JSON-RPC API
Overview
JSON RPC is a HTTP-based interface for communicating with XBMC. It replaces the now-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.
Enabling JSON RPC
TODO: add detail and check
To enable the JSON RPC interface in XBMC the "Allow External Control of XBMC" option must be enabled in the settings page. To control XBMC from other computers the "Allow Control from other computers" must also be enabled.
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)
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
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
VideoLibray.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 audio 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
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