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.
◆ log()
Function: xbmc.log(msg[, level])
Write a string to Kodi's log file and the debug window.
- Parameters
-
msg | string - 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()
Function: xbmc.shutdown()
Shutdown the htpc.
Example:
◆ restart()
Function: xbmc.restart()
Restart the htpc.
Example:
◆ executescript()
Function: xbmc.executescript(script)
Execute a python script.
- Parameters
-
script | string - script filename to execute. |
Example:
..
xbmc.executescript('special://home/scripts/update.py')
..
◆ executebuiltin()
Function: xbmc.executebuiltin(function)
Execute a built in Kodi function.
- Parameters
-
function | string - 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()
Function: xbmc.executeJSONRPC(jsonrpccommand)
Execute an JSONRPC command.
- Parameters
-
jsonrpccommand | string - jsonrpc command to execute. |
- Returns
- jsonrpc return string
Example:
..
response = xbmc.executeJSONRPC('{ "jsonrpc": "2.0", "method": "JSONRPC.Introspect", "id": 1 }')
..
◆ sleep()
Function: xbmc.sleep(time)
Sleeps for 'time' (msec).
- Parameters
-
time | integer - number of msec to sleep. |
- Exceptions
-
PyExc_TypeError | If 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:
◆ getLocalizedString()
getLocalizedString |
( |
|
... | ) |
|
Function: xbmc.getLocalizedString(id)
Get a localized 'unicode string'.
- Parameters
-
id | integer - 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()
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()
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()
Function: xbmc.getIPAddress()
Get the current ip address.
- Returns
- The current ip address as a string
Example:
..
ip = xbmc.getIPAddress()
..
◆ 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()
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()
Function: xbmc.getInfoLabel(infotag)
Get a info label
- Parameters
-
infotag | string - infoTag for value you want returned. |
- Returns
- InfoLabel as a string
List of InfoTags
Example:
..
label = xbmc.getInfoLabel('Weather.Conditions')
..
◆ getInfoImage()
Function: xbmc.getInfoImage(infotag)
Get filename including path to the InfoImage's thumbnail.
- Parameters
-
infotag | string - 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()
Function: xbmc.playSFX(filename,[useCached])
Plays a wav file by filename
- Parameters
-
filename | string - 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()
◆ enableNavSounds()
Function: xbmc.enableNavSounds(yesNo)
Enables/Disables nav sounds
- Parameters
-
yesNo | bool - enable (True) or disable (False) nav sounds |
Example:
..
xbmc.enableNavSounds(True)
..
◆ getCondVisibility()
Function: xbmc.getCondVisibility(condition)
Get visibility conditions
- Parameters
-
condition | string - 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()
Function: xbmc.getGlobalIdleTime()
Get the elapsed idle time in seconds.
- Returns
- Elapsed idle time in seconds as an integer
Example:
..
t = xbmc.getGlobalIdleTime()
..
◆ getCacheThumbName()
Function: xbmc.getCacheThumbName(path)
Get thumb cache filename.
- Parameters
-
path | string - 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
-
path | string - 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()
Function: xbmc.getRegion(id)
Returns your regions setting as a string for the specified id.
- Parameters
-
id | string - 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()
Function: xbmc.getSupportedMedia(media)
Get the supported file types for the specific media.
- Parameters
-
- 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()
Function: xbmc.skinHasImage(image)
Check skin for presence of Image.
- Parameters
-
image | string - 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()
Function: xbmc.startServer(typ, bStart, bWait)
Start or stop a server.
- Parameters
-
typ | integer - use SERVER_* constants
- Used format of the returned language string
|
bStart | bool - 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()
Function: xbmc.audioSuspend()
Suspend Audio engine.
Example:
..
xbmc.audioSuspend()
..
◆ audioResume()
Function: xbmc.audioResume()
Resume Audio engine.
Example:
◆ 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()
Function: xbmc.convertLanguage(language, format)
Returns the given language converted to the given format as a string.
- Parameters
-
language | string either as name in English, two letter code (ISO 639-1), or three letter code (ISO 639-2/T(B) |
format | 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) |
|
- Returns
- Converted Language string
- v13 Python API changes:
- New function added.
Example:
..
language = xbmc.convertLanguage(English, xbmc.ISO_639_2)
..