Addon.xml
Introduction
Each skin or script/plugin in XBMC contains the addon.xml file which sets up an overview of the addon and provides credits, versioning information and dependencies. Below we will explain which elements must be used to create an addon to be used in XBMC. At the end we will show you two different layouts to be used depending if you are developing a skin or script/addon.
Overview of the addon.xml items
There are a few things to notice:
- The <addon> element must be present, and is used to present the data about the addon package as a whole.
- Inside the <addon> element is a <requires> element, listing the requirements that this addon needs in order to function.
- Then there is one or more <extension> elements, each of which describes which part of XBMC the addon extends.
- Finally, there is a specific <extension> element which describes the addon for the user.
Mandatory
The <addon> element
The addon element has 4 attributes: id, version, name, and provider-name.
- 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 <type>.<uniquename>.
- The version attribute is used by XBMC to determine whether updates are available. This should be following the x.y.z version numbering for example: version="0.0.1" Most commenly you start with a 0.y.z for testing purpose and once you feel it is ready you go to version="1.0.0"
- 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.
- The provider-name attribute is used as the author field. This could be a team of authors or a single author.
- If it's maintained by multiple people please separate them by using a pipe sign |
Example:
<addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1|Dev2">
How versioning works:
- 2.2.1 is newer than 2.2.9
- 2.3 is newer than 2.2.9
- 2.3.0 is newer than 2.2
- 2.2.1 is older than 2.2.1b << only one character = newer version
- 2.2.1 is newer than 2.2.1bc << two or more = older version
- 2.2.1 is newer than 2.2.1 beta
- 2.2.1 is newer than 2.2.1beta</source>
The <requires> element
The requires element contains one or more <import> 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 3rd 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.
The requirement may be made optional by setting the optional attribute to true. This will only install the dependency when the depending addon actually needs it. If this dependency is missing the depending addon will still be able to be installed.
If your module relies on third party modules, they must be installed prior to installing your module, by the user. Assuming the third party module is available on an existing repository, XBMC will install this automatically when the user installs your addon. Libraries outside of the xbmc domain must be loaded by your code and do not form part of the <requires> statement as XBMC doesn't know what to do with them.
- Example of <requires> element:
<requires> <import addon="xbmc.python" version="2.1.0"/> <import addon="script.module.elementtree" version="1.2.7"/> <import addon="script.module.simplejson" version="2.0.10" optional="true"/> </requires>
- For example this will only install on OPENELEC:
</requires> <import addon="os.openelec.tv" version="2.0" optional="false"/> </requires>
- Example of an optional <requires> element:
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
Each different XBMC version might require you to use a higher version of the xbmc.* addon dependencies to control on which version of XBMC the addon can be installed.
XBMC version | xbmc.python | xbmc.gui | xbmc.json | xbmc.metadata | xbmc.addon | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Dharma 10.1 Deprecated | 1.0 | 2.11 | 2.0 | 1.0 | 0.1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Eden 11.0 | 2.0 | 3.0 | 4.0 | 1.0 | 11.0 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Frodo 12.0 | 2.1.0 | 4.0.0 | 6.0.0 | 2.0.0 | 12.0.0 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Gotham 13.0 | 2.1.0 | 4.0.0 | 6.0.0 | 2.0.0 | }
The <extension> elementsThe extension 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 addon.xml file for the Confluence skin extends the "xbmc.gui.skin" 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.pluginsourceThe most common extension point that will be used by plugin addon developers is "xbmc.python.pluginsource" . The <extension point="xbmc.python.pluginsource"> tag has an extra attribute "library". This is the name of the python script (startup script) that will be run when the plugin is activated. This file must exist in the root of your addon directory. The extension has an addition sub element <provides> and is a whitespace separated list of image, video, audio, executable. This determines in what area (or context) of the XBMC system your addon will make itself visible in.
Example: <extension point="xbmc.python.pluginsource" library="gpodderxbmc.py"> <provides>audio video</provides> </extension> More info on Plugin_Sources The xbmc.addon.metadata extensionThis 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 informationThere 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 minmum.:
<summary lang="en">Hello World script provides some basic examples on how to create your first script.</summary>
<description lang="en">Hello World script provides some basic examples on how to create your first script and hopefully will increase the number of XBMC users to start creating their own addons.</description>
<disclaimer lang="en">Feel free to use this script. For information visit the wiki.</disclaimer>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<platform>all</platform>
List_of_language_codes_(ISO-639:1988) <language>en de fr</language> or <language></language> or <language/>
<broken>deprecated</broken> Optional informationThese tags will be used to provide easy navigation on our upcoming add-on front-end where you can browse through available add-ons and directly visit the forum thread, source code or contact the add-on author.
<forum>put URL here</forum>
<website>put URL here</website>
<source>put URL here</source>
<email>[email protected]</email> <email>foo at bar dot com</email> Skin specific elementsOverview
How window xml files are foundXBMC 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 <width> and <height> 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:
This allows you to just put any window files that do not require special treatment for 16x9 resolutions etc. in the <defaultresolution> folder, preventing needless repetition.
Overview of the script/plugin specific itemsINFO HERE
addon.xml examplesaddon.xml for skins<?xml version="1.0" encoding="UTF-8"?> <addon id="skin.confluence" version="2.1.3" name="Confluence" provider-name="Jezz_X|Team XBMC"> <requires> <import addon="xbmc.gui" version="4.0.0"/> </requires> <extension point="xbmc.gui.skin" defaultthemename="textures.xbt" debugging="false" effectslowdown="0.75"> <res width="1280" height="720" aspect="16:9" default="true" folder="720p" /> </extension> <extension point="xbmc.addon.metadata"> <summary lang="en">Confluence skin by Jezz_X. (XBMC's default skin)</summary> <description lang="en">Confluence is the default skin for XBMC 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time XBMC users to understand and use.</description> <disclaimer lang="en">Confluence is the default skin for XBMC, removing it may cause issues</disclaimer> <platform>all</platform> <license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license> <forum></forum> <website></website> <email></email> <source></source> </extension> </addon> One thing to note is that all tag names are lower case. XML tag names are case sensitive! addon.xml for scripts/plugins<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <addon id="script.artwork.downloader" name="Artwork Downloader" version="12.0.12" provider-name="Martijn"> <requires> <import addon="xbmc.python" version="2.1.0"/> <import addon="xbmc.json" version="6.0.0"/> <import addon="xbmc.addon" version="12.0.0"/> <import addon="script.module.elementtree" version="1.2.7"/> <import addon="script.module.simplejson" version="2.0.10" optional="true"/> <import addon="script.common.plugin.cache" version="1.3.0"/> </requires> <extension point="xbmc.python.script" library="default.py"> <provides>executable</provides> </extension> <extension point="xbmc.service" library="service.py" start="login"/> <extension point="xbmc.addon.metadata"> <summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary> <description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description> <disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the XBMC forum.</disclaimer> <language></language> <platform>all</platform> <license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license> <forum></forum> <website></website> <email></email> <source></source> </extension> </addon> XBMC source codeaddon.xml is handled in following XML Schema Definition |