Plugin sources

Plugin sources are add-ons for XBMC that provide a media listing for the user. They are currently written in python, and can provide video, music, image or executable content. Once a user installs your plugin source, it will automatically show up in the appropriate section(s) within XBMC based on the content it provides.

Basic overview
When the user clicks on your plugin source, your python script gets called, allowing you to fetch a listing of media and return it for XBMC to display. You may return either media items directly (for immediate playback) or may return folder items that contain links back into your plugin source. When the user clicks on a media item it'll start playing straight away, just like any other media. When the user clicks on a folder that you provide, your script will be called again with information on what folder item was clicked on given in the arguments. You may then return a different listing of media content and folders as required.

What Kodi requires for your add-on
For XBMC to know what to do with your add-on, we require your script, and an addon.xml file which describes your plugin source. See here for more information on addon.xml, including how you add descriptions to your addon for users. A plugin source extends XBMC via the xbmc.python.pluginsource extension point. The layout of the XML describing this extension point is as follows:

The library attribute provides the file of the python script that contains the main entry point of your script. The element is a whitespace separated list of image, video, audio, executable. There is a schema available here to check you have your XML correctly defined.

Interacting with XBMC
The main form of interacting with XBMC will be parsing what XBMC feeds you in terms of arguments to your scripts to find out what "folder" the user wants to retrieve, and then returning items to XBMC as you construct them. Given that your script can return information to the user, you may wish to allow some (or all) of the information you provide to be translatable. You do this by providing a strings.xml file (in resources/language//strings.xml) which associates integer id's with each label. XBMC then handles loading these string files and ensuring that the users' locale information is taken into account. To display strings you use the getString function in the xbmcaddon module.

Your script only runs while it's retrieving a listing - once it has finished the listing it is terminated. Thus, if you wish to store state information, you can do so either in the URLs you return to XBMC (for different folders for instance) or by storing information in a settings file. In addition, you may have particular configuration settings for your addon which can also be accessed via the settings functions in the xbmcaddon module.

If your plugin can provide several content types, xbmc will pass a 'content_type' parameter to the plugin when listing the root directory. This can be used to only return content of the requested type.