Add-on structure

This page summarizes the add-ons system introduced in the Dharma release (v10) of XBMC. This system allows 3rd party-developed enhancements to XBMC to be distributed to XBMC users directly from inside the XBMC interface.

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

Introduction
Each add-on is kept in its own folder, and is described via an XML file named. In addition, some other files can also come with the add-on, such as,  , and. These are all optional, though we encourage you to at least have. All of these reside in the "root" of the folder that contains the add-on. Additional data may be contained within a  subfolder, such as language translations and descriptions of settings.

When installed, the whole add-on folder will be placed inside.

Directory Name
Your directory name should follow this convention:

Each name part is case sensitive and must be in lower case. The dot character separates each name part; you can use further dots to separate things in your plugin name if you wish. Alternatively, you may use a hyphen (-). No other non-alphanumeric characters should be used.

is one of the following:

The following table describes the available s for the available add-on types. Your add-on may provide more than one  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 add-ons each providing a single media type rather than one add-on that tries to do it all.

The add-on name is up to you, but be sure that it isn't already in use by another add-on. For instance, if you are creating an add-on that integrates the Gpodder software with XBMC for audio podcasts you might name your directory. If you are creating a screen scraper to present TV shows from MyGreatTv.com. It might be. A script to ping all your friends on twitter to tell them you are home might be called .

Directory structure
Your directory contains all the resources needed to operate your add-on. The directory must be considered read-only and should not be used for storing transient or inter-session data. Other mechanisms are available to do that (more later). The directory should be structured as follows:

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

Other files may be required to run your add-on, if your add-on becomes more complex. It is considered good practice to place various add-on resources and support code modules in the  folder. If those libs are commonly used by multiple add-ons, consider adding them as a separate add-on, e.g..

The most important thing to remember from this is that everything that doesn't need to be in the root of your directory is considered a resource and should be placed inside  or one of its subdirectories. Also remember, all the above is a recommended outline for your add-on; if you need fewer or more directories to organise your work, just change it. For instance, skins are add-ons that will require more directories than this.

addon.py
This will contain the main Python code for your add-on. You can name it whatever you want, since you'll define this Python file in  as your main script file.

addon.xml
gives XBMC important metadata about your add-on, such as:
 * what the add-on provides
 * what the add-on 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 the changes you make to the add-on for each release. This is displayed in the XBMC addon installation/update system. The 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 add-ons 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.)

Here is a sample :

v0.1.3 - Update with 13.0 Gotham_alpha2 v0.1.2 - Add notification for Ubuntu users checking through apt command v0.1.1 - Initial version

icon.png
This is an icon used to represent your add-on 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 add-ons. 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 JPEG 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.

LICENSE.txt
This file should contain the text of whatever software license you've chosen to release your add-on under (e.g. GPLv2).

resources/
The  subdirectory is the preferred place to put any files that the add-on uses that don't need to be stored in the root directory. For instance, translations, software libraries, and image resources would go in  or one of its subdirectories.

resources/settings.xml
This is an XML file that defines the user-configurable settings used by the add-on. The file defines the names and types of the settings, and how they should appear in the settings dialog for the add-on.

resources/language/
Translation tools:
 * Language support
 * Translation System
 * Convert .xml to .po: xbmc-xml2po
 * Check for .po files: xbmc-checkpo
 * Utility for keeping XBMC upstream language files and the language files hosted on transifex.com in sync: xbmc-txupdate

String ID range:
 * strings 30000 thru 30999 reserved for plugins and plugin settings
 * strings 31000 thru 31999 reserved for skins
 * strings 32000 thru 32999 reserved for scripts
 * strings 33000 thru 33999 reserved for common strings used in add-ons

strings.po

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.

Getting started
Following pages will explain in more depth to get started. Providing examples, background information and useful links.


 * Python development
 * Skinning