Kodi Development  20.0
for Binary and Script based Add-Ons
Library - xbmc

Detailed Description

General functions on Kodi.

Offers classes and functions that provide information about the media currently playing and that allow manipulation of the media player (such as starting a new song). You can also find system information using the functions available in this library.

Modules

 InfoTagGame
 Kodi's game info tag class.
 
 InfoTagMusic
 Kodi's music info tag class.
 
 InfoTagPicture
 Kodi's picture info tag class.
 
 InfoTagRadioRDS
 Kodi's radio RDS info tag class.
 
 Actor
 Actor class used in combination with InfoTagVideo.
 
 Keyboard
 Kodi's keyboard class.
 
 Monitor
 Kodi's monitor class.
 
 Player
 Kodi's player.
 
 PlayList
 Kodi's Play List class.
 
 RenderCapture
 Kodi's render capture.
 

Function Documentation

◆ log()

log (   ...)

Function: xbmc.log(msg[, level])


Write a string to Kodi's log file and the debug window.

Parameters
msgstring - text to output.
level[opt] integer - log level to output at. (default=LOGDEBUG)
Value: Description:
xbmc.LOGDEBUG In depth information about the status of Kodi. This information can pretty much only be deciphered by a developer or long time Kodi power user.
xbmc.LOGINFO Something has happened. It's not a problem, we just thought you might want to know. Fairly excessive output that most people won't care about.
xbmc.LOGWARNING Something potentially bad has happened. If Kodi did something you didn't expect, this is probably why. Watch for errors to follow.
xbmc.LOGERROR This event is bad. Something has failed. You likely noticed problems with the application be it skin artifacts, failure of playback a crash, etc.
xbmc.LOGFATAL We're screwed. Kodi is about to crash.
Note
Addon developers are advised to keep LOGDEBUG as the default logging level and to use conservative logging (log only if needed). Excessive logging makes it harder to debug kodi itself.

Logging in kodi has a global configuration level that controls how text is written to the log. This global logging behaviour can be changed in the GUI (Settings -> System -> Logging) (debug toggle) or furthered configured in advancedsettings (loglevel setting).

Text is written to the log for the following conditions:

  • loglevel == -1 (NONE, nothing at all is logged to the log)
  • loglevel == 0 (NORMAL, shows LOGINFO, LOGWARNING, LOGERROR and LOGFATAL) - Default kodi behaviour
  • loglevel == 1 (DEBUG, shows all) - Behaviour if you toggle debug log in the GUI

v17 Python API changes:
Default level changed from LOGNOTICE to LOGDEBUG
v19 Python API changes:
Removed LOGNOTICE (use LOGINFO) and LOGSEVERE (use LOGFATAL)

Example:

..
xbmc.log(msg='This is a test string.', level=xbmc.LOGDEBUG);
..

◆ shutdown()

shutdown ( )

Function: xbmc.shutdown()


Shutdown the htpc.


Example:

..
xbmc.shutdown()
..

◆ restart()

restart ( )

Function: xbmc.restart()


Restart the htpc.


Example:

..
xbmc.restart()
..

◆ executescript()

executescript (   ...)

Function: xbmc.executescript(script)


Execute a python script.

Parameters
scriptstring - script filename to execute.

Example:

..
xbmc.executescript('special://home/scripts/update.py')
..

◆ executebuiltin()

executebuiltin (   ...)

Function: xbmc.executebuiltin(function)


Execute a built in Kodi function.

Parameters
functionstring - builtin function to execute.
wait[opt] bool - If Kodi should wait for the builtin function execution to finish (default False)

List of builtin functions


Example:

..
xbmc.executebuiltin('Skin.SetString(abc,def)')
..

◆ executeJSONRPC()

executeJSONRPC (   ...)

Function: xbmc.executeJSONRPC(jsonrpccommand)


Execute an JSONRPC command.

Parameters
jsonrpccommandstring - jsonrpc command to execute.
Returns
jsonrpc return string

Example:

..
response = xbmc.executeJSONRPC('{ "jsonrpc": "2.0", "method": "JSONRPC.Introspect", "id": 1 }')
..

◆ sleep()

sleep (   ...)

Function: xbmc.sleep(time)


Sleeps for 'time' (msec).

Parameters
timeinteger - number of msec to sleep.
Exceptions
PyExc_TypeErrorIf time is not an integer.
Warning
This is useful if you need to sleep for a small amount of time (milisecond range) somewhere in your addon logic. Please note that Kodi will attempt to stop any running scripts when signaled to exit and wait for a maximum of 5 seconds before trying to force stop your script. If your addon makes use of xbmc.sleep() incorrectly (long periods of time, e.g. that exceed the force stop waiting time) it may lead to Kodi hanging on shutdown. In case your addon needs long sleep/idle periods use xbmc.Monitor().waitForAbort(secs) instead.

Example:

..
xbmc.sleep(2000) # sleeps for 2 seconds
..

◆ getLocalizedString()

getLocalizedString (   ...)

Function: xbmc.getLocalizedString(id)


Get a localized 'unicode string'.

Parameters
idinteger - id# for string you want to localize.
Returns
Localized 'unicode string'
Note
See strings.po in \language\{yourlanguage}\ for which id you need for a string.

Example:

..
locstr = xbmc.getLocalizedString(6)
..

◆ getSkinDir()

getSkinDir ( )

Function: xbmc.getSkinDir()


Get the active skin directory.

Returns
The active skin directory as a string
Note
This is not the full path like 'special://home/addons/MediaCenter', but only 'MediaCenter'.

Example:

..
skindir = xbmc.getSkinDir()
..

◆ getLanguage()

getLanguage (   ...)

Function: xbmc.getLanguage([format], [region])


Get the active language.

Parameters
format[opt] format of the returned language string
Value Description
xbmc.ISO_639_1 Two letter code as defined in ISO 639-1
xbmc.ISO_639_2 Three letter code as defined in ISO 639-2/T or ISO 639-2/B
xbmc.ENGLISH_NAME Full language name in English (default)
region[opt] append the region delimited by "-" of the language (setting) to the returned language string
Returns
The active language as a string

v13 Python API changes:
Added new options format and region.

Example:

..
language = xbmc.getLanguage(xbmc.ENGLISH_NAME)
..

◆ getIPAddress()

getIPAddress ( )

Function: xbmc.getIPAddress()


Get the current ip address.

Returns
The current ip address as a string

Example:

..
ip = xbmc.getIPAddress()
..

◆ getDVDState()

getDVDState ( )

Function: xbmc.getDVDState()


Returns the dvd state as an integer.

Returns
Values for state are:
Value Name
1 xbmc.DRIVE_NOT_READY
16 xbmc.TRAY_OPEN
64 xbmc.TRAY_CLOSED_NO_MEDIA
96 xbmc.TRAY_CLOSED_MEDIA_PRESENT

Example:

..
dvdstate = xbmc.getDVDState()
..

◆ getFreeMem()

getFreeMem ( )

Function: xbmc.getFreeMem()


Get amount of free memory in MB.

Returns
The amount of free memory in MB as an integer

Example:

..
freemem = xbmc.getFreeMem()
..

◆ getInfoLabel()

getInfoLabel (   ...)

Function: xbmc.getInfoLabel(infotag)


Get a info label

Parameters
infotagstring - infoTag for value you want returned.
Returns
InfoLabel as a string

List of InfoTags


Example:

..
label = xbmc.getInfoLabel('Weather.Conditions')
..

◆ getInfoImage()

getInfoImage (   ...)

Function: xbmc.getInfoImage(infotag)


Get filename including path to the InfoImage's thumbnail.

Parameters
infotagstring - infotag for value you want returned
Returns
Filename including path to the InfoImage's thumbnail as a string

List of InfoTags - http://kodi.wiki/view/InfoLabels


Example:

..
filename = xbmc.getInfoImage('Weather.Conditions')
..

◆ playSFX()

playSFX (   ...)

Function: xbmc.playSFX(filename,[useCached])


Plays a wav file by filename

Parameters
filenamestring - filename of the wav file to play
useCached[opt] bool - False = Dump any previously cached wav associated with filename

v14 Python API changes:
Added new option useCached.

Example:

..
xbmc.playSFX('special://xbmc/scripts/dingdong.wav')
xbmc.playSFX('special://xbmc/scripts/dingdong.wav',False)
..

◆ stopSFX()

stopSFX ( )

Function: xbmc.stopSFX()


Stops wav file


v14 Python API changes:
New function added.

Example:

..
xbmc.stopSFX()
..

◆ enableNavSounds()

enableNavSounds (   ...)

Function: xbmc.enableNavSounds(yesNo)


Enables/Disables nav sounds

Parameters
yesNobool - enable (True) or disable (False) nav sounds

Example:

..
xbmc.enableNavSounds(True)
..

◆ getCondVisibility()

getCondVisibility (   ...)

Function: xbmc.getCondVisibility(condition)


Get visibility conditions

Parameters
conditionstring - condition to check
Returns
True (if the condition is verified) or False (otherwise)

List of boolean conditions

Note
You can combine two (or more) of the above settings by using "+" as an AND operator, "|" as an OR operator, "!" as a NOT operator, and "[" and "]" to bracket expressions.

Example:

..
visible = xbmc.getCondVisibility('[Control.IsVisible(41) + !Control.IsVisible(12)]')
..

◆ getGlobalIdleTime()

getGlobalIdleTime ( )

Function: xbmc.getGlobalIdleTime()


Get the elapsed idle time in seconds.

Returns
Elapsed idle time in seconds as an integer

Example:

..
t = xbmc.getGlobalIdleTime()
..

◆ getCacheThumbName()

getCacheThumbName (   ...)

Function: xbmc.getCacheThumbName(path)


Get thumb cache filename.

Parameters
pathstring - path to file
Returns
Thumb cache filename

Example:

..
thumb = xbmc.getCacheThumbName('f:\\videos\\movie.avi')
..

◆ getCleanMovieTitle()

getCleanMovieTitle (   ...)

Function: xbmc.getCleanMovieTitle(path[, usefoldername])


Get clean movie title and year string if available.

Parameters
pathstring - String to clean
usefoldername[opt] bool - use folder names (defaults to false)
Returns
Clean movie title and year string if available.

Example:

..
title, year = xbmc.getCleanMovieTitle('/path/to/moviefolder/test.avi', True)
..

◆ getRegion()

getRegion (   ...)

Function: xbmc.getRegion(id)


Returns your regions setting as a string for the specified id.

Parameters
idstring - id of setting to return
Returns
Region setting
Note
choices are (dateshort, datelong, time, meridiem, tempunit, speedunit) You can use the above as keywords for arguments.

Example:

..
date_long_format = xbmc.getRegion('datelong')
..

◆ getSupportedMedia()

getSupportedMedia (   ...)

Function: xbmc.getSupportedMedia(media)


Get the supported file types for the specific media.

Parameters
mediastring - media type
Returns
Supported file types for the specific media as a string
Note
Media type can be (video, music, picture). The return value is a pipe separated string of filetypes (eg. '.mov |.avi').
You can use the above as keywords for arguments.

Example:

..
mTypes = xbmc.getSupportedMedia('video')
..

◆ skinHasImage()

skinHasImage (   ...)

Function: xbmc.skinHasImage(image)


Check skin for presence of Image.

Parameters
imagestring - image filename
Returns
True if the image file exists in the skin
Note
If the media resides in a subfolder include it. (eg. home-myfiles\home-myfiles2.png). You can use the above as keywords for arguments.

Example:

..
exists = xbmc.skinHasImage('ButtonFocusedTexture.png')
..

◆ startServer()

startServer (   ...)

Function: xbmc.startServer(typ, bStart, bWait)


Start or stop a server.

Parameters
typinteger - use SERVER_* constants
bStartbool - start (True) or stop (False) a server
Returns
bool - True or False

v20 Python API changes:
Removed option bWait.

Example:

..
xbmc.startServer(xbmc.SERVER_AIRPLAYSERVER, False)
..

◆ audioSuspend()

audioSuspend ( )

Function: xbmc.audioSuspend()


Suspend Audio engine.


Example:

..
xbmc.audioSuspend()
..

◆ audioResume()

audioResume ( )

Function: xbmc.audioResume()


Resume Audio engine.


Example:

..
xbmc.audioResume()
..

◆ getUserAgent()

getUserAgent ( )

Function: xbmc.getUserAgent()


Returns Kodi's HTTP UserAgent string

Returns
HTTP user agent

Example:

..
xbmc.getUserAgent()
..

example output: Kodi/17.0-ALPHA1 (X11; Linux x86_64) Ubuntu/15.10 App_Bitness/64 Version/17.0-ALPHA1-Git:2015-12-23-5770d28

◆ convertLanguage()

convertLanguage (   ...)

Function: xbmc.convertLanguage(language, format)


Returns the given language converted to the given format as a string.

Parameters
languagestring either as name in English, two letter code (ISO 639-1), or three letter code (ISO 639-2/T(B)
formatformat of the returned language string
Value Description
xbmc.ISO_639_1 Two letter code as defined in ISO 639-1
xbmc.ISO_639_2 Three letter code as defined in ISO 639-2/T or ISO 639-2/B
xbmc.ENGLISH_NAME Full language name in English (default)
Returns
Converted Language string

v13 Python API changes:
New function added.

Example:

..
language = xbmc.convertLanguage(English, xbmc.ISO_639_2)
..