XBMC will be renamed to Kodi for v14. Read here for more details

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 02: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