Library - xbmc

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) xbmc.ISO_NAME Language name in English without qualifiers, "English" rather than "English (Australia)"
region	[opt] append the region delimited by "-" of the language (setting) to the returned language string. The ISO 639 formats name the region as an ISO 3166-1 code, uppercase, for example en-AU

Returns

The active language as a string, or an empty string where the language has no code in the requested format. The region is never returned on its own, so the result is empty rather than a bare -AU.

Note

Not every language has an ISO 639-1 code - Filipino and Asturian are two that do not - so xbmc.ISO_639_2 answers for more languages than xbmc.ISO_639_1.

---

v13 Python API changes

Added new options format and region.

v22 Python API changes

Added the xbmc.ISO_NAME format. A language with no code in the requested format returns an empty string; previously the region could be returned on its own.

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), three letter code (ISO 639-2/T(B), or a BCP 47 language tag
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) xbmc.ISO_NAME Language name in English without qualifiers, "English" rather than "English (Australia)"

Returns

Converted Language string, or an empty string where the language is not recognized or has no code in the requested format

Note

Not every language has an ISO 639-1 code, so xbmc.ISO_639_2 answers for more languages than xbmc.ISO_639_1.

---

v13 Python API changes

New function added.

v22 Python API changes

A BCP 47 tag is accepted as input, for example en-AU, which the stream language functions of Player return. Added the xbmc.ISO_NAME format.

Example:

..
language = xbmc.convertLanguage(English, xbmc.ISO_639_2)
..