JSON-RPC API: Difference between revisions
>DCMarkie |
>Giftie |
||
Line 1,167: | Line 1,167: | ||
'''Type:''' ''array''<br /> | '''Type:''' ''array''<br /> | ||
'''Optional:''' true<br /> | '''Optional:''' true<br /> | ||
'''Fields:''' "genre","director","trailer","tagline","plot","plotoutline"," | '''Fields:''' "title", "genre", "year", "rating", "director", "trailer", "tagline", "plot", "plotoutline", "originaltitle", "lastplayed", "playcount", "writer", "studio", "mpaa", "cast", "country", "imdbnumber", "premiered", "productioncode", "runtime", "set", "showlink", "streamDetails", "top250", "votes", "writingcredits", "fanart", "thumbnail", "file" | ||
====Library.Fields.MusicVideo==== | ====Library.Fields.MusicVideo==== |
Revision as of 18:13, 2 May 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:
- Library.Id albumid
- [ Library.Fields.Album fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Audio.AlbumDetails albumdetails ]
AudioLibrary.GetAlbums
Retrieve all albums from specified artist or genre
Permission: ReadData
Parameters:
- [ Library.Id artistid = -1 ]
- [ Library.Id genreid = -1 ]
- [ Library.Fields.Album fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array albums ]
- List.LimitsReturned limits
AudioLibrary.GetArtists
Retrieve all artists
Permission: ReadData
Parameters:
- [ Library.Id genreid = -1 ]
- [ array fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- List.LimitsReturned limits
- [ array artists ]
AudioLibrary.GetGenres
Retrieve all genres
Permission: ReadData
Parameters:
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array genres ]
- List.LimitsReturned limits
AudioLibrary.GetSongDetails
Retrieve details about a specific song
Permission: ReadData
Parameters:
- Library.Id songid
- [ Library.Fields.Song fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Audio.SongDetails songdetails ]
AudioLibrary.GetSongs
Retrieve all songs from specified album, artist or genre
Permission: ReadData
Parameters:
- [ Library.Id artistid = -1 ]
- [ Library.Id albumid = -1 ]
- [ Library.Id genreid = -1 ]
- [ Library.Fields.Song fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- List.LimitsReturned limits
- [ array songs ]
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:
Type: object
Optional: true
Properties:
- boolean paused
- Global.Time total
- boolean playing
- object time
Properties:
- integer hours
- integer seconds
- integer minutes
- integer milliseconds
AudioPlayer.PlayPause
Pauses or unpause playback and returns the new state
Permission: ControlPlayback
Parameters: None
Returns:
Type: object
Optional: true
Properties:
- boolean paused
- boolean playing
AudioPlayer.Rewind
Rewind current playback
Permission: ControlPlayback
Parameters: None
Returns: string
AudioPlayer.SeekPercentage
Seek to a specific percentage
Permission: ControlPlayback
Parameters:
- Player.SeekPercentage value
Returns: string
AudioPlayer.SeekTime
Seek to a specific time
Permission: ControlPlayback
Parameters:
- 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:
Type: object
Optional: true
Properties:
- boolean paused
- boolean partymode
- boolean playing
AudioPlayer.Stop
Stops playback
Permission: ControlPlayback
Parameters: None
Returns: string
AudioPlaylist
AudioPlaylist.Add
Add item(s) to playlist
Permission: ControlPlayback
Parameters:
- 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:
- [ Library.Fields.Song fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- Audio.SongDetails items
- [ Playlist.State state ]
- List.LimitsReturned limits
AudioPlaylist.Insert
Insert item(s) into playlist
Permission: ControlPlayback
Parameters:
- Playlist.Item.Position index
- Playlist.Audio.Item item
Returns: string
AudioPlaylist.Play
Play current or a specific item
Permission: ControlPlayback
Parameters:
- [ Playlist.Item.Position item = -1 ]
- [ Library.Id songid = -1 ]
Returns:
Type: object
Optional: true
Properties:
- boolean success
AudioPlaylist.Remove
Remove item from playlist
Permission: ControlPlayback
Parameters:
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:
- string path
Returns:
Type: object
Optional: true
Properties:
- string path
Files.GetDirectory
Permission: ReadData
Parameters:
- string directory
- [ Files.Media media = "files" ]
- [ List.Fields.All fields ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array files ]
- List.LimitsReturned limits
Files.GetSources
Get the sources of the media windows
Permission: ReadData
Parameters:
- Files.Media media
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array shares ]
- object limits
Properties:
- integer start
- integer total
- integer end
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:
Type: object
Optional: true
Properties:
- boolean GUI
- boolean System
- boolean Player
- boolean AudioLibrary
- boolean Other
- boolean VideoLibrary
JSONRPC.Introspect
Enumerates all actions and descriptions
Permission: ReadData
Parameters:
- [ boolean getdescriptions = True ]
- [ boolean getmetadata = False ]
- [ boolean filterbytransport = True ]
Returns: object
JSONRPC.NotifyAll
Notify all other connected clients
Permission: ReadData
Parameters:
- string sender
- string message
- [ any data = null ]
Returns: any
JSONRPC.Permission
Retrieve the clients permissions
Permission: ReadData
Parameters: None
Returns:
Type: object
Optional: true
Properties:
- boolean Logging
- boolean ScanLibrary
- boolean ControlPlayback
- boolean ReadData
- boolean ControlNotify
- boolean ControlPower
JSONRPC.Ping
Ping responder
Permission: ReadData
Parameters: None
Returns: string
JSONRPC.SetNotificationFlags
Change the notification flags
Permission: ControlNotify
Parameters:
- [ boolean Playback = False ]
- [ boolean GUI = False ]
- [ boolean System = False ]
- [ boolean Library = False ]
- [ boolean Other = False ]
Returns:
Type: Notification.Flags
Optional: true
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:
- 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:
Type: object
Optional: true
Properties:
- boolean picture
- boolean audio
- boolean video
Playlist
Playlist.Add
Add items to the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
- Playlist.Id items
Returns: string
Playlist.Clear
Clear playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
Returns: string
Playlist.Create
Creates a virtual playlist from a given one from a file
Permission: ReadData
Parameters:
- Playlist.Id playlist
Returns:
Type: object
Optional: true
Properties:
- string playlistid
Playlist.Destroy
Destroys a virtual playlist
Permission: ReadData
Parameters:
- string playlistid
Returns: string
Playlist.GetItems
Retrieve items in the playlist
Permission: ReadData
Parameters:
- Playlist.Id playlist
- [ List.Fields.All fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- array items
- [ string name ]
Playlist.Remove
Remove item from the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
- ['string', 'integer'] item
Returns: string
Playlist.Shuffle
Shuffle playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
Returns: string
Playlist.Swap
Swap items in the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
- Playlist.Item.Position item1
- Playlist.Item.Position item2
Returns: string
Playlist.UnShuffle
Unshuffle playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
Returns: string
System
System.GetInfoBooleans
Retrieve info booleans about the system
Permission: ReadData
Parameters:
- array[1..X] booleans
Returns:
Type: object
Optional: true
System.GetInfoLabels
Retrieve info labels about the system
Permission: ReadData
Parameters:
- array[1..X] labels
Returns:
Type: object
Optional: true
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:
- Library.Id episodeid
- [ Library.Fields.Episode fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Library.Details.Episode episodedetails ]
VideoLibrary.GetEpisodes
Retrieve all tv show episodes
Permission: ReadData
Parameters:
- Library.Id tvshowid
- any season
- [ Library.Fields.Episode fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array episodes ]
- List.LimitsReturned limits
VideoLibrary.GetMovieDetails
Retrieve details about a specific movie
Permission: ReadData
Parameters:
- Library.Id movieid
- [ Library.Fields.Movie fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Library.Details.Movie moviedetails ]
VideoLibrary.GetMovies
Retrieve all movies
Permission: ReadData
Parameters:
- [ Library.Fields.Movie fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array movies ]
- List.LimitsReturned limits
VideoLibrary.GetMusicVideoDetails
Retrieve details about a specific music video
Permission: ReadData
Parameters:
- Library.Id musicvideoid
- [ Library.Fields.MusicVideo fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Library.Details.MusicVideo musicvideodetails ]
VideoLibrary.GetMusicVideos
Retrieve all music videos
Permission: ReadData
Parameters:
- [ Library.Id artistid = -1 ]
- [ Library.Id albumid = -1 ]
- [ Library.Fields.MusicVideo fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array musicvideos ]
- List.LimitsReturned limits
VideoLibrary.GetRecentlyAddedEpisodes
Retrieve all recently added tv episodes
Permission: ReadData
Parameters:
- [ Library.Fields.Episode fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array episodes ]
- List.LimitsReturned limits
VideoLibrary.GetRecentlyAddedMovies
Retrieve all recently added movies
Permission: ReadData
Parameters:
- [ Library.Fields.Movie fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array movies ]
- List.LimitsReturned limits
VideoLibrary.GetRecentlyAddedMusicVideos
Retrieve all recently added music videos
Permission: ReadData
Parameters:
- [ Library.Fields.MusicVideo fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array musicvideos ]
- List.LimitsReturned limits
VideoLibrary.GetSeasons
Retrieve all tv seasons
Permission: ReadData
Parameters:
- Library.Id tvshowid
- [ Library.Fields.Season fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array seasons ]
- List.LimitsReturned limits
VideoLibrary.GetTVShowDetails
Retrieve details about a specific tv show
Permission: ReadData
Parameters:
- Library.Id tvshowid
- [ Library.Fields.TVShow fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Library.Details.TVShow tvshowdetails ]
VideoLibrary.GetTVShows
Retrieve all tv shows
Permission: ReadData
Parameters:
- [ Library.Fields.TVShow fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- List.LimitsReturned limits
- [ array tvshows ]
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:
Type: Player.TimeValues
Optional: true
VideoPlayer.PlayPause
Pauses or unpause playback and returns the new state
Permission: ControlPlayback
Parameters: None
Returns:
Type: Player.State
Optional: true
VideoPlayer.Rewind
Rewind current playback
Permission: ControlPlayback
Parameters: None
Returns: string
VideoPlayer.SeekPercentage
Seek to a specific percentage
Permission: ControlPlayback
Parameters:
- Player.SeekPercentage value
Returns: string
VideoPlayer.SeekTime
Seek to a specific time
Permission: ControlPlayback
Parameters:
- 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:
Type: Player.State.Extended
Optional: true
VideoPlayer.Stop
Stops playback
Permission: ControlPlayback
Parameters: None
Returns: string
VideoPlaylist
VideoPlaylist.Add
Add item(s) to playlist
Permission: ControlPlayback
Parameters:
- 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:
- [ List.Fields.Video fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- array items
- [ object state ]
Properties:
- integer current
- boolean paused
- boolean playing
- List.LimitsReturned limits
VideoPlaylist.Insert
Insert item(s) into playlist
Permission: ControlPlayback
Parameters:
- Playlist.Item.Position index
- Playlist.Video.Item item
Returns: string
VideoPlaylist.Play
Play current or a specific item
Permission: ControlPlayback
Parameters:
- [ Playlist.Item.Position item = -1 ]
Returns:
Type: object
Optional: true
Properties:
- boolean success
VideoPlaylist.Remove
Remove item from playlist
Permission: ControlPlayback
Parameters:
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:
- string message
- [ string level = "debug" ]
Returns: string
XBMC.Play
Starts playback of the given file
Permission: ControlPlayback
Parameters:
- string file
Returns: string
XBMC.Quit
Quit XBMC
Permission: ControlPower
Parameters: None
Returns: string
XBMC.SetVolume
Set the current volume
Permission: ControlPlayback
Parameters:
- integer value
Returns: integer
XBMC.StartSlideshow
Starts slideshow with the images from the given directory
Permission: ControlPlayback
Parameters:
- string directory
- [ boolean random = True ]
- [ boolean recursive = True ]
Returns: string
XBMC.ToggleMute
Toggle mute/unmute
Permission: ControlPlayback
Parameters: None
Returns:
Type: integer
Optional: true
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
Fields: "title", "genre", "year", "rating", "director", "trailer", "tagline", "plot", "plotoutline", "originaltitle", "lastplayed", "playcount", "writer", "studio", "mpaa", "cast", "country", "imdbnumber", "premiered", "productioncode", "runtime", "set", "showlink", "streamDetails", "top250", "votes", "writingcredits", "fanart", "thumbnail", "file"
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:
- [ Library.Id songid = -1 ]
- [ Playlist.Id playlist ]
- [ Library.Id albumid = -1 ]
- [ Library.Id artistid = -1 ]
- [ string file = "" ]
- [ Library.Id genreid = -1 ]
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:
- [ Playlist.Id playlist ]
- [ Library.Id movieid = -1 ]
- [ Library.Id episodeid = -1 ]
- [ string file = "" ]
- [ Library.Id musicvideoid = -1 ]
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