JSON-RPC API

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
Application      Application information and control
System           System controls and information
XBMC             Dumping ground for very XBMC specific operations

Methods

AudioLibrary

AudioLibrary.GetAlbumDetails

Retrieve details about a specific album
Permission: ReadData
Parameters:

1. Library.Id albumid
2. [ 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:

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

Returns:
Type: object
Optional: true
Properties:

• [ array albums ]
• List.LimitsReturned limits

AudioLibrary.GetArtists

Retrieve all artists
Permission: ReadData
Parameters:

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

Returns:
Type: object
Optional: true
Properties:

• List.LimitsReturned limits
• [ array artists ]

AudioLibrary.GetGenres

Retrieve all genres
Permission: ReadData
Parameters:

1. [ List.Limits limits ]
2. [ 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:

1. Library.Id songid
2. [ 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:

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

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

1. Player.SeekPercentage value

Returns: string

AudioPlayer.SeekTime

Seek to a specific time
Permission: ControlPlayback
Parameters:

1. Player.SeekTime value

Returns: string

AudioPlayer.SkipNext

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

AudioPlayer.SkipPrevious

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

AudioPlayer.SmallSkipBackward

Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.SmallSkipForward

Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlayer.State

Returns playback state of the audio player (if it is active)
Permission: ReadData
Parameters: None
Returns:
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:

1. Playlist.Audio.Item item

Returns: string

AudioPlaylist.Clear

Clear playlist
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlaylist.GetItems

Get all items from playlist
Permission: ReadData
Parameters:

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

Returns:
Type: object
Optional: true
Properties:

• Audio.SongDetails items
• [ Playlist.State state ]
• List.LimitsReturned limits

AudioPlaylist.Insert

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

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

Returns: string

AudioPlaylist.Play

Play current or a specific item
Permission: ControlPlayback
Parameters:

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

Returns:
Type: object
Optional: true
Properties:

• boolean success

AudioPlaylist.Remove

Remove item from playlist
Permission: ControlPlayback
Parameters:

1. Playlist.Item.Position item

Returns: string

AudioPlaylist.Shuffle

Shuffle playlist
Permission: ControlPlayback
Parameters: None
Returns: string

AudioPlaylist.SkipNext

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

AudioPlaylist.SkipPrevious

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

AudioPlaylist.UnShuffle

Unshuffle playlist
Permission: ControlPlayback
Parameters: None
Returns: string

Files

Files.Download

Permission: ReadData
Parameters:

1. string path

Returns:
Type: object
Optional: true
Properties:

• string path

Files.GetDirectory

Permission: ReadData
Parameters:

1. string directory
2. [ Files.Media media = "files" ]
3. [ List.Fields.All fields ]
4. [ 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:

1. Files.Media media
2. [ List.Limits limits ]
3. [ 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:

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

Returns: object

JSONRPC.NotifyAll

Notify all other connected clients
Permission: ReadData
Parameters:

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

Returns: any

JSONRPC.Permission

Retrieve the clients permissions
Permission: ReadData
Parameters: None
Returns:
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:

1. [ boolean Playback = False ]
2. [ boolean GUI = False ]
3. [ boolean System = False ]
4. [ boolean Library = False ]
5. [ 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:

1. integer value

Returns: string

PicturePlayer.ZoomIn

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

PicturePlayer.ZoomOut

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

Player

Player.GetActivePlayers

Returns all active players
Permission: ReadData
Parameters: None
Returns:
Type: object
Optional: true
Properties:

• boolean picture
• boolean audio
• boolean video

Playlist

Playlist.Add

Add items to the playlist
Permission: ControlPlayback
Parameters:

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

Returns: string

Playlist.Clear

Clear playlist
Permission: ControlPlayback
Parameters:

1. Playlist.Id playlist

Returns: string

Playlist.Create

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

1. Playlist.Id playlist

Returns:
Type: object
Optional: true
Properties:

• string playlistid

Playlist.Destroy

Destroys a virtual playlist
Permission: ReadData
Parameters:

1. string playlistid

Returns: string

Playlist.GetItems

Retrieve items in the playlist
Permission: ReadData
Parameters:

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

Returns:
Type: object
Optional: true
Properties:

• array items
• [ string name ]

Playlist.Remove

Remove item from the playlist
Permission: ControlPlayback
Parameters:

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

Returns: string

Playlist.Shuffle

Shuffle playlist
Permission: ControlPlayback
Parameters:

1. Playlist.Id playlist

Returns: string

Playlist.Swap

Swap items in the playlist
Permission: ControlPlayback
Parameters:

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

Returns: string

Playlist.UnShuffle

Unshuffle playlist
Permission: ControlPlayback
Parameters:

1. Playlist.Id playlist

Returns: string

System

System.GetInfoBooleans

Retrieve info booleans about the system
Permission: ReadData
Parameters:

1. array[1..X] booleans

Returns:
Type: object
Optional: true

System.GetInfoLabels

Retrieve info labels about the system
Permission: ReadData
Parameters:

1. 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:

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

Returns:
Type: object
Optional: true
Properties:

• [ Library.Details.Episode episodedetails ]

VideoLibrary.GetEpisodes

Retrieve all tv show episodes
Permission: ReadData
Parameters:

1. Library.Id tvshowid
2. [integer season ]
3. [ Library.Fields.Episode fields ]
4. [ List.Limits limits ]
5. [ 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:

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

Returns:
Type: object
Optional: true
Properties:

• [ Library.Details.Movie moviedetails ]

VideoLibrary.GetMovies

Retrieve all movies
Permission: ReadData
Parameters:

1. [ Library.Fields.Movie fields ]
2. [ List.Limits limits ]
3. [ 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:

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

Returns:
Type: object
Optional: true
Properties:

• [ Library.Details.MusicVideo musicvideodetails ]

VideoLibrary.GetMusicVideos

Retrieve all music videos
Permission: ReadData
Parameters:

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

Returns:
Type: object
Optional: true
Properties:

• [ array musicvideos ]
• List.LimitsReturned limits

VideoLibrary.GetRecentlyAddedEpisodes

Retrieve all recently added tv episodes
Permission: ReadData
Parameters:

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

Returns:
Type: object
Optional: true
Properties:

• [ array episodes ]
• List.LimitsReturned limits

VideoLibrary.GetRecentlyAddedMovies

Retrieve all recently added movies
Permission: ReadData
Parameters:

1. [ Library.Fields.Movie fields ]
2. [ List.Limits limits ]
3. [ 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:

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

Returns:
Type: object
Optional: true
Properties:

• [ array musicvideos ]
• List.LimitsReturned limits

VideoLibrary.GetSeasons

Retrieve all tv seasons
Permission: ReadData
Parameters:

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

Returns:
Type: object
Optional: true
Properties:

• [ array seasons ]
• List.LimitsReturned limits

VideoLibrary.GetTVShowDetails

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

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

Returns:
Type: object
Optional: true
Properties:

• [ Library.Details.TVShow tvshowdetails ]

VideoLibrary.GetTVShows

Retrieve all tv shows
Permission: ReadData
Parameters:

1. [ Library.Fields.TVShow fields ]
2. [ List.Limits limits ]
3. [ 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:

1. Player.SeekPercentage value

Returns: string

VideoPlayer.SeekTime

Seek to a specific time
Permission: ControlPlayback
Parameters:

1. Player.SeekTime value

Returns: string

VideoPlayer.SkipNext

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

VideoPlayer.SkipPrevious

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

VideoPlayer.SmallSkipBackward

Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.SmallSkipForward

Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlayer.State

Returns playback state of the video player (if it is active)
Permission: ReadData
Parameters: None
Returns:
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:

1. Playlist.Video.Item item

Returns: string

VideoPlaylist.Clear

Clear playlist
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlaylist.GetItems

Get all items from playlist
Permission: ReadData
Parameters:

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

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

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

Returns: string

VideoPlaylist.Play

Play current or a specific item
Permission: ControlPlayback
Parameters:

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

Returns:
Type: object
Optional: true
Properties:

• boolean success

VideoPlaylist.Remove

Remove item from playlist
Permission: ControlPlayback
Parameters:

1. Playlist.Item.Position item

Returns: string

VideoPlaylist.Shuffle

Shuffle playlist
Permission: ControlPlayback
Parameters: None
Returns: string

VideoPlaylist.SkipNext

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

VideoPlaylist.SkipPrevious

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

VideoPlaylist.UnShuffle

Unshuffle playlist
Permission: ControlPlayback
Parameters: None
Returns: string

XBMC

XBMC.GetVolume

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

XBMC.Log

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

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

Returns: string

XBMC.Play

Starts playback of the given file
Permission: ControlPlayback
Parameters:

1. string file

Returns: string

XBMC.Quit

Quit XBMC
Permission: ControlPower
Parameters: None
Returns: string

XBMC.SetVolume

Set the current volume
Permission: ControlPlayback
Parameters:

1. integer value

Returns: integer

XBMC.StartSlideshow

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

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

Returns: string

XBMC.ToggleMute

Toggle mute/unmute
Permission: ControlPlayback
Parameters: None
Returns:
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

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