JSON-RPC API: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Montellese
(Remove fixed improvement areas)
>Montellese
No edit summary
Line 30: Line 30:
</pre>
</pre>


=== JSONRPC ===
==Methods==
==== JSONRPC.Introspect ====
===AudioLibrary===
Returns a list of all available method calls
====AudioLibrary.GetAlbumDetails====
<pre>
Retrieve details about a specific album<br />
PARAMETERS
'''Permission:''' ReadData<br />
getpermissions    boolean    OPTIONAL: return list of required permissions
'''Parameters:'''
getdescriptions    boolean    OPTIONAL: return list of method descriptions
#''[[#Library.Id|Library.Id]]'' albumid
filterbytransport  boolean    OPTIONAL: Return only methods available on this transport
#[ ''[[#Library.Fields.Album|Library.Fields.Album]]'' fields ]
</pre>
'''Returns: '''
====AudioLibrary.GetAlbums====
Retrieve all albums from specified artist or genre<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]
#[ ''[[#Library.Fields.Album|Library.Fields.Album]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====AudioLibrary.GetArtists====
Retrieve all artists<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]
#[ ''array'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====AudioLibrary.GetGenres====
Retrieve all genres<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====AudioLibrary.GetSongDetails====
Retrieve details about a specific song<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' songid
#[ ''[[#Library.Fields.Song|Library.Fields.Song]]'' fields ]
'''Returns: '''
====AudioLibrary.GetSongs====
Retrieve all songs from specified album, artist or genre<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' albumid = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]
#[ ''[[#Library.Fields.Song|Library.Fields.Song]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====AudioLibrary.ScanForContent====
Scans the audio sources for new library items<br />
'''Permission:''' ScanLibrary<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== JSONRPC.Version ====
===AudioPlayer===
Returns the version of this API (not JSONRPC version). An even number refers to a stable version while odd number is development.
====AudioPlayer.BigSkipBackward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== JSONRPC.Permission ====
====AudioPlayer.BigSkipForward====
Returns a list of client permissions
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== JSONRPC.Ping ====
====AudioPlayer.Forward====
Returns pong!
Forward current playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== JSONRPC.GetAnnouncementFlags ====
====AudioPlayer.GetPercentage====
Returns what announcements the client is listening for
Retrieve current playback progress in percentage<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''''number''


==== JSONRPC.SetAnnouncementFlags ====
====AudioPlayer.GetTime====
Sets what announcements the client is listening for
Retrieves the current and total time of the currently playing file<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''
====AudioPlayer.PlayPause====
Pauses or unpause playback and returns the new state<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''
====AudioPlayer.Rewind====
Rewind current playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== JSONRPC.Announce ====
====AudioPlayer.SeekPercentage====
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").
Seek to a specific percentage<br />
<pre>
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Player.SeekPercentage|Player.SeekPercentage]]'' value
'''Returns: '''''string''


PARAMETERS
====AudioPlayer.SeekTime====
sender            string    the sender of the announcement (your client name)
Seek to a specific time<br />
message            string    description of the announcement
'''Permission:''' ControlPlayback<br />
data              string    OPTIONAL: data associated with this message
'''Parameters:'''
</pre>
#''[[#Player.SeekTime|Player.SeekTime]]'' value
'''Returns: '''''string''


=== Player ===
====AudioPlayer.SkipNext====
==== Player.GetActivePlayers ====
Skips to next item on the playlist<br />
Returns which players are active (available for querying)<br />
'''Permission:''' ControlPlayback<br />
Note: AudioPlayer, VideoPlayer and Slideshow methods are only available if there respective player is active, use this function to obtain that information
'''Parameters:''' None
<pre>
<br />
RESULT
'''Returns: '''''string''
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
</pre>


=== AudioPlayer ===
====AudioPlayer.SkipPrevious====
==== AudioPlayer.State ====
Skips to previous item on the playlist<br />
Gets the state of the audio player
'''Permission:''' ControlPlayback<br />
<pre>
'''Parameters:''' None
RESULT
<br />
playing            boolean    True if audio is currently playing
'''Returns: '''''string''
paused            boolean    True if audio is currently paused
partymode          boolean    True if party mode is enabled
</pre>


==== AudioPlayer.PlayPause ====
====AudioPlayer.SmallSkipBackward====
Pauses or unpauses playback, returns new state
'''Permission:''' ControlPlayback<br />
<pre>
'''Parameters:''' None
RESULT
<br />
playing            boolean    True if audio is currently playing
'''Returns: '''''string''
paused            boolean    True if audio is currently paused
</pre>


==== AudioPlayer.Stop ====
====AudioPlayer.SmallSkipForward====
Stops playback
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlayer.SkipPrevious ====
====AudioPlayer.State====
Skips to the previous item in the playlist
Returns playback state of the audio player (if it is active)<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''
====AudioPlayer.Stop====
Stops playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlayer.SkipNext ====
===AudioPlaylist===
Skips to the next item in the playlist
====AudioPlaylist.Add====
Add item(s) to playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Audio.Item|Playlist.Audio.Item]]'' item
'''Returns: '''''string''


==== AudioPlayer.BigSkipBackward ====
====AudioPlaylist.Clear====
Skips backward in the current track by a big amount
Clear playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlayer.BigSkipForward ====
====AudioPlaylist.GetItems====
Skips forward in the current track by a big amount
Get all items from playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Fields.Song|Library.Fields.Song]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====AudioPlaylist.Insert====
Insert item(s) into playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' index
#''[[#Playlist.Audio.Item|Playlist.Audio.Item]]'' item
'''Returns: '''''string''


==== AudioPlayer.SmallSkipBackward ====
====AudioPlaylist.Play====
Skips backward in the current track by a small amount
Play current or a specific item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#[ ''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' songid = -1 ]
'''Returns: '''
====AudioPlaylist.Remove====
Remove item from playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item
'''Returns: '''''string''


==== AudioPlayer.SmallSkipForward ====
====AudioPlaylist.Shuffle====
Skips forward in the current track by a small amount
Shuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlayer.Rewind ====
====AudioPlaylist.SkipNext====
Rewind current track
Skip current item and play next item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlayer.Forward ====
====AudioPlaylist.SkipPrevious====
Play current track forwards (Fast Forwards? unknown)
Skip current item and play previous item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlayer.GetTime ====
====AudioPlaylist.UnShuffle====
Gets the state of the audio player, including time information, to the second
Unshuffle playlist<br />
<pre>
'''Permission:''' ControlPlayback<br />
RESULT
'''Parameters:''' None
time              number    Position in current track in seconds
<br />
total              number    Duration of current track in seconds
'''Returns: '''''string''
playing            boolean    True if audio is currently playing
paused            boolean    True if audio is currently paused
</pre>


==== AudioPlayer.GetTimeMS ====
===Files===
Gets the state of the audio player, including time information, to the millisecond
====Files.Download====
<pre>
'''Permission:''' ReadData<br />
RESULT
'''Parameters:'''
time              number    Position in current track in milliseconds
#''string'' path
total              number    Duration of current track in milliseconds
'''Returns: '''
playing            boolean    True if audio is currently playing
====Files.GetDirectory====
paused            boolean    True if audio is currently paused
'''Permission:''' ReadData<br />
</pre>
'''Parameters:'''
#''string'' directory
#[ ''[[#Files.Media|Files.Media]]'' media = "files" ]
#[ ''[[#List.Fields.All|List.Fields.All]]'' fields ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====Files.GetSources====
Get the sources of the media windows<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Files.Media|Files.Media]]'' media
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
===Input===
====Input.Back====
Goes back in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlayer.GetPercentage ====
====Input.Down====
Gets a percentage, of what is not obviously documented, presumably Position/Duration*100
Navigate down in GUI<br />
<pre>
'''Permission:''' Navigate<br />
RESULT            number    Percentage
'''Parameters:''' None
</pre>
<br />
'''Returns: '''''string''


==== AudioPlayer.SeekTime ====
====Input.Home====
Seek to a position in the track defined by position in seconds
Goes to home window in GUI<br />
<pre>
'''Permission:''' Navigate<br />
PARAMETER          number    Position to seek to
'''Parameters:''' None
</pre>
<br />
'''Returns: '''''string''


==== AudioPlayer.SeekPercentage ====
====Input.Left====
Seek to a position in the track defined by a percentage (of total duration?)
Navigate left in GUI<br />
<pre>
'''Permission:''' Navigate<br />
PARAMETER          number    Percentage to seek to
'''Parameters:''' None
</pre>
<br />
'''Returns: '''''string''


=== VideoPlayer ===
====Input.Right====
VideoPlayer contains exactly the same methods as AudioPlayer, see method in that namespace.
Navigate right in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


=== PicturePlayer ===
====Input.Select====
==== PicturePlayer.PlayPause ====
Select current item in GUI<br />
Pauses or unpauses slideshow.
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== PicturePlayer.Stop ====
====Input.Up====
Stops playback.
Navigate up in GUI<br />
'''Permission:''' Navigate<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== PicturePlayer.SkipPrevious ====
===JSONRPC===
Skips to the previous item in the slideshow.
====JSONRPC.GetNotificationFlags====
Get notification flags<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''
====JSONRPC.Introspect====
Enumerates all actions and descriptions<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''boolean'' getdescriptions = True ]
#[ ''boolean'' getmetadata = False ]
#[ ''boolean'' filterbytransport = True ]
'''Returns: '''''object''


==== PicturePlayer.SkipNext ====
====JSONRPC.NotifyAll====
Skips to the next item in the slideshow.
Notify all other connected clients<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''string'' sender
#''string'' message
#[ ''any'' data = null ]
'''Returns: '''''any''


==== PicturePlayer.MoveLeft ====
====JSONRPC.Permission====
In a zoomed view, pans the viewport to the left.
Retrieve the clients permissions<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''
====JSONRPC.Ping====
Ping responder<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== PicturePlayer.MoveRight ====
====JSONRPC.SetNotificationFlags====
In a zoomed view, pans the viewport to the right.
Change the notification flags<br />
'''Permission:''' ControlNotify<br />
'''Parameters:'''
#[ ''boolean'' Playback = False ]
#[ ''boolean'' GUI = False ]
#[ ''boolean'' System = False ]
#[ ''boolean'' Library = False ]
#[ ''boolean'' Other = False ]
'''Returns: '''
====JSONRPC.Version====
Retrieve the jsonrpc protocol version<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== PicturePlayer.MoveDown ====
===PicturePlayer===
In a zoomed view, pans the viewport downwards.
====PicturePlayer.MoveDown====
If picture is zoomed move viewport down<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== PicturePlayer.MoveUp ====
====PicturePlayer.MoveLeft====
In a zoomed view, pans the viewport upwards.
If picture is zoomed move viewport left otherwise skip previous<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== PicturePlayer.ZoomOut ====
====PicturePlayer.MoveRight====
Zooms the viewport out.
If picture is zoomed move viewport right otherwise skip next<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== PicturePlayer.ZoomIn ====
====PicturePlayer.MoveUp====
Zooms the viewport in.
If picture is zoomed move viewport up<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== PicturePlayer.Zoom ====
====PicturePlayer.PlayPause====
Zoom to a defined level
Pauses or unpause slideshow<br />
<pre>
'''Permission:''' ControlPlayback<br />
PARAMETER          number    Zoom level to seek to, as a whole number between 1-10
'''Parameters:''' None
</pre>
<br />
'''Returns: '''''string''


==== PicturePlayer.Rotate ====
====PicturePlayer.Rotate====
Rotate the current picture (clockwise or anticlockwise?)
Rotates current picture<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


=== AudioPlaylist ===
====PicturePlayer.SkipNext====
==== AudioPlaylist.Play ====
Skips to next picture in the slideshow<br />
Starts playing a playlist
'''Permission:''' ControlPlayback<br />
<pre>
'''Parameters:''' None
PARAMETER          number    id number of a song to play
<br />
OR
'''Returns: '''''string''
PARAMETER
songid            number    id number of a song to play


RESULT
====PicturePlayer.SkipPrevious====
status            boolean    whether method succeeded
Skips to previous picture in the slideshow<br />
</pre>
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlaylist.SkipPrevious ====
====PicturePlayer.Stop====
Skips to the previous track in the playlist
Stops slideshow<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlaylist.SkipNext ====
====PicturePlayer.Zoom====
Skips to the next track in the playlist
Zooms current picture<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''integer'' value
'''Returns: '''''string''


==== AudioPlaylist.GetItems ====
====PicturePlayer.ZoomIn====
Returns a list of items in the playlist, if you chose the right playlist type, also returns state information
Zoom in once<br />
<pre>
'''Permission:''' ControlPlayback<br />
RESULT
'''Parameters:''' None
items              array      a list of items in the playlist (This result is optional)
<br />
an item: {"fanart":"", "file":"", "label":"", "thumbnail":""}
'''Returns: '''''string''
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
====PicturePlayer.ZoomOut====
total              number
Zoom out once<br />
end                number
'''Permission:''' ControlPlayback<br />
</pre>
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== AudioPlaylist.Add ====
===Player===
Adds a track to the current audio playlist
====Player.GetActivePlayers====
<pre>
Returns all active players<br />
PARAMETER       
'''Permission:''' ReadData<br />
file              string           uri of the file to add
'''Parameters:''' None
</pre>
<br />
'''Returns: '''
===Playlist===
====Playlist.Add====
Add items to the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
#''[[#Playlist.Id|Playlist.Id]]'' items
'''Returns: '''''string''


==== AudioPlaylist.Clear ====
====Playlist.Clear====
Clears the current audio playlist
Clear playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
'''Returns: '''''string''


==== AudioPlaylist.Shuffle ====
====Playlist.Create====
Shuffles the current audio playlist
Creates a virtual playlist from a given one from a file<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
'''Returns: '''
====Playlist.Destroy====
Destroys a virtual playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''string'' playlistid
'''Returns: '''''string''


==== AudioPlaylist.UnShuffle ====
====Playlist.GetItems====
Removes the shuffle from the current audio playlist
Retrieve items in the playlist<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
#[ ''[[#List.Fields.All|List.Fields.All]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====Playlist.Remove====
Remove item from the playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
#''['string', 'integer']'' item
'''Returns: '''''string''


=== VideoPlaylist ===
====Playlist.Shuffle====
Contains exact the same methods as AudioPlaylist, except it affects the current video playlist, see AudioPlaylist method calls
Shuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
'''Returns: '''''string''


=== Playlist ===
====Playlist.Swap====
==== Playlist.Create ====
Swap items in the playlist<br />
Creates a virtual playlist, optionally from another file or virtual playlist
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item1
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item2
'''Returns: '''''string''


<pre>
====Playlist.UnShuffle====
PARAMETER
Unshuffle playlist<br />
playlist-virtual  string    OPTIONAL: id of an existing virtual playlist to copy from
'''Permission:''' ControlPlayback<br />
playlist-file      string     OPTIONAL: id of an existing file playlist to copy from
'''Parameters:'''
#''[[#Playlist.Id|Playlist.Id]]'' playlist
'''Returns: '''''string''


RESULT
===System===
playlist-virtual  string    id of the new playlist
====System.GetInfoBooleans====
</pre>
Retrieve info booleans about the system<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''array''[1..X] booleans
'''Returns: '''
====System.GetInfoLabels====
Retrieve info labels about the system<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''array''[1..X] labels
'''Returns: '''
====System.Hibernate====
Puts the system running XBMC into hibernate mode<br />
'''Permission:''' ControlPower<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== Playlist.Destroy ====
====System.Reboot====
Destroys (deletes) a virtual playlist
Reboots the system running XBMC<br />
<pre>
'''Permission:''' ControlPower<br />
PARAMETER      string    id of virtual playlist to delete
'''Parameters:''' None
</pre>
<br />
'''Returns: '''''string''


==== Playlist.GetItems ====
====System.Shutdown====
Returns a list of items in the playlist, if you chose the right playlist type, also returns state information
Shuts the system running XBMC down<br />
<pre>
'''Permission:''' ControlPower<br />
PARAMETER
'''Parameters:''' None
playlist-file      string    OPTIONAL: id of file playlist
<br />
playlist-virtual  string     OPTIONAL: id of virtual playlist
'''Returns: '''''string''


RESULT
====System.Suspend====
items              array      a list of items in the playlist
Suspends the system running XBMC<br />
name              string     name of the playlist
'''Permission:''' ControlPower<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


===VideoLibrary===
====VideoLibrary.GetEpisodeDetails====
Retrieve details about a specific tv show episode<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' episodeid
#[ ''[[#Library.Fields.Episode|Library.Fields.Episode]]'' fields ]
'''Returns: '''
====VideoLibrary.GetEpisodes====
Retrieve all tv show episodes<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' tvshowid
#''any'' season
#[ ''[[#Library.Fields.Episode|Library.Fields.Episode]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoLibrary.GetMovieDetails====
Retrieve details about a specific movie<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' movieid
#[ ''[[#Library.Fields.Movie|Library.Fields.Movie]]'' fields ]
'''Returns: '''
====VideoLibrary.GetMovies====
Retrieve all movies<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Fields.Movie|Library.Fields.Movie]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoLibrary.GetMusicVideoDetails====
Retrieve details about a specific music video<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' musicvideoid
#[ ''[[#Library.Fields.MusicVideo|Library.Fields.MusicVideo]]'' fields ]
'''Returns: '''
====VideoLibrary.GetMusicVideos====
Retrieve all music videos<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
#[ ''[[#Library.Id|Library.Id]]'' albumid = -1 ]
#[ ''[[#Library.Fields.MusicVideo|Library.Fields.MusicVideo]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoLibrary.GetRecentlyAddedEpisodes====
Retrieve all recently added tv episodes<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Fields.Episode|Library.Fields.Episode]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoLibrary.GetRecentlyAddedMovies====
Retrieve all recently added movies<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Fields.Movie|Library.Fields.Movie]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoLibrary.GetRecentlyAddedMusicVideos====
Retrieve all recently added music videos<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Fields.MusicVideo|Library.Fields.MusicVideo]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoLibrary.GetSeasons====
Retrieve all tv seasons<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' tvshowid
#[ ''[[#Library.Fields.Season|Library.Fields.Season]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoLibrary.GetTVShowDetails====
Retrieve details about a specific tv show<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#''[[#Library.Id|Library.Id]]'' tvshowid
#[ ''[[#Library.Fields.TVShow|Library.Fields.TVShow]]'' fields ]
'''Returns: '''
====VideoLibrary.GetTVShows====
Retrieve all tv shows<br />
'''Permission:''' ReadData<br />
'''Parameters:'''
#[ ''[[#Library.Fields.TVShow|Library.Fields.TVShow]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoLibrary.ScanForContent====
Scans the video sources for new library items<br />
'''Permission:''' ScanLibrary<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


playing            boolean    whether currently playing  (This result is optional)
===VideoPlayer===
paused            boolean    whether currently paused  (This result is optional)
====VideoPlayer.BigSkipBackward====
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


start              number
====VideoPlayer.BigSkipForward====
total              number
'''Permission:''' ControlPlayback<br />
end                number
'''Parameters:''' None
<br />
'''Returns: '''''string''


====VideoPlayer.Forward====
Forward current playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


</pre>
====VideoPlayer.GetPercentage====
Retrieve current playback progress in percentage<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''''number''


==== Playlist.Add ====
====VideoPlayer.GetTime====
Adds file(s) to a given playlist (file or virtual)
Retrieves the current and total time of the currently playing file<br />
<pre>
'''Permission:''' ReadData<br />
PARAMETER
'''Parameters:''' None
playlist-file      string    OPTIONAL: id of file playlist
<br />
playlist-virtual  string    OPTIONAL: id of virtual playlist
'''Returns: '''
file              string    the file to add (path)
====VideoPlayer.PlayPause====
</pre>
Pauses or unpause playback and returns the new state<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''
====VideoPlayer.Rewind====
Rewind current playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== Playlist.Remove ====
====VideoPlayer.SeekPercentage====
Removes file from a given playlist (file or virtual)
Seek to a specific percentage<br />
<pre>
'''Permission:''' ControlPlayback<br />
PARAMETER
'''Parameters:'''
playlist-file      string        OPTIONAL: id of file playlist
#''[[#Player.SeekPercentage|Player.SeekPercentage]]'' value
playlist-virtual  string        OPTIONAL: id of virtual playlist
'''Returns: '''''string''
item              string/number id of item to remove
</pre>


==== Playlist.Swap ====
====VideoPlayer.SeekTime====
Swaps the position of two items in a given playlist
Seek to a specific time<br />
<pre>
'''Permission:''' ControlPlayback<br />
PARAMETER
'''Parameters:'''
playlist-file      string    OPTIONAL: id of file playlist
#''[[#Player.SeekTime|Player.SeekTime]]'' value
playlist-virtual  string    OPTIONAL: id of virtual playlist
'''Returns: '''''string''
item1              number    id of first item
item2              number    id of second item
</pre>


==== Playlist.Shuffle ====
====VideoPlayer.SkipNext====
Shuffles the playlist
Skips to next item on the playlist<br />
<pre>
'''Permission:''' ControlPlayback<br />
PARAMETER
'''Parameters:''' None
playlist-file      string    OPTIONAL: id of file playlist
<br />
playlist-virtual  string    OPTIONAL: id of virtual playlist
'''Returns: '''''string''
</pre>


==== Playlist.UnShuffle ====
====VideoPlayer.SkipPrevious====
Removes the shuffle from the playlist
Skips to previous item on the playlist<br />
<pre>
'''Permission:''' ControlPlayback<br />
PARAMETER
'''Parameters:''' None
playlist-file      string    OPTIONAL: id of file playlist
<br />
playlist-virtual  string    OPTIONAL: id of virtual playlist
'''Returns: '''''string''
</pre>


=== Files ===
====VideoPlayer.SmallSkipBackward====
Many functions in this namespace allow filtering by type, valid types are the following:
'''Permission:''' ControlPlayback<br />
<pre>
'''Parameters:''' None
video
<br />
music
'''Returns: '''''string''
pictures
files
programs
</pre>
==== Files.GetSources ====
Returns a list of available source directories (directories in root folder)
<pre>
PARAMETER
media              string     media type filter, see Files namespace documentation for details, media entry not included if no data


RESULT
====VideoPlayer.SmallSkipForward====
shares            array      a list of file items in the directory {"fanart":"", "file":"","label":""}
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


====VideoPlayer.State====
Returns playback state of the video player (if it is active)<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''
====VideoPlayer.Stop====
Stops playback<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


start              number
===VideoPlaylist===
total              number
====VideoPlaylist.Add====
end                number
Add item(s) to playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Video.Item|Playlist.Video.Item]]'' item
'''Returns: '''''string''


</pre>
====VideoPlaylist.Clear====
Clear playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== Files.Download ====
====VideoPlaylist.GetItems====
Returns information about how to download a file (does not return the file itself)
Get all items from playlist<br />
<pre>
'''Permission:''' ReadData<br />
PARAMETER        string     URI to a file (not a folder)
'''Parameters:'''
#[ ''[[#List.Fields.Video|List.Fields.Video]]'' fields ]
#[ ''[[#List.Limits|List.Limits]]'' limits ]
#[ ''[[#List.Sort|List.Sort]]'' sort ]
'''Returns: '''
====VideoPlaylist.Insert====
Insert item(s) into playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' index
#''[[#Playlist.Video.Item|Playlist.Video.Item]]'' item
'''Returns: '''''string''


====VideoPlaylist.Play====
Play current or a specific item<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#[ ''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item = -1 ]
'''Returns: '''
====VideoPlaylist.Remove====
Remove item from playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''[[#Playlist.Item.Position|Playlist.Item.Position]]'' item
'''Returns: '''''string''


RESULT
====VideoPlaylist.Shuffle====
path              string
Shuffle playlist<br />
</pre>
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


==== Files.GetDirectory ====
====VideoPlaylist.SkipNext====
Returns a list of items in a directory, items can be filtered by type.
Skip current item and play next item<br />
<pre>
'''Permission:''' ControlPlayback<br />
PARAMETER
'''Parameters:''' None
directory          string    the directory to list, e.g. foo/bar
<br />
media              string     media type filter, see Files namespace documentation for details
'''Returns: '''''string''


RESULT
====VideoPlaylist.SkipPrevious====
directories        array      sub-directories in this directory
Skip current item and play previous item<br />
files              array      files in this directory
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


====VideoPlaylist.UnShuffle====
Unshuffle playlist<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''''string''


start              number
===XBMC===
total              number
====XBMC.GetVolume====
end                number
Retrieve the current volume<br />
'''Permission:''' ReadData<br />
'''Parameters:''' None
<br />
'''Returns: '''''integer''


====XBMC.Log====
Logs a line in the xbmc.log<br />
'''Permission:''' Logging<br />
'''Parameters:'''
#''string'' message
#[ ''string'' level = "debug" ]
'''Returns: '''''string''


</pre>
====XBMC.Play====
Starts playback of the given file<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''string'' file
'''Returns: '''''string''


=== AudioLibrary ===
====XBMC.Quit====
==== AudioLibrary.GetArtists ====
Quit XBMC<br />
Returns a list of artists in the audio library
'''Permission:''' ControlPower<br />
<pre>
'''Parameters:''' None
PARAMETER
<br />
genreid            number    filters by this genre id, -1 means all.
'''Returns: '''''string''


RESULT
====XBMC.SetVolume====
artists            array      artists in the library { "artistid" : number ,"fanart":string,"label":string, "thumbnail" :stringORnotpresent}
Set the current volume<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''integer'' value
'''Returns: '''''integer''


start              number
====XBMC.StartSlideshow====
total              number
Starts slideshow with the images from the given directory<br />
end                number
'''Permission:''' ControlPlayback<br />
'''Parameters:'''
#''string'' directory
#[ ''boolean'' random = True ]
#[ ''boolean'' recursive = True ]
'''Returns: '''''string''


</pre>
====XBMC.ToggleMute====
Toggle mute/unmute<br />
'''Permission:''' ControlPlayback<br />
'''Parameters:''' None
<br />
'''Returns: '''


==== AudioLibrary.GetAlbums ====
==Global types==
Returns a list of albums in the audio library
===Files===
<pre>
====Files.Media====
PARAMETER
'''Type:''' ''string''<br />
genreid            number    filters by this genre id
'''Optional:''' false
artistid          number    filters by this artist id
===Library===
start              number    integer value to start result listing from
====Library.Fields.Album====
end                number    integer value to end result listing from
'''Type:''' ''array''<br />
'''Optional:''' true
====Library.Fields.Episode====
'''Type:''' ''array''<br />
'''Optional:''' true
====Library.Fields.Movie====
'''Type:''' ''array''<br />
'''Optional:''' true
====Library.Fields.MusicVideo====
'''Type:''' ''array''<br />
'''Optional:''' true
====Library.Fields.Season====
'''Type:''' ''array''<br />
'''Optional:''' true
====Library.Fields.Song====
'''Type:''' ''array''<br />
'''Optional:''' true
====Library.Fields.TVShow====
'''Type:''' ''array''<br />
'''Optional:''' true
====Library.Id====
'''Type:''' ''integer''<br />
'''Optional:''' true<br />
'''Default:''' -1
===List===
====List.Fields.All====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Fields.Video====
'''Type:''' ''array''<br />
'''Optional:''' true
====List.Limits====
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''integer'' start = 0 ]
*[ ''integer'' end = -1 ]


RESULT
====List.Sort====
albums            array      artists in the library {"albumid" : number, "fanart" : string, "label" : string, "thumbnail" : string}
'''Type:''' ''object''<br />
'''Optional:''' true<br />
'''Properties:'''
*[ ''string'' order = "ascending" ]
*[ ''boolean'' ignorearticle = False ]
*[ ''string'' method = "none" ]


start              number
===Player===
total              number
====Player.SeekPercentage====
end                number
'''Type:''' ''number''<br />
'''Optional:''' false
====Player.SeekTime====
'''Type:''' ''integer''<br />
'''Optional:''' false
===Playlist===
====Playlist.Audio.Item====
'''Type:''' ''object''<br />
'''Optional:''' false<br />
'''Properties:'''
*[ ''[[#Library.Id|Library.Id]]'' songid = -1 ]
*[ ''[[#Playlist.Id|Playlist.Id]]'' playlist ]
*[ ''[[#Library.Id|Library.Id]]'' albumid = -1 ]
*[ ''[[#Library.Id|Library.Id]]'' artistid = -1 ]
*[ ''string'' file = "" ]
*[ ''[[#Library.Id|Library.Id]]'' genreid = -1 ]


</pre>
====Playlist.Id====
'''Type:''' ''object''<br />
'''Optional:''' false<br />
'''Properties:'''
*[ ''string'' id = "" ]
*[ ''string'' file = "" ]


==== AudioLibrary.GetSongs ====
====Playlist.Item.Position====
Returns a list of albums in the audio library
'''Type:''' ''integer''<br />
<pre>
'''Optional:''' true<br />
PARAMETER
'''Default:''' -1
fields            string    OPTIONAL: fields to return information for
====Playlist.Video.Item====
genreid            number    filters by this genre id
'''Type:''' ''object''<br />
artistid          number    filters by this artist id
'''Optional:''' false<br />
albumid            number    filters by this album id
'''Properties:'''
 
*[ ''[[#Playlist.Id|Playlist.Id]]'' playlist ]
RESULT
*[ ''[[#Library.Id|Library.Id]]'' movieid = -1 ]
albums            array      artists in the library {"fanart" : string, "file" : string, "label" : string, "songid" : number, "thumbnail" : string}
*[ ''[[#Library.Id|Library.Id]]'' episodeid = -1 ]
 
*[ ''string'' file = "" ]
start              number
*[ ''[[#Library.Id|Library.Id]]'' musicvideoid = -1 ]
total              number
end                number
 
</pre>
 
==== 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
 
<pre>
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}
</pre>
 
==== VideoLibrary.GetTVShows ====
Returns a list of tv shows in the video library
<pre>
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
</pre>
 
==== VideoLibrary.GetSeasons ====
Returns a list of seasons for a given tv show
<pre>
PARAMETER
tvshowid          number    id of the tv show to get seasons for
 
RESULT
seasons          array      seasons for the tv show
</pre>
 
==== VideoLibrary.GetEpisodes ====
Returns a list of episodes for a tv show and season
<pre>
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
</pre>
 
==== VideoLibrary.GetMusicVideos ====
Returns a list of Music videos in the video library
<pre>
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
</pre>
 
==== VideoLibrary.GetRecentlyAddedMovies ====
eturns a list of recently added movies in the video library
<pre>
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
</pre>
 
==== VideoLibrary.GetRecentlyAddedEpisodes ====
Returns a list of recently added episodes to the library
<pre>
PARAMETER
 
RESULT
episodes          array      seasons for the tv show
</pre>
 
==== VideoLibrary.GetRecentlyAddedMusicVideos ====
Returns a list of Music videos in the video library
<pre>
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
</pre>
 
==== 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
 
<pre>
PARAMETER        array      of string    <field name>s to return information for
 
RESULT            array      of object
<field name>    string    label that field 
</pre>
 
==== System.GetInfoBooleans ====
Get info booleans about the system
Available field names: <code>system.canshutdown  system.canpowerdown  system.cansuspend  system.canhibernate  system.canreboot</code>
<pre>
PARAMETER        array      of string    <field name>s to return information for
 
RESULT            array      of object
<field name>    boolean    value of that field 
</pre>
Example parameters:<br />
<code>[ 'system.canshutdown', 'system.cansuspend' ]</code>
 
Example result: <br />
<code>[ { 'system.canshutdown' : true }, { 'system.cansuspend' : true }]</code>
 
=== XBMC ===
==== XBMC.GetVolume ====
Gets the current volume
<pre>
RESULT            number    volume 
</pre>
 
==== XBMC.SetVolume ====
Sets the current volume as an int percent
<pre>
PARAMETER        number    volume to set to
</pre>
 
==== XBMC.ToggleMute ====
Toggle volume mute on/off, returns same as XBMC.GetVolume
 
==== XBMC.Play ====
Starts playback
 
==== XBMC.StartSlideshow ====
Starts slideshow
<pre>
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
</pre>
==== XBMC.Log ====
Logs a line in xbmc.log
<pre>
PARAMETER        string    text to log
OR
PARAMETER
message          string    text to log
level            string    log level, "debug", "info", "notice", "warning", "error", "severe", "fatal", "none"
</pre>
 
==== XBMC.Quit ====
Exits XBMC


== Debugging ==
== Debugging ==

Revision as of 15:33, 22 April 2011

Overview

JSON RPC is a HTTP-based or raw TCP Socket interface for communicating with XBMC. It replaces the soon-to-be-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.

Each method in the interface can have different security needs which means one client may be allowed to only control playback while another can only read and manipulate the library. In version 2 (first stable) all clients are granted full authority but will later be forced to ask for privileges and the user of XBMC will have to grant said client access. The design of JSON RPC is that most methods should behave roughly the same and maintain consistency while hiding the mechanics of XBMC from the client creator.

In XBMC JSON RPC can be accessed over a variety of transports and has been designed from the ground up to be flexible to allow control over new transports simply. Some of the transports have different limitations which will be enforced upon the interaction over that transport. As an example HTTP Transports allow response and downloading of files while the Raw TCP Transport allows response and announcements (events and information XBMC sends to its clients). Depending on the clients needs it will choose one (or many) of the transports.

Enabling JSON RPC

Since the interface is available on many transports enabling it will depends on the transport.

  • Python. Always enabled
  • HTTP. Enable webserver
  • TCP. "Allow External Control of XBMC" for localhost control and "Allow Control from other computers" for access from outside localhost.

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

Methods

AudioLibrary

AudioLibrary.GetAlbumDetails

Retrieve details about a specific album
Permission: ReadData
Parameters:

  1. Library.Id albumid
  2. [ Library.Fields.Album fields ]

Returns:

AudioLibrary.GetAlbums

Retrieve all albums from specified artist or genre
Permission: ReadData
Parameters:

  1. [ Library.Id artistid = -1 ]
  2. [ Library.Id genreid = -1 ]
  3. [ Library.Fields.Album fields ]
  4. [ List.Limits limits ]
  5. [ List.Sort sort ]

Returns:

AudioLibrary.GetArtists

Retrieve all artists
Permission: ReadData
Parameters:

  1. [ Library.Id genreid = -1 ]
  2. [ array fields ]
  3. [ List.Limits limits ]
  4. [ List.Sort sort ]

Returns:

AudioLibrary.GetGenres

Retrieve all genres
Permission: ReadData
Parameters:

  1. [ List.Limits limits ]
  2. [ List.Sort sort ]

Returns:

AudioLibrary.GetSongDetails

Retrieve details about a specific song
Permission: ReadData
Parameters:

  1. Library.Id songid
  2. [ Library.Fields.Song fields ]

Returns:

AudioLibrary.GetSongs

Retrieve all songs from specified album, artist or genre
Permission: ReadData
Parameters:

  1. [ Library.Id artistid = -1 ]
  2. [ Library.Id albumid = -1 ]
  3. [ Library.Id genreid = -1 ]
  4. [ Library.Fields.Song fields ]
  5. [ List.Limits limits ]
  6. [ List.Sort sort ]

Returns:

AudioLibrary.ScanForContent

Scans the audio sources for new library items
Permission: ScanLibrary
Parameters: None
Returns: string

AudioPlayer

AudioPlayer.BigSkipBackward

Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.BigSkipForward

Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.Forward

Forward current playback
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.GetPercentage

Retrieve current playback progress in percentage
Permission: ReadData
Parameters: None
Returns: number

AudioPlayer.GetTime

Retrieves the current and total time of the currently playing file
Permission: ReadData
Parameters: None
Returns:

AudioPlayer.PlayPause

Pauses or unpause playback and returns the new state
Permission: ControlPlayback
Parameters: None
Returns:

AudioPlayer.Rewind

Rewind current playback
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.SeekPercentage

Seek to a specific percentage
Permission: ControlPlayback
Parameters:

  1. Player.SeekPercentage value

Returns: string

AudioPlayer.SeekTime

Seek to a specific time
Permission: ControlPlayback
Parameters:

  1. Player.SeekTime value

Returns: string

AudioPlayer.SkipNext

Skips to next item on the playlist
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.SkipPrevious

Skips to previous item on the playlist
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.SmallSkipBackward

Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.SmallSkipForward

Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.State

Returns playback state of the audio player (if it is active)
Permission: ReadData
Parameters: None
Returns:

AudioPlayer.Stop

Stops playback
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlaylist

AudioPlaylist.Add

Add item(s) to playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Audio.Item item

Returns: string

AudioPlaylist.Clear

Clear playlist
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlaylist.GetItems

Get all items from playlist
Permission: ReadData
Parameters:

  1. [ Library.Fields.Song fields ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

AudioPlaylist.Insert

Insert item(s) into playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Item.Position index
  2. Playlist.Audio.Item item

Returns: string

AudioPlaylist.Play

Play current or a specific item
Permission: ControlPlayback
Parameters:

  1. [ Playlist.Item.Position item = -1 ]
  2. [ Library.Id songid = -1 ]

Returns:

AudioPlaylist.Remove

Remove item from playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Item.Position item

Returns: string

AudioPlaylist.Shuffle

Shuffle playlist
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlaylist.SkipNext

Skip current item and play next item
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlaylist.SkipPrevious

Skip current item and play previous item
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlaylist.UnShuffle

Unshuffle playlist
Permission: ControlPlayback
Parameters: None
Returns: string

Files

Files.Download

Permission: ReadData
Parameters:

  1. string path

Returns:

Files.GetDirectory

Permission: ReadData
Parameters:

  1. string directory
  2. [ Files.Media media = "files" ]
  3. [ List.Fields.All fields ]
  4. [ List.Sort sort ]

Returns:

Files.GetSources

Get the sources of the media windows
Permission: ReadData
Parameters:

  1. Files.Media media
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

Input

Input.Back

Goes back in GUI
Permission: Navigate
Parameters: None
Returns: string

Input.Down

Navigate down in GUI
Permission: Navigate
Parameters: None
Returns: string

Input.Home

Goes to home window in GUI
Permission: Navigate
Parameters: None
Returns: string

Input.Left

Navigate left in GUI
Permission: Navigate
Parameters: None
Returns: string

Input.Right

Navigate right in GUI
Permission: Navigate
Parameters: None
Returns: string

Input.Select

Select current item in GUI
Permission: Navigate
Parameters: None
Returns: string

Input.Up

Navigate up in GUI
Permission: Navigate
Parameters: None
Returns: string

JSONRPC

JSONRPC.GetNotificationFlags

Get notification flags
Permission: ReadData
Parameters: None
Returns:

JSONRPC.Introspect

Enumerates all actions and descriptions
Permission: ReadData
Parameters:

  1. [ boolean getdescriptions = True ]
  2. [ boolean getmetadata = False ]
  3. [ boolean filterbytransport = True ]

Returns: object

JSONRPC.NotifyAll

Notify all other connected clients
Permission: ReadData
Parameters:

  1. string sender
  2. string message
  3. [ any data = null ]

Returns: any

JSONRPC.Permission

Retrieve the clients permissions
Permission: ReadData
Parameters: None
Returns:

JSONRPC.Ping

Ping responder
Permission: ReadData
Parameters: None
Returns: string

JSONRPC.SetNotificationFlags

Change the notification flags
Permission: ControlNotify
Parameters:

  1. [ boolean Playback = False ]
  2. [ boolean GUI = False ]
  3. [ boolean System = False ]
  4. [ boolean Library = False ]
  5. [ boolean Other = False ]

Returns:

JSONRPC.Version

Retrieve the jsonrpc protocol version
Permission: ReadData
Parameters: None
Returns: string

PicturePlayer

PicturePlayer.MoveDown

If picture is zoomed move viewport down
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.MoveLeft

If picture is zoomed move viewport left otherwise skip previous
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.MoveRight

If picture is zoomed move viewport right otherwise skip next
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.MoveUp

If picture is zoomed move viewport up
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.PlayPause

Pauses or unpause slideshow
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.Rotate

Rotates current picture
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.SkipNext

Skips to next picture in the slideshow
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.SkipPrevious

Skips to previous picture in the slideshow
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.Stop

Stops slideshow
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.Zoom

Zooms current picture
Permission: ControlPlayback
Parameters:

  1. integer value

Returns: string

PicturePlayer.ZoomIn

Zoom in once
Permission: ControlPlayback
Parameters: None
Returns: string

PicturePlayer.ZoomOut

Zoom out once
Permission: ControlPlayback
Parameters: None
Returns: string

Player

Player.GetActivePlayers

Returns all active players
Permission: ReadData
Parameters: None
Returns:

Playlist

Playlist.Add

Add items to the playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Id playlist
  2. Playlist.Id items

Returns: string

Playlist.Clear

Clear playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Id playlist

Returns: string

Playlist.Create

Creates a virtual playlist from a given one from a file
Permission: ReadData
Parameters:

  1. Playlist.Id playlist

Returns:

Playlist.Destroy

Destroys a virtual playlist
Permission: ReadData
Parameters:

  1. string playlistid

Returns: string

Playlist.GetItems

Retrieve items in the playlist
Permission: ReadData
Parameters:

  1. Playlist.Id playlist
  2. [ List.Fields.All fields ]
  3. [ List.Limits limits ]
  4. [ List.Sort sort ]

Returns:

Playlist.Remove

Remove item from the playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Id playlist
  2. ['string', 'integer'] item

Returns: string

Playlist.Shuffle

Shuffle playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Id playlist

Returns: string

Playlist.Swap

Swap items in the playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Id playlist
  2. Playlist.Item.Position item1
  3. Playlist.Item.Position item2

Returns: string

Playlist.UnShuffle

Unshuffle playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Id playlist

Returns: string

System

System.GetInfoBooleans

Retrieve info booleans about the system
Permission: ReadData
Parameters:

  1. array[1..X] booleans

Returns:

System.GetInfoLabels

Retrieve info labels about the system
Permission: ReadData
Parameters:

  1. array[1..X] labels

Returns:

System.Hibernate

Puts the system running XBMC into hibernate mode
Permission: ControlPower
Parameters: None
Returns: string

System.Reboot

Reboots the system running XBMC
Permission: ControlPower
Parameters: None
Returns: string

System.Shutdown

Shuts the system running XBMC down
Permission: ControlPower
Parameters: None
Returns: string

System.Suspend

Suspends the system running XBMC
Permission: ControlPower
Parameters: None
Returns: string

VideoLibrary

VideoLibrary.GetEpisodeDetails

Retrieve details about a specific tv show episode
Permission: ReadData
Parameters:

  1. Library.Id episodeid
  2. [ Library.Fields.Episode fields ]

Returns:

VideoLibrary.GetEpisodes

Retrieve all tv show episodes
Permission: ReadData
Parameters:

  1. Library.Id tvshowid
  2. any season
  3. [ Library.Fields.Episode fields ]
  4. [ List.Limits limits ]
  5. [ List.Sort sort ]

Returns:

VideoLibrary.GetMovieDetails

Retrieve details about a specific movie
Permission: ReadData
Parameters:

  1. Library.Id movieid
  2. [ Library.Fields.Movie fields ]

Returns:

VideoLibrary.GetMovies

Retrieve all movies
Permission: ReadData
Parameters:

  1. [ Library.Fields.Movie fields ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

VideoLibrary.GetMusicVideoDetails

Retrieve details about a specific music video
Permission: ReadData
Parameters:

  1. Library.Id musicvideoid
  2. [ Library.Fields.MusicVideo fields ]

Returns:

VideoLibrary.GetMusicVideos

Retrieve all music videos
Permission: ReadData
Parameters:

  1. [ Library.Id artistid = -1 ]
  2. [ Library.Id albumid = -1 ]
  3. [ Library.Fields.MusicVideo fields ]
  4. [ List.Limits limits ]
  5. [ List.Sort sort ]

Returns:

VideoLibrary.GetRecentlyAddedEpisodes

Retrieve all recently added tv episodes
Permission: ReadData
Parameters:

  1. [ Library.Fields.Episode fields ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

VideoLibrary.GetRecentlyAddedMovies

Retrieve all recently added movies
Permission: ReadData
Parameters:

  1. [ Library.Fields.Movie fields ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

VideoLibrary.GetRecentlyAddedMusicVideos

Retrieve all recently added music videos
Permission: ReadData
Parameters:

  1. [ Library.Fields.MusicVideo fields ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

VideoLibrary.GetSeasons

Retrieve all tv seasons
Permission: ReadData
Parameters:

  1. Library.Id tvshowid
  2. [ Library.Fields.Season fields ]
  3. [ List.Limits limits ]
  4. [ List.Sort sort ]

Returns:

VideoLibrary.GetTVShowDetails

Retrieve details about a specific tv show
Permission: ReadData
Parameters:

  1. Library.Id tvshowid
  2. [ Library.Fields.TVShow fields ]

Returns:

VideoLibrary.GetTVShows

Retrieve all tv shows
Permission: ReadData
Parameters:

  1. [ Library.Fields.TVShow fields ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

VideoLibrary.ScanForContent

Scans the video sources for new library items
Permission: ScanLibrary
Parameters: None
Returns: string

VideoPlayer

VideoPlayer.BigSkipBackward

Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.BigSkipForward

Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.Forward

Forward current playback
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.GetPercentage

Retrieve current playback progress in percentage
Permission: ReadData
Parameters: None
Returns: number

VideoPlayer.GetTime

Retrieves the current and total time of the currently playing file
Permission: ReadData
Parameters: None
Returns:

VideoPlayer.PlayPause

Pauses or unpause playback and returns the new state
Permission: ControlPlayback
Parameters: None
Returns:

VideoPlayer.Rewind

Rewind current playback
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.SeekPercentage

Seek to a specific percentage
Permission: ControlPlayback
Parameters:

  1. Player.SeekPercentage value

Returns: string

VideoPlayer.SeekTime

Seek to a specific time
Permission: ControlPlayback
Parameters:

  1. Player.SeekTime value

Returns: string

VideoPlayer.SkipNext

Skips to next item on the playlist
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.SkipPrevious

Skips to previous item on the playlist
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.SmallSkipBackward

Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.SmallSkipForward

Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.State

Returns playback state of the video player (if it is active)
Permission: ReadData
Parameters: None
Returns:

VideoPlayer.Stop

Stops playback
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlaylist

VideoPlaylist.Add

Add item(s) to playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Video.Item item

Returns: string

VideoPlaylist.Clear

Clear playlist
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlaylist.GetItems

Get all items from playlist
Permission: ReadData
Parameters:

  1. [ List.Fields.Video fields ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

VideoPlaylist.Insert

Insert item(s) into playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Item.Position index
  2. Playlist.Video.Item item

Returns: string

VideoPlaylist.Play

Play current or a specific item
Permission: ControlPlayback
Parameters:

  1. [ Playlist.Item.Position item = -1 ]

Returns:

VideoPlaylist.Remove

Remove item from playlist
Permission: ControlPlayback
Parameters:

  1. Playlist.Item.Position item

Returns: string

VideoPlaylist.Shuffle

Shuffle playlist
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlaylist.SkipNext

Skip current item and play next item
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlaylist.SkipPrevious

Skip current item and play previous item
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlaylist.UnShuffle

Unshuffle playlist
Permission: ControlPlayback
Parameters: None
Returns: string

XBMC

XBMC.GetVolume

Retrieve the current volume
Permission: ReadData
Parameters: None
Returns: integer

XBMC.Log

Logs a line in the xbmc.log
Permission: Logging
Parameters:

  1. string message
  2. [ string level = "debug" ]

Returns: string

XBMC.Play

Starts playback of the given file
Permission: ControlPlayback
Parameters:

  1. string file

Returns: string

XBMC.Quit

Quit XBMC
Permission: ControlPower
Parameters: None
Returns: string

XBMC.SetVolume

Set the current volume
Permission: ControlPlayback
Parameters:

  1. integer value

Returns: integer

XBMC.StartSlideshow

Starts slideshow with the images from the given directory
Permission: ControlPlayback
Parameters:

  1. string directory
  2. [ boolean random = True ]
  3. [ boolean recursive = True ]

Returns: string

XBMC.ToggleMute

Toggle mute/unmute
Permission: ControlPlayback
Parameters: None
Returns:

Global types

Files

Files.Media

Type: string
Optional: false

Library

Library.Fields.Album

Type: array
Optional: true

Library.Fields.Episode

Type: array
Optional: true

Library.Fields.Movie

Type: array
Optional: true

Library.Fields.MusicVideo

Type: array
Optional: true

Library.Fields.Season

Type: array
Optional: true

Library.Fields.Song

Type: array
Optional: true

Library.Fields.TVShow

Type: array
Optional: true

Library.Id

Type: integer
Optional: true
Default: -1

List

List.Fields.All

Type: array
Optional: true

List.Fields.Video

Type: array
Optional: true

List.Limits

Type: object
Optional: true
Properties:

  • [ integer start = 0 ]
  • [ integer end = -1 ]

List.Sort

Type: object
Optional: true
Properties:

  • [ string order = "ascending" ]
  • [ boolean ignorearticle = False ]
  • [ string method = "none" ]

Player

Player.SeekPercentage

Type: number
Optional: false

Player.SeekTime

Type: integer
Optional: false

Playlist

Playlist.Audio.Item

Type: object
Optional: false
Properties:

Playlist.Id

Type: object
Optional: false
Properties:

  • [ string id = "" ]
  • [ string file = "" ]

Playlist.Item.Position

Type: integer
Optional: true
Default: -1

Playlist.Video.Item

Type: object
Optional: false
Properties:

Debugging

Output format

To be able to support easier debugging of (third party) development using the JSON RPC API, the JSON output generated by XBMC can be pretty printed by setting 

<jsonrpc>
    <compactoutput>false</compactoutput>
</jsonrpc>

in the advancedsettings.xml. Default JSON output will be in compact format to minimize sent data (especially useful for mobile devices).

Direct interaction

To be able to test some methods of XBMC's JSON RPC API it can be of great help to be able to send a single hand-written JSON RPC request to XBMC to see its effect and the generated response. Depending on the transport protocol used there are different possibilities to do that:

TCP

With a telnet connection (using PuTTY on Windows or telnet on Linux) to port 9090 of the machine running XBMC it is possible to send and receive raw json data to/from XBMC.

HTTP

A simple way of manually sending HTTP requests containing a JSON RPC request to XBMC is using the Simple REST Client extension for Google's Chrome/Chromium browser. It allows defining an URL and the HTTP request type (POST is what we need). The actual JSON RPC request can be defined in the Data field and then sent to XBMC.

Development

Dharma (10.0)

Supported features of JSON RPC 2.0

  • Method calls (with or without parameters) over HTTP or TCP
  • Server-side (XBMC) announcements (over TCP port 9090)
  • by-name parameters

Unsupported features of JSON RPC 2.0

  • support for by-value OR by-position parameters
  • "params" must always be an array (by-position) or an object (by-value) but never a simple type
  • Client-side announcements (XBMC returns an error response)
  • Bulk requests (XBMC returns a parse error response)

Eden (11.0) [WIP]

Additionally supported features of JSON RPC 2.0

  • Client-side announcements (methods can be called without the "id" field which will result in the execution of the method without returning a response) 625699dcd724b771c327
  • Bulk requests (multiple method calls can be sent as an array in a single json rpc request; all methods are executed and the response contains all responses of the bulk request in an array) 605dbbc542e61c888be4
  • Default JSON output in compact format (Advanced Settings option to disable compact json output) 20e18ee556b324da8f83
  • support for by-value OR by-position parameters 774b8868ee59a1778ad5
  • "params" must always be an array (by-position) or an object (by-value) but never a simple type 774b8868ee59a1778ad5

General improvement areas

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

Retrieved from "https://kodi.wiki/index.php?title=JSON-RPC_API&oldid=24120"