Plugin functions on Kodi. More...

Functions
	addDirectoryItem (...)
	`Function: xbmcplugin.addDirectoryItem(handle, url, listitem [,isFolder, totalItems])` Callback function to pass directory contents back to Kodi. More...

	addDirectoryItems (...)
	`Function: xbmcplugin.addDirectoryItems(handle, items[, totalItems])` Callback function to pass directory contents back to Kodi as a list. More...

	endOfDirectory (...)
	`Function: xbmcplugin.endOfDirectory(handle[, succeeded, updateListing, cacheToDisc])` Callback function to tell Kodi that the end of the directory listing in a virtualPythonFolder module is reached. More...

	setResolvedUrl (...)
	`Function: xbmcplugin.setResolvedUrl(handle, succeeded, listitem)` Callback function to tell Kodi that the file plugin has been resolved to a url More...

	addSortMethod (...)

	getSetting (...)
	`Function: xbmcplugin.getSetting(handle, id)` Returns the value of a setting as a string. More...

	setSetting (...)
	`Function: xbmcplugin.setSetting(handle, id, value)` Sets a plugin setting for the current running plugin. More...

	setContent (...)
	`Function: xbmcplugin.setContent(handle, content)` Sets the plugins content. More...

	setPluginCategory (...)
	`Function: xbmcplugin.setPluginCategory(handle, category)` Sets the plugins name for skins to display. More...

	setPluginFanart (...)
	`Function: xbmcplugin.setPluginFanart(handle, image, color1, color2, color3)` Sets the plugins fanart and color for skins to display. More...

	setProperty (...)
	`Function: xbmcplugin.setProperty(handle, key, value)` Sets a container property for this plugin. More...

Detailed Description

Plugin functions on Kodi.

Offers classes and functions that allow a developer to present information through Kodi's standard menu structure. While plugins don't have the same flexibility as scripts, they boast significantly quicker development time and a more consistent user experience.

Function Documentation

◆ addDirectoryItem()

addDirectoryItem ( ... )

`Function: xbmcplugin.addDirectoryItem(handle, url, listitem [,isFolder, totalItems])`

Callback function to pass directory contents back to Kodi.

Parameters

handle	integer - handle the plugin was started with.
url	string - url of the entry. would be `plugin://` for another virtual directory
listitem	ListItem - item to add.
isFolder	[opt] bool - True=folder / False=not a folder(default).
totalItems	[opt] integer - total number of items that will be passed.(used for progressbar)

Returns: Returns a bool for successful completion.

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.

Example:

..
if not xbmcplugin.addDirectoryItem(int(sys.argv[1]), 'F:\\Trailers\\300.mov', listitem, totalItems=50): break
..

◆ addDirectoryItems()

addDirectoryItems ( ... )

`Function: xbmcplugin.addDirectoryItems(handle, items[, totalItems])`

Callback function to pass directory contents back to Kodi as a list.

Parameters

handle	integer - handle the plugin was started with.
items	List - list of (url, listitem[, isFolder]) as a tuple to add.
totalItems	[opt] integer - total number of items that will be passed.(used for progressbar)

Returns: Returns a bool for successful completion.

Remarks: Large lists benefit over using the standard addDirectoryItem(). You may call this more than once to add items in chunks.

Example:

..
if not xbmcplugin.addDirectoryItems(int(sys.argv[1]), [(url, listitem, False,)]: raise
..

◆ addSortMethod()

addSortMethod ( ... )

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.addSortMethod(handle, sortMethod [,labelMask, label2Mask]) </big></font></span></code></h4><hr> \endhtmlonly

Adds a sorting method for the media list.

Parameters

handle integer - handle the plugin was started with.

sortMethod

integer - see available sort methods at the bottom (or see SortUtils).

Value	Description
xbmcplugin.SORT_METHOD_NONE	Do not sort
xbmcplugin.SORT_METHOD_LABEL	Sort by label
xbmcplugin.SORT_METHOD_LABEL_IGNORE_THE	Sort by the label and ignore "The" before
xbmcplugin.SORT_METHOD_DATE	Sort by the date
xbmcplugin.SORT_METHOD_SIZE	Sort by the size
xbmcplugin.SORT_METHOD_FILE	Sort by the file
xbmcplugin.SORT_METHOD_DRIVE_TYPE	Sort by the drive type
xbmcplugin.SORT_METHOD_TRACKNUM	Sort by the track number
xbmcplugin.SORT_METHOD_DURATION	Sort by the duration
xbmcplugin.SORT_METHOD_TITLE	Sort by the title
xbmcplugin.SORT_METHOD_TITLE_IGNORE_THE	Sort by the title and ignore "The" before
xbmcplugin.SORT_METHOD_ARTIST	Sort by the artist
xbmcplugin.SORT_METHOD_ARTIST_IGNORE_THE	Sort by the artist and ignore "The" before
xbmcplugin.SORT_METHOD_ALBUM	Sort by the album
xbmcplugin.SORT_METHOD_ALBUM_IGNORE_THE	Sort by the album and ignore "The" before
xbmcplugin.SORT_METHOD_GENRE	Sort by the genre
xbmcplugin.SORT_SORT_METHOD_VIDEO_YEAR, xbmcplugin.SORT_METHOD_YEAR	Sort by the year
xbmcplugin.SORT_METHOD_VIDEO_RATING	Sort by the video rating
xbmcplugin.SORT_METHOD_PROGRAM_COUNT	Sort by the program count
xbmcplugin.SORT_METHOD_PLAYLIST_ORDER	Sort by the playlist order
xbmcplugin.SORT_METHOD_EPISODE	Sort by the episode
xbmcplugin.SORT_METHOD_VIDEO_TITLE	Sort by the video title
xbmcplugin.SORT_METHOD_VIDEO_SORT_TITLE	Sort by the video sort title
xbmcplugin.SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE	Sort by the video sort title and ignore "The" before
xbmcplugin.SORT_METHOD_PRODUCTIONCODE	Sort by the production code
xbmcplugin.SORT_METHOD_SONG_RATING	Sort by the song rating
xbmcplugin.SORT_METHOD_MPAA_RATING	Sort by the mpaa rating
xbmcplugin.SORT_METHOD_VIDEO_RUNTIME	Sort by video runtime
xbmcplugin.SORT_METHOD_STUDIO	Sort by the studio
xbmcplugin.SORT_METHOD_STUDIO_IGNORE_THE	Sort by the studio and ignore "The" before
xbmcplugin.SORT_METHOD_UNSORTED	Use list not sorted
xbmcplugin.SORT_METHOD_BITRATE	Sort by the bitrate
xbmcplugin.SORT_METHOD_LISTENERS	Sort by the listeners
xbmcplugin.SORT_METHOD_COUNTRY	Sort by the country
xbmcplugin.SORT_METHOD_DATEADDED	Sort by the added date
xbmcplugin.SORT_METHOD_FULLPATH	Sort by the full path name
xbmcplugin.SORT_METHOD_LABEL_IGNORE_FOLDERS	Sort by the label names and ignore related folder names
xbmcplugin.SORT_METHOD_LASTPLAYED	Sort by last played date
xbmcplugin.SORT_METHOD_PLAYCOUNT	Sort by the play count
xbmcplugin.SORT_METHOD_CHANNEL	Sort by the channel
xbmcplugin.SORT_METHOD_DATE_TAKEN	Sort by the taken date
xbmcplugin.SORT_METHOD_VIDEO_USER_RATING	Sort by the rating of the user of video
xbmcplugin.SORT_METHOD_SONG_USER_RATING	Sort by the rating of the user of song

labelMask

[opt] string - the label mask to use for the first label.

applies to:

sortMethod	labelMask
SORT_METHOD_TRACKNUM	Defaults to `[%N. ]%T`
SORT_METHOD_EPISODE	Defaults to `%H. %T`
SORT_METHOD_PRODUCTIONCODE	Defaults to `%H. %T`
All other sort methods	Defaults to `%T`

label2Mask

[opt] string - the label mask to use for the second label. Defaults to %D

applies to:


SORT_METHOD_NONE	SORT_METHOD_UNSORTED	SORT_METHOD_VIDEO_TITLE
SORT_METHOD_TRACKNUM	SORT_METHOD_FILE	SORT_METHOD_TITLE
SORT_METHOD_TITLE_IGNORE_THE	SORT_METHOD_LABEL	SORT_METHOD_LABEL_IGNORE_THE
SORT_METHOD_VIDEO_SORT_TITLE	SORT_METHOD_FULLPATH	SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE
SORT_METHOD_LABEL_IGNORE_FOLDERS	SORT_METHOD_CHANNEL

Note: to add multiple sort methods just call the method multiple times.

v13 Python API changes:: Added new sort SORT_METHOD_DATE_TAKEN, SORT_METHOD_COUNTRY, SORT_METHOD_DATEADDED, SORT_METHOD_FULLPATH, SORT_METHOD_LABEL_IGNORE_FOLDERS, SORT_METHOD_LASTPLAYED, SORT_METHOD_PLAYCOUNT, SORT_METHOD_CHANNEL.

v17 Python API changes:: Added new sort SORT_METHOD_VIDEO_USER_RATING.

v19 Python API changes:: Added new option labelMask.

Example:

..
xbmcplugin.addSortMethod(int(sys.argv[1]), xbmcplugin.SORTMETHOD_DATEADDED)
..

◆ endOfDirectory()

endOfDirectory ( ... )

`Function: xbmcplugin.endOfDirectory(handle[, succeeded, updateListing, cacheToDisc])`

Callback function to tell Kodi that the end of the directory listing in a virtualPythonFolder module is reached.

Parameters

handle	integer - handle the plugin was started with.
succeeded	[opt] bool - True=script completed successfully(Default)/False=Script did not.
updateListing	[opt] bool - True=this folder should update the current listing/False=Folder is a subfolder(Default).
cacheToDisc	[opt] bool - True=Folder will cache if extended time(default)/False=this folder will never cache to disc.

Example:

..
xbmcplugin.endOfDirectory(int(sys.argv[1]), cacheToDisc=False)
..

◆ getSetting()

getSetting ( ... )

`Function: xbmcplugin.getSetting(handle, id)`

Returns the value of a setting as a string.

Parameters

handle	integer - handle the plugin was started with.
id	string - id of the setting that the module needs to access.

Returns: Setting value as string

Note: You can use the above as a keyword.

Example:

..
apikey = xbmcplugin.getSetting(int(sys.argv[1]), 'apikey')
..

◆ setContent()

setContent ( ... )

`Function: xbmcplugin.setContent(handle, content)`

Sets the plugins content.

Parameters

handle	integer - handle the plugin was started with.
content	string - content type (eg. movies)

Available content strings


files	songs	artists	albums
movies	tvshows	episodes	musicvideos
videos	images	games	–

Remarks: Use videos for all videos which do not apply to the more specific mentioned ones like "movies", "episodes" etc. A good example is youtube.

v18 Python API changes:: Added new games content

Example:

..
xbmcplugin.setContent(int(sys.argv[1]), 'movies')
..

◆ setPluginCategory()

setPluginCategory ( ... )

`Function: xbmcplugin.setPluginCategory(handle, category)`

Sets the plugins name for skins to display.

Parameters

handle	integer - handle the plugin was started with.
category	string or unicode - plugins sub category.

Example:

..
xbmcplugin.setPluginCategory(int(sys.argv[1]), 'Comedy')
..

◆ setPluginFanart()

setPluginFanart ( ... )

`Function: xbmcplugin.setPluginFanart(handle, image, color1, color2, color3)`

Sets the plugins fanart and color for skins to display.

Parameters

handle	integer - handle the plugin was started with.
image	[opt] string - path to fanart image.
color1	[opt] hexstring - color1. (e.g. '0xFFFFFFFF')
color2	[opt] hexstring - color2. (e.g. '0xFFFF3300')
color3	[opt] hexstring - color3. (e.g. '0xFF000000')

Example:

..
xbmcplugin.setPluginFanart(int(sys.argv[1]), 'special://home/addons/plugins/video/Apple movie trailers II/fanart.png', color2='0xFFFF3300')
..

◆ setProperty()

setProperty ( ... )

`Function: xbmcplugin.setProperty(handle, key, value)`

Sets a container property for this plugin.

Parameters

handle	integer - handle the plugin was started with.
key	string - property name.
value	string or unicode - value of property.

Note: Key is NOT case sensitive.

Example:

..
xbmcplugin.setProperty(int(sys.argv[1]), 'Emulator', 'M.A.M.E.')
..

◆ setResolvedUrl()

setResolvedUrl ( ... )

`Function: xbmcplugin.setResolvedUrl(handle, succeeded, listitem)`

Callback function to tell Kodi that the file plugin has been resolved to a url

Parameters

handle	integer - handle the plugin was started with.
succeeded	bool - True=script completed successfully/False=Script did not.
listitem	ListItem - item the file plugin resolved to for playback.

Example:

..
xbmcplugin.setResolvedUrl(int(sys.argv[1]), True, listitem)
..

◆ setSetting()

setSetting ( ... )

`Function: xbmcplugin.setSetting(handle, id, value)`

Sets a plugin setting for the current running plugin.

Parameters

handle	integer - handle the plugin was started with.
id	string - id of the setting that the module needs to access.
value	string or unicode - value of the setting.

Example:

..
xbmcplugin.setSetting(int(sys.argv[1]), id='username', value='teamxbmc')
..

Functions

Function: xbmcplugin.addDirectoryItem(handle, url, listitem [,isFolder, totalItems])

Function: xbmcplugin.addDirectoryItems(handle, items[, totalItems])

Function: xbmcplugin.endOfDirectory(handle[, succeeded, updateListing, cacheToDisc])

Function: xbmcplugin.setResolvedUrl(handle, succeeded, listitem)

Function: xbmcplugin.getSetting(handle, id)

Function: xbmcplugin.setSetting(handle, id, value)

Function: xbmcplugin.setContent(handle, content)

Function: xbmcplugin.setPluginCategory(handle, category)

Function: xbmcplugin.setPluginFanart(handle, image, color1, color2, color3)

Function: xbmcplugin.setProperty(handle, key, value)

Detailed Description

Function Documentation

◆ addDirectoryItem()

Function: xbmcplugin.addDirectoryItem(handle, url, listitem [,isFolder, totalItems])

◆ addDirectoryItems()

Function: xbmcplugin.addDirectoryItems(handle, items[, totalItems])

◆ addSortMethod()

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.addSortMethod(handle, sortMethod [,labelMask, label2Mask]) </big></font></span></code></h4><hr> \endhtmlonly

◆ endOfDirectory()

Function: xbmcplugin.endOfDirectory(handle[, succeeded, updateListing, cacheToDisc])

◆ getSetting()

Function: xbmcplugin.getSetting(handle, id)

◆ setContent()

Function: xbmcplugin.setContent(handle, content)

◆ setPluginCategory()

Function: xbmcplugin.setPluginCategory(handle, category)

◆ setPluginFanart()

Function: xbmcplugin.setPluginFanart(handle, image, color1, color2, color3)

◆ setProperty()

Function: xbmcplugin.setProperty(handle, key, value)

◆ setResolvedUrl()

Function: xbmcplugin.setResolvedUrl(handle, succeeded, listitem)

◆ setSetting()

Function: xbmcplugin.setSetting(handle, id, value)

`Function: xbmcplugin.addDirectoryItem(handle, url, listitem [,isFolder, totalItems])`

`Function: xbmcplugin.addDirectoryItems(handle, items[, totalItems])`

`Function: xbmcplugin.endOfDirectory(handle[, succeeded, updateListing, cacheToDisc])`

`Function: xbmcplugin.setResolvedUrl(handle, succeeded, listitem)`

`Function: xbmcplugin.getSetting(handle, id)`

`Function: xbmcplugin.setSetting(handle, id, value)`

`Function: xbmcplugin.setContent(handle, content)`

`Function: xbmcplugin.setPluginCategory(handle, category)`

`Function: xbmcplugin.setPluginFanart(handle, image, color1, color2, color3)`

`Function: xbmcplugin.setProperty(handle, key, value)`

`Function: xbmcplugin.addDirectoryItem(handle, url, listitem [,isFolder, totalItems])`

`Function: xbmcplugin.addDirectoryItems(handle, items[, totalItems])`

`Function: xbmcplugin.endOfDirectory(handle[, succeeded, updateListing, cacheToDisc])`

`Function: xbmcplugin.getSetting(handle, id)`

`Function: xbmcplugin.setContent(handle, content)`

`Function: xbmcplugin.setPluginCategory(handle, category)`

`Function: xbmcplugin.setPluginFanart(handle, image, color1, color2, color3)`

`Function: xbmcplugin.setProperty(handle, key, value)`

`Function: xbmcplugin.setResolvedUrl(handle, succeeded, listitem)`

`Function: xbmcplugin.setSetting(handle, id, value)`