Kodi Documentation  19.0
Kodi is an open source media player and entertainment hub.
Library - xbmc

General functions on Kodi. More...

Modules

 InfoTagMusic
 Kodi's music info tag class.
 
 InfoTagRadioRDS
 Kodi's radio RDS info tag class.
 
 InfoTagVideo
 Kodi's video info tag class.
 
 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.
 

Functions

 log (...)
 

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


Write a string to Kodi's log file and the debug window. More...
 
 shutdown ()
 

Function: xbmc.shutdown()


Shutdown the htpc. More...
 
 restart ()
 

Function: xbmc.restart()


Restart the htpc. More...
 
 executescript (...)
 

Function: xbmc.executescript(script)


Execute a python script. More...
 
 executebuiltin (...)
 

Function: xbmc.executebuiltin(function)


Execute a built in Kodi function. More...
 
 executeJSONRPC (...)
 

Function: xbmc.executeJSONRPC(jsonrpccommand)


Execute an JSONRPC command. More...
 
 sleep (...)
 

Function: xbmc.sleep(time)


Sleeps for 'time' (msec). More...
 
 getLocalizedString (...)
 

Function: xbmc.getLocalizedString(id)


Get a localized 'unicode string'. More...
 
 getSkinDir ()
 

Function: xbmc.getSkinDir()


Get the active skin directory. More...
 
 getLanguage (...)
 

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


Get the active language. More...
 
 getIPAddress ()
 

Function: xbmc.getIPAddress()


Get the current ip address. More...
 
 getDVDState ()
 

Function: xbmc.getDVDState()


Returns the dvd state as an integer. More...
 
 getFreeMem ()
 

Function: xbmc.getFreeMem()


Get amount of free memory in MB. More...
 
 getInfoLabel (...)
 

Function: xbmc.getInfoLabel(infotag)


Get a info label More...
 
 getInfoImage (...)
 

Function: xbmc.getInfoImage(infotag)


Get filename including path to the InfoImage's thumbnail. More...
 
 playSFX (...)
 

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


Plays a wav file by filename More...
 
 stopSFX ()
 

Function: xbmc.stopSFX()


Stops wav file More...
 
 enableNavSounds (...)
 

Function: xbmc.enableNavSounds(yesNo)


Enables/Disables nav sounds More...
 
 getCondVisibility (...)
 

Function: xbmc.getCondVisibility(condition)


Get visibility conditions More...
 
 getGlobalIdleTime ()
 

Function: xbmc.getGlobalIdleTime()


Get the elapsed idle time in seconds. More...
 
 getCacheThumbName (...)
 

Function: xbmc.getCacheThumbName(path)


Get thumb cache filename. More...
 
 translatePath (...)
 

Function: xbmc.translatePath(path)


Returns the translated path. More...
 
 getCleanMovieTitle (...)
 

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


Get clean movie title and year string if available. More...
 
 getRegion (...)
 

Function: xbmc.getRegion(id)


Returns your regions setting as a string for the specified id. More...
 
 getSupportedMedia (...)
 

Function: xbmc.getSupportedMedia(media)


Get the supported file types for the specific media. More...
 
 skinHasImage (...)
 

Function: xbmc.skinHasImage(image)


Check skin for presence of Image. More...
 
 startServer (...)
 

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


Start or stop a server. More...
 
 audioSuspend ()
 

Function: xbmc.audioSuspend()


Suspend Audio engine. More...
 
 audioResume ()
 

Function: xbmc.audioResume()


Resume Audio engine. More...
 
 getUserAgent ()
 

Function: xbmc.getUserAgent()


More...
 
 convertLanguage (...)
 

Function: xbmc.convertLanguage(language, format)


More...
 

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.

Function Documentation

§ audioResume()

audioResume ( )

Function: xbmc.audioResume()


Resume Audio engine.


Example:

..
xbmc.audioResume()
..

§ audioSuspend()

audioSuspend ( )

Function: xbmc.audioSuspend()


Suspend Audio engine.


Example:

..
xbmc.audioSuspend()
..

§ 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)
..

§ enableNavSounds()

enableNavSounds (   ...)

Function: xbmc.enableNavSounds(yesNo)


Enables/Disables nav sounds

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

Example:

..
xbmc.enableNavSounds(True)
..

§ executebuiltin()

executebuiltin (   ...)

Function: xbmc.executebuiltin(function)


Execute a built in Kodi function.

Parameters
functionstring - builtin function to execute.

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 }')
..

§ executescript()

executescript (   ...)

Function: xbmc.executescript(script)


Execute a python script.

Parameters
scriptstring - script filename to execute.

Example:

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

§ 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)
..

§ 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)]')
..

§ 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()
..

§ 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()
..

§ 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')
..

§ 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')
..

§ getIPAddress()

getIPAddress ( )

Function: xbmc.getIPAddress()


Get the current ip address.

Returns
The current ip address as a string

Example:

..
ip = xbmc.getIPAddress()
..

§ 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)
..

§ 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)
..

§ 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')
..

§ 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()
..

§ 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')
..

§ 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

§ 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);
..

§ 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)
..

§ restart()

restart ( )

Function: xbmc.restart()


Restart the htpc.


Example:

..
xbmc.restart()
..

§ shutdown()

shutdown ( )

Function: xbmc.shutdown()


Shutdown the htpc.


Example:

..
xbmc.shutdown()
..

§ 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')
..

§ 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
..

§ 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
bWait[opt] bool - wait on stop before returning (not supported by all servers)
Returns
bool - True or False

Example:

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

§ stopSFX()

stopSFX ( )

Function: xbmc.stopSFX()


Stops wav file


v14 Python API changes:
New function added.

Example:

..
xbmc.stopSFX()
..

§ translatePath()

translatePath (   ...)

Function: xbmc.translatePath(path)


Returns the translated path.

Parameters
pathstring - Path to format
Returns
Translated path
Note
Only useful if you are coding for both Linux and Windows. e.g. Converts 'special://home' -> '/home/[username]/.kodi' on Linux.

v19 Python API changes:
Deprecated xbmc.translatePath. Moved to xbmcvfs.translatePath

Example:

..
fpath = xbmc.translatePath('special://home')
..