Add-on development

Template:XBMC faq toc 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.

Anatomy of an addon

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.

Directory Name

Your directory name should follow this convention2; <addonType>[.<mediaType>].<yourPluginName>

The name parts are case sensitive and must be in lower case. The dot character separates each name part – you can use further dot's to separate things in your plugin name if you wish, alternatively you may use a hyphen (-). No other non-alphanumeric characters should be used. The addonType is one from the following list Addon Type Name Description repository A repository definition file that allows users to add new repositories to the XBMC addon manager. Media type is not required. plugin A plugin script or module that adds to the functionality of XBMC. Plugins appear under the relevant media section of the main home menu. script A runnable program file that will appear in the Program section of the main home menu. skin An XBMC skin definition and its supporting script files. Media type is not required. The mediaType is not required in all cases. The following table describes the available mediaTypes for the available addon types. Your addon may provide more than one mediaType if you wish, whereby it will appear in more than one section. In most cases, however, a single media type will suffice, and it may be preferable to have multiple addons each providing a single media type rather than one addon that tries to do it all.

Addon	Media Type Name	Description
plugin	audio	A music addon that will appear in the main menu music
plugin	video	A video addon that will appear in the main menu video
plugin	picture	A picture addon that will appear in the main menu picture
plugin	weather	A weather addon that will appear in the main menu weather
script	module	A script plugin that will not appear under a category or within the Addons manager, but provides support for other addons
script	service	A script that will be run at either login or startup

See section on addon.xml for further information

The plugin name is up to you, but beware that others haven't used it before you. So for instance, if you are creating an addon that integrates the Gpodder software with XBMC for audio podcasts you might name your directory; plugin.audio.gpodder-xbmc3 If you are creating a screen scraper to present tv shows from MyGreatTv.com. It might be; plugin.video.my-great-tv-com A script to ping all your friends on twitter to tell them you are home might be called; script.ping-twits-i-am-home Having settled on your name create the directory under the .xbmc/addons directory.

Directory structure

Your directory contains all the resources needed to operate your addon. The directory must be considered read-only and should not be used for storing intersession or transient data. Other mechanisms are available to do that (more later.) The directory must contain the follwing files and directories.

   addon.py
   addon.xml
   changelog.txt
   fanart.jpg
   icon.png
   LICENSE.txt
   /resources
       settings.xml
       /language
       /lib
       /media

Other files may be required to run your addon, if your addon becomes more complex. It is also considered good practice to place various addon resources and support code modules in the /lib folder. If those libs are more commonly used by different addons consider them to add as a separate script.module.foo

i.e. everything that shouldn't be in the root of your directory is considered a resource and should be placed in that sub-directory or a sub-directory from /resources.

File contents

addon.py

This will contain your main addon python code. It may be named differently as you will define this python file in addon.xml as your main script file.

addon.xml

addon.xml tells XBMC; • what the addon provides • what the addon relies on to work • what script to run when it is fired up (if it is meant to be started.)

changelog.txt

A text file that contains a description of each release change that you make to the system. This is displayed in the XBMC addon installation/update system. Recommended format is to have it sorted by version in descending order, with a simple description as to the major changes (new functionality, big fixes etc,) in each version. (In the author's opinion, too many addons skip this piece of information making it difficult for users to determine whether a particular problem that they may have been having has been fixed or not.) resources/settings.xml An XML file that contains the current configuration for the addon. If your addon has configurable items that are set by the user, put them here. This file drives what the user sees when they click on Addon settings for your addon in the various places in XBMC that it can appear. You need do no coding to utilise this functionality

icon.png

This used to to be displayed in various parts of XBMC. 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.
It is suggested that a logo on a plain background (non-transparent) is best in many situations

(e.g. for addons that retrieve media from an online service, use that service's logo [as long as you are free to do so]).

fanart.jpg

This helps to keep XBMC graphically rich when browsing and using addons. Some simple guidelines:

It should be 16:9 aspect ratio
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.

resources/settings.xml

This contains the settings that will be available for your add-on. This file should be located in

   /resources/settings.xml

See following link for all programmable options Addon_Settings

resource/language/

LANGUAGE THINGS

Translation tools:

Language_support
Translation_System
Convert .xml to .po https://github.com/alanwww1/xbmc-xml2po
Check for .po files https://github.com/alanwww1/xbmc-checkpo
Utility for keeping XBMC upstream language files and the language files hosted on transifex.com in sync. https://github.com/alanwww1/xbmc-txupdate

strings.po

Template:Frodo

resources/lib

put any module definitions or third party software libraries into this directory resources/data Store any other static data structures your application requires here. Examples might be XLT/XSD files or static XML files that contain lookup tables etc.

resources/media

store any static media (picture, audio, video etc.) files in this directory Remember, the above is a recommended outline for your addon – if you need fewer or more directories to organise your work, just change it. The only absolutely required file is;

addon.xml

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.

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.

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. The dependency must be provided with the minimum version number your script/skin requires.

Only install on OPENELEC

   <import addon="os.openelec.tv" version="2.0" optional="false"/>

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.

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 several elements that this should contain and all are compulsory (except the broken tag):

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.
All the above must always be present in English as a minmum.
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>
   or
   <language></language>
   or
   <language/>

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

   <broken>deprecated</broken>

Types of extension

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

Extension point	Addon Category
xbmc.gui.skin	Skin
xbmc.gui.webinterface	Web interface
xbmc.addon.repository	<None>
xbmc.service	Services
xbmc.metadata.scraper.albums	Album information
xbmc.metadata.scraper.artists	Artist information
xbmc.metadata.scraper.movies	Movie information
xbmc.metadata.scraper.musicvideos	Music video information
xbmc.metadata.scraper.tvshows	TV information
xbmc.metadata.scraper.library	<None>
xbmc.ui.screensaver	Screensaver
xbmc.player.musicviz	Visualization
xbmc.python.pluginsource	Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
xbmc.python.script	Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
xbmc.python.weather	Weather
xbmc.python.subtitles	Subtitles
xbmc.python.lyrics	Lyrics
xbmc.python.library	<None>
xbmc.python.module	<None>
xbmc.addon.video	<None>
xbmc.addon.audio	<None>
xbmc.addon.image	<None>

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.

Add-on development

Contents

Anatomy of an addon

Directory Name

Directory structure

File contents

addon.py

addon.xml

changelog.txt

icon.png

fanart.jpg

resources/settings.xml

resource/language/

strings.po

resources/lib

resources/media

addon.xml

The <addon> element

The <requires> element

The <extension> elements

The xbmc.addon.metadata extension

Types of extension

See also

Navigation menu

Add-on development

Anatomy of an addon

Directory Name

Directory structure

File contents

addon.py

addon.xml

changelog.txt

icon.png

fanart.jpg

resources/settings.xml

resource/language/

strings.po

resources/lib

resources/media

addon.xml

The <addon> element

The <requires> element

The <extension> elements

The xbmc.addon.metadata extension

Types of extension

See also

Navigation menu

Search