Kodi Documentation 18.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 (...)
 
 shutdown ()
 
 restart ()
 
 executescript (...)
 
 executebuiltin (...)
 
 executeJSONRPC (...)
 
 sleep (...)
 
 getLocalizedString (...)
 
 getSkinDir ()
 
 getLanguage (...)
 
 getIPAddress ()
 
 getDVDState ()
 
 getFreeMem ()
 
 getInfoLabel (...)
 
 getInfoImage (...)
 
 playSFX (...)
 
 stopSFX ()
 
 enableNavSounds (...)
 
 getCondVisibility (...)
 
 getGlobalIdleTime ()
 
 getCacheThumbName (...)
 
 makeLegalFilename (...)
 
 translatePath (...)
 
 getCleanMovieTitle (...)
 
 validatePath (...)
 
 getRegion (...)
 
 getSupportedMedia (...)
 
 skinHasImage (...)
 
 startServer (...)
 
 audioSuspend ()
 
 audioResume ()
 
 getUserAgent ()
 Returns Kodi's HTTP UserAgent string. More...
 
 convertLanguage (...)
 Returns the given language converted to the given format as a string. 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 ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.audioResume() </big></font></span></code></h4> \endhtmlonly

Resume Audio engine.


Example:

..
xbmc.audioResume()
..

◆ audioSuspend()

audioSuspend ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.audioSuspend() </big></font></span></code></h4> \endhtmlonly

Suspend Audio engine.


Example:

..
xbmc.audioSuspend()
..

◆ convertLanguage()

convertLanguage (   ...)

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.convertLanguage(language, format) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.enableNavSounds(yesNo) </big></font></span></code></h4> \endhtmlonly

Enables/Disables nav sounds

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

Example:

..
xbmc.enableNavSounds(True)
..

◆ executebuiltin()

executebuiltin (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.executebuiltin(function) </big></font></span></code></h4> \endhtmlonly

Execute a built in Kodi function.

Parameters
functionstring - builtin function to execute.

List of functions - http://kodi.wiki/view/List_of_Built_In_Functions


Example:

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

◆ executeJSONRPC()

executeJSONRPC (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.executeJSONRPC(jsonrpccommand) </big></font></span></code></h4> \endhtmlonly

Execute an JSONRPC command.

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

List of commands -


Example:

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

◆ executescript()

executescript (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.executescript(script) </big></font></span></code></h4> \endhtmlonly

Execute a python script.

Parameters
scriptstring - script filename to execute.

Example:

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

◆ getCacheThumbName()

getCacheThumbName (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getCacheThumbName(path) </big></font></span></code></h4> \endhtmlonly

Get thumb cache filename.

Parameters
pathstring or unicode - path to file
Returns
Thumb cache filename

Example:

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

◆ getCleanMovieTitle()

getCleanMovieTitle (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getCleanMovieTitle(path[, usefoldername]) </big></font></span></code></h4> \endhtmlonly

Get clean movie title and year string if available.

Parameters
pathstring or unicode - 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 (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getCondVisibility(condition) </big></font></span></code></h4> \endhtmlonly

Get visibility conditions

Parameters
conditionstring - condition to check
Returns
True (1) or False (0) as a bool

List of Conditions - http://kodi.wiki/view/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 ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getDVDState() </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getFreeMem() </big></font></span></code></h4> \endhtmlonly

Get amount of free memory in MB.

Returns
The amount of free memory in MB as an integer

Example:

..
freemem = xbmc.getFreeMem()
..

◆ getGlobalIdleTime()

getGlobalIdleTime ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getGlobalIdleTime() </big></font></span></code></h4> \endhtmlonly

Get the elapsed idle time in seconds.

Returns
Elapsed idle time in seconds as an integer

Example:

..
t = xbmc.getGlobalIdleTime()
..

◆ getInfoImage()

getInfoImage (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getInfoImage(infotag) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getInfoLabel(infotag) </big></font></span></code></h4> \endhtmlonly

Get a info label

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

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


Example:

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

◆ getIPAddress()

getIPAddress ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getIPAddress() </big></font></span></code></h4> \endhtmlonly

Get the current ip address.

Returns
The current ip address as a string

Example:

..
ip = xbmc.getIPAddress()
..

◆ getLanguage()

getLanguage (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getLanguage([format], [region]) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getLocalizedString(id) </big></font></span></code></h4> \endhtmlonly

Get a localized 'unicode string'.

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

Example:

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

◆ getRegion()

getRegion (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getRegion(id) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getSkinDir() </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getSupportedMedia(media) </big></font></span></code></h4> \endhtmlonly

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

Returns Kodi's HTTP UserAgent string.

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.getUserAgent() </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.log(msg[, level]) </big></font></span></code></h4> \endhtmlonly

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.LOGNOTICE Similar to INFO but the average Joe might want to know about these events. This level and above are logged by default.
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
You can use the above as keywords for arguments and skip certain optional arguments. Once you use a keyword, all following arguments require the keyword.

Text is written to the log for the following conditions.

  • loglevel == -1 (NONE, nothing at all is logged)
  • loglevel == 0 (NORMAL, shows LOGNOTICE, LOGERROR, LOGSEVERE and LOGFATAL)
  • loglevel == 1 (DEBUG, shows all) See pydocs for valid values for level.

v17 Python API changes:
Default level changed from LOGNOTICE to LOGDEBUG

Example:

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

◆ makeLegalFilename()

makeLegalFilename (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.makeLegalFilename(filename[, fatX]) </big></font></span></code></h4> \endhtmlonly

Returns a legal filename or path as a string.

Parameters
filenamestring or unicode - filename/path to make legal
fatX[opt] bool - True=Xbox file system(Default)
Returns
Legal filename or path as a string
Note
If fatX is true you should pass a full path. If fatX is false only pass the basename of the path.

You can use the above as keywords for arguments and skip certain optional arguments. Once you use a keyword, all following arguments require the keyword.

Example:

..
filename = xbmc.makeLegalFilename('F:\\Trailers\\Ice Age: The Meltdown.avi')
..

◆ playSFX()

playSFX (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.playSFX(filename,[useCached]) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.restart() </big></font></span></code></h4> \endhtmlonly

Restart the htpc.


Example:

..
xbmc.restart()
..

◆ shutdown()

shutdown ( )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.Shutdown() </big></font></span></code></h4> \endhtmlonly

Shutdown the htpc.


Example:

..
xbmc.shutdown()
..

◆ skinHasImage()

skinHasImage (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.skinHasImage(image) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.sleep(time) </big></font></span></code></h4> \endhtmlonly

Sleeps for 'time' msec.

Parameters
timeinteger - number of msec to sleep.
Exceptions
PyExc_TypeErrorIf time is not an integer.
Note
This is useful if you have for example a Player class that is waiting for onPlayBackEnded() calls.

Example:

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

◆ startServer()

startServer (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.startServer(typ, bStart, bWait) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.stopSFX() </big></font></span></code></h4> \endhtmlonly

Stops wav file


v14 Python API changes:
New function added.

Example:

..
xbmc.stopSFX()
..

◆ translatePath()

translatePath (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.translatePath(path) </big></font></span></code></h4> \endhtmlonly

Returns the translated path.

Parameters
pathstring or unicode - Path to format
Returns
Translated path
Note
Only useful if you are coding for both Linux and Windows. e.g. Converts 'special://masterprofile/script_data' -> '/home/user/XBMC/UserData/script_data' on Linux.

Example:

..
fpath = xbmc.translatePath('special://masterprofile/script_data')
..

◆ validatePath()

validatePath (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmc.validatePath(path) </big></font></span></code></h4> \endhtmlonly

Returns the validated path.

Parameters
pathstring or unicode - Path to format
Returns
Validated path
Note
Only useful if you are coding for both Linux and Windows for fixing slash problems. e.g. Corrects 'Z://something' -> 'Z:\something'

Example:

..
fpath = xbmc.validatePath(somepath)
..