JSON-RPC API/v8

From Official Kodi Wiki
Jump to: navigation, search
Home icon grey.png   ▶ Development ▶ JSON-RPC API ▶ v8

Version 8 is a stable version of Kodi's JSON-RPC API and is published with the release of v17 (Krypton).

It comes with support for WebSockets as an alternative transport for third party clients. Using WebSockets will allow webinterfaces (which are currently restricted to the HTTP transport only) to get access to a bidirectional transport with Kodi's JSON-RPC API and can therefore also profit from additional features like notifications.


Contents

1 JSON-RPC 2.0 compatibility

Version Method calls Notifications
(server-side)
Notifications
(client-side)
Parameters
by-name
Parameters
by-position
Batch requests
Version 6 Yes Yes Yes Yes Yes Yes

2 Documentation (JSON Schema)

2.1 Supported features of JSON Schema

Schema IETF Draft 03
type Yes
properties Yes
patternProperties No
additionalProperties Yes
items Yes
additionalItems Yes
required Yes
dependencies No
minimum Yes
maximum Yes
Schema IETF Draft 03
exclusiveMinimum Yes
exclusiveMaximum Yes
minItems Yes
maxItems Yes
uniqueItems Yes
pattern No
minLength Yes
maxLength Yes
enum Yes
default Yes
Schema IETF Draft 03
title No
description Yes
format No
divisibleBy Yes
disallow No
extends Yes
id Yes
$ref Yes
$schema No
Hyper Schema No

3 Error message

If Kodi detects a bad or missing parameter in a JSON-RPC request it returns an error object. The JSON schema description of that error object is

{
  "type": "object",
  "properties": {
    "code": { "type": "integer", "required": true },
    "message": { "type": "string", "required": true },
    "data": { "type": "object",
      "properties": {
        "method": { "type": "string", "required": true },
        "stack": { "type": "object", "id": "Error.Stack",
          "properties": {
            "name": { "type": "string", "required": true },
            "type": { "type": "string", "required": true },
            "message": { "type": "string", "required": true },
            "property": { "$ref": "Error.Stack" }
          }
        }
      }
    }
  }
}

4 Namespaces

The Kodi JSON-RPC API is split up into namespaces, which contain methods that can be called. These namespaces are:

Addons           List, enable and execute addons
Application      Application information and control
AudioLibrary     Audio Library information
Favourites       Favourites GetFavourites and AddFavourite
Files            Shares information & filesystem listings
GUI              Window properties and activation
Input            Allows limited navigation within Kodi
JSONRPC          A variety of standard JSONRPC calls
Player           Manages all available players
Playlist         Playlist modification
Profiles         Support for Profiles operations to xbmc. 
PVR              Live TV control
Settings         Allows manipulation of Kodi settings.
System           System controls and information
Textures         Supplies GetTextures and RemoveTexture. Textures are images.
VideoLibrary     Video Library information
XBMC             Dumping ground for very Kodi specific operations

5 Methods

5.1 Addons

5.1.1 Addons.ExecuteAddon

Executes the given addon with the given parameters (if possible)
Permissions:

  • ExecuteAddon

Parameters:

  1. string addonid
  2. [ mixed: object|array|string params ]
  3. [ boolean wait = false ]

Returns:

Type: string

5.1.2 Addons.GetAddonDetails

Gets the details of a specific addon
Permissions:

  • ReadData

Parameters:

  1. string addonid
  2. [ Addon.Fields properties ]

Returns:

Type: object
Properties:

5.1.3 Addons.GetAddons

Gets all available addons
Permissions:

  • ReadData

Parameters:

  1. [ Addon.Types type = "unknown" ]
  2. [ Addon.Content content = "unknown" ] Content provided by the addon. Only considered for plugins and scripts.
  3. [ mixed: boolean|string enabled = "all" ]
  4. [ Addon.Fields properties ]
  5. [ List.Limits limits ]
  6. [ mixed: boolean|string installed = true ]

Returns:

Type: object
Properties:

5.1.4 Addons.SetAddonEnabled

Enables/Disables a specific addon
Permissions:

  • ManageAddon

Parameters:

  1. string addonid
  2. Global.Toggle enabled

Returns:

Type: string

5.2 Application

5.2.1 Application.GetProperties

Retrieves the values of the given properties
Permissions:

  • ReadData

Parameters:

  1. Application.Property.Name[] properties

Returns:

Type: Application.Property.Value

5.2.2 Application.Quit

Quit application
Permissions:

  • ControlPower

Returns:

Type: string

5.2.3 Application.SetMute

Toggle mute/unmute
Permissions:

  • ControlPlayback

Parameters:

  1. Global.Toggle mute

Returns:

Type: boolean

Description: Mute state

5.2.4 Application.SetVolume

Set the current volume
Permissions:

  • ControlPlayback

Parameters:

  1. mixed volume

Returns:

Type: integer

5.3 AudioLibrary

5.3.1 AudioLibrary.Clean

Cleans the audio library from non-existent items
Permissions:

  • RemoveData

Parameters:

  1. [ boolean showdialogs = true ] Whether or not to show the progress bar or any other GUI dialog

Returns:

Type: string

5.3.2 AudioLibrary.Export

Exports all items from the audio library
Permissions:

  • WriteFile

Parameters:

  1. [ mixed: object|object options ]

Returns:

Type: string

5.3.3 AudioLibrary.GetAlbumDetails

Retrieve details about a specific album
Permissions:

  • ReadData

Parameters:

  1. Library.Id albumid
  2. [ Audio.Fields.Album properties ]

Returns:

Type: object
Properties:

5.3.4 AudioLibrary.GetAlbums

Retrieve all albums from specified artist (and role) or that has songs of the specified genre
Permissions:

  • ReadData

Parameters:

  1. [ Audio.Fields.Album properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]
  4. [ mixed filter ]
  5. [ boolean includesingles = false ]
  6. [ boolean allroles = false ] Whether or not to include all roles when filtering by artist, rather than the default of excluding other contributions. When true it overrides any role filter value.

Returns:

Type: object
Properties:

5.3.5 AudioLibrary.GetArtistDetails

Retrieve details about a specific artist
Permissions:

  • ReadData

Parameters:

  1. Library.Id artistid
  2. [ Audio.Fields.Artist properties ]

Returns:

Type: object
Properties:

5.3.6 AudioLibrary.GetArtists

Retrieve all artists. For backward compatibility by default this implicity does not include those that only contribute other roles, however absolutely all artists can be returned using allroles=true
Permissions:

  • ReadData

Parameters:

  1. [ Optional.Boolean albumartistsonly ] Whether or not to only include album artists rather than the artists of only individual songs as well. If the parameter is not passed or is passed as null the GUI setting will be used
  2. [ Audio.Fields.Artist properties ]
  3. [ List.Limits limits ]
  4. [ List.Sort sort ]
  5. [ mixed filter ]
  6. [ boolean allroles = false ] Whether or not to include all artists irrespective of the role they contributed. When true it overrides any role filter value.

Returns:

Type: object
Properties:

5.3.7 AudioLibrary.GetGenres

Retrieve all genres
Permissions:

  • ReadData

Parameters:

  1. [ Library.Fields.Genre properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.3.8 AudioLibrary.GetProperties

Retrieves the values of the music library properties
Permissions:

  • ReadData

Parameters:

  1. Audio.Property.Name[] properties

Returns:

Type: Audio.Property.Value

5.3.9 AudioLibrary.GetRecentlyAddedAlbums

Retrieve recently added albums
Permissions:

  • ReadData

Parameters:

  1. [ Audio.Fields.Album properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.3.10 AudioLibrary.GetRecentlyAddedSongs

Retrieve recently added songs
Permissions:

  • ReadData

Parameters:

  1. [ List.Amount albumlimit = "-1" ] The amount of recently added albums from which to return the songs
  2. [ Audio.Fields.Song properties ]
  3. [ List.Limits limits ]
  4. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.3.11 AudioLibrary.GetRecentlyPlayedAlbums

Retrieve recently played albums
Permissions:

  • ReadData

Parameters:

  1. [ Audio.Fields.Album properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.3.12 AudioLibrary.GetRecentlyPlayedSongs

Retrieve recently played songs
Permissions:

  • ReadData

Parameters:

  1. [ Audio.Fields.Song properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.3.13 AudioLibrary.GetRoles

Retrieve all contributor roles
Permissions:

  • ReadData

Parameters:

  1. [ Audio.Fields.Role properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.3.14 AudioLibrary.GetSongDetails

Retrieve details about a specific song
Permissions:

  • ReadData

Parameters:

  1. Library.Id songid
  2. [ Audio.Fields.Song properties ]

Returns:

Type: object
Properties:

5.3.15 AudioLibrary.GetSongs

Retrieve all songs from specified album, artist or genre
Permissions:

  • ReadData

Parameters:

  1. [ Audio.Fields.Song properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]
  4. [ mixed filter ]
  5. [ boolean includesingles = true ]
  6. [ boolean allroles = false ] Whether or not to include all roles when filtering by artist, rather than default of excluding other contributors. When true it overrides any role filter value.

Returns:

Type: object
Properties:

5.3.16 AudioLibrary.Scan

Scans the audio sources for new library items
Permissions:

  • UpdateData

Parameters:

  1. [ string directory ]
  2. [ boolean showdialogs = true ] Whether or not to show the progress bar or any other GUI dialog

Returns:

Type: string

5.3.17 AudioLibrary.SetAlbumDetails

Update the given album with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id albumid
  2. [ Optional.String title ]
  3. [ mixed artist ]
  4. [ Optional.String description ]
  5. [ mixed genre ]
  6. [ mixed theme ]
  7. [ mixed mood ]
  8. [ mixed style ]
  9. [ Optional.String type ]
  10. [ Optional.String albumlabel ]
  11. [ Optional.Number rating ]
  12. [ Optional.Integer year ]
  13. [ Optional.Integer userrating ]
  14. [ Optional.Integer votes ]

Returns:

Type: string

5.3.18 AudioLibrary.SetArtistDetails

Update the given artist with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id artistid
  2. [ Optional.String artist ]
  3. [ mixed instrument ]
  4. [ mixed style ]
  5. [ mixed mood ]
  6. [ Optional.String born ]
  7. [ Optional.String formed ]
  8. [ Optional.String description ]
  9. [ mixed genre ]
  10. [ Optional.String died ]
  11. [ Optional.String disbanded ]
  12. [ mixed yearsactive ]

Returns:

Type: string

5.3.19 AudioLibrary.SetSongDetails

Update the given song with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id songid
  2. [ Optional.String title ]
  3. [ mixed artist ]
  4. [ mixed albumartist ]
  5. [ mixed genre ]
  6. [ Optional.Integer year ]
  7. [ Optional.Number rating ]
  8. [ Optional.String album ]
  9. [ Optional.Integer track ]
  10. [ Optional.Integer disc ]
  11. [ Optional.Integer duration ]
  12. [ Optional.String comment ]
  13. [ Optional.String musicbrainztrackid ]
  14. [ Optional.String musicbrainzartistid ]
  15. [ Optional.String musicbrainzalbumid ]
  16. [ Optional.String musicbrainzalbumartistid ]
  17. [ Optional.Integer playcount ]
  18. [ Optional.String lastplayed ]
  19. [ Optional.Integer userrating ]
  20. [ Optional.Integer votes ]

Returns:

Type: string

5.4 Favourites

5.4.1 Favourites.AddFavourite

Add a favourite with the given details
Permissions:

  • UpdateData

Parameters:

  1. string title
  2. Favourite.Type type
  3. [ Optional.String path ] Required for media and script favourites types
  4. [ Optional.String window ] Required for window favourite type
  5. [ Optional.String windowparameter ]
  6. [ Optional.String thumbnail ]

Returns:

Type: string

5.4.2 Favourites.GetFavourites

Retrieve all favourites
Permissions:

  • ReadData

Parameters:

  1. [ mixed type ]
  2. [ Favourite.Fields.Favourite properties ]

Returns:

Type: object
Properties:

5.5 Files

5.5.1 Files.GetDirectory

Get the directories and files in the given directory
Permissions:

  • ReadData

Parameters:

  1. string directory
  2. [ Files.Media media = "files" ]
  3. [ List.Fields.Files properties ]
  4. [ List.Sort sort ]
  5. [ List.Limits limits ] Limits are applied after getting the directory content thus retrieval is not faster when they are applied.

Returns:

Type: object
Properties:

5.5.2 Files.GetFileDetails

Get details for a specific file
Permissions:

  • ReadData

Parameters:

  1. string file Full path to the file
  2. [ Files.Media media = "files" ]
  3. [ List.Fields.Files properties ]

Returns:

Type: object
Properties:

5.5.3 Files.GetSources

Get the sources of the media windows
Permissions:

  • ReadData

Parameters:

  1. Files.Media media
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.5.4 Files.PrepareDownload

Provides a way to download a given file (e.g. providing an URL to the real file location)
Permissions:

  • ReadData

Parameters:

  1. string path

Returns:

Type: object
Properties:

  • mixed Transport specific details on how/from where to download the given filedetails
  • string Direct mode allows using Files.Download whereas redirect mode requires the usage of a different protocolmode
  • string protocol

5.5.5 Files.SetFileDetails

Update the given specific file with the given details
Permissions:

  • UpdateData

Parameters:

  1. string file Full path to the file
  2. Files.Media media File type to update correct database. Currently only "video" is supported.
  3. [ Optional.Integer playcount ]
  4. [ Optional.String lastplayed ] Setting a valid lastplayed without a playcount will force playcount to 1.
  5. [ mixed resume ]

Returns:

Type: string

5.6 GUI

5.6.1 GUI.ActivateWindow

Activates the given window
Permissions:

  • ControlGUI

Parameters:

  1. GUI.Window window
  2. [ string[] parameters ]

Returns:

Type: string

5.6.2 GUI.GetProperties

Retrieves the values of the given properties
Permissions:

  • ReadData

Parameters:

  1. GUI.Property.Name[] properties

Returns:

Type: GUI.Property.Value

5.6.3 GUI.GetStereoscopicModes

Returns the supported stereoscopic modes of the GUI
Permissions:

  • ReadData

Returns:

Type: object
Properties:

5.6.4 GUI.SetFullscreen

Toggle fullscreen/GUI
Permissions:

  • ControlGUI

Parameters:

  1. Global.Toggle fullscreen

Returns:

Type: boolean

Description: Fullscreen state

5.6.5 GUI.SetStereoscopicMode

Sets the stereoscopic mode of the GUI to the given mode
Permissions:

  • ControlGUI

Parameters:

  1. string mode

Returns:

Type: string

5.6.6 GUI.ShowNotification

Shows a GUI notification
Permissions:

  • ControlGUI

Parameters:

  1. string title
  2. string message
  3. [ mixed: string|string image ]
  4. [ integer displaytime = "5000" ] The time in milliseconds the notification will be visible

Returns:

Type: string

5.7 Input

5.7.1 Input.Back

Goes back in GUI
Permissions:

  • Navigate

Returns:

Type: string

5.7.2 Input.ContextMenu

Shows the context menu
Permissions:

  • Navigate

Returns:

Type: string

5.7.3 Input.Down

Navigate down in GUI
Permissions:

  • Navigate

Returns:

Type: string

5.7.4 Input.ExecuteAction

Execute a specific action
Permissions:

  • Navigate

Parameters:

  1. Input.Action action

Returns:

Type: string

5.7.5 Input.Home

Goes to home window in GUI
Permissions:

  • Navigate

Returns:

Type: string

5.7.6 Input.Info

Shows the information dialog
Permissions:

  • Navigate

Returns:

Type: string

5.7.7 Input.Left

Navigate left in GUI
Permissions:

  • Navigate

Returns:

Type: string

5.7.8 Input.Right

Navigate right in GUI
Permissions:

  • Navigate

Returns:

Type: string

5.7.9 Input.Select

Select current item in GUI
Permissions:

  • Navigate

Returns:

Type: string

5.7.10 Input.SendText

Send a generic (unicode) text
Permissions:

  • Navigate

Parameters:

  1. string text Unicode text
  2. [ boolean done = true ] Whether this is the whole input or not (closes an open input dialog if true).

Returns:

Type: string

5.7.11 Input.ShowCodec

Show codec information of the playing item
Permissions:

  • Navigate

Returns:

Type: string

5.7.12 Input.ShowOSD

Show the on-screen display for the current player
Permissions:

  • Navigate

Returns:

Type: string

5.7.13 Input.ShowPlayerProcessInfo

Show player process information of the playing item, like video decoder, pixel format, pvr signal strength, ...
Permissions:

  • Navigate

Returns:

Type: string

5.7.14 Input.Up

Navigate up in GUI
Permissions:

  • Navigate

Returns:

Type: string

5.8 JSONRPC

5.8.1 JSONRPC.Introspect

Enumerates all actions and descriptions
Permissions:

  • ReadData

Parameters:

  1. [ boolean getdescriptions = true ]
  2. [ boolean getmetadata = false ]
  3. [ boolean filterbytransport = true ]
  4. [ mixed filter ]

Returns:

Type: object

5.8.2 JSONRPC.NotifyAll

Notify all other connected clients
Permissions:

  • ReadData

Parameters:

  1. string sender
  2. string message
  3. [ mixed data ]

Returns:

Type: any

5.8.3 JSONRPC.Permission

Retrieve the clients permissions
Permissions:

  • ReadData

Returns:

Type: object
Properties:

  • boolean controlgui
  • boolean controlnotify
  • boolean controlplayback
  • boolean controlpower
  • boolean controlpvr
  • boolean controlsystem
  • boolean executeaddon
  • boolean manageaddon
  • boolean navigate
  • boolean readdata
  • boolean removedata
  • boolean updatedata
  • boolean writefile

5.8.4 JSONRPC.Ping

Ping responder
Permissions:

  • ReadData

Returns:

Type: string

5.8.5 JSONRPC.Version

Retrieve the JSON-RPC protocol version.
Permissions:

  • ReadData

Returns:

Type: object
Properties:

  • mixed version

5.9 Player

5.9.1 Player.GetActivePlayers

Returns all active players
Permissions:

  • ReadData

Returns:

Type: array

5.9.2 Player.GetItem

Retrieves the currently played item
Permissions:

  • ReadData

Parameters:

  1. Player.Id playerid
  2. [ List.Fields.All properties ]

Returns:

Type: object
Properties:

5.9.3 Player.GetPlayers

Get a list of available players
Permissions:

  • ReadData

Parameters:

  1. [ string media = "all" ]

Returns:

Type: array

5.9.4 Player.GetProperties

Retrieves the values of the given properties
Permissions:

  • ReadData

Parameters:

  1. Player.Id playerid
  2. Player.Property.Name[] properties

Returns:

Type: Player.Property.Value

5.9.5 Player.GoTo

Go to previous/next/specific item in the playlist
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. mixed to

Returns:

Type: string

5.9.6 Player.Move

If picture is zoomed move viewport left/right/up/down otherwise skip previous/next
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. string direction

Returns:

Type: string

5.9.7 Player.Open

Start playback of either the playlist with the given ID, a slideshow with the pictures from the given directory or a single file or an item from the database.
Permissions:

  • ControlPlayback

Parameters:

  1. [ mixed item ]
  2. [ mixed options ]

Returns:

Type: string

5.9.8 Player.PlayPause

Pauses or unpause playback and returns the new state
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. [ Global.Toggle play = "toggle" ]

Returns:

Type: Player.Speed

5.9.9 Player.Rotate

Rotates current picture
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. [ string value = "clockwise" ]

Returns:

Type: string

5.9.10 Player.Seek

Seek through the playing item
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. mixed value

Returns:

Type: object
Properties:

5.9.11 Player.SetAudioStream

Set the audio stream played by the player
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. mixed: string|integer stream

Returns:

Type: string

5.9.12 Player.SetPartymode

Turn partymode on or off
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. Global.Toggle partymode

Returns:

Type: string

5.9.13 Player.SetRepeat

Set the repeat mode of the player
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. mixed repeat

Returns:

Type: string

5.9.14 Player.SetShuffle

Shuffle/Unshuffle items in the player
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. Global.Toggle shuffle

Returns:

Type: string

5.9.15 Player.SetSpeed

Set the speed of the current playback
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. mixed speed

Returns:

Type: Player.Speed

5.9.16 Player.SetSubtitle

Set the subtitle displayed by the player
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. mixed: string|integer subtitle
  3. [ boolean enable = false ] Whether to enable subtitles to be displayed after setting the new subtitle

Returns:

Type: string

5.9.17 Player.SetVideoStream

Set the video stream played by the player
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. mixed: string|integer stream

Returns:

Type: string

5.9.18 Player.Stop

Stops playback
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid

Returns:

Type: string

5.9.19 Player.Zoom

Zoom current picture
Permissions:

  • ControlPlayback

Parameters:

  1. Player.Id playerid
  2. mixed: string|integer zoom

Returns:

Type: string

5.10 Playlist

5.10.1 Playlist.Add

Add item(s) to playlist
Permissions:

  • ControlPlayback

Parameters:

  1. Playlist.Id playlistid
  2. mixed item

Returns:

Type: string

5.10.2 Playlist.Clear

Clear playlist
Permissions:

  • ControlPlayback

Parameters:

  1. Playlist.Id playlistid

Returns:

Type: string

5.10.3 Playlist.GetItems

Get all items from playlist
Permissions:

  • ReadData

Parameters:

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

Returns:

Type: object
Properties:

5.10.4 Playlist.GetPlaylists

Returns all existing playlists
Permissions:

  • ReadData

Returns:

Type: array

5.10.5 Playlist.GetProperties

Retrieves the values of the given properties
Permissions:

  • ReadData

Parameters:

  1. Playlist.Id playlistid
  2. Playlist.Property.Name[] properties

Returns:

Type: Playlist.Property.Value

5.10.6 Playlist.Insert

Insert item(s) into playlist. Does not work for picture playlists (aka slideshows).
Permissions:

  • ControlPlayback

Parameters:

  1. Playlist.Id playlistid
  2. Playlist.Position position
  3. mixed item

Returns:

Type: string

5.10.7 Playlist.Remove

Remove item from playlist. Does not work for picture playlists (aka slideshows).
Permissions:

  • ControlPlayback

Parameters:

  1. Playlist.Id playlistid
  2. Playlist.Position position

Returns:

Type: string

5.10.8 Playlist.Swap

Swap items in the playlist. Does not work for picture playlists (aka slideshows).
Permissions:

  • ControlPlayback

Parameters:

  1. Playlist.Id playlistid
  2. Playlist.Position position1
  3. Playlist.Position position2

Returns:

Type: string

5.11 Profiles

5.11.1 Profiles.GetCurrentProfile

Retrieve the current profile
Permissions:

  • ReadData

Parameters:

  1. [ Profiles.Fields.Profile properties ]

Returns:

Type: Profiles.Details.Profile

5.11.2 Profiles.GetProfiles

Retrieve all profiles
Permissions:

  • ReadData

Parameters:

  1. [ Profiles.Fields.Profile properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.11.3 Profiles.LoadProfile

Load the specified profile
Permissions:

  • Navigate

Parameters:

  1. string profile Profile name
  2. [ boolean prompt = false ] Prompt for password
  3. [ Profiles.Password password ]

Returns:

Type: string

5.12 PVR

5.12.1 PVR.AddTimer

Adds a timer to record the given show one times or a timer rule to record all showings of the given show
Permissions:

  • ControlPVR

Parameters:

  1. Library.Id broadcastid the broadcast id of the item to record
  2. [ boolean timerrule = false ] controls whether to create a timer rule or a onetime timer

Returns:

Type: string

5.12.2 PVR.DeleteTimer

Deletes a onetime timer or a timer rule
Permissions:

  • ControlPVR

Parameters:

  1. Library.Id timerid the id of the onetime timer or timer rule to delete

Returns:

Type: string

5.12.3 PVR.GetBroadcastDetails

Retrieves the details of a specific broadcast
Permissions:

  • ReadData

Parameters:

  1. Library.Id broadcastid
  2. [ PVR.Fields.Broadcast properties ]

Returns:

Type: object
Properties:

5.12.4 PVR.GetBroadcasts

Retrieves the program of a specific channel
Permissions:

  • ReadData

Parameters:

  1. Library.Id channelid
  2. [ PVR.Fields.Broadcast properties ]
  3. [ List.Limits limits ]

Returns:

Type: object
Properties:

5.12.5 PVR.GetChannelDetails

Retrieves the details of a specific channel
Permissions:

  • ReadData

Parameters:

  1. Library.Id channelid
  2. [ PVR.Fields.Channel properties ]

Returns:

Type: object
Properties:

5.12.6 PVR.GetChannelGroupDetails

Retrieves the details of a specific channel group
Permissions:

  • ReadData

Parameters:

  1. PVR.ChannelGroup.Id channelgroupid
  2. [ mixed channels ]

Returns:

Type: object
Properties:

5.12.7 PVR.GetChannelGroups

Retrieves the channel groups for the specified type
Permissions:

  • ReadData

Parameters:

  1. PVR.Channel.Type channeltype
  2. [ List.Limits limits ]

Returns:

Type: object
Properties:

5.12.8 PVR.GetChannels

Retrieves the channel list
Permissions:

  • ReadData

Parameters:

  1. PVR.ChannelGroup.Id channelgroupid
  2. [ PVR.Fields.Channel properties ]
  3. [ List.Limits limits ]

Returns:

Type: object
Properties:

5.12.9 PVR.GetProperties

Retrieves the values of the given properties
Permissions:

  • ReadData

Parameters:

  1. PVR.Property.Name[] properties

Returns:

Type: PVR.Property.Value

5.12.10 PVR.GetRecordingDetails

Retrieves the details of a specific recording
Permissions:

  • ReadData

Parameters:

  1. Library.Id recordingid
  2. [ PVR.Fields.Recording properties ]

Returns:

Type: object
Properties:

5.12.11 PVR.GetRecordings

Retrieves the recordings
Permissions:

  • ReadData

Parameters:

  1. [ PVR.Fields.Recording properties ]
  2. [ List.Limits limits ]

Returns:

Type: object
Properties:

5.12.12 PVR.GetTimerDetails

Retrieves the details of a specific timer
Permissions:

  • ReadData

Parameters:

  1. Library.Id timerid
  2. [ PVR.Fields.Timer properties ]

Returns:

Type: object
Properties:

5.12.13 PVR.GetTimers

Retrieves the timers
Permissions:

  • ReadData

Parameters:

  1. [ PVR.Fields.Timer properties ]
  2. [ List.Limits limits ]

Returns:

Type: object
Properties:

5.12.14 PVR.Record

Toggle recording of a channel
Permissions:

  • ControlPVR

Parameters:

  1. [ Global.Toggle record = "toggle" ]
  2. [ mixed channel = "current" ]

Returns:

Type: string

5.12.15 PVR.Scan

Starts a channel scan
Permissions:

  • ControlPVR

Returns:

Type: string

5.12.16 PVR.ToggleTimer

Creates or deletes a onetime timer or timer rule for a given show. If it exists, it will be deleted. If it does not exist, it will be created
Permissions:

  • ControlPVR

Parameters:

  1. Library.Id broadcastid the broadcast id of the item to toggle a onetime timer or time rule for
  2. [ boolean timerrule = false ] controls whether to create / delete a timer rule or a onetime timer

Returns:

Type: string

5.13 Settings

5.13.1 Settings.GetCategories

Retrieves all setting categories
Permissions:

  • ReadData

Parameters:

  1. [ Setting.Level level = "standard" ]
  2. [ string section ]
  3. [ mixed properties ]

Returns:

Type: object
Properties:

5.13.2 Settings.GetSections

Retrieves all setting sections
Permissions:

  • ReadData

Parameters:

  1. [ Setting.Level level = "standard" ]
  2. [ mixed properties ]

Returns:

Type: object
Properties:

5.13.3 Settings.GetSettings

Retrieves all settings
Permissions:

  • ReadData

Parameters:

  1. [ Setting.Level level = "standard" ]
  2. [ mixed: object filter ]

Returns:

Type: object
Properties:

5.13.4 Settings.GetSettingValue

Retrieves the value of a setting
Permissions:

  • ReadData

Parameters:

  1. string setting

Returns:

Type: object
Properties:

5.13.5 Settings.ResetSettingValue

Resets the value of a setting
Permissions:

  • ReadData

Parameters:

  1. string setting

Returns:

Type: string

5.13.6 Settings.SetSettingValue

Changes the value of a setting
Permissions:

  • ReadData

Parameters:

  1. string setting
  2. Setting.Value.Extended value

Returns:

Type: boolean

5.14 System

5.14.1 System.EjectOpticalDrive

Ejects or closes the optical disc drive (if available)
Permissions:

  • ControlSystem

Returns:

Type: string

5.14.2 System.GetProperties

Retrieves the values of the given properties
Permissions:

  • ReadData

Parameters:

  1. System.Property.Name[] properties

Returns:

Type: System.Property.Value

5.14.3 System.Hibernate

Puts the system running Kodi into hibernate mode
Permissions:

  • ControlPower

Returns:

Type: string

5.14.4 System.Reboot

Reboots the system running Kodi
Permissions:

  • ControlPower

Returns:

Type: string

5.14.5 System.Shutdown

Shuts the system running Kodi down
Permissions:

  • ControlPower

Returns:

Type: string

5.14.6 System.Suspend

Suspends the system running Kodi
Permissions:

  • ControlPower

Returns:

Type: string

5.15 Textures

5.15.1 Textures.GetTextures

Retrieve all textures
Permissions:

  • ReadData

Parameters:

  1. [ Textures.Fields.Texture properties ]
  2. [ List.Filter.Textures filter ]

Returns:

Type: object
Properties:

5.15.2 Textures.RemoveTexture

Remove the specified texture
Permissions:

  • RemoveData

Parameters:

  1. Library.Id textureid Texture database identifier

Returns:

Type: string

5.16 VideoLibrary

5.16.1 VideoLibrary.Clean

Cleans the video library from non-existent items
Permissions:

  • RemoveData

Parameters:

  1. [ boolean showdialogs = true ] Whether or not to show the progress bar or any other GUI dialog

Returns:

Type: string

5.16.2 VideoLibrary.Export

Exports all items from the video library
Permissions:

  • WriteFile

Parameters:

  1. [ mixed: object|object options ]

Returns:

Type: string

5.16.3 VideoLibrary.GetEpisodeDetails

Retrieve details about a specific tv show episode
Permissions:

  • ReadData

Parameters:

  1. Library.Id episodeid
  2. [ Video.Fields.Episode properties ]

Returns:

Type: object
Properties:

5.16.4 VideoLibrary.GetEpisodes

Retrieve all tv show episodes
Permissions:

  • ReadData

Parameters:

  1. [ Library.Id tvshowid = "-1" ]
  2. [ integer season = "-1" ]
  3. [ Video.Fields.Episode properties ]
  4. [ List.Limits limits ]
  5. [ List.Sort sort ]
  6. [ mixed filter ]

Returns:

Type: object
Properties:

5.16.5 VideoLibrary.GetGenres

Retrieve all genres
Permissions:

  • ReadData

Parameters:

  1. string type
  2. [ Library.Fields.Genre properties ]
  3. [ List.Limits limits ]
  4. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.16.6 VideoLibrary.GetInProgressTVShows

Retrieve all in progress tvshows
Permissions:

  • ReadData

Parameters:

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

Returns:

Type: object
Properties:

5.16.7 VideoLibrary.GetMovieDetails

Retrieve details about a specific movie
Permissions:

  • ReadData

Parameters:

  1. Library.Id movieid
  2. [ Video.Fields.Movie properties ]

Returns:

Type: object
Properties:

5.16.8 VideoLibrary.GetMovies

Retrieve all movies
Permissions:

  • ReadData

Parameters:

  1. [ Video.Fields.Movie properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]
  4. [ mixed filter ]

Returns:

Type: object
Properties:

5.16.9 VideoLibrary.GetMovieSetDetails

Retrieve details about a specific movie set
Permissions:

  • ReadData

Parameters:

  1. Library.Id setid
  2. [ Video.Fields.MovieSet properties ]
  3. [ mixed movies ]

Returns:

Type: object
Properties:

5.16.10 VideoLibrary.GetMovieSets

Retrieve all movie sets
Permissions:

  • ReadData

Parameters:

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

Returns:

Type: object
Properties:

5.16.11 VideoLibrary.GetMusicVideoDetails

Retrieve details about a specific music video
Permissions:

  • ReadData

Parameters:

  1. Library.Id musicvideoid
  2. [ Video.Fields.MusicVideo properties ]

Returns:

Type: object
Properties:

5.16.12 VideoLibrary.GetMusicVideos

Retrieve all music videos
Permissions:

  • ReadData

Parameters:

  1. [ Video.Fields.MusicVideo properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]
  4. [ mixed filter ]

Returns:

Type: object
Properties:

5.16.13 VideoLibrary.GetRecentlyAddedEpisodes

Retrieve all recently added tv episodes
Permissions:

  • ReadData

Parameters:

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

Returns:

Type: object
Properties:

5.16.14 VideoLibrary.GetRecentlyAddedMovies

Retrieve all recently added movies
Permissions:

  • ReadData

Parameters:

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

Returns:

Type: object
Properties:

5.16.15 VideoLibrary.GetRecentlyAddedMusicVideos

Retrieve all recently added music videos
Permissions:

  • ReadData

Parameters:

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

Returns:

Type: object
Properties:

5.16.16 VideoLibrary.GetSeasonDetails

Retrieve details about a specific tv show season
Permissions:

  • ReadData

Parameters:

  1. Library.Id seasonid
  2. [ Video.Fields.Season properties ]

Returns:

Type: object
Properties:

5.16.17 VideoLibrary.GetSeasons

Retrieve all tv seasons
Permissions:

  • ReadData

Parameters:

  1. [ Library.Id tvshowid = "-1" ]
  2. [ Video.Fields.Season properties ]
  3. [ List.Limits limits ]
  4. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.16.18 VideoLibrary.GetTags

Retrieve all tags
Permissions:

  • ReadData

Parameters:

  1. string type
  2. [ Library.Fields.Tag properties ]
  3. [ List.Limits limits ]
  4. [ List.Sort sort ]

Returns:

Type: object
Properties:

5.16.19 VideoLibrary.GetTVShowDetails

Retrieve details about a specific tv show
Permissions:

  • ReadData

Parameters:

  1. Library.Id tvshowid
  2. [ Video.Fields.TVShow properties ]

Returns:

Type: object
Properties:

5.16.20 VideoLibrary.GetTVShows

Retrieve all tv shows
Permissions:

  • ReadData

Parameters:

  1. [ Video.Fields.TVShow properties ]
  2. [ List.Limits limits ]
  3. [ List.Sort sort ]
  4. [ mixed filter ]

Returns:

Type: object
Properties:

5.16.21 VideoLibrary.RefreshEpisode

Refresh the given episode in the library
Permissions:

  • UpdateData

Parameters:

  1. Library.Id episodeid
  2. [ boolean ignorenfo = false ] Whether or not to ignore a local NFO if present.
  3. [ string title ] Title to use for searching (instead of determining it from the item's filename/path).

Returns:

Type: string

5.16.22 VideoLibrary.RefreshMovie

Refresh the given movie in the library
Permissions:

  • UpdateData

Parameters:

  1. Library.Id movieid
  2. [ boolean ignorenfo = false ] Whether or not to ignore a local NFO if present.
  3. [ string title ] Title to use for searching (instead of determining it from the item's filename/path).

Returns:

Type: string

5.16.23 VideoLibrary.RefreshMusicVideo

Refresh the given music video in the library
Permissions:

  • UpdateData

Parameters:

  1. Library.Id musicvideoid
  2. [ boolean ignorenfo = false ] Whether or not to ignore a local NFO if present.
  3. [ string title ] Title to use for searching (instead of determining it from the item's filename/path).

Returns:

Type: string

5.16.24 VideoLibrary.RefreshTVShow

Refresh the given tv show in the library
Permissions:

  • UpdateData

Parameters:

  1. Library.Id tvshowid
  2. [ boolean ignorenfo = false ] Whether or not to ignore a local NFO if present.
  3. [ boolean refreshepisodes = false ] Whether or not to refresh all episodes belonging to the TV show.
  4. [ string title ] Title to use for searching (instead of determining it from the item's filename/path).

Returns:

Type: string

5.16.25 VideoLibrary.RemoveEpisode

Removes the given episode from the library
Permissions:

  • RemoveData

Parameters:

  1. Library.Id episodeid

Returns:

Type: string

5.16.26 VideoLibrary.RemoveMovie

Removes the given movie from the library
Permissions:

  • RemoveData

Parameters:

  1. Library.Id movieid

Returns:

Type: string

5.16.27 VideoLibrary.RemoveMusicVideo

Removes the given music video from the library
Permissions:

  • RemoveData

Parameters:

  1. Library.Id musicvideoid

Returns:

Type: string

5.16.28 VideoLibrary.RemoveTVShow

Removes the given tv show from the library
Permissions:

  • RemoveData

Parameters:

  1. Library.Id tvshowid

Returns:

Type: string

5.16.29 VideoLibrary.Scan

Scans the video sources for new library items
Permissions:

  • UpdateData

Parameters:

  1. [ string directory ]
  2. [ boolean showdialogs = true ] Whether or not to show the progress bar or any other GUI dialog

Returns:

Type: string

5.16.30 VideoLibrary.SetEpisodeDetails

Update the given episode with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id episodeid
  2. [ Optional.String title ]
  3. [ Optional.Integer playcount ]
  4. [ Optional.Integer runtime ] Runtime in seconds
  5. [ mixed director ]
  6. [ Optional.String plot ]
  7. [ Optional.Number rating ]
  8. [ Optional.String votes ]
  9. [ Optional.String lastplayed ]
  10. [ mixed writer ]
  11. [ Optional.String firstaired ]
  12. [ Optional.String productioncode ]
  13. [ Optional.Integer season ]
  14. [ Optional.Integer episode ]
  15. [ Optional.String originaltitle ]
  16. [ Optional.String thumbnail ]
  17. [ Optional.String fanart ]
  18. [ mixed art ]
  19. [ mixed resume ]
  20. [ Optional.Integer userrating ]
  21. [ Video.Ratings.Set ratings ]
  22. [ Optional.String dateadded ]
  23. [ mixed uniqueid ]

Returns:

Type: string

5.16.31 VideoLibrary.SetMovieDetails

Update the given movie with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id movieid
  2. [ Optional.String title ]
  3. [ Optional.Integer playcount ]
  4. [ Optional.Integer runtime ] Runtime in seconds
  5. [ mixed director ]
  6. [ mixed studio ]
  7. [ Optional.Integer year ] linked with premiered. Overridden by premiered parameter
  8. [ Optional.String plot ]
  9. [ mixed genre ]
  10. [ Optional.Number rating ]
  11. [ Optional.String mpaa ]
  12. [ Optional.String imdbnumber ]
  13. [ Optional.String votes ]
  14. [ Optional.String lastplayed ]
  15. [ Optional.String originaltitle ]
  16. [ Optional.String trailer ]
  17. [ Optional.String tagline ]
  18. [ Optional.String plotoutline ]
  19. [ mixed writer ]
  20. [ mixed country ]
  21. [ Optional.Integer top250 ]
  22. [ Optional.String sorttitle ]
  23. [ Optional.String set ]
  24. [ mixed showlink ]
  25. [ Optional.String thumbnail ]
  26. [ Optional.String fanart ]
  27. [ mixed tag ]
  28. [ mixed art ]
  29. [ mixed resume ]
  30. [ Optional.Integer userrating ]
  31. [ Video.Ratings.Set ratings ]
  32. [ Optional.String dateadded ]
  33. [ Optional.String premiered ] linked with year. Overriedes year
  34. [ mixed uniqueid ]

Returns:

Type: string

5.16.32 VideoLibrary.SetMovieSetDetails

Update the given movie set with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id setid
  2. [ Optional.String title ]
  3. [ mixed art ]

Returns:

Type: string

5.16.33 VideoLibrary.SetMusicVideoDetails

Update the given music video with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id musicvideoid
  2. [ Optional.String title ]
  3. [ Optional.Integer playcount ]
  4. [ Optional.Integer runtime ] Runtime in seconds
  5. [ mixed director ]
  6. [ mixed studio ]
  7. [ Optional.Integer year ] linked with premiered. Overridden by premiered parameter
  8. [ Optional.String plot ]
  9. [ Optional.String album ]
  10. [ mixed artist ]
  11. [ mixed genre ]
  12. [ Optional.Integer track ]
  13. [ Optional.String lastplayed ]
  14. [ Optional.String thumbnail ]
  15. [ Optional.String fanart ]
  16. [ mixed tag ]
  17. [ mixed art ]
  18. [ mixed resume ]
  19. [ Optional.Number rating ]
  20. [ Optional.Integer userrating ]
  21. [ Optional.String dateadded ]
  22. [ Optional.String premiered ] linked with year. Overriedes year

Returns:

Type: string

5.16.34 VideoLibrary.SetSeasonDetails

Update the given season with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id seasonid
  2. [ mixed art ]
  3. [ Optional.Integer userrating ]

Returns:

Type: string

5.16.35 VideoLibrary.SetTVShowDetails

Update the given tvshow with the given details
Permissions:

  • UpdateData

Parameters:

  1. Library.Id tvshowid
  2. [ Optional.String title ]
  3. [ Optional.Integer playcount ]
  4. [ mixed studio ]
  5. [ Optional.String plot ]
  6. [ mixed genre ]
  7. [ Optional.Number rating ]
  8. [ Optional.String mpaa ]
  9. [ Optional.String imdbnumber ]
  10. [ Optional.String premiered ]
  11. [ Optional.String votes ]
  12. [ Optional.String lastplayed ]
  13. [ Optional.String originaltitle ]
  14. [ Optional.String sorttitle ]
  15. [ Optional.String episodeguide ]
  16. [ Optional.String thumbnail ]
  17. [ Optional.String fanart ]
  18. [ mixed tag ]
  19. [ mixed art ]
  20. [ Optional.Integer userrating ]
  21. [ Video.Ratings.Set ratings ]
  22. [ Optional.String dateadded ]
  23. [ Optional.Integer runtime ] Runtime in seconds
  24. [ Optional.String status ]
  25. [ mixed uniqueid ]

Returns:

Type: string

5.17 XBMC

5.17.1 XBMC.GetInfoBooleans

Retrieve info booleans about Kodi and the system
Permissions:

  • ReadData

Parameters:

  1. string[] booleans

Returns:

Type: object

Description: Object containing key-value pairs of the retrieved info booleans

5.17.2 XBMC.GetInfoLabels

Retrieve info labels about Kodi and the system
Permissions:

  • ReadData

Parameters:

  1. string[] labels See http://kodi.wiki/view/InfoLabels for a list of possible info labels

Returns:

Type: object

Description: Object containing key-value pairs of the retrieved info labels

6 Global Types

6.1 Addon

6.1.1 Addon.Content

Type: string

6.1.2 Addon.Details

Extends:


Properties:

  • string addonid
  • [ string author ]
  • [ mixed: boolean|string broken ]
  • [ object dependencies ]
  • [ string description ]
  • [ string disclaimer ]
  • [ boolean enabled = false ]
  • [ object extrainfo ]
  • [ string fanart ]
  • [ boolean installed = false ]
  • [ string name ]
  • [ string path ]
  • [ integer rating = "0" ]
  • [ string summary ]
  • [ string thumbnail ]
  • Addon.Types type
  • [ string version ]

6.1.3 Addon.Fields

Extends:

6.1.4 Addon.Types

Type: string

6.2 Application

6.2.1 Application.Property.Name

Type: string

6.2.2 Application.Property.Value

Type: mixed
Properties:

  • [ boolean muted = false ]
  • [ string name ]
  • [ mixed version ]
  • [ integer volume = "0" ]

6.3 Array

6.3.1 Array.Integer

Type: mixed

6.3.2 Array.String

Type: mixed

6.4 Audio

6.4.1 Audio.Album.ReleaseType

Type: string

6.4.2 Audio.Artist.Roles

Type: mixed

6.4.3 Audio.Contributors

Type: mixed

6.4.4 Audio.Details.Album

Extends:


Properties:

6.4.5 Audio.Details.Artist

Extends:


Properties:

6.4.6 Audio.Details.Base

Extends:


Properties:

6.4.7 Audio.Details.Genres

Type: mixed

6.4.8 Audio.Details.Media

Extends:


Properties:

  • [ Array.String artist ]
  • [ Array.Integer artistid ]
  • [ string displayartist ]
  • [ Array.Integer genreid ]
  • [ string musicbrainzalbumartistid ]
  • [ string musicbrainzalbumid ]
  • [ number rating = "0" ]
  • [ string title ]
  • [ integer userrating = "0" ]
  • [ integer votes = "0" ]
  • [ integer year = "0" ]

6.4.9 Audio.Details.Role

Extends:


Properties:

6.4.10 Audio.Details.Song

Extends:


Properties:

  • [ string album ]
  • [ Array.String albumartist ]
  • [ Array.Integer albumartistid ]
  • [ Library.Id albumid = "-1" ]
  • [ Audio.Album.ReleaseType albumreleasetype = "album" ]
  • [ string comment ]
  • [ Audio.Contributors contributors ]
  • [ integer disc = "0" ]
  • [ string displaycomposer ]
  • [ string displayconductor ]
  • [ string displaylyricist ]
  • [ string displayorchestra ]
  • [ integer duration = "0" ]
  • [ string file ]
  • [ string lastplayed ]
  • [ string lyrics ]
  • [ string mood ]
  • [ string musicbrainzartistid ]
  • [ string musicbrainztrackid ]
  • [ integer playcount = "0" ]
  • Library.Id songid
  • [ integer track = "0" ]