Addon.xml

= Introduction =

Every skin, script, or plugin in XBMC contains an  file which describes the add-on, providing credits, version information and dependencies. Below, we will explain how this file is structured and which elements must be used to create an add-on for XBMC. You can also consult the examples at the end to see how this file is laid out depending on if you are developing a skin or script/plugin.

Every  file has the same basic structure:

There are a few important things to note in the above sample:


 * The  element must be present, and be the root node. It presents data about the add-on package as a whole.
 * Inside the  element is a   element, listing all the dependencies that this add-on needs in order to function.
 * Then there are one or more  elements, each of which describes a part of XBMC that the add-on extends.
 * Finally, there is a specific  element that extends  . This describes the add-on to the user.

= Elements =

The  element has 4 attributes, all required: ,  ,  , and. For example:

id attribute
The id attribute is the unique identifier used for this add-on. It must be unique, and must use only lowercase characters, periods, underscores, dashes and numbers. This identifier is also used as the name of the folder that contains the add-on, so for ease of searching, we suggest you use something like. .

version attribute
The version attribute is used by XBMC to determine whether updates are available. This should be use a version scheme like  (major.minor.patch). For example:. Generally, you'll start with a version of  for test releases and once you feel it is ready for a full release, you'd bump the version to.

How versioning works

 * is newer than
 * is newer than
 * is newer than
 * is older than  (only one character => newer version)
 * is newer than  (two or more characters => older version)
 * is newer than
 * is newer than

name attribute
The name attribute is the name of the add-on as it appears in the UI. This should be in English where it makes sense for it to be so, and is not translatable.

provider-name attribute
The provider-name attribute is used as the author field. This could be a team of authors or a single author. If the add-on is maintained by multiple people please separate them with a comma.

The  element contains one or more   elements which specify which other add-ons this particular add-on requires, and which version of those add-ons it requires. These add-ons may be part of XBMC itself, or may be parts of other third-party add-ons.

XBMC will only allow the add-on to be run if suitable versions of the (non-optional) add-ons on which this add-on depends are installed. When a user installs your add-on from an online repository via XBMC's add-on manager, XBMC attempts to resolve these dependencies, and install anything that your add-on relies on first. The dependency must be provided with the minimum version number your script/skin requires.

Examples
Here is a sample  block that imports two required modules and one optional one:

Here's another example, which will only install on OpenELEC:

Each  element describes one dependency for an add-on, with two required attributes:   and. There is also an optional attribute called, fittingly,.

If your add-on relies on other third-party add-ons, XBMC will automatically install them as well, provided they are available on an existing add-on repository. If they aren't available on any existing repository, the user must install the other add-ons themselves. Note that you need to include any Python libraries you need directly in your add-on; these can't be loaded with an  element, since XBMC wouldn't know what to do with them.

addon attribute
The  attribute specifies the id of the required add-on, e.g..

version attribute
The  attribute specifies the minimum version of the required add-on to be installed.

Dependency versions
Each different XBMC version might require you to use a higher version of the  add-on dependencies to control on which version of XBMC the add-on can be installed.

optional attribute
The dependency may be made optional by setting the  attribute to. This will only install the dependency when the add-on actually needs it. Even if this dependency is missing, the add-on can still be installed.

The  element describes the technical aspects of this add-on. It will have at least a point attribute which will give the part of XBMC that the add-on extends. For instance, the  file for the Confluence skin extends the   part of XBMC. All available extension points are given below.

The various extension points that XBMC provides are given in the list below.

Add-ons that don't correspond to a specific add-on category can not be installed by users. These are usually supporting or shared add-ons that are installed automatically by the add-ons that require them.

xbmc.python.pluginsource
The most common extension point that will be used by plugin addon developers is.

library attribute
The  element has an extra attribute:. This is the name of the Python script (startup script) that will be run when the add-on is activated. This file must exist in the root of your add-on directory.

element
The extension has an additional child element named, which contains a whitespace separated list of  ,  ,  , and/or. This determines in what area (or context) of the XBMC system your addon will make itself visible in:

xbmc.addon.metadata
This special extension point must be provided by all add-ons, and is the way that your add-on is described to users of the XBMC add-on manager.

Required elements
There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. See the List of language codes (ISO-639:1988) for possible language strings. If there's no  attribute for a translatable element, it defaults to English. However, even for English, adding the  attribute is recommended.

One or more  elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages.

One or more  elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

The  tag specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so  is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:



The  elements indicate the language(s) of the content provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

The  element indicates what license is used for this add-on.

The  element provides the forum thread URL for this specific add-on. Leave this blank if there is no forum thread.

The  element provides the website URL for this specific add-on.

=
element provides the URL for the source code for this specific add-on.

The  element provides the email address of the author if he wishes to do so for this specific add-on. Here are two examples of how you can make it look (the second one it harder for spambots to use). This can be left blank if you do not want to make your email address public.

One or more  elements that indicate what (if any) things the user should know about the add-on. There is no need to have a disclaimer if you don't want one, though if something requires settings, or only works in a particular country then you may want to state this here. It may be translated into multiple languages.

The  tag will mark the add-on as broken in the XBMC repo and provide the reason why. You don't need to do a version bump for this to work.

How window xml files are found
XBMC can run in many differing resolutions, and a skin should try and cater to all these resolutions. The easiest way is to develop for one specific resolution and make sure that all controls contain and tags. That way, XBMC can scale the controls to the new screen resolution.

However, you may choose to develop alternative window xml files for differing resolutions (such as for HDTV resolutions, or for widescreen versus 4x3 resolutions).

The order that XBMC looks for it's skin files are as follows:


 * 1) It first looks in the current screenmode folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
 * 2) If the current screenmode is 1080i, it then looks in the 720p folder.
 * 3) If the current screenmode is a widescreen mode (1080i, 720p, NTSC16x9, PAL16x9) then it looks in the folder.
 * 4) Finally, it looks in the folder.

This allows you to just put any window files that do not require special treatment for 16x9 resolutions etc. in the folder, preventing needless repetition.

= Examples =

addon.xml for skins
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

addon.xml for scripts/plugins
= Schema Definition =

The XML schema definition for  is located here.