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.

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.

Function Documentation

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

◆ shutdown()

shutdown ( )

`Function: xbmc.shutdown()`

Shutdown the htpc.

Example:

..
xbmc.shutdown()
..

◆ restart()

restart ( )

`Function: xbmc.restart()`

Restart the htpc.

Example:

..
xbmc.restart()
..

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

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

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

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

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

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

getIPAddress ( )

`Function: xbmc.getIPAddress()`

Get the current ip address.

Returns: The current ip address as a string

Example:

..
ip = xbmc.getIPAddress()
..

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

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

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

◆ getDatabaseName()

getDatabaseName ( ... )

`Function: xbmc.getDatabaseName(dbType)`

Get the name of the database of the supplied type.

Parameters

dbType string - database type of the database name to be returned.

Returns: The database name currently in-use.

Note: Database type values are: addons, epg, music, textures, tv, videos, viewmodes.

v22 Python API changes: New function added.

Example:

..
video_database = xbmc.getDatabaseName('videos')
..

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

◆ stopSFX()

stopSFX ( )

`Function: xbmc.stopSFX()`

Stops wav file

v14 Python API changes: New function added.

Example:

..
xbmc.stopSFX()
..

◆ enableNavSounds()

enableNavSounds ( ... )

`Function: xbmc.enableNavSounds(yesNo)`

Enables/Disables nav sounds

Parameters

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

Example:

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

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

◆ getDevicePowerStatus()

getDevicePowerStatus ( ... )

`Function: xbmc.getDevicePowerStatus([adapterName])`

Get the power status of the device attached via HDMI-CEC.

Parameters

adapterName [opt] string - the CEC adapter to query, either its name (e.g. HDMI 1) or, for an adapter that the driver didn't name, its port. Defaults to empty, which queries the first adapter that reports a status.

Returns

int - one of the following constants:

Value	Description
xbmc.DEVICE_POWER_NO_ADAPTER	No CEC adapter present
xbmc.DEVICE_POWER_ON	Device is powered on
xbmc.DEVICE_POWER_STANDBY	Device is in standby
xbmc.DEVICE_POWER_TRANSITION_TO_ON	Device is powering on
xbmc.DEVICE_POWER_TRANSITION_TO_STANDBY	Device is going to standby
xbmc.DEVICE_POWER_UNKNOWN	Power status could not be determined

Note: This is the result of calling libCEC's GetDevicePowerStatus. DEVICE_POWER_UNKNOWN means the device could not be found or queried on the CEC bus. DEVICE_POWER_NO_ADAPTER means no CEC adapter is present, no adapter matches the given name, or the matching adapter isn't running.; The name is matched case insensitively.

v22 Python API changes: New function added.

Example:

..
if xbmc.getDevicePowerStatus() == xbmc.DEVICE_POWER_ON:
    xbmc.log('Device is on')
 
if xbmc.getDevicePowerStatus('HDMI 2') == xbmc.DEVICE_POWER_STANDBY:
    xbmc.log('The device on HDMI 2 is in standby')
..

◆ getCecAdapterNames()

getCecAdapterNames ( )

`Function: xbmc.getCecAdapterNames()`

Get the names of the HDMI-CEC adapters that are present.

Returns: list - the name of each adapter, in the form that getDevicePowerStatus accepts.

v22 Python API changes: New function added.

Example:

..
for adapter in xbmc.getCecAdapterNames():
    xbmc.log(f'{adapter}: {xbmc.getDevicePowerStatus(adapter)}')
..

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

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

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

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

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

◆ audioSuspend()

audioSuspend ( )

`Function: xbmc.audioSuspend()`

Suspend Audio engine.

Example:

..
xbmc.audioSuspend()
..

◆ audioResume()

audioResume ( )

`Function: xbmc.audioResume()`

Resume Audio engine.

Example:

..
xbmc.audioResume()
..

◆ 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

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

Detailed Description

Topics

Function Documentation

◆ log()

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

◆ shutdown()

Function: xbmc.shutdown()

◆ restart()

Function: xbmc.restart()

◆ executescript()

Function: xbmc.executescript(script)

◆ executebuiltin()

Function: xbmc.executebuiltin(function)

◆ executeJSONRPC()

Function: xbmc.executeJSONRPC(jsonrpccommand)

◆ sleep()

Function: xbmc.sleep(time)

◆ getLocalizedString()

Function: xbmc.getLocalizedString(id)

◆ getSkinDir()

Function: xbmc.getSkinDir()

◆ getLanguage()

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

◆ getIPAddress()

Function: xbmc.getIPAddress()

◆ getDVDState()

Function: xbmc.getDVDState()

◆ getFreeMem()

Function: xbmc.getFreeMem()

◆ getInfoLabel()

Function: xbmc.getInfoLabel(infotag)

◆ getInfoImage()

Function: xbmc.getInfoImage(infotag)

◆ getDatabaseName()

Function: xbmc.getDatabaseName(dbType)

◆ playSFX()

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

◆ stopSFX()

Function: xbmc.stopSFX()

◆ enableNavSounds()

Function: xbmc.enableNavSounds(yesNo)

◆ getCondVisibility()

Function: xbmc.getCondVisibility(condition)

◆ getGlobalIdleTime()

Function: xbmc.getGlobalIdleTime()

◆ getDevicePowerStatus()

Function: xbmc.getDevicePowerStatus([adapterName])

◆ getCecAdapterNames()

Function: xbmc.getCecAdapterNames()

◆ getCacheThumbName()

Function: xbmc.getCacheThumbName(path)

◆ getCleanMovieTitle()

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

◆ getRegion()

Function: xbmc.getRegion(id)

◆ getSupportedMedia()

Function: xbmc.getSupportedMedia(media)

◆ skinHasImage()

Function: xbmc.skinHasImage(image)

◆ startServer()

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

◆ audioSuspend()

Function: xbmc.audioSuspend()

◆ audioResume()

Function: xbmc.audioResume()

◆ getUserAgent()

Function: xbmc.getUserAgent()

◆ convertLanguage()

Function: xbmc.convertLanguage(language, format)

`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.getDatabaseName(dbType)`

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

`Function: xbmc.stopSFX()`

`Function: xbmc.enableNavSounds(yesNo)`

`Function: xbmc.getCondVisibility(condition)`

`Function: xbmc.getGlobalIdleTime()`

`Function: xbmc.getDevicePowerStatus([adapterName])`

`Function: xbmc.getCecAdapterNames()`

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