JSON-RPC API: Difference between revisions
No edit summary |
>Nonpolar |
||
Line 503: | Line 503: | ||
===Files=== | ===Files=== | ||
====Files.Download==== | ====Files.Download==== | ||
Takes a XBMC internal path to a file (e.g. special://masterprofile/Thumbnails/Music/e/ec96cd54.tbn) and returns the URL where the file can be downloaded (e. g. http://192.168.1.2:8080/vfs/special://masterprofile/Thumbnails/Music/e/ec96cd54.tbn). | |||
'''Permission:''' ReadData<br /> | '''Permission:''' ReadData<br /> | ||
'''Parameters:''' | '''Parameters:''' | ||
Line 511: | Line 512: | ||
'''Properties:''' | '''Properties:''' | ||
*''string'' path | *''string'' path | ||
====Files.GetDirectory==== | ====Files.GetDirectory==== |
Revision as of 15:39, 9 October 2011
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 Application Application information and control System System controls and information XBMC Dumping ground for very XBMC specific operations
Methods
Application
Application.GetProperties
Retrieves the values of the given properties
Permission: ReadData
Parameters:
- array properties
Returns:
Type: Application.Property.Value
Optional: true
Application.Quit
Quit application
Permission: ControlPower
Parameters: None
Returns:
Type: string
Optional: true
Application.SetVolume
Set the current volume
Permission: ControlPlayback
Parameters:
- integer value
Returns:
Type: integer
Optional: true
Application.ToggleMute
Toggle mute/unmute
Permission: ControlPlayback
Parameters: None
Returns:
Type: integer
Optional: true
AudioLibrary
AudioLibrary.Clean
Cleans the audio library from non-existent items
Permission: RemoveData
Parameters: None
Returns:
Type: string
Optional: true
AudioLibrary.Export
Exports all items from the audio library
Permission: WriteFile
Parameters:
- [ boolean singlefile = True ]
- [ boolean images = False ]
- [ boolean overwrite = False ]
- [ string path = "" ]
Returns:
Type: string
Optional: true
AudioLibrary.GetAlbumDetails
Retrieve details about a specific album
Permission: ReadData
Parameters:
- Library.Id albumid
- [ Audio.Fields.Album fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Audio.Details.Album albumdetails ]
AudioLibrary.GetAlbums
Retrieve all albums from specified artist or genre
Permission: ReadData
Parameters:
- [ Library.Id artistid = -1 ]
- [ Library.Id genreid = -1 ]
- [ Audio.Fields.Album fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array albums ]
- List.LimitsReturned limits
AudioLibrary.GetArtistDetails
Retrieve details about a specific artist
Permission: ReadData
Parameters:
- Library.Id artistid
- [ Audio.Fields.Artist fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Audio.Details.Artist artistdetails ]
AudioLibrary.GetArtists
Retrieve all artists
Permission: ReadData
Parameters:
- [ Optional.Boolean albumartistsonly = null ]
- [ Library.Id genreid = -1 ]
- [ Audio.Fields.Artist 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:
- [ Library.Fields.Genre fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- array genres
- List.LimitsReturned limits
AudioLibrary.GetRecentlyAddedAlbums
Retrieve recently added albums
Permission: ReadData
Parameters:
- [ List.Amount albums = -1 ]
- [ Audio.Fields.Album fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array albums ]
- List.LimitsReturned limits
AudioLibrary.GetRecentlyAddedSongs
Retrieve recently added songs
Permission: ReadData
Parameters:
- [ List.Amount albums = -1 ]
- [ Audio.Fields.Song fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- List.LimitsReturned limits
- [ array songs ]
AudioLibrary.GetSongDetails
Retrieve details about a specific song
Permission: ReadData
Parameters:
- Library.Id songid
- [ Audio.Fields.Song fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Audio.Details.Song 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 ]
- [ Audio.Fields.Song fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- List.LimitsReturned limits
- [ array songs ]
AudioLibrary.Scan
Scans the audio sources for new library items
Permission: UpdateData
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer
AudioPlayer.BigSkipBackward
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer.BigSkipForward
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer.Forward
Forward current playback
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer.GetPercentage
Retrieve current playback progress in percentage
Permission: ReadData
Parameters: None
Returns:
Type: number
Optional: true
AudioPlayer.GetTime
Retrieves the current and total time of the currently playing file
Permission: ReadData
Parameters: None
Returns:
Type: Player.TimeValues
Optional: true
AudioPlayer.PlayPause
Pauses or unpause playback and returns the new state
Permission: ControlPlayback
Parameters: None
Returns:
Type: Player.State
Optional: true
AudioPlayer.Rewind
Rewind current playback
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer.SeekPercentage
Seek to a specific percentage
Permission: ControlPlayback
Parameters:
- Player.SeekPercentage value
Returns:
Type: string
Optional: true
AudioPlayer.SeekTime
Seek to a specific time
Permission: ControlPlayback
Parameters:
- Player.SeekTime value
Returns:
Type: string
Optional: true
AudioPlayer.SkipNext
Skips to next item on the playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer.SkipPrevious
Skips to previous item on the playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer.SmallSkipBackward
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer.SmallSkipForward
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlayer.State
Returns playback state of the audio player (if it is active)
Permission: ReadData
Parameters: None
Returns:
Type: Player.State.Extended
Optional: true
AudioPlayer.Stop
Stops playback
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlaylist
AudioPlaylist.Add
Add item(s) to playlist
Permission: ControlPlayback
Parameters:
- Playlist.Audio.Item item
Returns:
Type: string
Optional: true
AudioPlaylist.Clear
Clear playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlaylist.GetItems
Get all items from playlist
Permission: ReadData
Parameters:
- [ Audio.Fields.Song fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- List.Items.Audio 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:
Type: string
Optional: true
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:
Type: string
Optional: true
AudioPlaylist.Repeat
Set the repeat mode of the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Repeat state
Returns:
Type: string
Optional: true
AudioPlaylist.Shuffle
Shuffle playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlaylist.SkipNext
Skip current item and play next item
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlaylist.SkipPrevious
Skip current item and play previous item
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
AudioPlaylist.State
Provides information about the current state of the playlist
Permission: ReadData
Parameters: None
Returns:
Type: Playlist.State
Optional: true
AudioPlaylist.Swap
Swap items in the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Item.Position item1
- Playlist.Item.Position item2
Returns:
Type: string
Optional: true
AudioPlaylist.UnShuffle
Unshuffle playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
Files
Files.Download
Takes a XBMC internal path to a file (e.g. special://masterprofile/Thumbnails/Music/e/ec96cd54.tbn) and returns the URL where the file can be downloaded (e. g. http://192.168.1.2:8080/vfs/special://masterprofile/Thumbnails/Music/e/ec96cd54.tbn).
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:
- List.Items.Files 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:
- List.Items.Shares shares
- List.LimitsReturned limits
Input
Input.Back
Goes back in GUI
Permission: Navigate
Parameters: None
Returns:
Type: string
Optional: true
Input.Down
Navigate down in GUI
Permission: Navigate
Parameters: None
Returns:
Type: string
Optional: true
Input.Home
Goes to home window in GUI
Permission: Navigate
Parameters: None
Returns:
Type: string
Optional: true
Input.Left
Navigate left in GUI
Permission: Navigate
Parameters: None
Returns:
Type: string
Optional: true
Input.Right
Navigate right in GUI
Permission: Navigate
Parameters: None
Returns:
Type: string
Optional: true
Input.Select
Select current item in GUI
Permission: Navigate
Parameters: None
Returns:
Type: string
Optional: true
Input.Up
Navigate up in GUI
Permission: Navigate
Parameters: None
Returns:
Type: string
Optional: true
JSONRPC
JSONRPC.GetConfiguration
Get client-specific configurations
Permission: ReadData
Parameters: None
Returns:
Type: Configuration
Optional: true
JSONRPC.Introspect
Enumerates all actions and descriptions
Permission: ReadData
Parameters:
- [ boolean getdescriptions = True ]
- [ boolean getmetadata = False ]
- [ boolean filterbytransport = True ]
- [ object filter ]
Properties:
- string type
- string id
- [ boolean getreferences = True ]
Returns:
Type: object
Optional: true
JSONRPC.NotifyAll
Notify all other connected clients
Permission: ReadData
Parameters:
- string sender
- string message
- [ any data = null ]
Returns:
Type: any
Optional: true
JSONRPC.Permission
Retrieve the clients permissions
Permission: ReadData
Parameters: None
Returns:
Type: object
Optional: true
Properties:
- boolean removedata
- boolean controlplayback
- boolean readdata
- boolean updatedata
- boolean writefile
- boolean controlnotify
- boolean controlpower
JSONRPC.Ping
Ping responder
Permission: ReadData
Parameters: None
Returns:
Type: string
Optional: true
JSONRPC.SetConfiguration
Change the client-specific configuration
Permission: ControlNotify
Parameters:
- [ object notifications ]
Properties:
- [ Optional.Boolean gui = null ]
- [ Optional.Boolean system = null ]
- [ Optional.Boolean player = null ]
- [ Optional.Boolean audiolibrary = null ]
- [ Optional.Boolean other = null ]
- [ Optional.Boolean videolibrary = null ]
Returns:
Type: Configuration
Optional: true
JSONRPC.Version
Retrieve the jsonrpc protocol version
Permission: ReadData
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer
PicturePlayer.MoveDown
If picture is zoomed move viewport down
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.MoveLeft
If picture is zoomed move viewport left otherwise skip previous
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.MoveRight
If picture is zoomed move viewport right otherwise skip next
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.MoveUp
If picture is zoomed move viewport up
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.PlayPause
Pauses or unpause slideshow
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.Rotate
Rotates current picture
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.SkipNext
Skips to next picture in the slideshow
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.SkipPrevious
Skips to previous picture in the slideshow
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.Stop
Stops slideshow
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.Zoom
Zooms current picture
Permission: ControlPlayback
Parameters:
- integer value
Returns:
Type: string
Optional: true
PicturePlayer.ZoomIn
Zoom in once
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
PicturePlayer.ZoomOut
Zoom out once
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
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:
Type: string
Optional: true
Playlist.Clear
Clear playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
Returns:
Type: string
Optional: true
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:
Type: string
Optional: true
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:
- List.Items.All items
- [ string name = "" ]
- List.LimitsReturned limits
Playlist.Remove
Remove item from the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
- ['string', 'integer'] item
Returns:
Type: string
Optional: true
Playlist.Shuffle
Shuffle playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
Returns:
Type: string
Optional: true
Playlist.Swap
Swap items in the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
- Playlist.Item.Position item1
- Playlist.Item.Position item2
Returns:
Type: string
Optional: true
Playlist.UnShuffle
Unshuffle playlist
Permission: ControlPlayback
Parameters:
- Playlist.Id playlist
Returns:
Type: string
Optional: true
System
System.GetProperties
Retrieves the values of the given properties
Permission: ReadData
Parameters:
- array properties
Returns:
Type: System.Property.Value
Optional: true
System.Hibernate
Puts the system running XBMC into hibernate mode
Permission: ControlPower
Parameters: None
Returns:
Type: string
Optional: true
System.Reboot
Reboots the system running XBMC
Permission: ControlPower
Parameters: None
Returns:
Type: string
Optional: true
System.Shutdown
Shuts the system running XBMC down
Permission: ControlPower
Parameters: None
Returns:
Type: string
Optional: true
System.Suspend
Suspends the system running XBMC
Permission: ControlPower
Parameters: None
Returns:
Type: string
Optional: true
VideoLibrary
VideoLibrary.Clean
Cleans the video library from non-existent items
Permission: RemoveData
Parameters: None
Returns:
Type: string
Optional: true
VideoLibrary.Export
Exports all items from the video library
Permission: WriteFile
Parameters:
- [ boolean singlefile = True ]
- [ boolean images = False ]
- [ boolean actorthumbs = False ]
- [ boolean overwrite = False ]
- [ string path = "" ]
Returns:
Type: string
Optional: true
VideoLibrary.GetEpisodeDetails
Retrieve details about a specific tv show episode
Permission: ReadData
Parameters:
- Library.Id episodeid
- [ Video.Fields.Episode fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Video.Details.Episode episodedetails ]
VideoLibrary.GetEpisodes
Retrieve all tv show episodes
Permission: ReadData
Parameters:
- [ Library.Id tvshowid = -1 ]
- [ integer season = -1 ]
- [ Video.Fields.Episode fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- [ array episodes ]
- List.LimitsReturned limits
VideoLibrary.GetGenres
Retrieve all genres
Permission: ReadData
Parameters:
- string type
- [ Library.Fields.Genre fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- array genres
- List.LimitsReturned limits
VideoLibrary.GetMovieDetails
Retrieve details about a specific movie
Permission: ReadData
Parameters:
- Library.Id movieid
- [ Video.Fields.Movie fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Video.Details.Movie moviedetails ]
VideoLibrary.GetMovieSetDetails
Retrieve details about a specific movie set
Permission: ReadData
Parameters:
- Library.Id setid
- [ Video.Fields.MovieSet fields ]
- [ object movies ]
Properties:
- [ List.Sort sort ]
- [ Video.Fields.Movie fields ]
- [ List.Limits limits ]
Returns:
Type: object
Optional: true
Properties:
- [ Video.Details.MovieSet.Extended setdetails ]
VideoLibrary.GetMovieSets
Retrieve all movie sets
Permission: ReadData
Parameters:
- [ Video.Fields.MovieSet fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- List.LimitsReturned limits
- [ array sets ]
VideoLibrary.GetMovies
Retrieve all movies
Permission: ReadData
Parameters:
- [ Video.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
- [ Video.Fields.MusicVideo fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Video.Details.MusicVideo musicvideodetails ]
VideoLibrary.GetMusicVideos
Retrieve all music videos
Permission: ReadData
Parameters:
- [ Library.Id artistid = -1 ]
- [ Library.Id albumid = -1 ]
- [ Video.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:
- [ Video.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:
- [ Video.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:
- [ Video.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
- [ Video.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
- [ Video.Fields.TVShow fields ]
Returns:
Type: object
Optional: true
Properties:
- [ Video.Details.TVShow tvshowdetails ]
VideoLibrary.GetTVShows
Retrieve all tv shows
Permission: ReadData
Parameters:
- [ Video.Fields.TVShow fields ]
- [ List.Limits limits ]
- [ List.Sort sort ]
Returns:
Type: object
Optional: true
Properties:
- List.LimitsReturned limits
- [ array tvshows ]
VideoLibrary.Scan
Scans the video sources for new library items
Permission: UpdateData
Parameters: None
Returns:
Type: string
Optional: true
VideoPlayer
VideoPlayer.BigSkipBackward
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlayer.BigSkipForward
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlayer.Forward
Forward current playback
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlayer.GetPercentage
Retrieve current playback progress in percentage
Permission: ReadData
Parameters: None
Returns:
Type: number
Optional: true
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:
Type: string
Optional: true
VideoPlayer.SeekPercentage
Seek to a specific percentage
Permission: ControlPlayback
Parameters:
- Player.SeekPercentage value
Returns:
Type: string
Optional: true
VideoPlayer.SeekTime
Seek to a specific time
Permission: ControlPlayback
Parameters:
- Player.SeekTime value
Returns:
Type: string
Optional: true
VideoPlayer.SkipNext
Skips to next item on the playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlayer.SkipPrevious
Skips to previous item on the playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlayer.SmallSkipBackward
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlayer.SmallSkipForward
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
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:
Type: string
Optional: true
VideoPlaylist
VideoPlaylist.Add
Add item(s) to playlist
Permission: ControlPlayback
Parameters:
- Playlist.Video.Item item
Returns:
Type: string
Optional: true
VideoPlaylist.Clear
Clear playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
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:
- List.Items.Video items
- [ Playlist.State state ]
- List.LimitsReturned limits
VideoPlaylist.Insert
Insert item(s) into playlist
Permission: ControlPlayback
Parameters:
- Playlist.Item.Position index
- Playlist.Video.Item item
Returns:
Type: string
Optional: true
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:
Type: string
Optional: true
VideoPlaylist.Repeat
Set the repeat mode of the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Repeat state
Returns:
Type: string
Optional: true
VideoPlaylist.Shuffle
Shuffle playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlaylist.SkipNext
Skip current item and play next item
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlaylist.SkipPrevious
Skip current item and play previous item
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
VideoPlaylist.State
Provides information about the current state of the playlist
Permission: ReadData
Parameters: None
Returns:
Type: Playlist.State
Optional: true
VideoPlaylist.Swap
Swap items in the playlist
Permission: ControlPlayback
Parameters:
- Playlist.Item.Position item1
- Playlist.Item.Position item2
Returns:
Type: string
Optional: true
VideoPlaylist.UnShuffle
Unshuffle playlist
Permission: ControlPlayback
Parameters: None
Returns:
Type: string
Optional: true
XBMC
XBMC.GetInfoBooleans
Retrieve info booleans about XBMC and the system
Permission: ReadData
Parameters:
- array booleans
Returns:
Type: object
Optional: true
XBMC.GetInfoLabels
Retrieve info labels about XBMC and the system
Permission: ReadData
Parameters:
- array labels
Returns:
Type: object
Optional: true
XBMC.Play
Starts playback of the given file
Permission: ControlPlayback
Parameters:
- string file
Returns:
Type: string
Optional: true
XBMC.StartSlideshow
Starts slideshow with the images from the given directory
Permission: ControlPlayback
Parameters:
- string directory
- [ boolean random = True ]
- [ boolean recursive = True ]
Returns:
Type: string
Optional: true
Global types
Application
Application.Property.Name
Type: string
Optional: true
Default: "volume"
Application.Property.Value
Type: object
Optional: true
Properties:
- [ boolean muted = False ]
- [ integer volume = 0 ]
Array
Array.Integer
Type: array
Optional: true
Array.String
Type: array
Optional: true
Audio
Audio.Details.Album
Type: object
Optional: true
Properties:
- [ integer rating = 0 ]
- [ string style = "" ]
- [ string theme = "" ]
- [ string description = "" ]
- [ string artist = "" ]
- [ string fanart = "" ]
- [ string albumlabel = "" ]
- [ string thumbnail = "" ]
- [ string musicbrainzalbumartistid = "" ]
- string label
- Library.Id albumid
- [ Library.Id artistid = -1 ]
- [ integer year = 0 ]
- [ string genre = "" ]
- [ string title = "" ]
- [ string type = "" ]
- [ string musicbrainzalbumid = "" ]
- [ string mood = "" ]
Audio.Details.Artist
Type: object
Optional: true
Properties:
- [ string style = "" ]
- [ string description = "" ]
- [ string musicbrainzartistid = "" ]
- string artist
- [ string fanart = "" ]
- [ string formed = "" ]
- [ string disbanded = "" ]
- [ string born = "" ]
- Library.Id artistid
- [ string yearsactive = "" ]
- [ string instrument = "" ]
- [ string genre = "" ]
- string label
- [ string thumbnail = "" ]
- [ string died = "" ]
- [ string mood = "" ]
Audio.Details.Song
Type: object
Optional: true
Properties:
- [ string comment = "" ]
- [ integer rating = 0 ]
- [ string lyrics = "" ]
- [ string albumartist = "" ]
- [ string file = "" ]
- [ integer year = 0 ]
- [ integer duration = 0 ]
- [ string musicbrainzalbumid = "" ]
- [ string album = "" ]
- [ string title = "" ]
- [ string fanart = "" ]
- [ Library.Id artistid = -1 ]
- string label
- [ Library.Id albumid = -1 ]
- [ string thumbnail = "" ]
- Library.Id songid
- [ integer track = 0 ]
- [ string musicbrainztrackid = "" ]
- [ string genre = "" ]
- [ string musicbrainzartistid = "" ]
- [ string artist = "" ]
- [ string musicbrainzalbumartistid = "" ]
- [ integer playcount = 0 ]
Audio.Fields.Album
Type: array
Optional: true
Audio.Fields.Artist
Type: array
Optional: true
Audio.Fields.Song
Type: array
Optional: true
Configuration
Configuration
Type: object
Optional: false
Properties:
- Configuration.Notifications notifications
Configuration.Notifications
Type: object
Optional: true
Properties:
- boolean gui
- boolean system
- boolean player
- boolean audiolibrary
- boolean other
- boolean videolibrary
Files
Files.Media
Type: string
Optional: true
Default: "video"
Global
Global.Time
Type: object
Optional: true
Properties:
- integer hours
- integer seconds
- integer minutes
- integer milliseconds
Library
Library.Details.Genre
Type: object
Optional: true
Properties:
- Library.Id genreid
- [ string title = "" ]
- [ string thumbnail = "" ]
- string label
Library.Fields.Genre
Type: array
Optional: true
Library.Id
Type: integer
Optional: true
Default: -1
List
List.Amount
Type: integer
Optional: true
Default: -1
List.Fields.All
Type: array
Optional: true
List.Fields.Video
Type: array
Optional: true
List.Items.All
Type: array
Optional: true
List.Items.Audio
Type: array
Optional: true
List.Items.Files
Type: array
Optional: true
Type: array
Optional: true
List.Items.Video
Type: array
Optional: true
List.Limits
Type: object
Optional: true
Properties:
- [ integer start = 0 ]
- [ integer end = -1 ]
List.LimitsReturned
Type: object
Optional: true
Properties:
- integer start
- integer total
- integer end
List.Sort
Type: object
Optional: true
Properties:
- [ string order = "ascending" ]
- [ boolean ignorearticle = False ]
- [ string method = "none" ]
Optional
Optional.Boolean
Type: ['null', 'boolean']
Optional: true
Default: null
Player
Player.SeekPercentage
Type: number
Optional: true
Default: 0
Player.SeekTime
Type: integer
Optional: true
Default: 0
Player.State
Type: object
Optional: true
Properties:
- boolean paused
- boolean playing
Player.State.Extended
Type: object
Optional: true
Properties:
- boolean paused
- boolean partymode
- boolean playing
Player.TimeValues
Type: object
Optional: true
Properties:
- boolean paused
- Global.Time total
- boolean playing
- Global.Time time
Playlist
Playlist.Audio.Item
Type: object
Optional: true
Properties:
- [ Playlist.Id playlist ]
- [ Library.Id songid = -1 ]
- [ Library.Id albumid = -1 ]
- [ Library.Id artistid = -1 ]
- [ string file = "" ]
- [ string directory = "" ]
- [ Library.Id genreid = -1 ]
Playlist.Id
Type: object
Optional: true
Properties:
- [ string id = "" ]
- [ string file = "" ]
Playlist.Item.Position
Type: integer
Optional: true
Default: -1
Playlist.Repeat
Type: string
Optional: true
Default: "off"
Playlist.State
Type: object
Optional: true
Properties:
- integer current
- boolean paused
- Playlist.Repeat repeat
- boolean playing
- boolean shuffled
Playlist.Video.Item
Type: object
Optional: true
Properties:
- [ Playlist.Id playlist ]
- [ Library.Id movieid = -1 ]
- [ Library.Id episodeid = -1 ]
- [ string file = "" ]
- [ string directory = "" ]
- [ Library.Id musicvideoid = -1 ]
System
System.Property.Name
Type: string
Optional: true
Default: "canshutdown"
System.Property.Value
Type: object
Optional: true
Properties:
- [ boolean canreboot = False ]
- [ boolean cansuspend = False ]
- [ boolean canhibernate = False ]
- [ boolean canshutdown = False ]
Video
Video.Cast
Type: array
Optional: true
Video.Details.Episode
Type: object
Optional: true
Properties:
- [ number rating = 0 ]
- [ Library.Id tvshowid = -1 ]
- [ string file = "" ]
- [ string plot = "" ]
- [ string votes = "" ]
- [ string title = "" ]
- [ string fanart = "" ]
- [ string writer = "" ]
- string label
- [ string thumbnail = "" ]
- [ Video.Streams streamdetails ]
- [ Video.Resume resume ]
- [ integer season = 0 ]
- [ string director = "" ]
- [ string showtitle = "" ]
- [ integer episode = 0 ]
- [ string productioncode = "" ]
- [ string lastplayed = "" ]
- Library.Id episodeid
- [ string originaltitle = "" ]
- [ Video.Cast cast ]
- [ string firstaired = "" ]
- [ integer playcount = 0 ]
- [ string runtime = "" ]
Video.Details.Movie
Type: object
Optional: true
Properties:
- [ number rating = 0 ]
- [ Array.String set ]
- [ string tagline = "" ]
- [ string file = "" ]
- [ integer year = 0 ]
- [ Array.Integer setid ]
- [ string plot = "" ]
- [ string votes = "" ]
- [ string title = "" ]
- [ string fanart = "" ]
- [ string mpaa = "" ]
- [ string writer = "" ]
- string label
- [ string thumbnail = "" ]
- [ Video.Streams streamdetails ]
- [ string plotoutline = "" ]
- [ Video.Resume resume ]
- [ string director = "" ]
- [ string imdbnumber = "" ]
- [ string studio = "" ]
- [ string showlink = "" ]
- [ string genre = "" ]
- Library.Id movieid
- [ string productioncode = "" ]
- [ string country = "" ]
- [ string lastplayed = "" ]
- [ string premiered = "" ]
- [ string originaltitle = "" ]
- [ Video.Cast cast ]
- [ string sorttitle = "" ]
- [ integer playcount = 0 ]
- [ string runtime = "" ]
- [ integer top250 = 0 ]
- [ string trailer = "" ]
Video.Details.MovieSet
Type: object
Optional: true
Properties:
- [ string title = "" ]
- [ string fanart = "" ]
- string label
- [ integer playcount = 0 ]
- [ string thumbnail = "" ]
- Library.Id setid
Video.Details.MovieSet.Extended
Type: object
Optional: true
Properties:
- [ string title = "" ]
- [ string fanart = "" ]
- string label
- [ array movies ]
- [ integer playcount = 0 ]
- [ string thumbnail = "" ]
- Library.Id setid
Video.Details.MusicVideo
Type: object
Optional: true
Properties:
- [ string album = "" ]
- [ string plot = "" ]
- [ string artist = "" ]
- [ string fanart = "" ]
- [ string lastplayed = "" ]
- [ integer year = 0 ]
- [ Video.Resume resume ]
- string label
- [ string director = "" ]
- [ string thumbnail = "" ]
- [ string studio = "" ]
- [ string file = "" ]
- [ integer track = 0 ]
- [ string genre = "" ]
- [ string title = "" ]
- [ integer playcount = 0 ]
- [ string runtime = "" ]
- Library.Id musicvideoid
- [ Video.Streams streamdetails ]
Video.Details.Season
Type: object
Optional: true
Properties:
- [ Library.Id tvshowid = -1 ]
- [ integer episode = 0 ]
- [ string fanart = "" ]
- integer season
- string label
- [ integer playcount = 0 ]
- [ string thumbnail = "" ]
- [ string showtitle = "" ]
Video.Details.TVShow
Type: object
Optional: true
Properties:
- [ string episodeguide = "" ]
- Library.Id tvshowid
- [ number rating = 0 ]
- [ string file = "" ]
- [ integer year = 0 ]
- [ string plot = "" ]
- [ string votes = "" ]
- [ string title = "" ]
- [ string fanart = "" ]
- [ string mpaa = "" ]
- string label
- [ string thumbnail = "" ]
- [ string imdbnumber = "" ]
- [ string studio = "" ]
- [ string genre = "" ]
- [ integer episode = 0 ]
- [ string lastplayed = "" ]
- [ string premiered = "" ]
- [ string originaltitle = "" ]
- [ Video.Cast cast ]
- [ string sorttitle = "" ]
- [ integer playcount = 0 ]
Video.Fields.Episode
Type: array
Optional: true
Video.Fields.Movie
Type: array
Optional: true
Video.Fields.MovieSet
Type: array
Optional: true
Video.Fields.MusicVideo
Type: array
Optional: true
Video.Fields.Season
Type: array
Optional: true
Video.Fields.TVShow
Type: array
Optional: true
Video.Resume
Type: object
Optional: true
Properties:
- [ number position = 0 ]
- [ number total = 0 ]
Video.Streams
Type: object
Optional: true
Properties:
- [ array video ]
- [ array audio ]
- [ array subtitle ]
Notifications
AudioLibrary
AudioLibrary.OnRemove
An audio item has been removed.
Parameters:
- string sender
- object data
Properties:
Returns: null
AudioLibrary.OnUpdate
An audio item has been updated.
Parameters:
- string sender
- object data
Properties:
- string type
- Library.Id id
Returns: null
Player
Player.OnPause
Playback of a media item has been paused. If there is no ID available extra information will be provided.
Parameters:
- string sender
- object data
Properties:
- [ string album ]
- [ integer episode ]
- [ string artist ]
- [ integer track ]
- [ integer season ]
- [ string title ]
- [ integer year ]
- Notifications.Player.Type type
- [ Library.Id id ]
- [ string showtitle ]
Returns: null
Player.OnPlay
Playback of a media item has been started or the playback speed has changed. If there is no ID available extra information will be provided.
Parameters:
- string sender
- object data
Properties:
- [ string album ]
- [ integer episode ]
- [ string artist ]
- [ integer track ]
- [ integer season ]
- [ string title ]
- [ integer year ]
- string type
- integer speed
- [ Library.Id id ]
- [ string showtitle ]
Returns: null
Player.OnSeek
The playback position has been changed.
Parameters:
- string sender
- object data
Properties:
- integer seekoffset
- integer time
Returns: null
Player.OnStop
Playback of a media item has been stopped. If there is no ID available extra information will be provided.
Parameters:
- string sender
- object data
Properties:
- [ string album ]
- [ integer episode ]
- [ string artist ]
- [ integer track ]
- [ integer season ]
- [ string title ]
- [ integer year ]
- [ Notifications.Player.Type type ]
- [ Library.Id id ]
- [ string showtitle ]
Returns: null
System
System.OnLowBattery
The system is on low battery.
Parameters:
- string sender
- null data
Returns: null
System.OnQuit
XBMC will be closed.
Parameters:
- string sender
- null data
Returns: null
System.OnRestart
The system will be restarted.
Parameters:
- string sender
- null data
Returns: null
System.OnSleep
The system will be suspended.
Parameters:
- string sender
- null data
Returns: null
System.OnWake
The system woke up from suspension.
Parameters:
- string sender
- null data
Returns: null
VideoLibrary
VideoLibrary.OnRemove
A video item has been removed.
Parameters:
- string sender
- object data
Properties:
Returns: null
VideoLibrary.OnUpdate
A video item has been updated.
Parameters:
- string sender
- object data
Properties:
- [ integer playcount = -1 ]
- string type
- Library.Id id
Returns: null
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
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