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

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

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

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

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: @icode{py} .. xbmcplugin.addSortMethod(int(sys.argv[1]), xbmcplugin.SORTMETHOD_DATEADDED) .. @endicode

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

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

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