XBMC will be renamed to Kodi for v14. Read here for more details
Various pages on the wiki might contain old references to "XBMC", but will most often still apply to "Kodi". Find out how you can help here.

JSON-RPC API/v2, Template:Divbox

From Kodi
< JSON-RPC API(Difference between pages)
Jump to: navigation, search
m (Robot: Cosmetic changes)
 
 
Line 1: Line 1:
{{DevsHeader|'''XBMC (Dharma) JSON-RPC API'''}}
+
<div class="boilerplate metadata" id="{{{2}}}" style="{{divstyle{{{1}}}}}"><center><b>{{{2}}}</b></center>{{{3}}}</div>
{{DISPLAYTITLE:JSON-RPC v2 (Dharma)}}{{JSON-RPC API nav}}<br />
+
  
Version 2 is the first official version of the JSON-RPC API. It does not fullfil all the features, functionalities and requirements of the [http://jsonrpc.org/spec.html JSON-RPC 2.0 specification] and should therefore not be used anymore.
+
<noinclude>
 +
==How to use==
 +
<nowiki>{{divbox|color of box|Headtitle|Message}}</nowiki>
 +
==Example==
 +
<nowiki>{{divbox|green|An example|This is only an example of how this template works.}}</nowiki>
  
{{TOC right}}
+
Writing this code will give you...
== JSON-RPC 2.0 compatibility ==
+
{| class="wikitable" style="margin-right: 0;"
+
!style="padding-left: 5px; width: 7em; text-align: left;"|Version
+
!style="padding-left: 10px; padding-right: 10px;"|Method calls
+
!style="padding-left: 10px; padding-right: 10px;"|Notifications<br />(server-side)
+
!style="padding-left: 10px; padding-right: 10px;"|Notifications<br />(client-side)
+
!style="padding-left: 10px; padding-right: 10px;"|Parameters<br />by-name
+
!style="padding-left: 10px; padding-right: 10px;"|Parameters<br />by-position
+
!style="padding-left: 10px; padding-right: 10px;"|Batch requests
+
|-
+
|style="padding-left: 5px;"|Version 2
+
|{{yes}}
+
|{{yes}}
+
|{{no}}
+
|{{yes}}
+
|{{no}}
+
|{{no}}
+
|-
+
|}
+
  
== Documentation ==
+
{{divbox|green|An example|This is only an example of how this template works.}}
Using the [[#JSONRPC.Introspect|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 ==
+
[[Category:Templates|Divbox]]
XBMC's JSON-RPC API is split up into namespaces, which contain methods that can be called. These namespaces are:
+
</noinclude>
<pre>
+
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
+
</pre>
+
  
== Methods ==
+
woohoo were cool
=== JSONRPC ===
+
==== JSONRPC.Introspect ====
+
Returns a list of all available method calls
+
<pre>
+
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
+
</pre>
+
 
+
==== 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").
+
<pre>
+
 
+
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
+
</pre>
+
 
+
=== Player ===
+
==== Player.GetActivePlayers ====
+
Returns which players are active (available for querying)<br />
+
Note: AudioPlayer, VideoPlayer and Slideshow methods are only available if there respective player is active, use this function to obtain that information
+
<pre>
+
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
+
</pre>
+
 
+
=== AudioPlayer ===
+
==== AudioPlayer.State ====
+
Gets the state of the audio player
+
<pre>
+
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
+
</pre>
+
 
+
==== AudioPlayer.PlayPause ====
+
Pauses or unpauses playback, returns new state
+
<pre>
+
RESULT
+
playing            boolean    True if audio is currently playing
+
paused            boolean    True if audio is currently paused
+
</pre>
+
 
+
==== 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
+
<pre>
+
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
+
</pre>
+
 
+
==== AudioPlayer.GetTimeMS ====
+
Gets the state of the audio player, including time information, to the millisecond
+
<pre>
+
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
+
</pre>
+
 
+
==== AudioPlayer.GetPercentage ====
+
Gets a percentage, of what is not obviously documented, presumably Position/Duration*100
+
<pre>
+
RESULT            number    Percentage
+
</pre>
+
 
+
==== AudioPlayer.SeekTime ====
+
Seek to a position in the track defined by position in seconds
+
<pre>
+
PARAMETER          number    Position to seek to
+
</pre>
+
 
+
==== AudioPlayer.SeekPercentage ====
+
Seek to a position in the track defined by a percentage (of total duration?)
+
<pre>
+
PARAMETER          number    Percentage to seek to
+
</pre>
+
 
+
=== 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
+
<pre>
+
PARAMETER          number    Zoom level to seek to, as a whole number between 1-10
+
</pre>
+
 
+
==== PicturePlayer.Rotate ====
+
Rotate the current picture (clockwise or anticlockwise?)
+
 
+
=== AudioPlaylist ===
+
==== AudioPlaylist.Play ====
+
Starts playing a playlist
+
<pre>
+
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
+
</pre>
+
 
+
==== 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
+
<pre>
+
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
+
</pre>
+
 
+
==== AudioPlaylist.Add ====
+
Adds a track to the current audio playlist
+
<pre>
+
PARAMETER       
+
file              string            uri of the file to add
+
</pre>
+
 
+
==== 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
+
 
+
<pre>
+
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
+
</pre>
+
 
+
==== Playlist.Destroy ====
+
Destroys (deletes) a virtual playlist
+
<pre>
+
PARAMETER      string    id of virtual playlist to delete
+
</pre>
+
 
+
==== Playlist.GetItems ====
+
Returns a list of items in the playlist, if you chose the right playlist type, also returns state information
+
<pre>
+
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
+
 
+
 
+
</pre>
+
 
+
==== Playlist.Add ====
+
Adds file(s) to a given playlist (file or virtual)
+
<pre>
+
PARAMETER
+
playlist-file      string    OPTIONAL: id of file playlist
+
playlist-virtual  string    OPTIONAL: id of virtual playlist
+
file              string    the file to add (path)
+
</pre>
+
 
+
==== Playlist.Remove ====
+
Removes file from a given playlist (file or virtual)
+
<pre>
+
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
+
</pre>
+
 
+
==== Playlist.Swap ====
+
Swaps the position of two items in a given playlist
+
<pre>
+
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
+
</pre>
+
 
+
==== Playlist.Shuffle ====
+
Shuffles the playlist
+
<pre>
+
PARAMETER
+
playlist-file      string    OPTIONAL: id of file playlist
+
playlist-virtual  string    OPTIONAL: id of virtual playlist
+
</pre>
+
 
+
==== Playlist.UnShuffle ====
+
Removes the shuffle from the playlist
+
<pre>
+
PARAMETER
+
playlist-file      string    OPTIONAL: id of file playlist
+
playlist-virtual  string    OPTIONAL: id of virtual playlist
+
</pre>
+
 
+
=== Files ===
+
Many functions in this namespace allow filtering by type, valid types are the following:
+
<pre>
+
video
+
music
+
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
+
shares            array      a list of file items in the directory {"fanart":"", "file":"","label":""}
+
 
+
 
+
start              number
+
total              number
+
end                number
+
 
+
</pre>
+
 
+
==== Files.Download ====
+
Returns information about how to download a file (does not return the file itself)
+
<pre>
+
PARAMETER        string    URI to a file (not a folder)
+
 
+
 
+
RESULT
+
path              string
+
</pre>
+
 
+
==== Files.GetDirectory ====
+
Returns a list of items in a directory, items can be filtered by type.
+
<pre>
+
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
+
 
+
 
+
</pre>
+
 
+
=== AudioLibrary ===
+
==== AudioLibrary.GetArtists ====
+
Returns a list of artists in the audio library
+
<pre>
+
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
+
 
+
</pre>
+
 
+
==== AudioLibrary.GetAlbums ====
+
Returns a list of albums in the audio library
+
<pre>
+
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
+
 
+
</pre>
+
 
+
==== AudioLibrary.GetSongs ====
+
Returns a list of albums in the audio library
+
<pre>
+
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
+
 
+
</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
+
 
+
== See also ==
+
* [[JSON-RPC API]]
+
* [[JSON-RPC API/v3|JSON-RPC API v3 (pre Eden)]]
+
 
+
[[Category:Development]]
+

Revision as of 01:33, 15 April 2007


1 How to use

{{divbox|color of box|Headtitle|Message}}

2 Example

{{divbox|green|An example|This is only an example of how this template works.}}

Writing this code will give you...


woohoo were cool

Personal tools
Namespaces

Variants
Actions
Navigation
Wiki help
Toolbox