Kodi Development  20.0
for Binary and Script based Add-Ons
List of built-in functions

Add-on built-in's


FunctionDescription
Addon.Default.OpenSettings(extensionpoint) Open a settings dialog for the default addon of the given type (extensionpoint)
Parameters
[in]extensionpointThe add-on type
Addon.Default.Set(extensionpoint) Open a select dialog to allow choosing the default addon of the given type (extensionpoint)
Parameters
[in]extensionpointThe add-on type
Addon.OpenSettings(id) Open a settings dialog for the addon of the given id
Parameters
[in]idThe add-on ID
EnableAddon(id)

Enable the specified plugin/script

Parameters
[in]idThe add-on id

v19 Skinning engine changes:
[New builtin] EnableAddon(id)

InstallAddon(id) Install the specified plugin/script
Parameters
[in]idThe add-on id
InstallFromZip Opens the "Install from zip" dialog if "Unknown sources" is enabled. Prompts the warning message if not.
RunAddon(id[,opt]) Runs the specified plugin/script
Parameters
[in]idThe add-on id.
[in]optis blank for no add-on parameters
or
[in]optAdd-on parameters in url format
or
[in]opt[,...]Additional parameters in format param=value.
RunAppleScript(script[,args]*) Run the specified AppleScript command
Parameters
[in]scriptIs the URL to the apple script
or
[in]scriptIs the addon-ID to the script add-on
or
[in]scriptIs the URL to the python script. /
Note
Set the OnlyApple template parameter to true to only attempt execution of applescripts.
RunPlugin(plugin) Runs the plugin. Full path must be specified. Does not work for folder plugins
Parameters
[in]pluginplugin:// URL to script.
RunScript(script[,args]*) Runs the python script. You must specify the full path to the script. If the script is an add-on, you can also execute it using its add-on id. As of 2007/02/24, all extra parameters are passed to the script as arguments and can be accessed by python using sys.argv
Parameters
[in]scriptIs the addon-ID to the script add-on
or
[in]scriptIs the URL to the python script.
StopScript(id) Stop the script by ID or path, if running
Parameters
[in]idThe add-on ID of the script to stop
or
[in]idThe URL of the script to stop.
UpdateAddonRepos Triggers a forced update of enabled add-on repositories.
UpdateLocalAddons Triggers a scan of local add-on directories.

Android built-in's


FunctionDescription
StartAndroidActivity(package,[intent,dataType,dataURI]) Launch an Android native app with the given package name. Optional parms (in order): intent, dataType, dataURI.
Parameters
[in]package
[in]intent(optional)
[in]datatype(optional)
[in]dataURI(optional)

Application built-in's


FunctionDescription
Extract(url [, dest]) Extracts a specified archive to an optionally specified 'absolute' path.
Parameters
[in]urlThe archive URL.
[in]destDestination path (optional).
Note
If not given, extracts to folder with archive.
Mute Mutes (or unmutes) the volume.
NotifyAll(sender, data [, json]) Notify all connected clients
Parameters
[in]senderSender.
[in]dataData.
[in]jsonJSON with extra parameters (optional).
SetVolume(percent[,showvolumebar]) Sets the volume to the percentage specified. Optionally, show the Volume Dialog in Kodi when setting the volume.
Parameters
[in]percentVolume level.
[in]showvolumebarAdd "showVolumeBar" to show volume bar (optional).
ToggleDebug Toggles debug mode on/off
ToggleDPMS Toggle DPMS mode manually
WakeOnLan(mac) Sends the wake-up packet to the broadcast address for the specified MAC address (Format: FF:FF:FF:FF:FF:FF or FF-FF-FF-FF-FF-FF).
Parameters
[in]macThe MAC of the host to wake.

CEC built-in's


FunctionDescription
CECActivateSource Wake up playing device via a CEC peripheral
CECStandby Put playing device on standby via a CEC peripheral
CECToggleState Toggle state of playing device via a CEC peripheral

GUI built-in's


FunctionDescription
Action(action[,window]) Executes an action (same as in keymap) for the given window or the active window if the parameter window is omitted. The parameter window can either be the window's id, or in the case of a standard window, the window's name. See here for a list of window names, and their respective ids.
Parameters
[in]actionAction to execute.
[in]windowWindow to send action to (optional).
CancelAlarm(name[,silent]) Cancel a running alarm. Set silent to true to hide the alarm notification.
Parameters
[in]silentSend "true" or "silent" to silently cancel alarm (optional).
AlarmClock(name,command,time[,silent,loop]) Pops up a dialog asking for the length of time for the alarm (unless the parameter time is specified), and starts a timer. When the timer runs out, it'll execute the built-in command (the parameter command) if it is specified, otherwise it'll pop up an alarm notice. Add silent to hide the alarm notification. Add loop for the alarm to execute the command each time the specified time interval expires.
Parameters
[in]namename
[in]commandcommand
[in]timeLength in seconds (optional).
[in]silentSend "silent" to suppress notifications.
[in]loopSend "loop" to loop the alarm.
ActivateWindow(window[,dir, return]) Opens the given window. The parameter window can either be the window's id, or in the case of a standard window, the window's name. See here for a list of window names, and their respective ids. If, furthermore, the window is Music, Video, Pictures, or Program files, then the optional dir parameter specifies which folder Kodi should default to once the window is opened. This must be a source as specified in sources.xml, or a subfolder of a valid source. For some windows (MusicLibrary and VideoLibrary), a third parameter (return) may be specified, which indicates that Kodi should use this folder as the "root" of the level, and thus the "parent directory" action from within this folder will return the user to where they were prior to the window activating.
Parameters
[in]windowThe window name.
[in]dirWindow starting folder (optional).
[in]returnif dir should be used as the rootfolder of the level
ActivateWindowAndFocus(id1, id2,item1, id3,item2) Activate window with id1, first focus control id2 and then focus control id3. if either of the controls is a container, you can specify which item to focus (else, set it to 0).
Parameters
[in]id1The window name.
[in]params[1,...]Pair of (container ID, focus item).
ClearProperty(key[,id]) Clears a window property for the current focused window/dialog(key), or the specified window (key,id).
Parameters
[in]keyThe property to clear.
[in]idThe window to clear property in (optional).
Dialog.Close(dialog[,force]) Close a dialog. Set force to true to bypass animations. Use (all,true) to close all opened dialogs at once.
Parameters
[in]dialogSend "all" to close all dialogs, or dialog name.
[in]forceSend "true" to force close (skip animations) (optional).
Notification(header,message[,time,image]) Will display a notification dialog with the specified header and message, in addition you can set the length of time it displays in milliseconds and a icon image.
Parameters
[in]headerNotification title.
[in]messageNotification text.
[in]timeDisplay time in milliseconds (optional).
[in]imageNotification icon (optional).
RefreshRSS Reload RSS feeds from RSSFeeds.xml
ReplaceWindow(window,dir) Replaces the current window with the given window. This is the same as ActivateWindow() but it doesn't update the window history list, so when you go back from the new window it will not return to the previous window, rather will return to the previous window's previous window.
Parameters
[in]windowThe window name.
[in]dirWindow starting folder (optional).
ReplaceWindowAndFocus(id1, id2,item1, id3,item2) Replace window with id1, first focus control id2 and then focus control id3. if either of the controls is a container, you can specify which item to focus (else, set it to 0).
Parameters
[in]id1The window name.
[in]params[1,...]Pair of (container ID, focus item).
Resolution(resIdent) Change Kodi's Resolution (default is 4x3). param[in] resIdent A resolution identifier.
Identifiers
pal pal16x9 ntsc
ntsc16x9 720p 720psbs
720ptb 1080psbs 1080ptb
1080i
SetGUILanguage(lang) Set GUI Language
Parameters
[in]langThe language to use.
SetProperty(key,value[,id]) Sets a window property for the current window (key,value), or the specified window (key,value,id).
Parameters
[in]keyThe property to set.
[in]valueThe property value.
[in]idThe window to set property in (optional).
SetStereoMode(ident) Changes the stereo mode of the GUI. Params can be: toggle, next, previous, select, tomono or any of the supported stereomodes (off, split_vertical, split_horizontal, row_interleaved, hardware_based, anaglyph_cyan_red, anaglyph_green_magenta, monoscopic)
Parameters
[in]identStereo mode identifier.
TakeScreenshot(url[,sync) Takes a Screenshot
Parameters
[in]urlURL to save file to. Blank to use default.
[in]syncAdd "sync" to run synchronously (optional).
ToggleDirtyRegionVisualization makes dirty regions visible for debugging proposes.

GUI container built-in's


FunctionDescription
Container.NextSortMethod Change to the next sort method.
Container.NextViewMode Select the next view mode.
Container.PreviousSortMethod Change to the previous sort method.
Container.PreviousViewMode Select the previous view mode.
Container.Refresh(url) Refresh current listing
Parameters
[in]urlThe URL to refresh window at.
Container.SetSortMethod(id) Change to the specified sort method. (For list of ID's see List of sort methods below)
Parameters
[in]idID of sort method.
Container.SetViewMode(id) Set the current view mode (list, icons etc.) to the given container id.
Parameters
[in]idID of view mode.
Container.SortDirection Toggle the sort direction
Container.Update(url,[replace]) Update current listing. Send Container.Update(path,replace) to reset the path history.
Parameters
[in]urlThe URL to update listing at.
[in]replace"replace" to reset history (optional).

GUI control built-in's


FunctionDescription
control.message(controlId, action[, windowId]) Send a given message to a control within a given window
Parameters
[in]controlIdID of control.
[in]actionAction name.
[in]windowIdID of window with control (optional).
control.move(id, offset) Tells the specified control to 'move' to another entry specified by offset
Parameters
[in]idID of control.
[in]offsetOffset of move.
control.setfocus(controlId[, subitemId]) Change current focus to a different control id
Parameters
[in]controlIdID of control.
[in]subitemIdID of subitem of control (optional).
[in]absolute"absolute" to focus the absolute position instead of the relative one (optional).
pagedown(controlId) Send a page down event to the pagecontrol with given id
Parameters
[in]controlIdID of control.
pageup(controlId) Send a page up event to the pagecontrol with given id
Parameters
[in]controlIdID of control.
sendclick(controlId [, windowId]) Send a click message from the given control to the given window
Parameters
[in]controlIdID of control.
[in]windowIdID for window with control (optional).
setfocus Change current focus to a different control id
Parameters
[in]controlIdID of control.
[in]subitemIdID of subitem of control (optional).
[in]absolute"absolute" to focus the absolute position instead of the relative one (optional).

Library built-in's


FunctionDescription
cleanlibrary(type) Clean the video/music library
Parameters
[in]type"video", "movies", "tvshows", "musicvideos" or "music".
exportlibrary(type [, exportSingeFile, exportThumbs, overwrite, exportActorThumbs]) Export the video/music library
Parameters
[in]type"video" or "music".
[in]exportSingleFileAdd "true" to export to separate files (optional).
[in]exportThumbsAdd "true" to export thumbs (optional).
[in]overwriteAdd "true" to overwrite existing files (optional).
[in]exportActorThumbsAdd "true" to export actor thumbs (optional).
exportlibrary2(library, exportFiletype, path [, unscraped][, overwrite][, artwork][, skipnfo] [, albums][, albumartists][, songartists][, otherartists][, actorthumbs]) Export the video/music library with extended parameters
Parameters
[in]library"video" or "music".
[in]exportFiletype"singlefile", "separate" or "library".
[in]pathPath to destination folder.
[in]unscrapedAdd "unscraped" to include unscraped items.
[in]overwriteAdd "overwrite" to overwrite exitsing files.
[in]artworkAdd "artwork" to include images such as thumbs and fanart.
[in]skipnfoAdd "skipnfo" to not include nfo files(just art).
[in]albumsAdd "ablums" to include albums.
[in]albumartistsAdd "albumartists" to include album artists.
[in]songartistsAdd "songartists" to include song artists.
[in]otherartistsAdd "otherartists" to include other artists.
[in]actorthumbsAdd "actorthumbs" to include other actor thumbs.
updatelibrary([type, suppressDialogs]) Update the selected library (music or video)
Parameters
[in]type"video" or "music".
[in]suppressDialogsAdd "true" to suppress dialogs (optional).
videolibrary.search Brings up a search dialog which will search the library

Optical container built-in's


FunctionDescription
EjectTray Either opens or closes the DVD tray, depending on its current state.
RipCD Will rip the inserted CD from the DVD-ROM drive.

Picture built-in's


FunctionDescription
RecursiveSlideShow(dir) Run a slideshow from the specified directory, including all subdirs.
Parameters
[in]dirPath to run slideshow for.
[in]randomAdd "random" to randomize slideshow (optional).
[in]notrandomAdd "notrandom" to not randomize slideshow (optional).
[in]pauseAdd "pause" to start slideshow paused (optional).
[in]beginslideAdd "beginslide=<number>" to start at a given slide (optional).
ShowPicture(picture) Display a picture by file path.
Parameters
[in]urlURL of picture.
SlideShow(dir [,recursive, [not]random]) Starts a slideshow of pictures in the folder dir. Optional parameters are recursive, and random or notrandom slideshow, adding images from sub-folders. The random and notrandom parameters override the Randomize setting found in the pictures media window.
Parameters
[in]dirPath to run slideshow for.
[in]recursiveAdd "recursive" to run a recursive slideshow (optional).
[in]randomAdd "random" to randomize slideshow (optional).
[in]notrandomAdd "notrandom" to not randomize slideshow (optional).
[in]pauseAdd "pause" to start slideshow paused (optional).
[in]beginslideAdd "beginslide=<number>" to start at a given slide (optional).

Player built-in's


FunctionDescription
PlaysDisc(parm)
PlayDVD(param)(deprecated)
Plays the inserted disc, like CD, DVD or Blu-ray, in the disc drive.
Parameters
[in]param"restart" to restart from resume point (optional)
PlayerControl(control[,param]) Allows control of music and videos.

Control Video playback behaviour Audio playback behaviour Added in
Play Play/Pause Play/Pause
Stop Stop Stop
Forward Fast Forward Fast Forward
Rewind Rewind Rewind
Next Next chapter or movie in playlists Next track
Previous Previous chapter or movie in playlists Previous track
TempoUp Increases playback speed none Kodi v18
TempoDown Decreases playback speed none Kodi v18
Tempo(n) Sets playback speed to given value none Kodi v19
BigSkipForward Big Skip Forward Big Skip Forward Kodi v15
BigSkipBackward Big Skip Backward Big Skip Backward Kodi v15
SmallSkipForward Small Skip Forward Small Skip Forward Kodi v15
SmallSkipBackward Small Skip Backward Small Skip Backward Kodi v15
SeekPercentage(n) Seeks to given percentage Seeks to given percentage
Random * Toggle Random Playback Toggle Random Playback
RandomOn Sets 'Random' to 'on' Sets 'Random' to 'on'
RandomOff Sets 'Random' to 'off' Sets 'Random' to 'off'
Repeat * Cycles through repeat modes Cycles through repeat modes
RepeatOne Repeats a single video Repeats a single track
RepeatAll Repeat all videos in a list Repeats all tracks in a list
RepeatOff Sets 'Repeat' to 'off' Sets 'Repeat' to 'off'
Partymode(music) ** none Toggles music partymode
Partymode(video) ** Toggles video partymode none
Partymode(path to .xsp) Partymode for *.xsp-file Partymode for *.xsp-file
ShowVideoMenu Shows the DVD/BR menu if available none
FrameAdvance(n) *** Advance video by n frames none Kodi v18

'*' = For these controls, the PlayerControl built-in function can make use of the 'notify'-parameter. For example: PlayerControl(random, notify)
'**' = If no argument is given for 'partymode', the control will default to music.
'***' = This only works if the player is paused.
Parameters
[in]controlControl to execute.
[in]param"notify" to notify user (optional, certain controls). /
Note
'TempoUp' or 'TempoDown' only works if "Sync playback to display" is enabled.
'Next' will behave differently while using video playlists. In those, chapters will be ignored and the next movie will be played.
Playlist.Clear Clear the current playlist
Parameters
[in](ignored)
Playlist.PlayOffset(positionType[,position]) Start playing from a particular offset in the playlist
Parameters
[in]positionTypePosition in playlist or playlist type.
[in]positionPosition in playlist if params[0] is playlist type (optional).
PlayMedia(media[,isdir][,1],[playoffset=xx]) Plays the media. This can be a playlist, music, or video file, directory, plugin or an Url. The optional parameter ",isdir" can be used for playing a directory. ",1" will start the media without switching to fullscreen. If media is a playlist, you can use playoffset=xx where xx is the position to start playback from.
Parameters
[in]mediaURL to media to play (optional).
[in]isdirSet "isdir" if media is a directory (optional).
[in]windowedSet "1" to start playback without switching to fullscreen (optional).
[in]resumeSet "resume" to force resuming (optional).
[in]noresumeSet "noresume" to force not resuming (optional).
[in]playeroffsetSet "playoffset=<offset>" to start playback from a given position in a playlist (optional).
PlayWith(core) Play the selected item with the specified player core.
Parameters
[in]coreName of playback core.
Seek(seconds) Seeks to the specified relative amount of seconds within the current playing media. A negative value will seek backward and a positive value forward.
Parameters
[in]secondsNumber of seconds to seek.

Profile built-in's


FunctionDescription
LoadProfile(profilename,[prompt]) Load the specified profile. If prompt is not specified, and a password would be required for the requested profile, this command will silently fail. If prompt is specified and a password is required, a password dialog will be shown.
Parameters
[in]profilenameThe profile name.
[in]promptAdd "prompt" to allow unlocking dialogs (optional)
Mastermode Runs Kodi in master mode
System.LogOff Log off current user.

PVR built-in's


FunctionDescription
PVR.SearchMissingChannelIcons Will start a search for missing channel icons
PVR.ToggleRecordPlayingChannel Will toggle recording on playing channel, if any
PVR.SeekPercentage Performs a seek to the given percentage in timeshift buffer, if timeshifting is supported
PVR.EpgGridControl Control PVR Guide window's EPG grid

Skin built-in's


FunctionDescription
ReloadSkin(reload) Reloads the current skin – useful for Skinners to use after they upload modified skin files (saves power cycling)
Parameters
[in]reload"confirm" to show a confirmation dialog (optional).
UnloadSkin() Unloads the current skin
Skin.Reset(setting) Resets the skin setting. If setting is a bool setting (i.e. set via SetBool or ToggleSetting) then the setting is reset to false. If setting is a string (Set via SetString, SetImage or SetPath) then it is set to empty.
Parameters
[in]settingName of setting to reset.
Skin.ResetSettings() Resets all the above skin settings to their defaults (toggles all set to false, strings all set to empty.)
Skin.SetAddon(string,type) Pops up a select dialog and allows the user to select an add-on of the given type to be used elsewhere in the skin via the info tag Skin.String(string). The most common types are xbmc.addon.video, xbmc.addon.audio, xbmc.addon.image and xbmc.addon.executable.
Parameters
[in]string[0]Skin setting to store result in.
[in]type[1,...]Add-on types to allow selecting.
Skin.SetBool(setting[,value) Sets the skin setting to true, for use with the conditional visibility tags containing Skin.HasSetting(setting). The settings are saved per-skin in settings.xml just like all the other Kodi settings.
Parameters
[in]settingName of skin setting.
[in]valueValue to set ("false", or "true") (optional).
Skin.SetFile(string,mask,folderpath) " minus quotes. If the folderpath parameter is set the file browser will start in that folder.
Parameters
[in]stringName of skin setting.
[in]maskFile mask or add-on type (optional).
[in]folderpathExtra URL to allow selection from or. content type if mask is an addon-on type (optional).
Skin.SetImage(string[,url]) Pops up a file browser and allows the user to select an image file to be used in an image control elsewhere in the skin via the info tag Skin.String(string). If the value parameter is specified, then the file browser dialog does not pop up, and the image path is set directly. The path option allows you to open the file browser in the specified folder.
Parameters
[in]stringName of skin setting.
[in]urlExtra URL to allow selection from (optional).
Skin.SetNumeric(numeric[,value]) Pops up a keyboard dialog and allows the user to input a numerical.
Parameters
[in]numericName of skin setting.
[in]valueValue of skin setting (optional).
Skin.SetPath(string[,value]) Pops up a folder browser and allows the user to select a folder of images to be used in a multi image control else where in the skin via the info tag Skin.String(string). If the value parameter is specified, then the file browser dialog does not pop up, and the path is set directly.
Parameters
[in]stringName of skin setting.
[in]valueExtra URL to allow selection from (optional).
Skin.SetString(string[,value]) Pops up a keyboard dialog and allows the user to input a string which can be used in a label control elsewhere in the skin via the info tag Skin.String(string). If the value parameter is specified, then the keyboard dialog does not pop up, and the string is set directly.
Parameters
[in]stringName of skin setting.
[in]valueValue of skin setting (optional).
Skin.Theme(cycle) Cycles the skin theme. Skin.theme(-1) will go backwards.
Parameters
[in]cycle0 or 1 to increase theme, -1 to decrease.
Skin.ToggleDebug Toggles skin debug info on/off
Skin.ToggleSetting(setting) Toggles the skin setting for use with conditional visibility tags containing Skin.HasSetting(setting).
Parameters
[in]settingSkin setting to toggle

System built-in's


FunctionDescription
ActivateScreensaver Starts the screensaver
InhibitScreensaver(yesNo) Inhibit the screensaver
Parameters
[in]yesNovalue with "true" or "false" to inhibit or allow screensaver (leaving empty defaults to false)
Hibernate Hibernate (S4) the System
InhibitIdleShutdown(true/false) Prevent the system to shutdown on idle.
Parameters
[in]value"true" to inhibit shutdown timer (optional).
Minimize Minimizes Kodi
Powerdown Powerdown system
Quit Quits Kodi
Reboot Cold reboots the system (power cycle)
Reset Reset the system (same as reboot)
Restart Restart the system (same as reboot)
RestartApp Restarts Kodi (only implemented under Windows and Linux)
ShutDown Trigger default Shutdown action defined in System Settings
Suspend Suspends (S3 / S1 depending on bios setting) the System
System.Exec(exec) Execute shell commands
Parameters
[in]execThe path to the executable
System.ExecWait(exec) Execute shell commands and freezes Kodi until shell is closed
Parameters
[in]execThe path to the executable

Weather built-in's


FunctionDescription
Weather.Refresh Force weather data refresh.
Weather.LocationNext Switch to next weather location
Weather.LocationPrevious Switch to previous weather location
Weather.LocationSet Switch to given weather location (parameter can be 1-3).
Parameters
[in]parameter1-3