Kodi Documentation 18.0
Kodi is an open source media player and entertainment hub.
Functions
Library - xbmcplugin
Python

Plugin functions on Kodi. More...

Functions

 addDirectoryItem (...)
 
 addDirectoryItems (...)
 
 endOfDirectory (...)
 
 setResolvedUrl (...)
 
 addSortMethod (...)
 
 getSetting (...)
 
 setSetting (...)
 
 setContent (...)
 
 setPluginCategory (...)
 
 setPluginFanart (...)
 
 setProperty (...)
 

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.addDirectoryItem(handle, url, listitem [,isFolder, totalItems]) </big></font></span></code></h4> \endhtmlonly

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

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

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

◆ 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 [,label2Mask]) </big></font></span></code></h4> \endhtmlonly

Adds a sorting method for the media list.

Parameters
handleinteger - handle the plugin was started with.
sortMethodinteger - see available sort methods at the bottom (or see SortFileItem.h).
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
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.

Example:

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

◆ endOfDirectory()

endOfDirectory (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.endOfDirectory(handle[, succeeded, updateListing, cacheToDisc]) </big></font></span></code></h4> \endhtmlonly

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

◆ getSetting()

getSetting (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.getSetting(handle, id) </big></font></span></code></h4> \endhtmlonly

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

◆ setContent()

setContent (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.setContent(handle, content) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.setPluginCategory(handle, category) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.setPluginFanart(handle, image, color1, color2, color3) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.setProperty(handle, key, value) </big></font></span></code></h4> \endhtmlonly

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

◆ setResolvedUrl()

setResolvedUrl (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.setResolvedUrl(handle, succeeded, listitem) </big></font></span></code></h4> \endhtmlonly

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

◆ setSetting()

setSetting (   ...)

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> xbmcplugin.setSetting(handle, id, value) </big></font></span></code></h4> \endhtmlonly

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