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

	makeLegalFilename (...)
	`Function: xbmc.makeLegalFilename(filename[, fatX])` Returns a legal filename or path as a string. 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...

	validatePath (...)
	`Function: xbmc.validatePath(path)` Returns the validated path. 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

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

List of functions - http://kodi.wiki/view/List_of_Built_In_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

List of commands -

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

`Function: xbmc.getCondVisibility(condition)`

Get visibility conditions

Parameters

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

`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 - http://kodi.wiki/view/InfoLabels

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

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

`Function: xbmc.makeLegalFilename(filename[, fatX])`

Returns a legal filename or path as a string.

Parameters

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

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

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

`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

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

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

`Function: xbmc.validatePath(path)`

Returns the validated path.

Parameters

path	string 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:'

Example:

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

Modules

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.makeLegalFilename(filename[, fatX])

Function: xbmc.translatePath(path)

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

Function: xbmc.validatePath(path)

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.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.makeLegalFilename(filename[, fatX])`

`Function: xbmc.translatePath(path)`

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

`Function: xbmc.validatePath(path)`

`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.makeLegalFilename(filename[, fatX])`

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

`Function: xbmc.translatePath(path)`

`Function: xbmc.validatePath(path)`