xbmcplugin

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.

Functions

addDirectoryItem(handle, url, listitem[, ...])

Callback function to pass directory contents back to Kodi.

addDirectoryItems(handle, items[, totalItems])

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

addSortMethod(handle, sortMethod[, ...])

@brief python_func{ xbmcplugin.addSortMethod(handle, sortMethod [,labelMask, label2Mask]) }Adds a sorting method for the media list.

endOfDirectory(handle[, succeeded, ...])

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

getSetting(handle, id)

Returns the value of a setting as a string.

setContent(handle, content)

Sets the plugins content.

setPluginCategory(handle, category)

Sets the plugins name for skins to display.

setPluginFanart(handle[, image, color1, ...])

Sets the plugins fanart and color for skins to display.

setProperty(handle, key, value)

Sets a container property for this plugin.

setResolvedUrl(handle, succeeded, listitem)

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

setSetting(handle, id, value)

Sets a plugin setting for the current running plugin.
xbmcplugin.addDirectoryItem(handle: int, url: str, listitem: xbmcgui.ListItem, isFolder: bool = False, totalItems: int = 0) → bool[source]

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
..
xbmcplugin.addDirectoryItems(handle: int, items: List[Tuple[str, xbmcgui.ListItem, bool]], totalItems: int = 0) → bool[source]

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.

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
..
xbmcplugin.endOfDirectory(handle: int, succeeded: bool = True, updateListing: bool = False, cacheToDisc: bool = True) → None[source]

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)
..
xbmcplugin.setResolvedUrl(handle: int, succeeded: bool, listitem: xbmcgui.ListItem) → None[source]

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)
..
xbmcplugin.addSortMethod(handle: int, sortMethod: int, labelMask: str = '', label2Mask: str = '') → None[source]

@brief python_func{ xbmcplugin.addSortMethod(handle, sortMethod [,labelMask, label2Mask]) }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
Parameters:

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``
Parameters:

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.

@python_v13 Added new sort SORT_METHOD_DATE_TAKEN, SORT_METHOD_COU NTRY, SORT_METHOD_DATEADDED, SORT_METHOD_FULLPATH, SORT_METHO D_LABEL_IGNORE_FOLDERS, SORT_METHOD_LASTPLAYED, SORT_METHOD_PLAY COUNT, SORT_METHOD_CHANNEL.

@python_v17 Added new sort SORT_METHOD_VIDEO_USER_RATING.

@python_v19 Added new option labelMask.

Example:

..
xbmcplugin.addSortMethod(int(sys.argv[1]), xbmcplugin.SORTMETHOD_DATEADDED)
..
xbmcplugin.getSetting(handle: int, id: str) → str[source]

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')
..
xbmcplugin.setSetting(handle: int, id: str, value: str) → None[source]

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')
..
xbmcplugin.setContent(handle: int, content: str) → None[source]

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

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

@python_v18 Added new games contentExample:

..
xbmcplugin.setContent(int(sys.argv[1]), 'movies')
..
xbmcplugin.setPluginCategory(handle: int, category: str) → None[source]

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')
..
xbmcplugin.setPluginFanart(handle: int, image: str | None = None, color1: str | None = None, color2: str | None = None, color3: str | None = None) → None[source]

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')
..
xbmcplugin.setProperty(handle: int, key: str, value: str) → None[source]

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