Plugin sources

Plugin sources are addons 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 XBMC requires for your addon

For XBMC to know what to do with your addon, we require your script, and an addon.xml file which describes your plugin source. See addons for XBMC 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:

<extension point="xbmc.python.pluginsource"
           library="myscript.py">
  <provides>image video</provides>
</extension>

The library attribute provides the file of the python script that contains the main entry point of your script. The <provides> element is a whitespace separated list of image, video, audio, executable. There is a schema 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, we 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/<name_of_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.

The xbmcaddon module

The documentation for the xbmcaddon module may be found here <linky to auto-gen'd python docs>. The getSetting and setSetting commands may be used to store state information between calls, in addition to accessing configuration information. openSettings pops up the configuration dialog allowing the user to change the configuration of your plugin source. getString retrieves translated strings, and getAddonInfo returns pertinent information about your pluginsource should you want to display this via some other means.