Kodi Development  20.0
for Binary and Script based Add-Ons
Library - xbmcplugin

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
handleinteger - handle the plugin was started with.
urlstring - url of the entry. would be plugin:// for another virtual directory
listitemListItem - 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
handleinteger - handle the plugin was started with.
itemsList - 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
..

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

◆ setResolvedUrl()

setResolvedUrl (   ...)

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


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

Parameters
handleinteger - handle the plugin was started with.
succeededbool - True=script completed successfully/False=Script did not.
listitemListItem - item the file plugin resolved to for playback.

Example:

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

◆ addSortMethod()

addSortMethod (   ...)

Function: xbmcplugin.addSortMethod(handle, sortMethod [,labelMask, label2Mask])


Adds a sorting method for the media list.

@param handle integer - handle the plugin was started with. @param sortMethod integer - see available sort methods at the bottom (or see \ref List_of_sort_methods "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 @param 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 @param label2Mask [opt] string - the label mask to use for the second label. Defaults to %Dttapplies 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. \xrefitem python_v13 14. \xrefitem python_v17 18. \xrefitem python_v19 31. Example: @code{py} .. xbmcplugin.addSortMethod(int(sys.argv[1]), xbmcplugin.SORTMETHOD_DATEADDED) .. @endcode

◆ getSetting()

getSetting (   ...)

Function: xbmcplugin.getSetting(handle, id)


Returns the value of a setting as a string.

Parameters
handleinteger - handle the plugin was started with.
idstring - 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')
..

◆ setSetting()

setSetting (   ...)

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


Sets a plugin setting for the current running plugin.

Parameters
handleinteger - handle the plugin was started with.
idstring - id of the setting that the module needs to access.
valuestring or unicode - value of the setting.

Example:

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

◆ setContent()

setContent (   ...)

Function: xbmcplugin.setContent(handle, content)


Sets the plugins content.

Parameters
handleinteger - handle the plugin was started with.
contentstring - 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
handleinteger - handle the plugin was started with.
categorystring 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
handleinteger - 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
handleinteger - handle the plugin was started with.
keystring - property name.
valuestring or unicode - value of property.
Note
Key is NOT case sensitive.

Example:

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