Official Kodi Wiki - User contributions [en]

Add-on development

2014-04-19T19:46:46Z

Pline: Remove redirect for A/V add-on tutorial

{{mininav|[[Development]]}}
[[File:Wiki logo.png|150px|link=|left]]
<section begin="intro" />This area contains information, tutorials, and links for creating add-ons for XBMC.<section end="intro" />

{{-}}
----
{{huge|'''[[General topics|{{color|black|General}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Nuvola apps kthememgr.png|link=About Add-ons}}
| width="33%" align="center" | {{Main page icon|image=Applications-development.svg|link=Add-on structure|title=Add-on Structure}}
| width="33%" align="center" | {{Main page icon|image=Administration.png|link=Development Tools}}
|}
----
{{huge|'''[[Tutorials|{{color|black|Tutorials}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=IYY logo.png|link=Audio/video add-on tutorial|title=Audio/Video Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Translation - Noun project 987.svg|link=HOW-TO:HelloWorld_addon|title=GUI Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Programming-128.png‎|link=Program Tutorial}}
|}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Web-icon.png|link=Writing_media_info_scrapers_guide|title=Scraper Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Video.svg|link=3rd Party Tutorials}}
| width="33%" align="center" | {{Main page icon|image=HP-TV-icon.png|link=ScreenSaver Tutorial}}
|}
----
{{huge|'''[[Advanced|{{color|black|Advanced}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Book icon 1.png|link=Python Libraries}}
| width="33%" align="center" | {{Main page icon|image=Network2.png|link=Add-on Repositories}}
| width="33%" align="center" | {{Main page icon|image=Gnome-system-run.svg|link=Add-on settings|title=Add-on Settings}}
|}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Bug.png‎|link=HOW-TO:Debug_Python_Scripts_with_Eclipse|title=Debugging Python}}
| width="33%" align="center" | {{Main page icon|image=Python.svg‎|link=Python Development}}
| width="33%" align="center" | {{Main page icon|image=Blue-Dossier-128.png|link=http://mirrors.xbmc.org/docs/python-docs PyDocs}}
|}
----
{{huge|'''[[Advanced|{{color|black|Publishing}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Upload-128.png|link=Submitting Add-ons}}
| width="33%" align="center" | {{Main page icon|image=Thumbs up font awesome.svg‎|link=Add-on Rules}}
| width="33%" align="center" | {{Main page icon|image=Tape-Measure-128.png‎|link=Add-on Standards}}
|}
----
{{huge|'''[[Repositories|{{color|black|Repositories}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=XBMC New Logo.svg|link=Official_add-on_repository|title=Official Add-on Repository}}
| width="33%" align="center" | {{Main page icon|image=Zappy.png|link=Add-on Website}}
| width="33%" align="center" | {{Main page icon|image=Box_icon.png‎|link=3rd_party_add-on_repositories|title=Third Party Add-on Repository}}
|}

[[Category:Addon Development|*]]

Add-on development

2014-04-19T19:46:11Z

Pline:

{{mininav|[[Development]]}}
[[File:Wiki logo.png|150px|link=|left]]
<section begin="intro" />This area contains information, tutorials, and links for creating add-ons for XBMC.<section end="intro" />

{{-}}
----
{{huge|'''[[General topics|{{color|black|General}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Nuvola apps kthememgr.png|link=About Add-ons}}
| width="33%" align="center" | {{Main page icon|image=Applications-development.svg|link=Add-on structure|title=Add-on Structure}}
| width="33%" align="center" | {{Main page icon|image=Administration.png|link=Development Tools}}
|}
----
{{huge|'''[[Tutorials|{{color|black|Tutorials}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=IYY logo.png|link=Audio/Video add-on tutorial|title=Audio/Video Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Translation - Noun project 987.svg|link=HOW-TO:HelloWorld_addon|title=GUI Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Programming-128.png‎|link=Program Tutorial}}
|}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Web-icon.png|link=Writing_media_info_scrapers_guide|title=Scraper Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Video.svg|link=3rd Party Tutorials}}
| width="33%" align="center" | {{Main page icon|image=HP-TV-icon.png|link=ScreenSaver Tutorial}}
|}
----
{{huge|'''[[Advanced|{{color|black|Advanced}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Book icon 1.png|link=Python Libraries}}
| width="33%" align="center" | {{Main page icon|image=Network2.png|link=Add-on Repositories}}
| width="33%" align="center" | {{Main page icon|image=Gnome-system-run.svg|link=Add-on settings|title=Add-on Settings}}
|}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Bug.png‎|link=HOW-TO:Debug_Python_Scripts_with_Eclipse|title=Debugging Python}}
| width="33%" align="center" | {{Main page icon|image=Python.svg‎|link=Python Development}}
| width="33%" align="center" | {{Main page icon|image=Blue-Dossier-128.png|link=http://mirrors.xbmc.org/docs/python-docs PyDocs}}
|}
----
{{huge|'''[[Advanced|{{color|black|Publishing}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Upload-128.png|link=Submitting Add-ons}}
| width="33%" align="center" | {{Main page icon|image=Thumbs up font awesome.svg‎|link=Add-on Rules}}
| width="33%" align="center" | {{Main page icon|image=Tape-Measure-128.png‎|link=Add-on Standards}}
|}
----
{{huge|'''[[Repositories|{{color|black|Repositories}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=XBMC New Logo.svg|link=Official_add-on_repository|title=Official Add-on Repository}}
| width="33%" align="center" | {{Main page icon|image=Zappy.png|link=Add-on Website}}
| width="33%" align="center" | {{Main page icon|image=Box_icon.png‎|link=3rd_party_add-on_repositories|title=Third Party Add-on Repository}}
|}

[[Category:Addon Development|*]]

Audio-video add-on tutorial

2014-01-28T07:54:00Z

Pline: s/encode/urlencode/

{{mininav|[[Development]]|[[Add-on development]]}}

This page will outline the basics of creating your first Python add-on for XBMC. It assumes you're at least familiar with the basics of Python (or at least, programming in general). If not, we recommend visiting the [http://docs.python.org/2/tutorial/ Python tutorial] first, and then returning here.

= Before we get started =
{{See also|Add-on structure}}

The first step to making an add-on is to put the basic structure in place. Make sure your directory is properly named, e.g. <code>plugin.video.my-addon</code>, and that you have a properly-constructed <code>[[addon.xml]]</code> file. Once these are done, you can get started writing the actual code for your add-on!

= Hello, World! =

The simplest form of Python add-on is one that gets run, adds some list items, and exits to let XBMC take over the navigation; people who have written server-side code for the web should be familiar with how this works. (More complex add-ons can process user input in real-time, but we'll discuss those later.) Let's start by looking at an extremely basic example script:

<source lang="python">
import sys
import xbmcgui
import xbmcplugin

addon_handle = int(sys.argv[1])

xbmcplugin.setContent(addon_handle, 'movies')

url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem('My First Video!', iconImage='DefaultVideo.png')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url, listitem=li)

xbmcplugin.endOfDirectory(addon_handle)
</source>

While not particularly exciting, this shows the minimal amount of code you need to get an XBMC add-on up and running in Python. First, we get the add-on's process handle from <code>sys.argv[1]</code>. We need this to tell XBMC who we are. Next, we tell XBMC that we're going to show a list of <code>'movies'</code>. There are other options, like <code>'audio'</code> or <code>'episodes'</code>; these just change some details of how XBMC presents your add-on.

The most important part is that we create an <code>xbmcgui.ListItem</code> with the name and icon we want (<code>'DefaultVideo.png'</code> comes from the XBMC skin), set it to be a video item, and then add it to the directory. Once we're done adding items, we need to be sure to call <code>xbmcplugin.endOfDirectory</code> to let XBMC know we're done!

= Navigating between pages =

While the first example might be enough for extremely simple add-ons, most add-ons will want to have the ability to navigate between different pages. Most add-ons are designed to imitate a folder hierarchy where opening folder items shows a different list of items, and going "up" returns you to the parent folder.

== Retrieving arguments ==

As we saw in the first example, XBMC passes some arguments to us via <code>sys.argv</code>. This is important, since it's what will let us tailor the output on the add-on based on user input. Remember, much like a web site, each folder (or page) in an XBMC add-on is the result of a separate invocation of our script. The arguments available to us are:

{| class="wikitable"
! Index !! Description
|-
| 0 || The base URL of your add-on, e.g. <code>'plugin://plugin.video.myaddon/'</code>
|-
| 1 || The process handle for this add-on, as a numeric string
|-
| 2 || The query string passed to your add-on, e.g. <code>'?foo=bar&baz=quux'</code>
|}

Of particular interest is <code>sys.argv[2]</code>, which is what we'll generally use to show different things in the add-on.

=== Multiple content types ===
{{See also|Addon.xml#<provides> element}}

If your add-on provides multiple content types, e.g. <code>audio</code> and <code>video</code>, when the user invokes your add-on from the add-on list, XBMC will add a <code>content_type</code> parameter to your add-on's query string. For example: <code>'?content_type=audio'</code>. This will allow you to modify the output depending on what context your add-on was invoked in.

== Passing arguments ==

Now that we know how to retrieve the arguments passed to our add-on, we'll have to actually pass some along to it. Generally speaking, this involves creating a folder <code>ListItem</code> with a URL back to your add-on; then the next invocation of the add-on will parse those arguments and do something with them. Let's look at another brief example that adds some folders to let the user navigate between different pages of the add-on:

<source lang="python">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

base_url = sys.argv[0]
addon_handle = int(sys.argv[1])
args = urlparse.parse_qs(sys.argv[2][1:])

xbmcplugin.setContent(addon_handle, 'movies')

def build_url(query):
return base_url + '?' + urllib.urlencode(query)

mode = args.get('mode', None)

if mode is None:
url = build_url({'mode': 'folder', 'foldername': 'Folder One'})
li = xbmcgui.ListItem('Folder One', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url,
listitem=li, isFolder=True)

url = build_url({'mode': 'folder', 'foldername': 'Folder Two'})
li = xbmcgui.ListItem('Folder Two', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url,
listitem=li, isFolder=True)

xbmcplugin.endOfDirectory(addon_handle)

elif mode[0] == 'folder':
foldername = args['foldername'][0]
url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem(foldername + ' Video', iconImage='DefaultVideo.png')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url, listitem=li)
xbmcplugin.endOfDirectory(addon_handle)
</source>

As you can see, many parts of our code are very similar to the first example. There are a few important additions, however. First, we want to respond to the arguments supplied to our script, so we parse the query string with:

<source lang="python">
urlparse.parse_qs(sys.argv[2][1:])
</source>

We skip the first character, since it's always <code>'?'</code>. This will give us a <code>dict</code> of <code>list</code>s; for example, <code>'?foo=bar&foo=baz&quux=spam'</code> would be converted to <code>{'foo': ['bar', 'baz'], 'quux': ['spam']}</code>. With this information, we can tailor the output of our add-on to the supplied arguments.

We also need to be able to create links back to our add-on in order to display related pages (e.g. subfolders). We can do this by creating an <code>xbmc.ListItem</code>, passing <code>isFolder=True</code>, and setting the URL of the item to point back to our add-on. We create the URL in the helper function <code>build_url()</code>, which gives us a URL that looks something like:

plugin://plugin.video.myaddon/?mode=folder&foldername=Folder+One

= Working with user settings =
{{See also|Add-on settings}}

Your add-on may require some configurable options for the user (e.g. login credentials for a service). These can be stored as settings. To use settings with your add-on, you'll need to make a file defining the settings in <code>resources/settings.xml</code>. For example:

<source lang="xml">
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
<setting id="my_setting" type="bool" default="true" label="My Setting"/>
</settings>
</source>

This will allow the user to open the settings for your add-on and modify this setting as needed. Then, in your add-on, you can retrieve or set this setting with the following code:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.my-addon')
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</source>

= Showing additional metadata =

We've already seen how to show some basic metadata, like the icon image and the type of the item (<code>'video'</code> in our case). However, there are many more pieces of metadata that XBMC understands, and adding them can make life easier on your users. We'll take a look at some of the more important ones. You can also find a full list in the [http://mirrors.xbmc.org/docs/python-docs Python documentation] for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem xbmcgui.ListItem]</code>.

== Icons and thumbnails ==

Our previous examples already showed how to set an icon, but you can also set a larger thumbnail for each list item. Both of these can be set in the <code>ListItem</code> constructor:

<source lang="python">
li = xbmcgui.ListItem(label='My video', iconImage='icon.png', thumbnailImage='thumbnail.png')
</source>

You can also set these ''after'' creating the list item:

<source lang="python">
li.setIconImage('icon.png')
li.setThumbnailImage('thumbnail.png')
</source>

== Fanart ==

Fanart (full-screen background images) are another common thing for add-ons to show. This works a bit differently from icons and thumbnails, but it's still a simple process:

<source lang="python">
li.setProperty('fanart_image', 'fanart.jpg')
</source>

If you'd prefer to show the default fanart from your add-on, you can get the path to that image from the <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcaddon.html#Addon xbmcaddon.Addon]</code> object:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setProperty('fanart_image', my_addon.getAddonInfo('fanart'))
</source>

== Info labels ==

XBMC also lets you add useful information about each list item, like the cast, episode number, play count, and duration. The specific fields available depend on whether your list item is video, audio, or a picture. In all cases though, the format is roughly the same. For example, to add info labels to a movie, you might do the following:

<source lang="python">
li.setInfo('video', { 'genre': 'Horror',
'year': 1979,
'title': 'Alien' })
</source>

For a full list of the available info labels, consult the documentation for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-setInfo ListItem.setInfo]</code>.

== Stream info ==

In addition to metadata about the file's contents, you can add information about the audio/video streams themselves. For a video, you might do the following:

<source lang="python">
li.addStreamInfo('video', { 'codec': 'h264', 'aspect': 1.78, 'width': 1280,
'height': 720, 'duration': 60 })
li.addStreamInfo('audio', { 'codec': 'dts', 'language': 'en', 'channels': 2 })
li.addStreamInfo('subtitle', { 'language': 'en' })
</source>

For complete documentation about this function, see <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-addStreamInfo ListItem.addStreamInfo]</code>.

= Adding context menus =

In addition to the default action for a list item (e.g. playing the video), your add-on can provide additional actions for an item in the context menu. Note that this only applies to list items in ''your'' add-on. Currently, you're not able to modify the context menu for movies in the user's library. To add a context menu item, you need to give it a label and a [[List of built-in functions|built-in function]] as a string:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh'),
('Go up', 'Action(ParentDir)') ])
</source>

You can also elect to show ''only'' your context menu items:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh') ], replaceItems=True)
</source>

[[Category:Addon Development|*]]

Addon.xml

2014-01-09T23:17:45Z

Pline: /* Examples */

{{mininav|[[Development]]|[[Add-on development]]}}
 
{{frodo updated}}

= Introduction =

Every skin, script, or plugin in XBMC contains an <code>addon.xml</code> file which describes the add-on, providing credits, version information and dependencies. Below, we will explain how this file is structured and which elements must be used to create an add-on for XBMC. You can also consult the examples at the end to see how this file is laid out depending on if you are developing a skin or script/plugin.

Every <code>addon.xml</code> file has the same basic structure:

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="your.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Your add-on's summary</summary>
<description lang="en">Your add-on's description</description>
<disclaimer lang="en"></disclaimer>
<language></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of XBMC that the add-on extends.
* Finally, there is a specific <code><extension></code> element that extends <code>"xbmc.addon.metadata"</code>. This describes the add-on to the user.

= Elements =

== <addon> ==

The <code><addon></code> element has 4 attributes, all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>. For example:

<source lang="xml">
<addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2">
</source>

=== id attribute ===

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

=== version attribute ===

The version attribute is used by XBMC to determine whether updates are available. This should be use a version scheme like <code>x.y.z</code> (major.minor.patch). For example: <code>version="0.0.1"</code>. Generally, you'll start with a version of <code>0.y.z</code> for test releases and once you feel it is ready for a full release, you'd bump the version to <code>1.0.0</code>.

==== How versioning works ====

* <code>2.2.1</code> is newer than <code>2.2.9</code>
* <code>2.3</code> is newer than <code>2.2.9</code>
* <code>2.3.0</code> is newer than <code>2.2</code>
* <code>2.2.1</code> is older than <code>2.2.1b</code> ''(only one character => newer version)''
* <code>2.2.1</code> is newer than <code>2.2.1bc</code> ''(two or more characters => older version)''
* <code>2.2.1</code> is newer than <code>2.2.1 beta</code>
* <code>2.2.1</code> is newer than <code>2.2.1beta</code>

{{tip|Text should only be added for a beta or release version. In other cases version number should only contain numbers.}}

=== name attribute ===

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.

=== provider-name attribute ===

The provider-name attribute is used as the author field. This could be a team of authors or a single author. If the add-on is maintained by multiple people please separate them with a comma (<code>,</code>).

== <requires> ==

The <code><requires></code> element contains one or more <code><import></code> 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 third-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.

=== Examples ===

Here is a sample <code><requires></code> block that imports two required modules and one optional one:

<source lang="xml">
<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>
</source>

Here's another example, which will only install on OpenELEC:

<source lang="xml">
<requires>
<import addon="os.openelec.tv" version="2.0" optional="false"/>
</requires>
</source>

== <import> ==

Each <code><import></code> element describes one dependency for an add-on, with two required attributes: <code>addon</code> and <code>version</code>. There is also an optional attribute called, fittingly, <code>optional</code>.

If your add-on relies on other third-party add-ons, XBMC will automatically install them as well, provided they are available on an existing add-on repository. If they aren't available on any existing repository, the user must install the other add-ons themselves. Note that you need to include any Python libraries you need directly in your add-on; these can't be loaded with an <code><import></code> element, since XBMC wouldn't know what to do with them.

=== addon attribute ===

The <code>addon</code> attribute specifies the id of the required add-on, e.g. <code>script.module.elementtree</code>.

=== version attribute ===

The <code>version</code> attribute specifies the minimum version of the required add-on to be installed.

==== Dependency versions ====

Each different XBMC version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of XBMC the add-on can be installed.

{| class="wikitable" border="1"
|+ Current versions
! 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 & 12.1 & 12.2 || 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.0 || 2.14.0 || 5.0.1 || 6.6.0 || 2.1.0 || 12.0.0
|}

=== optional attribute ===

The dependency may be made optional by setting the <code>optional</code> attribute to <code>true</code>. This will only install the dependency when the add-on actually needs it. Even if this dependency is missing, the add-on can still be installed.

== <extension> ==

The <code><extension></code> 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 <code>addon.xml</code> file for the Confluence skin extends the <code>xbmc.gui.skin</code> part of XBMC. All available extension points are given below.

The various extension points that XBMC provides are given in the list below.
{| class="wikitable"
!Extension point
!Add-on Category
|-
|<code>[[Add-ons for XBMC (Development)#addon.xml|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.gui.webinterface</code>
|Web interface
|-
|<code>[[Add-ons for XBMC (Developement)#Repository Add-on|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[HOW-TO:_Automatically_start_addons_using_services|xbmc.service]]</code>
|Services
|-
|<code>xbmc.metadata.scraper.albums</code>
|Album information
|-
|<code>xbmc.metadata.scraper.artists</code>
|Artist information
|-
|<code>xbmc.metadata.scraper.movies</code>
|Movie information
|-
|<code>xbmc.metadata.scraper.musicvideos</code>
|Music video information
|-
|<code>xbmc.metadata.scraper.tvshows</code>
|TV information
|-
|<code>xbmc.metadata.scraper.library</code>
|''None''
|-
|<code>xbmc.ui.screensaver</code>
|Screensaver
|-
|<code>xbmc.player.musicviz</code>
|Visualization
|-
|<code>[[Plugin Sources#What XBMC requires for your add-on|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script Sources#What XBMC requires for your add-on|xbmc.python.script]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>xbmc.python.weather</code>
|Weather
|-{{Gotham row}}
|<code>[[Script Subtitles#What XBMC requires for your add-on|xbmc.python.subtitles]]</code>
|'''([[:Category:Gotham feature|Future Gotham removal]])''' Subtitles
|-{{Gotham row}}
|<code>xbmc.subtitle.module</code>
|'''([[:Category:Gotham feature|Future Gotham addition]])''' Subtitle service module
|-
|<code>[[Script Lyrics#What XBMC requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script Library#What XBMC requires for your add-on|xbmc.python.library]]</code>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|}

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.pluginsource ===
{{See also|Plugin Sources}}

The most common extension point that will be used by plugin addon developers is <code>xbmc.python.pluginsource</code>.

==== library attribute ====

The <code><extension point="xbmc.python.pluginsource"></code> element has an extra attribute: <code>library</code>. This is the name of the Python script (startup script) that will be run when the add-on is activated. This file must exist in the root of your add-on directory.

==== <provides> element ====

The extension has an additional child element named <code><provides></code>, which contains a whitespace separated list of <code>image</code>, <code>video</code>, <code>audio</code>, and/or <code>executable</code>. This determines in what area (or context) of the XBMC system your addon will make itself visible in:

{| class="wikitable"
!Provides
!Appears in
|-
|<code>image</code>
|Pictures
|-
|<code>audio</code>
|Music
|-
|<code>video</code>
|Video
|-
|<code>executable</code>
|Programs
|-
|''(blank)''
|Not visible
|}

==== Example ====

<source lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</source>

=== xbmc.addon.metadata ===

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.

==== Required elements ====

There 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 minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. See the [[List of language codes (ISO-639:1988)]] for possible language strings. If there's no <code>lang</code> attribute for a translatable element, it defaults to English. However, even for English, adding the <code>lang</code> attribute is recommended.

===== <summary> =====

One or more <code><summary></code> elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages.

<source lang="xml">
<summary lang="en">Hello World script provides some basic examples on how to create your first script.</summary>
</source>

===== <description> =====

One or more <code><description></code> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

<source lang="xml">
<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>
</source>

===== <platform> =====

The <code><platform></code> tag specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx32</code>
* <code>ios</code>
* <code>windx</code>
* <code>wingl</code>
* <code>android</code>

<source lang="xml">
<platform>all</platform>
</source>

===== <language> =====

The <code><language></code> elements indicate 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.

<source lang="xml">
<language>en de fr</language>
or
<language></language>
</source>

===== <license> =====

The <code><license></code> element indicates what license is used for this add-on.

<source lang="xml">
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
</source>

===== <forum> =====

The <code><forum></code> element provides the forum thread URL for this specific add-on. Leave this blank if there is no forum thread.
<source lang="xml">
<forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum>
</source>

===== <website> =====

The <code><website></code> element provides the website URL for this specific add-on.

<source lang="xml">
<website>http://www.myaddonwebsite.com/</website>
</source>

===== <nowiki><source></nowiki> =====

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml">
<source>http://github.com/someone/myaddon</source>
</syntaxhighlight>

===== <email> =====

The <code><email></code> element provides the email address of the author if he wishes to do so for this specific add-on. Here are two examples of how you can make it look (the second one it harder for spambots to use). This can be left blank if you do not want to make your email address public.
<source lang="xml">
<email>foo@bar.com</email>
or
<email>foo at bar dot com</email>
</source>

==== Optional elements ====

===== <disclaimer> =====

One or more <code><disclaimer></code> 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. It may be translated into multiple languages.

<source lang="xml">
<disclaimer lang="en">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <broken> =====

The <code><broken></code> tag will mark the add-on as broken in the XBMC repo and provide the reason why. You don't need to do a version bump for this to work.

<source lang="xml">
<broken>deprecated</broken>
</source>

== Skin specific elements ==
=== Overview ===
{| class="wikitable"
| '''defaultresolution'''
| Default resolution folder for this skin. This is the base directory that all window xml file requests will fall back to.
|-
| '''defaultresolutionwide'''
| Default widescreen resolution folder for this skin. This is the directory that all window xml file requests from widescreen resolutions (1080i, 720p, 480p 16x9, NTSC 16x9 and PAL 16x9) will fallback to. If the file isn't found in this window, then it'll fall back to the <defaultresolution> folder.
|-
| '''defaultthemename'''
| Default theme name. Currently set to: Default.
|-
| '''effectslowdown'''
| A multiplier that is applied to all <animation> effect lengths in the skin. Useful to slow down all animations globally so that you can better configure timings and see interactions between animating controls.
|-
| '''debugging'''
| When set to true, it'll display onscreen debug information (xml filename, mouse position and focused control type and name) in the skin.

|-
| '''res'''
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===

XBMC 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:

# It first looks in the current screenmode folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current screenmode is 1080i, it then looks in the 720p folder.
# If the current screenmode is a widescreen mode (1080i, 720p, NTSC16x9, PAL16x9) then it looks in the <defaultresolutionwide> folder.
# Finally, it looks in the <defaultresolution> folder.

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.

= Examples =

== addon.xml for skins ==

<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts/plugins ==

<syntaxhighlight lang="xml" enclose="div">
<?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>
</syntaxhighlight>

= Schema Definition =

The XML schema definition for <code>addon.xml</code> is located [https://github.com/xbmc/xbmc/blob/master/addons/xbmc.addon/metadata.xsd here].

[[Category:Add-ons]]
[[Category:Addon Development]]
[[Category:Skin Development]]
[[Category:Development]]

Addon.xml

2014-01-09T23:17:20Z

Pline: /* Introduction */

Addon.xml

2014-01-09T23:16:47Z

Pline: /* Examples */

{{mininav|[[Development]]|[[Add-on development]]}}
 
{{frodo updated}}

= Introduction =

Every skin, script, or plugin in XBMC contains an <code>addon.xml</code> file which describes the add-on, providing credits, version information and dependencies. Below, we will explain how this file is structured and which elements must be used to create an add-on for XBMC. You can also consult the examples at the end to see how this file is laid out depending on if you are developing a skin or script/plugin.

Every <code>addon.xml</code> file has the same basic structure:

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="your.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.1.0"/>

</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Your add-on's summary</summary>
<description lang="en">Your add-on's description</description>
<disclaimer lang="en"></disclaimer>
<language></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of XBMC that the add-on extends.
* Finally, there is a specific <code><extension></code> element that extends <code>"xbmc.addon.metadata"</code>. This describes the add-on to the user.

= Elements =

== <addon> ==

The <code><addon></code> element has 4 attributes, all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>. For example:

<source lang="xml">
<addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2">
</source>

=== id attribute ===

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

=== version attribute ===

The version attribute is used by XBMC to determine whether updates are available. This should be use a version scheme like <code>x.y.z</code> (major.minor.patch). For example: <code>version="0.0.1"</code>. Generally, you'll start with a version of <code>0.y.z</code> for test releases and once you feel it is ready for a full release, you'd bump the version to <code>1.0.0</code>.

==== How versioning works ====

* <code>2.2.1</code> is newer than <code>2.2.9</code>
* <code>2.3</code> is newer than <code>2.2.9</code>
* <code>2.3.0</code> is newer than <code>2.2</code>
* <code>2.2.1</code> is older than <code>2.2.1b</code> ''(only one character => newer version)''
* <code>2.2.1</code> is newer than <code>2.2.1bc</code> ''(two or more characters => older version)''
* <code>2.2.1</code> is newer than <code>2.2.1 beta</code>
* <code>2.2.1</code> is newer than <code>2.2.1beta</code>

{{tip|Text should only be added for a beta or release version. In other cases version number should only contain numbers.}}

=== name attribute ===

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.

=== provider-name attribute ===

The provider-name attribute is used as the author field. This could be a team of authors or a single author. If the add-on is maintained by multiple people please separate them with a comma (<code>,</code>).

== <requires> ==

The <code><requires></code> element contains one or more <code><import></code> 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 third-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.

=== Examples ===

Here is a sample <code><requires></code> block that imports two required modules and one optional one:

<source lang="xml">
<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>
</source>

Here's another example, which will only install on OpenELEC:

<source lang="xml">
<requires>
<import addon="os.openelec.tv" version="2.0" optional="false"/>
</requires>
</source>

== <import> ==

Each <code><import></code> element describes one dependency for an add-on, with two required attributes: <code>addon</code> and <code>version</code>. There is also an optional attribute called, fittingly, <code>optional</code>.

If your add-on relies on other third-party add-ons, XBMC will automatically install them as well, provided they are available on an existing add-on repository. If they aren't available on any existing repository, the user must install the other add-ons themselves. Note that you need to include any Python libraries you need directly in your add-on; these can't be loaded with an <code><import></code> element, since XBMC wouldn't know what to do with them.

=== addon attribute ===

The <code>addon</code> attribute specifies the id of the required add-on, e.g. <code>script.module.elementtree</code>.

=== version attribute ===

The <code>version</code> attribute specifies the minimum version of the required add-on to be installed.

==== Dependency versions ====

Each different XBMC version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of XBMC the add-on can be installed.

{| class="wikitable" border="1"
|+ Current versions
! 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 & 12.1 & 12.2 || 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.0 || 2.14.0 || 5.0.1 || 6.6.0 || 2.1.0 || 12.0.0
|}

=== optional attribute ===

The dependency may be made optional by setting the <code>optional</code> attribute to <code>true</code>. This will only install the dependency when the add-on actually needs it. Even if this dependency is missing, the add-on can still be installed.

== <extension> ==

The <code><extension></code> 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 <code>addon.xml</code> file for the Confluence skin extends the <code>xbmc.gui.skin</code> part of XBMC. All available extension points are given below.

The various extension points that XBMC provides are given in the list below.
{| class="wikitable"
!Extension point
!Add-on Category
|-
|<code>[[Add-ons for XBMC (Development)#addon.xml|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.gui.webinterface</code>
|Web interface
|-
|<code>[[Add-ons for XBMC (Developement)#Repository Add-on|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[HOW-TO:_Automatically_start_addons_using_services|xbmc.service]]</code>
|Services
|-
|<code>xbmc.metadata.scraper.albums</code>
|Album information
|-
|<code>xbmc.metadata.scraper.artists</code>
|Artist information
|-
|<code>xbmc.metadata.scraper.movies</code>
|Movie information
|-
|<code>xbmc.metadata.scraper.musicvideos</code>
|Music video information
|-
|<code>xbmc.metadata.scraper.tvshows</code>
|TV information
|-
|<code>xbmc.metadata.scraper.library</code>
|''None''
|-
|<code>xbmc.ui.screensaver</code>
|Screensaver
|-
|<code>xbmc.player.musicviz</code>
|Visualization
|-
|<code>[[Plugin Sources#What XBMC requires for your add-on|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script Sources#What XBMC requires for your add-on|xbmc.python.script]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>xbmc.python.weather</code>
|Weather
|-{{Gotham row}}
|<code>[[Script Subtitles#What XBMC requires for your add-on|xbmc.python.subtitles]]</code>
|'''([[:Category:Gotham feature|Future Gotham removal]])''' Subtitles
|-{{Gotham row}}
|<code>xbmc.subtitle.module</code>
|'''([[:Category:Gotham feature|Future Gotham addition]])''' Subtitle service module
|-
|<code>[[Script Lyrics#What XBMC requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script Library#What XBMC requires for your add-on|xbmc.python.library]]</code>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|}

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.pluginsource ===
{{See also|Plugin Sources}}

The most common extension point that will be used by plugin addon developers is <code>xbmc.python.pluginsource</code>.

==== library attribute ====

The <code><extension point="xbmc.python.pluginsource"></code> element has an extra attribute: <code>library</code>. This is the name of the Python script (startup script) that will be run when the add-on is activated. This file must exist in the root of your add-on directory.

==== <provides> element ====

The extension has an additional child element named <code><provides></code>, which contains a whitespace separated list of <code>image</code>, <code>video</code>, <code>audio</code>, and/or <code>executable</code>. This determines in what area (or context) of the XBMC system your addon will make itself visible in:

{| class="wikitable"
!Provides
!Appears in
|-
|<code>image</code>
|Pictures
|-
|<code>audio</code>
|Music
|-
|<code>video</code>
|Video
|-
|<code>executable</code>
|Programs
|-
|''(blank)''
|Not visible
|}

==== Example ====

<source lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</source>

=== xbmc.addon.metadata ===

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.

==== Required elements ====

There 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 minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. See the [[List of language codes (ISO-639:1988)]] for possible language strings. If there's no <code>lang</code> attribute for a translatable element, it defaults to English. However, even for English, adding the <code>lang</code> attribute is recommended.

===== <summary> =====

One or more <code><summary></code> elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages.

<source lang="xml">
<summary lang="en">Hello World script provides some basic examples on how to create your first script.</summary>
</source>

===== <description> =====

One or more <code><description></code> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

<source lang="xml">
<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>
</source>

===== <platform> =====

The <code><platform></code> tag specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx32</code>
* <code>ios</code>
* <code>windx</code>
* <code>wingl</code>
* <code>android</code>

<source lang="xml">
<platform>all</platform>
</source>

===== <language> =====

The <code><language></code> elements indicate 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.

<source lang="xml">
<language>en de fr</language>
or
<language></language>
</source>

===== <license> =====

The <code><license></code> element indicates what license is used for this add-on.

<source lang="xml">
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
</source>

===== <forum> =====

The <code><forum></code> element provides the forum thread URL for this specific add-on. Leave this blank if there is no forum thread.
<source lang="xml">
<forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum>
</source>

===== <website> =====

The <code><website></code> element provides the website URL for this specific add-on.

<source lang="xml">
<website>http://www.myaddonwebsite.com/</website>
</source>

===== <nowiki><source></nowiki> =====

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml">
<source>http://github.com/someone/myaddon</source>
</syntaxhighlight>

===== <email> =====

The <code><email></code> element provides the email address of the author if he wishes to do so for this specific add-on. Here are two examples of how you can make it look (the second one it harder for spambots to use). This can be left blank if you do not want to make your email address public.
<source lang="xml">
<email>foo@bar.com</email>
or
<email>foo at bar dot com</email>
</source>

==== Optional elements ====

===== <disclaimer> =====

One or more <code><disclaimer></code> 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. It may be translated into multiple languages.

<source lang="xml">
<disclaimer lang="en">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <broken> =====

The <code><broken></code> tag will mark the add-on as broken in the XBMC repo and provide the reason why. You don't need to do a version bump for this to work.

<source lang="xml">
<broken>deprecated</broken>
</source>

== Skin specific elements ==
=== Overview ===
{| class="wikitable"
| '''defaultresolution'''
| Default resolution folder for this skin. This is the base directory that all window xml file requests will fall back to.
|-
| '''defaultresolutionwide'''
| Default widescreen resolution folder for this skin. This is the directory that all window xml file requests from widescreen resolutions (1080i, 720p, 480p 16x9, NTSC 16x9 and PAL 16x9) will fallback to. If the file isn't found in this window, then it'll fall back to the <defaultresolution> folder.
|-
| '''defaultthemename'''
| Default theme name. Currently set to: Default.
|-
| '''effectslowdown'''
| A multiplier that is applied to all <animation> effect lengths in the skin. Useful to slow down all animations globally so that you can better configure timings and see interactions between animating controls.
|-
| '''debugging'''
| When set to true, it'll display onscreen debug information (xml filename, mouse position and focused control type and name) in the skin.

|-
| '''res'''
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===

XBMC 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:

# It first looks in the current screenmode folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current screenmode is 1080i, it then looks in the 720p folder.
# If the current screenmode is a widescreen mode (1080i, 720p, NTSC16x9, PAL16x9) then it looks in the <defaultresolutionwide> folder.
# Finally, it looks in the <defaultresolution> folder.

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.

= Examples =

== addon.xml for skins ==

<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts/plugins ==

<syntaxhighlight lang="xml" enclose="div">
<?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>
</syntaxhighlight>

= Schema Definition =

The XML schema definition for <code>addon.xml</code> is located [https://github.com/xbmc/xbmc/blob/master/addons/xbmc.addon/metadata.xsd here].

[[Category:Add-ons]]
[[Category:Addon Development]]
[[Category:Skin Development]]
[[Category:Development]]

Add-on structure

2014-01-09T23:14:23Z

Pline: /* Directory structure */

{{mininav|[[Development]]|[[Add-on development]]}}

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 [http://www.c-pluff.org c-pluff].

== Introduction ==

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

When installed, the whole add-on folder will be placed inside <code>.xbmc/addons/</code>.

== Directory Name ==

Your directory name should follow this convention: <code><addon-type>[.<media-type>].<your-plugin-name></code>

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.

<code>addon-type</code> is one of the following:

{| class="wikitable" border="1"
!Add-on Type
!Description
!Media Type Required?
|-
|<code>repository</code>
|A repository definition file that allows users to add new repositories to the XBMC addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of XBMC. Plugins appear under the relevant media section of the main home menu.
|'''Yes'''
|-
|<code>script</code>
|A runnable program file that will appear in the Program section of the main home menu.
|'''Yes'''
|-
|<code>skin</code>
|An XBMC skin definition and its supporting script files.
|No
|}

The following table describes the available <code>media-type</code>s for the available add-on types. Your add-on may provide more than one <code>media-type</code> 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.

{| class="wikitable" border="1"
!Add-on Type
!Media Type
! Description
|-
|<code>plugin</code>
|<code>audio</code>
|A music add-on that will appear in the Music main menu.
|-
|<code>plugin</code>
|<code>video</code>
|A video add-on that will appear in the Video main menu.
|-
|<code>plugin</code>
|<code>picture</code>
|A picture add-on that will appear in the Pictures main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu.
|-
|<code>script</code>
|<code>module</code>
|A script plugin that will not appear under a category or within the Add-ons manager, but provides support for other add-ons.
|-
|<code>script</code>
|<code>service</code>
|A script that will be run at either login or startup
|}

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 <code>plugin.audio.gpodder-xbmc3</code>. If you are creating a screen scraper to present TV shows from MyGreatTv.com. It might be <code>plugin.video.my-great-tv-com</code>. A script to ping all your friends on twitter to tell them you are home might be called
<code>script.service.ping-twits-i-am-home</code>.

== 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 <code>lib/</code> folder. If those libs are commonly used by multiple add-ons, consider adding them as a separate add-on, e.g. <code>script.module.foo</code>.

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 <code>resources/</code> 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 <code>[[addon.xml]]</code> as your main script file.

=== addon.xml ===
{{See also|addon.xml}}

<code>addon.xml</code> 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 <code>changelog.txt</code>:

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 ===
{{See also|Submitting_Add-ons#Repository_Submission_Guidelines_-_Please_Read_Before_Submitting_Your_Addon|label 1=Repository guidelines}}

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

=== resources/ ===

The <code>resources/</code> 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 <code>resources/</code> or one of its subdirectories.

==== resources/settings.xml ====
{{See also|Add-on settings}}

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: [https://github.com/alanwww1/xbmc-xml2po xbmc-xml2po]
* Check for .po files: [https://github.com/alanwww1/xbmc-checkpo 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 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'''

{{note|strings.xml will possibly be deprecated after the release of Frodo/Gotham. Frodo and Gotham will still be backwards compatible with .xml}}

==== 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]]

== See also ==
* [[Add-ons]]
* [[:Category:All add-ons]]
* [[3rd party add-on repositories]]
'''Development:'''
* [[Add-on development]]
* [[Addon Settings]]
* [[Python development]]
* [[Skinning]]
* [[Add-on repositories]]
* [[Official add-on repository]]

[[Category:Addon Development]]

Archive talk:HOW-TO:Write plugins for XBMC

2014-01-09T23:08:16Z

Pline:

==Bad Design==
This page is very badly designed, it mixes many layers of knowledge:

- python

- python editor

- traffic sniffing

- plugin writing

Instead it should only delve into details about "how to write a plugin", taking for granted knowledge about the rest

An "object oriented" approach would be better, explaining the meaning an expected behavior of the methods that must be implemented in the plugin to make xbmc accept it

== I'll be cleaning this up ==
I'm doing some house-cleaning on this, this page is hideous. --[[User:Webbeh|Webbeh]] 23:28, 1 May 2011 (UTC)

== Delete this page? ==

I added a [[Audio/video add-on tutorial|tutorial]] for audio/video add-ons that should cover most of the XBMC-specific parts of this. Maybe we should just delete this page and redirect it to the new tutorial? It might be wise to look over this page to make sure the new tutorial isn't missing anything useful. [[User:Pline|Pline]] ([[User talk:Pline|talk]]) 18:08, 9 January 2014 (EST)

Add-on development

2013-12-19T18:19:16Z

Pline:

{{mininav|[[Development]]}}
[[File:Wiki logo.png|150px|link=|left]]

Here you will find all the information you need to start writing Add-ons for XBMC.

We provide tutorials and guides as well as explanations of the structure of Add-ons.

{{-}}
----
{{huge|'''[[General topics|{{color|black|General}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Nuvola apps kthememgr.png|link=About Add-ons}}
| width="33%" align="center" | {{Main page icon|image=Applications-development.svg|link=Add-on structure|title=Add-on Structure}}
| width="33%" align="center" | {{Main page icon|image=Administration.png|link=Development Tools}}
|}
----
{{huge|'''[[Tutorials|{{color|black|Tutorials}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=IYY logo.png|link=Audio/Video plugin tutorial|title=Audio/Video Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Translation - Noun project 987.svg|link=HOW-TO:HelloWorld_addon|title=GUI Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Programming-128.png‎|link=Program Tutorial}}
|}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Web-icon.png|link=Writing_media_info_scrapers_guide|title=Scraper Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Video.svg|link=PVR Tutorial}}
| width="33%" align="center" | {{Main page icon|image=HP-TV-icon.png|link=ScreenSaver Tutorial}}
|}
----
{{huge|'''[[Advanced|{{color|black|Advanced}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Book icon 1.png|link=Python Libraries}}
| width="33%" align="center" | {{Main page icon|image=Network2.png|link=Add-on Repositories}}
| width="33%" align="center" | {{Main page icon|image=Gnome-system-run.svg|link=Add-on settings|title=Add-on Settings}}
|}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Bug.png‎|link=HOW-TO:Debug_Python_Scripts_with_Eclipse|title=Debugging Python}}
| width="33%" align="center" | {{Main page icon|image=Python.svg‎|link=Python Development}}
| width="33%" align="center" | {{Main page icon|image=Blue-Dossier-128.png|link=http://mirrors.xbmc.org/docs/python-docs PyDocs}}
|}
----
{{huge|'''[[Advanced|{{color|black|Publishing}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Upload-128.png|link=Submitting Add-ons}}
| width="33%" align="center" | {{Main page icon|image=Thumbs up font awesome.svg‎|link=Add-on Rules}}
| width="33%" align="center" | {{Main page icon|image=Tape-Measure-128.png‎|link=Add-on Standards}}
|}
----
{{huge|'''[[Repositories|{{color|black|Repositories}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=XBMC New Logo.svg|link=Official_add-on_repository|title=Official Add-on Repository}}
| width="33%" align="center" | {{Main page icon|image=Zappy.png|link=Add-on Website}}
| width="33%" align="center" | {{Main page icon|image=Box_icon.png‎|link=3rd_party_add-on_repositories|title=Third Party Add-on Repository}}
|}

[[Category:Addon Development|*]]

Audio-video add-on tutorial

2013-12-19T18:16:35Z

Pline: Pline moved page Audio/Video tutorial to Audio/Video plugin tutorial: Clarify name of page

{{mininav|[[Development]]|[[Add-on development]]}}

This page will outline the basics of creating your first Python add-on for XBMC. It assumes you're at least familiar with the basics of Python (or at least, programming in general). If not, we recommend visiting the [http://docs.python.org/2/tutorial/ Python tutorial] first, and then returning here.

= Before we get started =
{{See also|Add-on structure}}

The first step to making an add-on is to put the basic structure in place. Make sure your directory is properly named, e.g. <code>plugin.video.my-addon</code>, and that you have a properly-constructed <code>[[addon.xml]]</code> file. Once these are done, you can get started writing the actual code for your add-on!

= Hello, World! =

The simplest form of Python add-on is one that gets run, adds some list items, and exits to let XBMC take over the navigation; people who have written server-side code for the web should be familiar with how this works. (More complex add-ons can process user input in real-time, but we'll discuss those later.) Let's start by looking at an extremely basic example script:

<source lang="python">
import sys
import xbmcgui
import xbmcplugin

addon_handle = int(sys.argv[1])

xbmcplugin.setContent(addon_handle, 'movies')

url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem('My First Video!', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url, listitem=li)

xbmcplugin.endOfDirectory(addon_handle)
</source>

While not particularly exciting, this shows the minimal amount of code you need to get an XBMC add-on up and running in Python. First, we get the add-on's process handle from <code>sys.argv[1]</code>. We need this to tell XBMC who we are. Next, we tell XBMC that we're going to show a list of <code>'movies'</code>. There are other options, like <code>'audio'</code> or <code>'episodes'</code>; these just change some details of how XBMC presents your add-on.

The most important part is that we create an <code>xbmcgui.ListItem</code> with the name and icon we want (<code>'DefaultVideo.png'</code> comes from the XBMC skin), set it to be a video item, and then add it to the directory. Once we're done adding items, we need to be sure to call <code>xbmcplugin.endOfDirectory</code> to let XBMC know we're done!

= Navigating between pages =

While the first example might be enough for extremely simple add-ons, most add-ons will want to have the ability to navigate between different pages. Most add-ons are designed to imitate a folder hierarchy where opening folder items shows a different list of items, and going "up" returns you to the parent folder.

== Retrieving arguments ==

As we saw in the first example, XBMC passes some arguments to us via <code>sys.argv</code>. This is important, since it's what will let us tailor the output on the add-on based on user input. Remember, much like a web site, each folder (or page) in an XBMC add-on is the result of a separate invocation of our script. The arguments available to us are:

{| class="wikitable"
! Index !! Description
|-
| 0 || The base URL of your add-on, e.g. <code>'plugin://plugin.video.myaddon/'</code>
|-
| 1 || The process handle for this add-on, as a numeric string
|-
| 2 || The query string passed to your add-on, e.g. <code>'?foo=bar&baz=quux'</code>
|}

Of particular interest is <code>sys.argv[2]</code>, which is what we'll generally use to show different things in the add-on.

=== Multiple content types ===
{{See also|Addon.xml#<provides> element}}

If your add-on provides multiple content types, e.g. <code>audio</code> and <code>video</code>, when the user invokes your add-on from the add-on list, XBMC will add a <code>content_type</code> parameter to your add-on's query string. For example: <code>'?content_type=audio'</code>. This will allow you to modify the output depending on what context your add-on was invoked in.

== Passing arguments ==

Now that we know how to retrieve the arguments passed to our add-on, we'll have to actually pass some along to it. Generally speaking, this involves creating a folder <code>ListItem</code> with a URL back to your add-on; then the next invocation of the add-on will parse those arguments and do something with them. Let's look at another brief example that adds some folders to let the user navigate between different pages of the add-on:

<source lang="python">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

base_url = sys.argv[0]
addon_handle = int(sys.argv[1])
args = urlparse.parse_qs(sys.argv[2][1:])

xbmcplugin.setContent(addon_handle, 'movies')

def build_url(query):
return base_url + '?' + urllib.encode(query)

mode = args.get('mode', None)

if mode is None:
url = build_url({'mode': 'folder', 'foldername': 'Folder One'})
li = xbmcgui.ListItem('Folder One', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url,
listitem=li, isFolder=True)

url = build_url({'mode': 'folder', 'foldername': 'Folder Two'})
li = xbmcgui.ListItem('Folder Two', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url,
listitem=li, isFolder=True)

xbmcplugin.endOfDirectory(addon_handle)

elif mode[0] == 'folder':
foldername = args['foldername'][0]
url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem(foldername + ' Video', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url, listitem=li)
xbmcplugin.endOfDirectory(addon_handle)
</source>

As you can see, many parts of our code are very similar to the first example. There are a few important additions, however. First, we want to respond to the arguments supplied to our script, so we parse the query string with:

<source lang="python">
urlparse.parse_qs(sys.argv[2][1:])
</source>

We skip the first character, since it's always <code>'?'</code>. This will give us a <code>dict</code> of <code>list</code>s; for example, <code>'?foo=bar&foo=baz&quux=spam'</code> would be converted to <code>{'foo': ['bar', 'baz'], 'quux': ['spam']}</code>. With this information, we can tailor the output of our add-on to the supplied arguments.

We also need to be able to create links back to our add-on in order to display related pages (e.g. subfolders). We can do this by creating an <code>xbmc.ListItem</code>, passing <code>isFolder=True</code>, and setting the URL of the item to point back to our add-on. We create the URL in the helper function <code>build_url()</code>, which gives us a URL that looks something like:

plugin://plugin.video.myaddon/?mode=folder&foldername=Folder+One

= Working with user settings =
{{See also|Add-on settings}}

Your add-on may require some configurable options for the user (e.g. login credentials for a service). These can be stored as settings. To use settings with your add-on, you'll need to make a file defining the settings in <code>resources/settings.xml</code>. For example:

<source lang="xml">
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
<setting id="my_setting" type="bool" default="true" label="My Setting"/>
</settings>
</source>

This will allow the user to open the settings for your add-on and modify this setting as needed. Then, in your add-on, you can retrieve or set this setting with the following code:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.my-addon')
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</source>

= Showing additional metadata =

We've already seen how to show some basic metadata, like the icon image and the type of the item (<code>'video'</code> in our case). However, there are many more pieces of metadata that XBMC understands, and adding them can make life easier on your users. We'll take a look at some of the more important ones. You can also find a full list in the [http://mirrors.xbmc.org/docs/python-docs Python documentation] for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem xbmcgui.ListItem]</code>.

== Icons and thumbnails ==

Our previous examples already showed how to set an icon, but you can also set a larger thumbnail for each list item. Both of these can be set in the <code>ListItem</code> constructor:

<source lang="python">
li = xbmcgui.ListItem(label='My video', iconImage='icon.png', thumbnailImage='thumbnail.png')
</source>

You can also set these ''after'' creating the list item:

<source lang="python">
li.setIconImage('icon.png')
li.setThumbnailImage('thumbnail.png')
</source>

== Fanart ==

Fanart (full-screen background images) are another common thing for add-ons to show. This works a bit differently from icons and thumbnails, but it's still a simple process:

<source lang="python">
li.setProperty('fanart_image', 'fanart.jpg')
</source>

If you'd prefer to show the default fanart from your add-on, you can get the path to that image from the <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcaddon.html#Addon xbmcaddon.Addon]</code> object:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setProperty('fanart_image', my_addon.getAddonInfo('fanart'))
</source>

== Info labels ==

XBMC also lets you add useful information about each list item, like the cast, episode number, play count, and duration. The specific fields available depend on whether your list item is video, audio, or a picture. In all cases though, the format is roughly the same. For example, to add info labels to a movie, you might do the following:

<source lang="python">
li.setInfo('video', { 'genre': 'Horror',
'year': 1979,
'title': 'Alien' })
</source>

For a full list of the available info labels, consult the documentation for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-setInfo ListItem.setInfo]</code>.

== Stream info ==

In addition to metadata about the file's contents, you can add information about the audio/video streams themselves. For a video, you might do the following:

<source lang="python">
li.addStreamInfo('video', { 'codec': 'h264', 'aspect': 1.78, 'width': 1280,
'height': 720, 'duration': 60 })
li.addStreamInfo('audio', { 'codec': 'dts', 'language': 'en', 'channels': 2 })
li.addStreamInfo('subtitle', { 'language': 'en' })
</source>

For complete documentation about this function, see <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-addStreamInfo ListItem.addStreamInfo]</code>.

= Adding context menus =

In addition to the default action for a list item (e.g. playing the video), your add-on can provide additional actions for an item in the context menu. Note that this only applies to list items in ''your'' add-on. Currently, you're not able to modify the context menu for movies in the user's library. To add a context menu item, you need to give it a label and a [[List of built-in functions|built-in function]] as a string:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh'),
('Go up', 'Action(ParentDir)') ])
</source>

You can also elect to show ''only'' your context menu items:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh') ], replaceItems=True)
</source>

[[Category:Addon Development|*]]

Audio-video add-on tutorial

2013-12-18T21:54:17Z

Pline: s/addon_id/addon_handle/g

{{mininav|[[Development]]|[[Add-on development]]}}

This page will outline the basics of creating your first Python add-on for XBMC. It assumes you're at least familiar with the basics of Python (or at least, programming in general). If not, we recommend visiting the [http://docs.python.org/2/tutorial/ Python tutorial] first, and then returning here.

= Before we get started =
{{See also|Add-on structure}}

The first step to making an add-on is to put the basic structure in place. Make sure your directory is properly named, e.g. <code>plugin.video.my-addon</code>, and that you have a properly-constructed <code>[[addon.xml]]</code> file. Once these are done, you can get started writing the actual code for your add-on!

= Hello, World! =

The simplest form of Python add-on is one that gets run, adds some list items, and exits to let XBMC take over the navigation; people who have written server-side code for the web should be familiar with how this works. (More complex add-ons can process user input in real-time, but we'll discuss those later.) Let's start by looking at an extremely basic example script:

<source lang="python">
import sys
import xbmcgui
import xbmcplugin

addon_handle = int(sys.argv[1])

xbmcplugin.setContent(addon_handle, 'movies')

url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem('My First Video!', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url, listitem=li)

xbmcplugin.endOfDirectory(addon_handle)
</source>

While not particularly exciting, this shows the minimal amount of code you need to get an XBMC add-on up and running in Python. First, we get the add-on's process handle from <code>sys.argv[1]</code>. We need this to tell XBMC who we are. Next, we tell XBMC that we're going to show a list of <code>'movies'</code>. There are other options, like <code>'audio'</code> or <code>'episodes'</code>; these just change some details of how XBMC presents your add-on.

The most important part is that we create an <code>xbmcgui.ListItem</code> with the name and icon we want (<code>'DefaultVideo.png'</code> comes from the XBMC skin), set it to be a video item, and then add it to the directory. Once we're done adding items, we need to be sure to call <code>xbmcplugin.endOfDirectory</code> to let XBMC know we're done!

= Navigating between pages =

While the first example might be enough for extremely simple add-ons, most add-ons will want to have the ability to navigate between different pages. Most add-ons are designed to imitate a folder hierarchy where opening folder items shows a different list of items, and going "up" returns you to the parent folder.

== Retrieving arguments ==

As we saw in the first example, XBMC passes some arguments to us via <code>sys.argv</code>. This is important, since it's what will let us tailor the output on the add-on based on user input. Remember, much like a web site, each folder (or page) in an XBMC add-on is the result of a separate invocation of our script. The arguments available to us are:

{| class="wikitable"
! Index !! Description
|-
| 0 || The base URL of your add-on, e.g. <code>'plugin://plugin.video.myaddon/'</code>
|-
| 1 || The process handle for this add-on, as a numeric string
|-
| 2 || The query string passed to your add-on, e.g. <code>'?foo=bar&baz=quux'</code>
|}

Of particular interest is <code>sys.argv[2]</code>, which is what we'll generally use to show different things in the add-on.

=== Multiple content types ===
{{See also|Addon.xml#<provides> element}}

If your add-on provides multiple content types, e.g. <code>audio</code> and <code>video</code>, when the user invokes your add-on from the add-on list, XBMC will add a <code>content_type</code> parameter to your add-on's query string. For example: <code>'?content_type=audio'</code>. This will allow you to modify the output depending on what context your add-on was invoked in.

== Passing arguments ==

Now that we know how to retrieve the arguments passed to our add-on, we'll have to actually pass some along to it. Generally speaking, this involves creating a folder <code>ListItem</code> with a URL back to your add-on; then the next invocation of the add-on will parse those arguments and do something with them. Let's look at another brief example that adds some folders to let the user navigate between different pages of the add-on:

<source lang="python">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

base_url = sys.argv[0]
addon_handle = int(sys.argv[1])
args = urlparse.parse_qs(sys.argv[2][1:])

xbmcplugin.setContent(addon_handle, 'movies')

def build_url(query):
return base_url + '?' + urllib.encode(query)

mode = args.get('mode', None)

if mode is None:
url = build_url({'mode': 'folder', 'foldername': 'Folder One'})
li = xbmcgui.ListItem('Folder One', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url,
listitem=li, isFolder=True)

url = build_url({'mode': 'folder', 'foldername': 'Folder Two'})
li = xbmcgui.ListItem('Folder Two', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url,
listitem=li, isFolder=True)

xbmcplugin.endOfDirectory(addon_handle)

elif mode[0] == 'folder':
foldername = args['foldername'][0]
url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem(foldername + ' Video', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_handle, url=url, listitem=li)
xbmcplugin.endOfDirectory(addon_handle)
</source>

As you can see, many parts of our code are very similar to the first example. There are a few important additions, however. First, we want to respond to the arguments supplied to our script, so we parse the query string with:

<source lang="python">
urlparse.parse_qs(sys.argv[2][1:])
</source>

We skip the first character, since it's always <code>'?'</code>. This will give us a <code>dict</code> of <code>list</code>s; for example, <code>'?foo=bar&foo=baz&quux=spam'</code> would be converted to <code>{'foo': ['bar', 'baz'], 'quux': ['spam']}</code>. With this information, we can tailor the output of our add-on to the supplied arguments.

We also need to be able to create links back to our add-on in order to display related pages (e.g. subfolders). We can do this by creating an <code>xbmc.ListItem</code>, passing <code>isFolder=True</code>, and setting the URL of the item to point back to our add-on. We create the URL in the helper function <code>build_url()</code>, which gives us a URL that looks something like:

plugin://plugin.video.myaddon/?mode=folder&foldername=Folder+One

= Working with user settings =
{{See also|Add-on settings}}

Your add-on may require some configurable options for the user (e.g. login credentials for a service). These can be stored as settings. To use settings with your add-on, you'll need to make a file defining the settings in <code>resources/settings.xml</code>. For example:

<source lang="xml">
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
<setting id="my_setting" type="bool" default="true" label="My Setting"/>
</settings>
</source>

This will allow the user to open the settings for your add-on and modify this setting as needed. Then, in your add-on, you can retrieve or set this setting with the following code:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.my-addon')
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</source>

= Showing additional metadata =

We've already seen how to show some basic metadata, like the icon image and the type of the item (<code>'video'</code> in our case). However, there are many more pieces of metadata that XBMC understands, and adding them can make life easier on your users. We'll take a look at some of the more important ones. You can also find a full list in the [http://mirrors.xbmc.org/docs/python-docs Python documentation] for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem xbmcgui.ListItem]</code>.

== Icons and thumbnails ==

Our previous examples already showed how to set an icon, but you can also set a larger thumbnail for each list item. Both of these can be set in the <code>ListItem</code> constructor:

<source lang="python">
li = xbmcgui.ListItem(label='My video', iconImage='icon.png', thumbnailImage='thumbnail.png')
</source>

You can also set these ''after'' creating the list item:

<source lang="python">
li.setIconImage('icon.png')
li.setThumbnailImage('thumbnail.png')
</source>

== Fanart ==

Fanart (full-screen background images) are another common thing for add-ons to show. This works a bit differently from icons and thumbnails, but it's still a simple process:

<source lang="python">
li.setProperty('fanart_image', 'fanart.jpg')
</source>

If you'd prefer to show the default fanart from your add-on, you can get the path to that image from the <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcaddon.html#Addon xbmcaddon.Addon]</code> object:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setProperty('fanart_image', my_addon.getAddonInfo('fanart'))
</source>

== Info labels ==

XBMC also lets you add useful information about each list item, like the cast, episode number, play count, and duration. The specific fields available depend on whether your list item is video, audio, or a picture. In all cases though, the format is roughly the same. For example, to add info labels to a movie, you might do the following:

<source lang="python">
li.setInfo('video', { 'genre': 'Horror',
'year': 1979,
'title': 'Alien' })
</source>

For a full list of the available info labels, consult the documentation for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-setInfo ListItem.setInfo]</code>.

== Stream info ==

In addition to metadata about the file's contents, you can add information about the audio/video streams themselves. For a video, you might do the following:

<source lang="python">
li.addStreamInfo('video', { 'codec': 'h264', 'aspect': 1.78, 'width': 1280,
'height': 720, 'duration': 60 })
li.addStreamInfo('audio', { 'codec': 'dts', 'language': 'en', 'channels': 2 })
li.addStreamInfo('subtitle', { 'language': 'en' })
</source>

For complete documentation about this function, see <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-addStreamInfo ListItem.addStreamInfo]</code>.

= Adding context menus =

In addition to the default action for a list item (e.g. playing the video), your add-on can provide additional actions for an item in the context menu. Note that this only applies to list items in ''your'' add-on. Currently, you're not able to modify the context menu for movies in the user's library. To add a context menu item, you need to give it a label and a [[List of built-in functions|built-in function]] as a string:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh'),
('Go up', 'Action(ParentDir)') ])
</source>

You can also elect to show ''only'' your context menu items:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh') ], replaceItems=True)
</source>

[[Category:Addon Development|*]]

User:Pline

2013-12-18T00:33:48Z

Pline: Blanking this, since I moved it to Audio/Video tutorial

Audio-video add-on tutorial

2013-12-18T00:33:05Z

Pline: Created page with "{{mininav|Development|Add-on development}} This page will outline the basics of creating your first Python add-on for XBMC. It assumes you're at least familiar with t..."

{{mininav|[[Development]]|[[Add-on development]]}}

This page will outline the basics of creating your first Python add-on for XBMC. It assumes you're at least familiar with the basics of Python (or at least, programming in general). If not, we recommend visiting the [http://docs.python.org/2/tutorial/ Python tutorial] first, and then returning here.

= Before we get started =
{{See also|Add-on structure}}

The first step to making an add-on is to put the basic structure in place. Make sure your directory is properly named, e.g. <code>plugin.video.my-addon</code>, and that you have a properly-constructed <code>[[addon.xml]]</code> file. Once these are done, you can get started writing the actual code for your add-on!

= Hello, World! =

The simplest form of Python add-on is one that gets run, adds some list items, and exits to let XBMC take over the navigation; people who have written server-side code for the web should be familiar with how this works. (More complex add-ons can process user input in real-time, but we'll discuss those later.) Let's start by looking at an extremely basic example script:

<source lang="python">
import sys
import xbmcgui
import xbmcplugin

addon_id = int(sys.argv[1])

xbmcplugin.setContent(addon_id, 'movies')

url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem('My First Video!', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url, listitem=li)

xbmcplugin.endOfDirectory(addon_id)
</source>

While not particularly exciting, this shows the minimal amount of code you need to get an XBMC add-on up and running in Python. First, we get the add-on's process handle from <code>sys.argv[1]</code>. We need this to tell XBMC who we are. Next, we tell XBMC that we're going to show a list of <code>'movies'</code>. There are other options, like <code>'audio'</code> or <code>'episodes'</code>; these just change some details of how XBMC presents your add-on.

The most important part is that we create an <code>xbmcgui.ListItem</code> with the name and icon we want (<code>'DefaultVideo.png'</code> comes from the XBMC skin), set it to be a video item, and then add it to the directory. Once we're done adding items, we need to be sure to call <code>xbmcplugin.endOfDirectory</code> to let XBMC know we're done!

= Navigating between pages =

While the first example might be enough for extremely simple add-ons, most add-ons will want to have the ability to navigate between different pages. Most add-ons are designed to imitate a folder hierarchy where opening folder items shows a different list of items, and going "up" returns you to the parent folder.

== Retrieving arguments ==

As we saw in the first example, XBMC passes some arguments to us via <code>sys.argv</code>. This is important, since it's what will let us tailor the output on the add-on based on user input. Remember, much like a web site, each folder (or page) in an XBMC add-on is the result of a separate invocation of our script. The arguments available to us are:

{| class="wikitable"
! Index !! Description
|-
| 0 || The base URL of your add-on, e.g. <code>'plugin://plugin.video.myaddon/'</code>
|-
| 1 || The process handle for this add-on, as a numeric string
|-
| 2 || The query string passed to your add-on, e.g. <code>'?foo=bar&baz=quux'</code>
|}

Of particular interest is <code>sys.argv[2]</code>, which is what we'll generally use to show different things in the add-on.

=== Multiple content types ===
{{See also|Addon.xml#<provides> element}}

If your add-on provides multiple content types, e.g. <code>audio</code> and <code>video</code>, when the user invokes your add-on from the add-on list, XBMC will add a <code>content_type</code> parameter to your add-on's query string. For example: <code>'?content_type=audio'</code>. This will allow you to modify the output depending on what context your add-on was invoked in.

== Passing arguments ==

Now that we know how to retrieve the arguments passed to our add-on, we'll have to actually pass some along to it. Generally speaking, this involves creating a folder <code>ListItem</code> with a URL back to your add-on; then the next invocation of the add-on will parse those arguments and do something with them. Let's look at another brief example that adds some folders to let the user navigate between different pages of the add-on:

<source lang="python">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

base_url = sys.argv[0]
addon_id = int(sys.argv[1])
args = urlparse.parse_qs(sys.argv[2][1:])

xbmcplugin.setContent(addon_id, 'movies')

def build_url(query):
return base_url + '?' + urllib.encode(query)

mode = args.get('mode', None)

if mode is None:
url = build_url({'mode': 'folder', 'foldername': 'Folder One'})
li = xbmcgui.ListItem('Folder One', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url,
listitem=li, isFolder=True)

url = build_url({'mode': 'folder', 'foldername': 'Folder Two'})
li = xbmcgui.ListItem('Folder Two', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url,
listitem=li, isFolder=True)

xbmcplugin.endOfDirectory(addon_id)

elif mode[0] == 'folder':
foldername = args['foldername'][0]
url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem(foldername + ' Video', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url, listitem=li)
xbmcplugin.endOfDirectory(addon_id)
</source>

As you can see, many parts of our code are very similar to the first example. There are a few important additions, however. First, we want to respond to the arguments supplied to our script, so we parse the query string with:

<source lang="python">
urlparse.parse_qs(sys.argv[2][1:])
</source>

We skip the first character, since it's always <code>'?'</code>. This will give us a <code>dict</code> of <code>list</code>s; for example, <code>'?foo=bar&foo=baz&quux=spam'</code> would be converted to <code>{'foo': ['bar', 'baz'], 'quux': ['spam']}</code>. With this information, we can tailor the output of our add-on to the supplied arguments.

We also need to be able to create links back to our add-on in order to display related pages (e.g. subfolders). We can do this by creating an <code>xbmc.ListItem</code>, passing <code>isFolder=True</code>, and setting the URL of the item to point back to our add-on. We create the URL in the helper function <code>build_url()</code>, which gives us a URL that looks something like:

plugin://plugin.video.myaddon/?mode=folder&foldername=Folder+One

= Working with user settings =
{{See also|Add-on settings}}

Your add-on may require some configurable options for the user (e.g. login credentials for a service). These can be stored as settings. To use settings with your add-on, you'll need to make a file defining the settings in <code>resources/settings.xml</code>. For example:

<source lang="xml">
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
<setting id="my_setting" type="bool" default="true" label="My Setting"/>
</settings>
</source>

This will allow the user to open the settings for your add-on and modify this setting as needed. Then, in your add-on, you can retrieve or set this setting with the following code:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.my-addon')
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</source>

= Showing additional metadata =

We've already seen how to show some basic metadata, like the icon image and the type of the item (<code>'video'</code> in our case). However, there are many more pieces of metadata that XBMC understands, and adding them can make life easier on your users. We'll take a look at some of the more important ones. You can also find a full list in the [http://mirrors.xbmc.org/docs/python-docs Python documentation] for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem xbmcgui.ListItem]</code>.

== Icons and thumbnails ==

Our previous examples already showed how to set an icon, but you can also set a larger thumbnail for each list item. Both of these can be set in the <code>ListItem</code> constructor:

<source lang="python">
li = xbmcgui.ListItem(label='My video', iconImage='icon.png', thumbnailImage='thumbnail.png')
</source>

You can also set these ''after'' creating the list item:

<source lang="python">
li.setIconImage('icon.png')
li.setThumbnailImage('thumbnail.png')
</source>

== Fanart ==

Fanart (full-screen background images) are another common thing for add-ons to show. This works a bit differently from icons and thumbnails, but it's still a simple process:

<source lang="python">
li.setProperty('fanart_image', 'fanart.jpg')
</source>

If you'd prefer to show the default fanart from your add-on, you can get the path to that image from the <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcaddon.html#Addon xbmcaddon.Addon]</code> object:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setProperty('fanart_image', my_addon.getAddonInfo('fanart'))
</source>

== Info labels ==

XBMC also lets you add useful information about each list item, like the cast, episode number, play count, and duration. The specific fields available depend on whether your list item is video, audio, or a picture. In all cases though, the format is roughly the same. For example, to add info labels to a movie, you might do the following:

<source lang="python">
li.setInfo('video', { 'genre': 'Horror',
'year': 1979,
'title': 'Alien' })
</source>

For a full list of the available info labels, consult the documentation for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-setInfo ListItem.setInfo]</code>.

== Stream info ==

In addition to metadata about the file's contents, you can add information about the audio/video streams themselves. For a video, you might do the following:

<source lang="python">
li.addStreamInfo('video', { 'codec': 'h264', 'aspect': 1.78, 'width': 1280,
'height': 720, 'duration': 60 })
li.addStreamInfo('audio', { 'codec': 'dts', 'language': 'en', 'channels': 2 })
li.addStreamInfo('subtitle', { 'language': 'en' })
</source>

For complete documentation about this function, see <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-addStreamInfo ListItem.addStreamInfo]</code>.

= Adding context menus =

In addition to the default action for a list item (e.g. playing the video), your add-on can provide additional actions for an item in the context menu. Note that this only applies to list items in ''your'' add-on. Currently, you're not able to modify the context menu for movies in the user's library. To add a context menu item, you need to give it a label and a [[List of built-in functions|built-in function]] as a string:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh'),
('Go up', 'Action(ParentDir)') ])
</source>

You can also elect to show ''only'' your context menu items:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh') ], replaceItems=True)
</source>

[[Category:Addon Development|*]]

Add-on development

2013-12-18T00:29:47Z

Pline:

{{mininav|[[Development]]}}
[[File:Wiki logo.png|150px|link=|left]]

Here you will find all the information you need to start writing Add-ons for XBMC.

We provide tutorials and guides as well as explanations of the structure of Add-ons.

{{-}}
----
{{huge|'''[[General topics|{{color|black|General}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Nuvola apps kthememgr.png|link=About Add-ons}}
| width="33%" align="center" | {{Main page icon|image=Applications-development.svg|link=Add-on structure|title=Add-on Structure}}
| width="33%" align="center" | {{Main page icon|image=Administration.png|link=Development Tools}}
|}
----
{{huge|'''[[Tutorials|{{color|black|Tutorials}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=IYY logo.png|link=Audio/Video tutorial|title=Audio/Video Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Translation - Noun project 987.svg|link=HOW-TO:HelloWorld_addon|title=GUI Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Programming-128.png‎|link=Program Tutorial}}
|}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Web-icon.png|link=Writing_media_info_scrapers_guide|title=Scraper Tutorial}}
| width="33%" align="center" | {{Main page icon|image=Video.svg|link=PVR Tutorial}}
| width="33%" align="center" | {{Main page icon|image=HP-TV-icon.png|link=ScreenSaver Tutorial}}
|}
----
{{huge|'''[[Advanced|{{color|black|Advanced}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Book icon 1.png|link=Python Libraries}}
| width="33%" align="center" | {{Main page icon|image=Network2.png|link=Add-on Repositories}}
| width="33%" align="center" | {{Main page icon|image=Gnome-system-run.svg|link=Add-on settings|title=Add-on Settings}}
|}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Bug.png‎|link=HOW-TO:Debug_Python_Scripts_with_Eclipse|title=Debugging Python}}
| width="33%" align="center" | {{Main page icon|image=Python.svg‎|link=Python Development}}
| width="33%" align="center" | {{Main page icon|image=Blue-Dossier-128.png|link=http://mirrors.xbmc.org/docs/python-docs PyDocs}}
|}
----
{{huge|'''[[Advanced|{{color|black|Publishing}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=Upload-128.png|link=Submitting Add-ons}}
| width="33%" align="center" | {{Main page icon|image=Thumbs up font awesome.svg‎|link=Add-on Rules}}
| width="33%" align="center" | {{Main page icon|image=Tape-Measure-128.png‎|link=Add-on Standards}}
|}
----
{{huge|'''[[Repositories|{{color|black|Repositories}}]]'''}}
{| width="100%"
|- valign="top"
| width="33%" align="center" | {{Main page icon|image=XBMC New Logo.svg|link=Official_add-on_repository|title=Official Add-on Repository}}
| width="33%" align="center" | {{Main page icon|image=Zappy.png|link=Add-on Website}}
| width="33%" align="center" | {{Main page icon|image=Box_icon.png‎|link=3rd_party_add-on_repositories|title=Third Party Add-on Repository}}
|}

[[Category:Addon Development|*]]

User:Pline

2013-12-18T00:21:57Z

Pline: /* Adding context menus */

This is a staging area for some rewrites to the Python add-on documentation. Ok, let's go!

= Before we get started =
{{See also|Add-on structure}}

The first step to making an add-on is to put the basic structure in place. Make sure your directory is properly named, e.g. <code>plugin.video.my-addon</code>, and that you have a properly-constructed <code>[[addon.xml]]</code> file. Once these are done, you can get started writing the actual code for your add-on!

= Hello, World! =

The simplest form of Python add-on is one that gets run, adds some list items, and exits to let XBMC take over the navigation; people who have written server-side code for the web should be familiar with how this works. (More complex add-ons can process user input in real-time, but we'll discuss those later.) Let's start by looking at an extremely basic example script:

<source lang="python">
import sys
import xbmcgui
import xbmcplugin

addon_id = int(sys.argv[1])

xbmcplugin.setContent(addon_id, 'movies')

url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem('My First Video!', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url, listitem=li)

xbmcplugin.endOfDirectory(addon_id)
</source>

While not particularly exciting, this shows the minimal amount of code you need to get an XBMC add-on up and running in Python. First, we get the add-on's process handle from <code>sys.argv[1]</code>. We need this to tell XBMC who we are. Next, we tell XBMC that we're going to show a list of <code>'movies'</code>. There are other options, like <code>'audio'</code> or <code>'episodes'</code>; these just change some details of how XBMC presents your add-on.

The most important part is that we create an <code>xbmcgui.ListItem</code> with the name and icon we want (<code>'DefaultVideo.png'</code> comes from the XBMC skin), set it to be a video item, and then add it to the directory. Once we're done adding items, we need to be sure to call <code>xbmcplugin.endOfDirectory</code> to let XBMC know we're done!

= Navigating between pages =

While the first example might be enough for extremely simple add-ons, most add-ons will want to have the ability to navigate between different pages. Most add-ons are designed to imitate a folder hierarchy where opening folder items shows a different list of items, and going "up" returns you to the parent folder.

== Retrieving arguments ==

As we saw in the first example, XBMC passes some arguments to us via <code>sys.argv</code>. This is important, since it's what will let us tailor the output on the add-on based on user input. Remember, much like a web site, each folder (or page) in an XBMC add-on is the result of a separate invocation of our script. The arguments available to us are:

{| class="wikitable"
! Index !! Description
|-
| 0 || The base URL of your add-on, e.g. <code>'plugin://plugin.video.myaddon/'</code>
|-
| 1 || The process handle for this add-on, as a numeric string
|-
| 2 || The query string passed to your add-on, e.g. <code>'?foo=bar&baz=quux'</code>
|}

Of particular interest is <code>sys.argv[2]</code>, which is what we'll generally use to show different things in the add-on.

=== Multiple content types ===
{{See also|Addon.xml#<provides> element}}

If your add-on provides multiple content types, e.g. <code>audio</code> and <code>video</code>, when the user invokes your add-on from the add-on list, XBMC will add a <code>content_type</code> parameter to your add-on's query string. For example: <code>'?content_type=audio'</code>. This will allow you to modify the output depending on what context your add-on was invoked in.

== Passing arguments ==

Now that we know how to retrieve the arguments passed to our add-on, we'll have to actually pass some along to it. Generally speaking, this involves creating a folder <code>ListItem</code> with a URL back to your add-on; then the next invocation of the add-on will parse those arguments and do something with them. Let's look at another brief example that adds some folders to let the user navigate between different pages of the add-on:

<source lang="python">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

base_url = sys.argv[0]
addon_id = int(sys.argv[1])
args = urlparse.parse_qs(sys.argv[2][1:])

xbmcplugin.setContent(addon_id, 'movies')

def build_url(query):
return base_url + '?' + urllib.encode(query)

mode = args.get('mode', None)

if mode is None:
url = build_url({'mode': 'folder', 'foldername': 'Folder One'})
li = xbmcgui.ListItem('Folder One', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url,
listitem=li, isFolder=True)

url = build_url({'mode': 'folder', 'foldername': 'Folder Two'})
li = xbmcgui.ListItem('Folder Two', iconImage='DefaultFolder.png')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url,
listitem=li, isFolder=True)

xbmcplugin.endOfDirectory(addon_id)

elif mode[0] == 'folder':
foldername = args['foldername'][0]
url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem(foldername + ' Video', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url, listitem=li)
xbmcplugin.endOfDirectory(addon_id)
</source>

As you can see, many parts of our code are very similar to the first example. There are a few important additions, however. First, we want to respond to the arguments supplied to our script, so we parse the query string with:

<source lang="python">
urlparse.parse_qs(sys.argv[2][1:])
</source>

We skip the first character, since it's always <code>'?'</code>. This will give us a <code>dict</code> of <code>list</code>s; for example, <code>'?foo=bar&foo=baz&quux=spam'</code> would be converted to <code>{'foo': ['bar', 'baz'], 'quux': ['spam']}</code>. With this information, we can tailor the output of our add-on to the supplied arguments.

We also need to be able to create links back to our add-on in order to display related pages (e.g. subfolders). We can do this by creating an <code>xbmc.ListItem</code>, passing <code>isFolder=True</code>, and setting the URL of the item to point back to our add-on. We create the URL in the helper function <code>build_url()</code>, which gives us a URL that looks something like:

plugin://plugin.video.myaddon/?mode=folder&foldername=Folder+One

= Working with user settings =
{{See also|Add-on settings}}

Your add-on may require some configurable options for the user (e.g. login credentials for a service). These can be stored as settings. To use settings with your add-on, you'll need to make a file defining the settings in <code>resources/settings.xml</code>. For example:

<source lang="xml">
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
<setting id="my_setting" type="bool" default="true" label="My Setting"/>
</settings>
</source>

This will allow the user to open the settings for your add-on and modify this setting as needed. Then, in your add-on, you can retrieve or set this setting with the following code:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.my-addon')
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</source>

= Showing additional metadata =

We've already seen how to show some basic metadata, like the icon image and the type of the item (<code>'video'</code> in our case). However, there are many more pieces of metadata that XBMC understands, and adding them can make life easier on your users. We'll take a look at some of the more important ones. You can also find a full list in the [http://mirrors.xbmc.org/docs/python-docs Python documentation] for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem xbmcgui.ListItem]</code>.

== Icons and thumbnails ==

Our previous examples already showed how to set an icon, but you can also set a larger thumbnail for each list item. Both of these can be set in the <code>ListItem</code> constructor:

<source lang="python">
li = xbmcgui.ListItem(label='My video', iconImage='icon.png', thumbnailImage='thumbnail.png')
</source>

You can also set these ''after'' creating the list item:

<source lang="python">
li.setIconImage('icon.png')
li.setThumbnailImage('thumbnail.png')
</source>

== Fanart ==

Fanart (full-screen background images) are another common thing for add-ons to show. This works a bit differently from icons and thumbnails, but it's still a simple process:

<source lang="python">
li.setProperty('fanart_image', 'fanart.jpg')
</source>

If you'd prefer to show the default fanart from your add-on, you can get the path to that image from the <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcaddon.html#Addon xbmcaddon.Addon]</code> object:

<source lang="python">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setProperty('fanart_image', my_addon.getAddonInfo('fanart'))
</source>

== Info labels ==

XBMC also lets you add useful information about each list item, like the cast, episode number, play count, and duration. The specific fields available depend on whether your list item is video, audio, or a picture. In all cases though, the format is roughly the same. For example, to add info labels to a movie, you might do the following:

<source lang="python">
li.setInfo('video', { 'genre': 'Horror',
'year': 1979,
'title': 'Alien' })
</source>

For a full list of the available info labels, consult the documentation for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-setInfo ListItem.setInfo]</code>.

== Stream info ==

In addition to metadata about the file's contents, you can add information about the audio/video streams themselves. For a video, you might do the following:

<source lang="python">
li.addStreamInfo('video', { 'codec': 'h264', 'aspect': 1.78, 'width': 1280,
'height': 720, 'duration': 60 })
li.addStreamInfo('audio', { 'codec': 'dts', 'language': 'en', 'channels': 2 })
li.addStreamInfo('subtitle', { 'language': 'en' })
</source>

For complete documentation about this function, see <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem-addStreamInfo ListItem.addStreamInfo]</code>.

= Adding context menus =

In addition to the default action for a list item (e.g. playing the video), your add-on can provide additional actions for an item in the context menu. Note that this only applies to list items in ''your'' add-on. Currently, you're not able to modify the context menu for movies in the user's library. To add a context menu item, you need to give it a label and a [[List of built-in functions|built-in function]] as a string:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh'),
('Go up', 'Action(ParentDir)') ])
</source>

You can also elect to show ''only'' your context menu items:

<source lang="python">
li.addContextMenuItems([ ('Refresh', 'Container.Refresh') ], replaceItems=True)
</source>

2013-12-13T03:17:47Z

Addon.xml

2013-12-12T20:13:16Z

Pline: Merge introduction and overview since they're both pretty short.

{{mininav|[[Development]]|[[Add-on development]]}}
 
{{frodo updated}}

= Introduction =

Every skin, script, or plugin in XBMC contains an <code>addon.xml</code> file which describes the add-on, providing credits, version information and dependencies. Below, we will explain how this file is structured and which elements must be used to create an add-on for XBMC. You can also consult the examples at the end to see how this file is laid out depending on if you are developing a skin or script/plugin.

Every <code>addon.xml</code> file has the same basic structure:

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="your.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.1.0"/>

</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Your add-on's summary</summary>
<description lang="en">Your add-on's description</description>
<disclaimer lang="en"></disclaimer>
<language></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of XBMC that the add-on extends.
* Finally, there is a specific <code><extension></code> element that extends <code>"xbmc.addon.metadata"</code>. This describes the add-on to the user.

= Elements =

== <addon> ==

The <code><addon></code> element has 4 attributes, all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>. For example:

<source lang="xml">
<addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2">
</source>

=== id attribute ===

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

=== version attribute ===

The version attribute is used by XBMC to determine whether updates are available. This should be use a version scheme like <code>x.y.z</code> (major.minor.patch). For example: <code>version="0.0.1"</code>. Generally, you'll start with a version of <code>0.y.z</code> for test releases and once you feel it is ready for a full release, you'd bump the version to <code>1.0.0</code>.

==== How versioning works ====

* <code>2.2.1</code> is newer than <code>2.2.9</code>
* <code>2.3</code> is newer than <code>2.2.9</code>
* <code>2.3.0</code> is newer than <code>2.2</code>
* <code>2.2.1</code> is older than <code>2.2.1b</code> ''(only one character => newer version)''
* <code>2.2.1</code> is newer than <code>2.2.1bc</code> ''(two or more characters => older version)''
* <code>2.2.1</code> is newer than <code>2.2.1 beta</code>
* <code>2.2.1</code> is newer than <code>2.2.1beta</code>

{{tip|Text should only be added for a beta or release version. In other cases version number should only contain numbers.}}

=== name attribute ===

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.

=== provider-name attribute ===

The provider-name attribute is used as the author field. This could be a team of authors or a single author. If the add-on is maintained by multiple people please separate them with a comma (<code>,</code>).

== <requires> ==

The <code><requires></code> element contains one or more <code><import></code> 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 third-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.

=== Examples ===

Here is a sample <code><requires></code> block that imports two required modules and one optional one:

<source lang="xml">
<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>
</source>

Here's another example, which will only install on OpenELEC:

<source lang="xml">
</requires>
<import addon="os.openelec.tv" version="2.0" optional="false"/>
</requires>
</source>

== <import> ==

Each <code><import></code> element describes one dependency for an add-on, with two required attributes: <code>addon</code> and <code>version</code>. There is also an optional attribute called, fittingly, <code>optional</code>.

If your add-on relies on other third-party add-ons, XBMC will automatically install them as well, provided they are available on an existing add-on repository. If they aren't available on any existing repository, the user must install the other add-ons themselves. Note that you need to include any Python libraries you need directly in your add-on; these can't be loaded with an <code><import></code> element, since XBMC wouldn't know what to do with them.

=== addon attribute ===

The <code>addon</code> attribute specifies the id of the required add-on, e.g. <code>script.module.elementtree</code>.

=== version attribute ===

The <code>version</code> attribute specifies the minimum version of the required add-on to be installed.

==== Dependency versions ====

Each different XBMC version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of XBMC the add-on can be installed.

{| class="wikitable" border="1"
|+ Current versions
! 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 & 12.1 & 12.2 || 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.0 || 2.12.0 || 5.0.1 || 6.6.0 || 2.1.0 || 12.0.0
|}

=== optional attribute ===

The dependency may be made optional by setting the <code>optional</code> attribute to <code>true</code>. This will only install the dependency when the add-on actually needs it. Even if this dependency is missing, the add-on can still be installed.

== <extension> ==

The <code><extension></code> 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 <code>addon.xml</code> file for the Confluence skin extends the <code>xbmc.gui.skin</code> part of XBMC. All available extension points are given below.

The various extension points that XBMC provides are given in the list below.
{| class="wikitable"
!Extension point
!Add-on Category
|-
|<code>[[Add-ons for XBMC (Development)#addon.xml|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.gui.webinterface</code>
|Web interface
|-
|<code>[[Add-ons for XBMC (Developement)#Repository Add-on|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[HOW-TO:_Automatically_start_addons_using_services|xbmc.service]]</code>
|Services
|-
|<code>xbmc.metadata.scraper.albums</code>
|Album information
|-
|<code>xbmc.metadata.scraper.artists</code>
|Artist information
|-
|<code>xbmc.metadata.scraper.movies</code>
|Movie information
|-
|<code>xbmc.metadata.scraper.musicvideos</code>
|Music video information
|-
|<code>xbmc.metadata.scraper.tvshows</code>
|TV information
|-
|<code>xbmc.metadata.scraper.library</code>
|''None''
|-
|<code>xbmc.ui.screensaver</code>
|Screensaver
|-
|<code>xbmc.player.musicviz</code>
|Visualization
|-
|<code>[[Plugin Sources#What XBMC requires for your add-on|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script Sources#What XBMC requires for your add-on|xbmc.python.script]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>xbmc.python.weather</code>
|Weather
|-{{Gotham row}}
|<code>[[Script Subtitles#What XBMC requires for your add-on|xbmc.python.subtitles]]</code>
|'''([[:Category:Gotham feature|Future Gotham removal]])''' Subtitles
|-{{Gotham row}}
|<code>xbmc.subtitle.module</code>
|'''([[:Category:Gotham feature|Future Gotham addition]])''' Subtitle service module
|-
|<code>[[Script Lyrics#What XBMC requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script Library#What XBMC requires for your add-on|xbmc.python.library]]</code>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|}

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.pluginsource ===
{{See also|Plugin Sources}}

The most common extension point that will be used by plugin addon developers is <code>xbmc.python.pluginsource</code>.

==== library attribute ====

The <code><extension point="xbmc.python.pluginsource"></code> element has an extra attribute: <code>library</code>. This is the name of the Python script (startup script) that will be run when the add-on is activated. This file must exist in the root of your add-on directory.

==== <provides> element ====

The extension has an additional child element named <code><provides></code>, which contains a whitespace separated list of <code>image</code>, <code>video</code>, <code>audio</code>, and/or <code>executable</code>. This determines in what area (or context) of the XBMC system your addon will make itself visible in:

{| class="wikitable"
!Provides
!Appears in
|-
|<code>image</code>
|Pictures
|-
|<code>audio</code>
|Music
|-
|<code>video</code>
|Video
|-
|<code>executable</code>
|Programs
|-
|''(blank)''
|Not visible
|}

==== Example ====

<source lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</source>

=== xbmc.addon.metadata ===

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.

==== Required elements ====

There 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 minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. See the [[List of language codes (ISO-639:1988)]] for possible language strings. If there's no <code>lang</code> attribute for a translatable element, it defaults to English. However, even for English, adding the <code>lang</code> attribute is recommended.

===== <summary> =====

One or more <code><summary></code> elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages.

<source lang="xml">
<summary lang="en">Hello World script provides some basic examples on how to create your first script.</summary>
</source>

===== <description> =====

One or more <code><description></code> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

<source lang="xml">
<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>
</source>

===== <platform> =====

The <code><platform></code> tag specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx32</code>
* <code>ios</code>
* <code>windx</code>
* <code>wingl</code>
* <code>android</code>

<source lang="xml">
<platform>all</platform>
</source>

===== <language> =====

The <code><language></code> elements indicate 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.

<source lang="xml">
<language>en de fr</language>
or
<language></language>
</source>

===== <license> =====

The <code><license></code> element indicates what license is used for this add-on.

<source lang="xml">
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
</source>

===== <forum> =====

The <code><forum></code> element provides the forum thread URL for this specific add-on. Leave this blank if there is no forum thread.
<source lang="xml">
<forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum>
</source>

===== <website> =====

The <code><website></code> element provides the website URL for this specific add-on.

<source lang="xml">
<website>http://www.myaddonwebsite.com/</website>
</source>

===== <nowiki><source></nowiki> =====

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml">
<source>http://github.com/someone/myaddon</source>
</syntaxhighlight>

===== <email> =====

The <code><email></code> element provides the email address of the author if he wishes to do so for this specific add-on. Here are two examples of how you can make it look (the second one it harder for spambots to use). This can be left blank if you do not want to make your email address public.
<source lang="xml">
<email>foo@bar.com</email>
or
<email>foo at bar dot com</email>
</source>

==== Optional elements ====

===== <disclaimer> =====

One or more <code><disclaimer></code> 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. It may be translated into multiple languages.

<source lang="xml">
<disclaimer lang="en">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <broken> =====

The <code><broken></code> tag will mark the add-on as broken in the XBMC repo and provide the reason why. You don't need to do a version bump for this to work.

<source lang="xml">
<broken>deprecated</broken>
</source>

== Skin specific elements ==
=== Overview ===
{| class="wikitable"
| '''defaultresolution'''
| Default resolution folder for this skin. This is the base directory that all window xml file requests will fall back to.
|-
| '''defaultresolutionwide'''
| Default widescreen resolution folder for this skin. This is the directory that all window xml file requests from widescreen resolutions (1080i, 720p, 480p 16x9, NTSC 16x9 and PAL 16x9) will fallback to. If the file isn't found in this window, then it'll fall back to the <defaultresolution> folder.
|-
| '''defaultthemename'''
| Default theme name. Currently set to: Default.
|-
| '''effectslowdown'''
| A multiplier that is applied to all <animation> effect lengths in the skin. Useful to slow down all animations globally so that you can better configure timings and see interactions between animating controls.
|-
| '''debugging'''
| When set to true, it'll display onscreen debug information (xml filename, mouse position and focused control type and name) in the skin.

|-
| '''res'''
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===

XBMC 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:

# It first looks in the current screenmode folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current screenmode is 1080i, it then looks in the 720p folder.
# If the current screenmode is a widescreen mode (1080i, 720p, NTSC16x9, PAL16x9) then it looks in the <defaultresolutionwide> folder.
# Finally, it looks in the <defaultresolution> folder.

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.

= Examples =

== addon.xml for skins ==

<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts/plugins ==

<syntaxhighlight lang="xml" enclose="div">
<?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>
</syntaxhighlight>

= Schema Definition =

The XML schema definition for <code>addon.xml</code> is located [https://github.com/xbmc/xbmc/blob/master/addons/xbmc.addon/metadata.xsd here].

[[Category:Add-ons]]
[[Category:Addon Development]]
[[Category:Skin Development]]
[[Category:Development]]

User:Pline

2013-12-11T22:02:54Z

Pline: /* Passing arguments */

User:Pline

2013-12-11T22:02:23Z

Pline: /* Passing arguments */

User:Pline

2013-12-11T21:58:18Z

Pline: /* Passing arguments */

2013-12-09T22:59:03Z

Pline: Remove irrelevant cross-reference

{{mininav|[[Development]]|[[Add-on development]]}}

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 [http://www.c-pluff.org c-pluff].

== Introduction ==

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

When installed, the whole add-on folder will be placed inside <code>.xbmc/addons/</code>.

== Directory Name ==

Your directory name should follow this convention: <code><addonType>[.<mediaType>].<yourPluginName></code>

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.

<code>addonType</code> is one of the following:

{| class="wikitable" border="1"
!Add-on Type
!Description
!Media Type Required?
|-
|<code>repository</code>
|A repository definition file that allows users to add new repositories to the XBMC addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of XBMC. Plugins appear under the relevant media section of the main home menu.
|'''Yes'''
|-
|<code>script</code>
|A runnable program file that will appear in the Program section of the main home menu.
|'''Yes'''
|-
|<code>skin</code>
|An XBMC skin definition and its supporting script files.
|No
|}

The following table describes the available <code>mediaType</code>s for the available add-on types. Your add-on may provide more than one <code>mediaType</code> 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.

{| class="wikitable" border="1"
!Add-on Type
!Media Type
! Description
|-
|<code>plugin</code>
|<code>audio</code>
|A music add-on that will appear in the Music main menu.
|-
|<code>plugin</code>
|<code>video</code>
|A video add-on that will appear in the Video main menu.
|-
|<code>plugin</code>
|<code>picture</code>
|A picture add-on that will appear in the Pictures main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu.
|-
|<code>script</code>
|<code>module</code>
|A script plugin that will not appear under a category or within the Add-ons manager, but provides support for other add-ons.
|-
|<code>script</code>
|<code>service</code>
|A script that will be run at either login or startup
|}

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 <code>plugin.audio.gpodder-xbmc3</code>. If you are creating a screen scraper to present TV shows from MyGreatTv.com. It might be <code>plugin.video.my-great-tv-com</code>. A script to ping all your friends on twitter to tell them you are home might be called
<code>script.service.ping-twits-i-am-home</code>.

== 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/
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 <code>lib/</code> folder. If those libs are commonly used by multiple add-ons, consider adding them as a separate add-on, e.g. <code>script.module.foo</code>.

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 <code>resources/</code> or one of its subdirectories.

=== 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 <code>[[addon.xml]]</code> as your main script file.

=== addon.xml ===

<code>addon.xml</code> tells XBMC
:* 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.)

More information on formatting can be found here: [[addon.xml]]

=== 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.)

=== 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 ===

See [[Official add-on repository#Repository guidelines|repository guidelines]].

=== resources/settings.xml ===

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. For more information about the format see [[Addon Settings]].

=== resources/language/ ===

'''Translation tools:'''
* [[Language support]]
* [[Translation System]]
* Convert .xml to .po: [https://github.com/alanwww1/xbmc-xml2po xbmc-xml2po]
* Check for .po files: [https://github.com/alanwww1/xbmc-checkpo 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 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'''

{{note|strings.xml will possibly be deprecated after the release of Frodo/Gotham. Frodo and Gotham will still be backwards compatible with .xml}}

=== 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 add-on – if you need fewer or more
directories to organise your work, just change it. Skins are add-ons that will require more directories than this.

== Getting started ==

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

* [[Python development]]
* [[Skinning]]

== See also ==
* [[Add-ons]]
* [[:Category:All add-ons]]
* [[3rd party add-on repositories]]
'''Development:'''
* [[Add-on development]]
* [[Addon Settings]]
* [[Python development]]
* [[Skinning]]
* [[Add-on repositories]]
* [[Official add-on repository]]

[[Category:Addon Development]]

Add-on structure

2013-12-09T22:58:33Z

Pline: /* addon.py */

{{mininav|[[Development]]|[[Add-on development]]}}

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 [http://www.c-pluff.org c-pluff].

== Introduction ==

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

When installed, the whole add-on folder will be placed inside <code>.xbmc/addons/</code>.

== Directory Name ==

Your directory name should follow this convention: <code><addonType>[.<mediaType>].<yourPluginName></code>

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.

<code>addonType</code> is one of the following:

{| class="wikitable" border="1"
!Add-on Type
!Description
!Media Type Required?
|-
|<code>repository</code>
|A repository definition file that allows users to add new repositories to the XBMC addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of XBMC. Plugins appear under the relevant media section of the main home menu.
|'''Yes'''
|-
|<code>script</code>
|A runnable program file that will appear in the Program section of the main home menu.
|'''Yes'''
|-
|<code>skin</code>
|An XBMC skin definition and its supporting script files.
|No
|}

The following table describes the available <code>mediaType</code>s for the available add-on types. Your add-on may provide more than one <code>mediaType</code> 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.

{| class="wikitable" border="1"
!Add-on Type
!Media Type
! Description
|-
|<code>plugin</code>
|<code>audio</code>
|A music add-on that will appear in the Music main menu.
|-
|<code>plugin</code>
|<code>video</code>
|A video add-on that will appear in the Video main menu.
|-
|<code>plugin</code>
|<code>picture</code>
|A picture add-on that will appear in the Pictures main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu.
|-
|<code>script</code>
|<code>module</code>
|A script plugin that will not appear under a category or within the Add-ons manager, but provides support for other add-ons.
|-
|<code>script</code>
|<code>service</code>
|A script that will be run at either login or startup
|}

See section on [[Add-on development#addon.xml|addon.xml]] for further information

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 <code>plugin.audio.gpodder-xbmc3</code>. If you are creating a screen scraper to present TV shows from MyGreatTv.com. It might be <code>plugin.video.my-great-tv-com</code>. A script to ping all your friends on twitter to tell them you are home might be called
<code>script.service.ping-twits-i-am-home</code>.

== 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/
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 <code>lib/</code> folder. If those libs are commonly used by multiple add-ons, consider adding them as a separate add-on, e.g. <code>script.module.foo</code>.

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 <code>resources/</code> or one of its subdirectories.

=== 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 <code>[[addon.xml]]</code> as your main script file.

=== addon.xml ===

<code>addon.xml</code> tells XBMC
:* 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.)

More information on formatting can be found here: [[addon.xml]]

=== 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.)

=== 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 ===

See [[Official add-on repository#Repository guidelines|repository guidelines]].

=== resources/settings.xml ===

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. For more information about the format see [[Addon Settings]].

=== resources/language/ ===

'''Translation tools:'''
* [[Language support]]
* [[Translation System]]
* Convert .xml to .po: [https://github.com/alanwww1/xbmc-xml2po xbmc-xml2po]
* Check for .po files: [https://github.com/alanwww1/xbmc-checkpo 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 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'''

{{note|strings.xml will possibly be deprecated after the release of Frodo/Gotham. Frodo and Gotham will still be backwards compatible with .xml}}

=== 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 add-on – if you need fewer or more
directories to organise your work, just change it. Skins are add-ons that will require more directories than this.

== Getting started ==

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

* [[Python development]]
* [[Skinning]]

== See also ==
* [[Add-ons]]
* [[:Category:All add-ons]]
* [[3rd party add-on repositories]]
'''Development:'''
* [[Add-on development]]
* [[Addon Settings]]
* [[Python development]]
* [[Skinning]]
* [[Add-on repositories]]
* [[Official add-on repository]]

[[Category:Addon Development]]