Structure and Lifecycle of an xbmc add-on

Introduction

We will start by writing video addons. Video add-ons expose programming available on the web, through a set of menus which display sub-menus or launch a video.

Add-on Lifecycle

An add-on is a standalone Python program, which is launched whenever a user clicks on your addon's icon. The following arguments are set when the program is launched:

• sys.argv[0]: the executable path to your icon (in xbmc, it will be a string starting with plugin:// followed by the plugin name, for example plugin://plugin.video.1channel/
• sys.argv[1]: your plugin handle, which is used in xbmc api calls to identify your plugin.
• sys.argv[2]: a parameter string, starting with a question mark, followed by parameter name/value pairs, with the parameter name separated from the value by an equal sign, and the name/value pair separated by an ampersand, for example ?category=News&date=20130519. Note that if the parameter names or values contain the reserved characters ? or &, they should be URL encoded.

You will notice that the first and third arguments put together form a web like URL. Also note that there are no parameters defined when your plugin is first invoked.

So let's say we define a plugin named 'plugin.video.myplugin'. It is invoked as plugin://plugin.video.myplugin. We see that no parameters are defined so we diplay the top level menu.Lets say we need to define a menu listing some categories. When we define the menu, we provide a link for each menu item with a URL pointing back to our plugin, with a parameter defining each category, for example plugin://plugin.video.myplugin?category=1, plugin://plugin.video.myplugin?category=2, etc..

Now if a user clicks on category 1, our plugin will be invoked with sys.argv[2] set to ?category=1. When our plugin sees this, it will  build the menu for that category, with either  a link back to our plugin to display additional sub-menus or play a file, or a direct link to a file to be played.

Add-on Structure

Add-ons are located in the xbmc add-on OS dependent directory, for example %APPDATA%\XBMC\addons for Windows 7 and $HOME/xbmc for Linux. A video add-on will be located in a sub-directory with a name starting with plugin.video., and containing the following files at a minimum::

• A Pyhton file containing the code for your plugin. Any name can be used but default.py seems to used by convention.
• An icon for your add-on, as a PNG file named icon.png, 256 by 256 pixels.
• An XML file describing your plugin, named addon.xml, further described below.

Other files could be included, especially if you plan to submit your plugin to the official xbmc repository, and are described in the references section below. What I have listed is the minimum needed to get a reasonable plugin. .

addon.xml file structure 

The following is a sample addon.xml file:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.video.myplugin"
       name="My first Plugin"
       version="1.0.0"
       provider-name="My Name">
  <requires>
 <import addon="xbmc.python" version="2.1.0"/>
  </requires>
  <extension point="xbmc.python.pluginsource" library="default.py">
        <provides>video</provides>
  </extension>
  <extension point="xbmc.addon.metadata">
    <summary lang="en">This is my first plugin.</summary>
    <description lang="en">This is a longer description of my first plugin.</description>
    <platform>all</platform>
 <language>en</language>
 <disclaimer> report any issues with this addon to someone@gmail.com</disclaimer>
  </extension>
</addon>

You will need to change the following information for your plugin:

• The plugin id (line 2), which should match the folder name
• The plugin name (line 3), which will be displayed in the xbmc gui
• The plugin version (line 4)
• The plugin provider(line 5), that's your name, although many people use an alias
• The requires section can be left as is, and as our plugins get more advanced, we will add additional required components
• The entry point Python script file name, if not named default.py, should be changed on line 9.
• The title, description and disclaimer should be specified on lines 13,14 and 17 respectively.

That's it for now, the next post will implement a simple plugin.

More Information and References

http://wiki.xbmc.org/index.php?title=Addon.xml

http://wiki.xbmc.org/index.php?title=Official_add-on_repository