Add-on development

From Official Kodi Wiki
Revision as of 06:25, 30 June 2010 by >Amet (→‎Types of Extension)
Jump to navigation Jump to search

This page summarizes the new addons system introduced in the Dharma release (10.05) 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.

Structure of an Addon

Each addon 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 addon, 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 addon. Additional data may be contained within a resources/ subfolder, such as language translations and descriptions of settings.

Guidlines for images

Each addon 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 addon, then feel free to ask the community on the XBMC forums - there are many talented designers who are more than happy to do up artwork for your addons.

icon.png

We recommend that icon.png be a square PNG image. Some simple guidelines:

  • It should convey what the addon does to the user by graphical means.
  • It should be 256x256 PNG.
  • It should not have any shadows, gloss, or other overlays on it - XBMC's skinning system will handle that.
  • It is suggested that a logo on a plain background (non-transparent) is best in many situations (eg for addons that retrieve media from an online service, use that service's logo).

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.

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 addon offers) and also what the addon relies on (minimal versions of interfaces in XBMC that interact with the addon.

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"/>
  </requires>
  <extension 
    point="xbmc.gui.skin"
    defaultresolution="720p" 
    defaultresolutionwide="720p"
    defaultthemename="textures.xbt" 
    effectslowdown="0.75"
    debugging="false"/>
  <extension point="xbmc.addon.metadata">
    <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.

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 addon. 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 addon, 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 addon 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.

The <requires> element

The requires element contains one or more <import> elements which specify which other addons this particular addon requires, and which version of those addons it requires. These addons may be part of XBMC itself, or may (in the future) be parts of other 3rd party addons. XBMC will only allow the addon to be run if versions of the addons on which this addon depends are installed. When a user installs your addon from an online repository via XBMC's addon manager, XBMC attempts to resolve these dependencies, and install anything that your addon relies on first.

The <extension> elements

The extension element describes the technical aspects of this addon. It will have at least a point attribute which will give the part of XBMC that the addon 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.

The xbmc.addon.metadata extension

This special extension point must be provided by all addons, and is the way that your addon is described to users of the XBMC addon 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 addon 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 addon does. Again, these can be translated.
  • One or more disclaimer elements that indicate what (if any) things the user should know about the addon. 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 addon runs on. Many addons 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 addon runs on all platforms.

Types of Extension

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