Add-on development

Revision as of 20:08, 4 May 2012

This page summarizes the new addons system introduced in the Dharma release (v10) of XBMC.

XBMC has introduced an addons system. This allows 3rd party developed enhancements to XBMC to be distributed to XBMC users direct from inside the XBMC interface.

The addons system is based on the plugin library c-pluff.

You can find a more detailed Addon Developers Document at XBMC Addon Developers Guide It builds on information found on this page and elsewhere. The document is delivered as a PDF.

1 Structure of an Add-on

Each add-on is kept in it's own folder, and is described via an XML file named addon.xml. In addition, some other files can also come with the add-on, namely icon.png, changelog.txt, and fanart.jpg. These are all optional, though we encourage you to at least have icon.png. All of these reside in the "root" of the folder that contains the add-on. Additional data may be contained within a resources/ subfolder, such as language translations and descriptions of settings.

2 Guidelines for images

Each add-on has 2 images associated with it: An icon (icon.png) and an optional fanart image (fanart.jpg). If you want a high quality icon or fanart image made for your add-on, then feel free to ask freezy at xbmc.org or the community on the XBMC forums - there are many talented designers who are more than happy to do up artwork for your add-ons.

2.1 icon.png

In order to keep a coherent look and give the skinner a good idea how the icons of the add-ons look, we have defined the following rules:

• The icon size must be 256x256 pixels.
• File format is PNG.
• Background must be 100% solid. That doesn't mean one color, it also can be a gradient or a low contrast texture. Just make sure there is no transparency.
• Keep the logo as simple a possible, no exaggerated 3D effects or high contrast textures.
• Use a padding of at least 25px for your logo (not the background!). Excepted are large text logos (see icon for themoviedb.org).
• Keep text to a minimum. However, a text logo along with the graphical logo is recommended in order to easily recognize the addon.
• Don't mix logos with XBMC's logo, it's obvious that we're talking about XBMC here.
• Don't add borders or any overlays, that's the skinner's job. However, if borders are an element of your logo, make sure there is enough padding.

2.2 fanart.jpg

We recommend that fanart.png be a 16:9 JPG image. Some simple guidelines:

• It is intended for the background, so should be simple and without text where reasonable.
• We recommend a 1280x720 JPG image. It should certainly be no larger than 1920x1080.
• We recommend keeping it as small as is reasonable with respect to file-size. Remember that hundreds of thousands of users are going to be downloading this.

3 addon.xml

The addon.xml file is the most important file, as it tells XBMC what the addon provides (i.e. what type of extensions this add-on offers) and also what the add-on relies on (minimal versions of interfaces in XBMC that interact with the add-on.

An example addon.xml file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="skin.confluence"
  version="1.1.0"
  name="Confluence"
  provider-name="Jezz_X, Team XBMC">
  <requires>
    <import addon="xbmc.gui" version="2.11" optional="false" />
  </requires>
  <extension 
    point="xbmc.gui.skin"
    defaultresolution="720p" 
    defaultresolutionwide="720p"
    defaultthemename="textures.xbt" 
    effectslowdown="0.75"
    debugging="false"/>
  <extension point="xbmc.addon.metadata">
    <language></language>
    <summary>Confluence skin by Jezz_X. (XBMC's default skin)</summary>
    <summary lang="nl">Confluence skin door Jezz_X</summary>
    <summary lang="zh">Jezz_X开发的Confluence皮肤</summary>
    <description>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>
    <description lang="nl">Confluence is de standaard skin voor XBMC 9.11 en hoger. Het combineert de concepten van andere populaire skins, waarbij het tracht hun goede ideëen te integreren in een skin die gemakkelijk in gebruik is.</description>
    <description lang="zh">在XBMC 9.11之后的版本中Confluence是默认皮肤。它集合了许多流行皮肤的创意，力求把这些优点融合到一个皮肤中，使得首次使用XBMC的用户能更容易上手。</description>
    <disclaimer>Confluence is the default skin for XBMC, removing it may cause issues</disclaimer>
    <disclaimer lang="nl">Confluence is de standaard XMBC skin, het verwijderen van Confluence kan leiden tot problemen.</disclaimer>
    <disclaimer lang="zh">Confluence是XMBC的默认皮肤，删除它可能导致故障。</disclaimer>
    <platform>all</platform>
  </extension>
</addon>

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.

3.1 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. You should use something like 1.0.3 for this.
• 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 translateable.
• The provider-name attribute is used as the author field. This could be a team of authors or a single author.

3.2 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. The requirement may be made optional by setting the optional attribute to true. 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.

3.3 The <extension> elements

The 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 above extends the "xbmc.gui.skin" part of XBMC. Other extension points are given below.

3.4 The xbmc.addon.metadata extension

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. There are 4 elements that this should contain, though only the first is compulsory:

• One or more summary elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages, whereby each has a lang="ch" attribute. No lang attribute indicates English.
• One or more description elements provide a more detailed summary of what the add-on does. Again, these can be translated.
• One or more disclaimer 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.
• A platform tag which specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so "all" is an option, as are "linux", "osx", "windx" and "wingl". If the platform tag is missing, we assume the add-on runs on all platforms.
• Language tag(s). These are 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.

   List_of_language_codes_(ISO-639:1988)
   <language>en de fr</language>
   <language></language>

• Broken tag. This will mark the add-on as broken in the XBMC repo with providing the reason why. For this you work you need to do a version bump.

   <broken>deprecated</broken>

4 Types of extension

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

• xbmc.gui.skin
• xbmc.gui.webinterface
• xbmc.addon.repository
• xbmc.service
• xbmc.metadata.scraper.albums
• xbmc.metadata.scraper.artists
• xbmc.metadata.scraper.movies
• xbmc.metadata.scraper.musicvideos
• xbmc.metadata.scraper.tvshows
• xbmc.metadata.scraper.library
• xbmc.ui.screensaver
• xbmc.player.musicviz
• xbmc.python.pluginsource
• xbmc.python.script
• xbmc.python.weather
• xbmc.python.subtitles
• xbmc.python.lyrics
• xbmc.python.library
• xbmc.python.module
• xbmc.addon.video
• xbmc.addon.audio
• xbmc.addon.image

5 See also

• Add-ons
• Category:All add-ons
• 3rd party add-on repositories

Development:

• Addon Settings
• Python development
• Skinning
• Add-on repositories
• Official add-on repository