General functions on Kodi. More...

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

	VideoStreamDetail
	Video stream details class used in combination with InfoTagVideo.

	AudioStreamDetail
	Audio stream details class used in combination with InfoTagVideo.

	SubtitleStreamDetail
	Subtitle stream details class used in combination with InfoTagVideo.

	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.

	shutdown ()
	`Function: xbmc.shutdown()` Shutdown the htpc.

	restart ()
	`Function: xbmc.restart()` Restart the htpc.

	executescript (...)
	`Function: xbmc.executescript(script)` Execute a python script.

	executebuiltin (...)
	`Function: xbmc.executebuiltin(function)` Execute a built in Kodi function.

	executeJSONRPC (...)
	`Function: xbmc.executeJSONRPC(jsonrpccommand)` Execute an JSONRPC command.

	sleep (...)
	`Function: xbmc.sleep(time)` Sleeps for 'time' (msec).

	getLocalizedString (...)
	`Function: xbmc.getLocalizedString(id)` Get a localized 'unicode string'.

	getSkinDir ()
	`Function: xbmc.getSkinDir()` Get the active skin directory.

	getLanguage (...)
	`Function: xbmc.getLanguage([format], [region])` Get the active language.

	getIPAddress ()
	`Function: xbmc.getIPAddress()` Get the current ip address.

	getDVDState ()
	`Function: xbmc.getDVDState()` Returns the dvd state as an integer.

	getFreeMem ()
	`Function: xbmc.getFreeMem()` Get amount of free memory in MB.

	getInfoLabel (...)
	`Function: xbmc.getInfoLabel(infotag)` Get a info label

	getInfoImage (...)
	`Function: xbmc.getInfoImage(infotag)` Get filename including path to the InfoImage's thumbnail.

	playSFX (...)
	`Function: xbmc.playSFX(filename,[useCached])` Plays a wav file by filename

	stopSFX ()
	`Function: xbmc.stopSFX()` Stops wav file

	enableNavSounds (...)
	`Function: xbmc.enableNavSounds(yesNo)` Enables/Disables nav sounds

	getCondVisibility (...)
	`Function: xbmc.getCondVisibility(condition)` Get visibility conditions

	getGlobalIdleTime ()
	`Function: xbmc.getGlobalIdleTime()` Get the elapsed idle time in seconds.

	getCacheThumbName (...)
	`Function: xbmc.getCacheThumbName(path)` Get thumb cache filename.

	getCleanMovieTitle (...)
	`Function: xbmc.getCleanMovieTitle(path[, usefoldername])` Get clean movie title and year string if available.

	getRegion (...)
	`Function: xbmc.getRegion(id)` Returns your regions setting as a string for the specified id.

	getSupportedMedia (...)
	`Function: xbmc.getSupportedMedia(media)` Get the supported file types for the specific media.

	skinHasImage (...)
	`Function: xbmc.skinHasImage(image)` Check skin for presence of Image.

	startServer (...)
	`Function: xbmc.startServer(typ, bStart, bWait)` Start or stop a server.

	audioSuspend ()
	`Function: xbmc.audioSuspend()` Suspend Audio engine.

	audioResume ()
	`Function: xbmc.audioResume()` Resume Audio engine.

	getUserAgent ()
	`Function: xbmc.getUserAgent()`

	convertLanguage (...)
	`Function: xbmc.convertLanguage(language, format)`

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

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

◆ enableNavSounds()

enableNavSounds ( ... )

`Function: xbmc.enableNavSounds(yesNo)`

Enables/Disables nav sounds

Parameters

yesNo bool - enable (True) or disable (False) nav sounds

Example:

..
xbmc.enableNavSounds(True)
..

◆ executebuiltin()

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

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

◆ executescript()

executescript ( ... )

`Function: xbmc.executescript(script)`

Execute a python script.

Parameters

script string - script filename to execute.

Example:

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

◆ getCacheThumbName()

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

◆ getCondVisibility()

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

◆ 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

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

◆ getInfoLabel()

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

◆ 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

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

◆ getRegion()

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, datelongraw, dateshortraw, timeraw) You can use the above as keywords for arguments.

Warning: an empty string is returned if the provided Id is not supported

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

media string - 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

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

◆ playSFX()

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

◆ 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

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

◆ sleep()

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

typ

integer - use SERVER_* constants

Used format of the returned language string

Value	Description
xbmc.SERVER_WEBSERVER	To control Kodi's builtin webserver
xbmc.SERVER_AIRPLAYSERVER	AirPlay is a proprietary protocol stack/suite developed by Apple Inc.
xbmc.SERVER_JSONRPCSERVER	Control JSON-RPC HTTP/TCP socket-based interface
xbmc.SERVER_UPNPRENDERER	UPnP client (aka UPnP renderer)
xbmc.SERVER_UPNPSERVER	Control built-in UPnP A/V media server (UPnP-server)
xbmc.SERVER_EVENTSERVER	Set eventServer part that accepts remote device input on all platforms
xbmc.SERVER_ZEROCONF	Control Kodi's Avahi Zeroconf

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

◆ stopSFX()

stopSFX ( )

`Function: xbmc.stopSFX()`

Stops wav file

v14 Python API changes: New function added.

Example:

..
xbmc.stopSFX()
..

Topics

Functions

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

Function: xbmc.shutdown()

Function: xbmc.restart()

Function: xbmc.executescript(script)

Function: xbmc.executebuiltin(function)

Function: xbmc.executeJSONRPC(jsonrpccommand)

Function: xbmc.sleep(time)

Function: xbmc.getLocalizedString(id)

Function: xbmc.getSkinDir()

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

Function: xbmc.getIPAddress()

Function: xbmc.getDVDState()

Function: xbmc.getFreeMem()

Function: xbmc.getInfoLabel(infotag)

Function: xbmc.getInfoImage(infotag)

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

Function: xbmc.stopSFX()

Function: xbmc.enableNavSounds(yesNo)

Function: xbmc.getCondVisibility(condition)

Function: xbmc.getGlobalIdleTime()

Function: xbmc.getCacheThumbName(path)

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

Function: xbmc.getRegion(id)

Function: xbmc.getSupportedMedia(media)

Function: xbmc.skinHasImage(image)

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

Function: xbmc.audioSuspend()

Function: xbmc.audioResume()

Function: xbmc.getUserAgent()

Function: xbmc.convertLanguage(language, format)

Detailed Description

Function Documentation

◆ audioResume()

Function: xbmc.audioResume()

◆ audioSuspend()

Function: xbmc.audioSuspend()

◆ convertLanguage()

Function: xbmc.convertLanguage(language, format)

◆ enableNavSounds()

Function: xbmc.enableNavSounds(yesNo)

◆ executebuiltin()

Function: xbmc.executebuiltin(function)

◆ executeJSONRPC()

Function: xbmc.executeJSONRPC(jsonrpccommand)

◆ executescript()

Function: xbmc.executescript(script)

◆ getCacheThumbName()

Function: xbmc.getCacheThumbName(path)

◆ getCleanMovieTitle()

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

◆ getCondVisibility()

Function: xbmc.getCondVisibility(condition)

◆ getDVDState()

Function: xbmc.getDVDState()

◆ getFreeMem()

Function: xbmc.getFreeMem()

◆ getGlobalIdleTime()

Function: xbmc.getGlobalIdleTime()

◆ getInfoImage()

Function: xbmc.getInfoImage(infotag)

◆ getInfoLabel()

Function: xbmc.getInfoLabel(infotag)

◆ getIPAddress()

Function: xbmc.getIPAddress()

◆ getLanguage()

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

◆ getLocalizedString()

Function: xbmc.getLocalizedString(id)

◆ getRegion()

Function: xbmc.getRegion(id)

◆ getSkinDir()

Function: xbmc.getSkinDir()

◆ getSupportedMedia()

Function: xbmc.getSupportedMedia(media)

◆ getUserAgent()

Function: xbmc.getUserAgent()

◆ log()

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

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

`Function: xbmc.shutdown()`

`Function: xbmc.restart()`

`Function: xbmc.executescript(script)`

`Function: xbmc.executebuiltin(function)`

`Function: xbmc.executeJSONRPC(jsonrpccommand)`

`Function: xbmc.sleep(time)`

`Function: xbmc.getLocalizedString(id)`

`Function: xbmc.getSkinDir()`

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

`Function: xbmc.getIPAddress()`

`Function: xbmc.getDVDState()`

`Function: xbmc.getFreeMem()`

`Function: xbmc.getInfoLabel(infotag)`

`Function: xbmc.getInfoImage(infotag)`

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

`Function: xbmc.stopSFX()`

`Function: xbmc.enableNavSounds(yesNo)`

`Function: xbmc.getCondVisibility(condition)`

`Function: xbmc.getGlobalIdleTime()`

`Function: xbmc.getCacheThumbName(path)`

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

`Function: xbmc.getRegion(id)`

`Function: xbmc.getSupportedMedia(media)`

`Function: xbmc.skinHasImage(image)`

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

`Function: xbmc.audioSuspend()`

`Function: xbmc.audioResume()`

`Function: xbmc.getUserAgent()`

`Function: xbmc.convertLanguage(language, format)`

`Function: xbmc.audioResume()`

`Function: xbmc.audioSuspend()`

`Function: xbmc.convertLanguage(language, format)`

`Function: xbmc.enableNavSounds(yesNo)`

`Function: xbmc.executebuiltin(function)`

`Function: xbmc.executeJSONRPC(jsonrpccommand)`

`Function: xbmc.executescript(script)`

`Function: xbmc.getCacheThumbName(path)`

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

`Function: xbmc.getCondVisibility(condition)`

`Function: xbmc.getDVDState()`

`Function: xbmc.getFreeMem()`

`Function: xbmc.getGlobalIdleTime()`

`Function: xbmc.getInfoImage(infotag)`

`Function: xbmc.getInfoLabel(infotag)`

`Function: xbmc.getIPAddress()`

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

`Function: xbmc.getLocalizedString(id)`

`Function: xbmc.getRegion(id)`

`Function: xbmc.getSkinDir()`

`Function: xbmc.getSupportedMedia(media)`

`Function: xbmc.getUserAgent()`

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

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

`Function: xbmc.restart()`

`Function: xbmc.shutdown()`

`Function: xbmc.skinHasImage(image)`

`Function: xbmc.sleep(time)`

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

`Function: xbmc.stopSFX()`