Official Kodi Wiki - User contributions [en]

Addon.xml

2023-01-23T16:19:15Z

Enen92:

{{Mininav|[[Development]]|[[Add-on development]]}}
<div class="noautonum toclimit-7" style="background: none; clear: right; float: right; margin-bottom: 0.5em; padding: 0.5em 0 0.8em 1.4em; width: auto;">__TOC__</div>

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <samp>addon.xml</samp> file has the same basic structure, this example is for a video plugin:
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0" />
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/2013)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:
* The <syntaxhighlight lang="xml" inline><addon></syntaxhighlight> element must be present, and be the root node. It presents data about the add-on package as a whole. Inside it should be:
** A <syntaxhighlight lang="xml" inline><requires></syntaxhighlight> element, listing all the dependencies that this add-on needs in order to function inside individual <syntaxhighlight lang="xml" inline><import></syntaxhighlight> elements for each one.
** One or more <syntaxhighlight lang="xml" inline><extension></syntaxhighlight> elements, each of which describes a part of Kodi that the add-on extends.
*** Finally, there is a specific extension element, <syntaxhighlight lang="xml" inline><extension point="xbmc.addon.metadata"></syntaxhighlight> that describes the add-on to the user.
**** Image assets such as icons, a banner and screenshots declared inside their own named elements inside of an <syntaxhighlight lang="xml" inline><assets></syntaxhighlight> tag (exclusive to Kodi v18+)

== Core elements ==
=== <addon> ===
The <syntaxhighlight lang="xml" inline><addon></syntaxhighlight> element has 4 attributes, and they are all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>.

''Example'': <syntaxhighlight lang="xml" inline><addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2"></syntaxhighlight>

==== 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 <code><var>type</var>.<var>uniquename</var></code>.

==== version attribute ====
The version attribute is used by Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{Tip|Text should only be added for a beta 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 <syntaxhighlight lang="xml" inline><requires></syntaxhighlight> element contains one or more <syntaxhighlight lang="xml" inline><import></syntaxhighlight> 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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 <syntaxhighlight lang="xml" inline><requires></syntaxhighlight> block that imports two required modules:
<syntaxhighlight lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0" />
<import addon="script.module.elementtree" version="1.2.7" />
</requires>
</syntaxhighlight>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:
<syntaxhighlight lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0" />
</requires>
</syntaxhighlight>

==== <import> ====
Each <syntaxhighlight lang="xml" inline><import></syntaxhighlight> 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, Kodi 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 <syntaxhighlight lang="xml" inline><import></syntaxhighlight> element, since Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.
{| role="presentation" class="wikitable" style="border: 1px solid #000; border-collapse: collapse;"
|+ Current versions
! scope="col" | Kodi version
! scope="col" | xbmc.python
! scope="col" | xbmc.gui
! scope="col" | xbmc.json
! scope="col" | xbmc.metadata
! scope="col" | xbmc.addon
|-
! scope="row" | [[Archive:Dharma Guide|Dharma 10.1]] {{Red|Deprecated}}
| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
! scope="row" | [[Archive:Eden API changes|Eden 11.0]] {{Red|Deprecated}}
| 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
! scope="row" | [[Frodo|Frodo 12.x]] {{Red|Deprecated}}
| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
! scope="row" | [[Archive:Gotham API changes|Gotham 13.x]]
| 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 13.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Archive:Helix|Helix 14.x]]
| 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 14.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Archive:Isengard|Isengard 15.x]]
| 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 15.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Archive:Jarvis|Jarvis 16.x]]
| 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 16.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Archive:Krypton|Krypton 17.x]]
| 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Leia|Leia 18.x]]
| 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.9.910 (ABI 12.0.0)
|-
! scope="row" | [[Matrix|Matrix 19.x]]
| 3.0.0 (ABI 3.0.0) || 5.15.0 (ABI 5.14.0) || 11.2.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 19.1.0 (ABI 12.0.0)
|-
! scope="row" | [[Nexus|Nexus 20.x]]
| 3.0.1 (ABI 3.0.0) || 5.16.0 (ABI 5.15.0) || 13.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 20.90.101 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work on Leia 18.x. Same happens for Matrix and Nexus addons. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

===== 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 <syntaxhighlight lang="xml" inline><extension></syntaxhighlight> element describes the technical aspects of this add-on. It will have at least a point attribute which will give the part of Kodi 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.

==== point attribute ====
The various extension points that Kodi provides are given in the list below.
{| role="presentation" class="wikitable"
! scope="col" | Extension point
! scope="col" | Type declaration
|-
! scope="row" | <code>kodi.resource.font</code>
| [[Fonts|Additional fonts]]
|-
! scope="row" | <code>kodi.resource.images</code>
| Additional image files
|-
! scope="row" | <code>kodi.resource.language</code>
| [[Language support|Additional languages]]
|-
! scope="row" | <code>kodi.resource.uisounds</code>
| [[UI sounds add-ons|Additional UI event sounds]]
|-
! scope="row" | <code>[[:Category:Music add-ons|xbmc.addon.audio]]</code>
| [[:Category:Music add-ons|Music add-ons]] <small>(audio)</small>
|-
! scope="row" | <code>[[:Category:Picture add-ons|xbmc.addon.image]]</code>
| [[:Category:Picture add-ons|Picture add-ons]] <small>(images)</small>
|-
! scope="row" | <code>[[Add-on repositories|xbmc.addon.repository]]</code>
| [[Unofficial repositories]]
|-
! scope="row" | <code>[[:Category:Video add-ons|xbmc.addon.video]]</code>
| [[:Category:Video add-ons|Video add-ons]] <small>(video)</small>
|-
! scope="row" | <code>[[Skinning|xbmc.gui.skin]]</code>
| [[Skins]]
|-
! scope="row" | <code>[[:Category:Album scraper add-ons|xbmc.metadata.scraper.albums]]</code>
| [[Scraping Music#Albums|Album information]]
|-
! scope="row" | <code>[[:Category:Artist scraper add-ons|xbmc.metadata.scraper.artists]]</code>
| [[Scraping Music#Artists|Artist information]]
|-
! scope="row" | <code>[[:Category:Scraper|xbmc.metadata.scraper.library]]</code>
| [[Scrapers]]
|-
! scope="row" | <code>[[:Category:Movie scraper add-ons|xbmc.metadata.scraper.movies]]</code>
| Movie information
|-
! scope="row" | <code>[[:Category:Music video scraper add-ons|xbmc.metadata.scraper.musicvideos]]</code>
| [[Music videos|Music video information]]
|-
! scope="row" | <code>[[:Category:TV scraper add-ons|xbmc.metadata.scraper.tvshows]]</code>
| [[TV Shows|TV show information]]
|-
! scope="row" | <code>[[:Category:Music visualization add-ons|xbmc.player.musicviz]]</code>
| Music visualization
|-
! scope="row" | <code>[[:Category:Add-on libraries/modules|xbmc.python.library]]</code>
| [[Python libraries]] {{Note|These don't show up in the add-on browser and are purely to satisfy dependencies.}}
|-
! scope="row" | <code>[[:Category:Lyrics add-ons|xbmc.python.lyrics]]</code>
| [[Script lyrics|Lyrics]]
|-
! scope="row" | <code>[[:Category:Add-on libraries/modules|xbmc.python.module]]</code>
| [[Python development|Additional python library]], mainly for use by script.module add-ons.
|-
! scope="row" | <code>[[Plugin sources|xbmc.python.pluginsource]]</code>
| rowspan="2" | [[:Category:Music add-ons|Music add-ons]] <small>(audio)</small> / [[:Category:Picture add-ons|Picture add-ons]] <small>(images)</small> / [[:Category:Program add-ons|Program add-ons]] <small>(executables)</small> / [[:Category:Video add-ons|Video add-ons]] <small>(video)</small>
|-
! scope="row" | <code>[[Script sources|xbmc.python.script]]</code>
|-
! scope="row" | <code>[[Weather addons|xbmc.python.weather]]</code>
| [[Weather]]
|-
! scope="row" | <code>[[Service add-ons|xbmc.service]]</code>
| [[Service add-ons|Services]]
|-
! scope="row" | <code>[[:Category:Subtitle add-ons|xbmc.subtitle.module]]</code>
| [[Subtitles|Subtitle source]]
|-
! scope="row" | <code>[[:Category:Screensaver add-ons|xbmc.ui.screensaver]]</code>
| [[HOW-TO:Screensaver addon|Screensaver]]
|-
! scope="row" | <code>[[Web interface|xbmc.webinterface]]</code>
| [[Web interface]]
|}
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 <syntaxhighlight lang="xml" inline><extension point="xbmc.python.pluginsource"></syntaxhighlight> 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 <syntaxhighlight lang="xml" inline><provides></syntaxhighlight>, which contains a whitespace separated list of <code>audio</code>, <code>executable</code>, <code>image</code> and/or <code>video</code>. This determines in what area (or context) of the Kodi system your addon will make itself visible in (please note that this applies only to <kbd>pluginsource</kbd> extension points):
{| role="presentation" class="wikitable" style="padding: 0.5em 1em;"
! scope="col" | Provides
! scope="col" | Appears in
|-
| <code>image</code>
| Pictures
|-
| <code>audio</code>
| Music
|-
| <code>video</code>
| Video
|-
| <code>executable</code>
| Programs
|-
| ''(blank)''
| See Note below
|}
{{Note|If the <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> element is not defined, behavior will depend on the structure of your add-on. If it has a single extension point (e.g. a single '''<code>xbmc.python.script</code>''' or '''<code>xbmc.python.pluginsource</code>'''), {{Kodi}} will default to <code>executable</code> (thus your add-on will be shown in Programs). If your add-on has multiple extension points and none specifies a <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> element, different entries for your add-on will be shown in "Programs" (multiple fallbacks to "executable"). If your add-on has multiple extension points and only one (or some) define the <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> tag it really depends on the order of the extension points. If the first extension point (your add-on's '''main extension point''') defines the <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> element, {{Kodi}} will assume all the other (empty) extension points provide the same content. Otherwise, it will set the content for all the extension points that specify the <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> tag and fallback all the others to "executable". '''At the moment, there is no way to hide an add-on from the interface.'''|Reminder}}

''Example'':
<syntaxhighlight lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</syntaxhighlight>

===== 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 Kodi add-on manager. There are several elements that this should contain. Most of these elements are required (except the deprecated tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file.

====== Localization ======
Language specific elements 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. The <code>lang</code> attribute should contain a [[wikipedia:Locale (computer software)|locale identifier]]. If omitted, it defaults to en_GB.
{{Note|Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]}}

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

''Example'': <syntaxhighlight lang="xml" inline><summary lang="en_GB">Hello World script provides some basic examples on how to create your first script.</summary></syntaxhighlight>

====== <description> ======
One or more <syntaxhighlight lang="xml" inline><description></syntaxhighlight> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

''Example'':
<syntaxhighlight lang="xml">
<description lang="en_GB">Hello World script provides some basic examples on how to create your first script and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</syntaxhighlight>

====== <disclaimer> ======
One or more <syntaxhighlight lang="xml" inline><disclaimer></syntaxhighlight> 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.

''Example'': <syntaxhighlight lang="xml" inline><disclaimer lang="en_GB">Feel free to use this script. For information visit the wiki.</disclaimer></syntaxhighlight>

====== <news> ======
{{Note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <syntaxhighlight lang="xml" inline><news></syntaxhighlight> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters); you might want to only include the changes for the last version here.

Here is an example:
<syntaxhighlight lang="xml">
<news>v0.1.2 (2014-01-15)
- Added notification for Ubuntu users checking through apt command</news>
</syntaxhighlight>

====== <platform> ======
The <syntaxhighlight lang="xml" inline><platform></syntaxhighlight> tag specifies which platforms (operating systems, hardware, architecture) 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 space-delimited combination of these is also possible. Currently available options are:
* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</code>

{{Note|Kodi v19 Matrix and later.}}

* <code>tvos</code>
* <code>tvos-aarch64</code>

''Example'': <syntaxhighlight lang="xml" inline><platform>linux osx-x86_64 windows-x86_64</platform></syntaxhighlight>

====== <language> ======
The <syntaxhighlight lang="xml" inline><language></syntaxhighlight> 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, omit it from the addon.xml.

''Example'': <syntaxhighlight lang="xml" inline><language>en de fr</language></syntaxhighlight>

====== <license> ======
The <syntaxhighlight lang="xml" inline><license></syntaxhighlight> element indicates what license is used for this add-on. In general, the [https://spdx.dev/ids/ SPDX License Expression] for the license(s) are preferable to the full license name:

''Examples'':<br />
SPDX License Expression: <syntaxhighlight lang="xml" inline><license>GPL-2.0-or-later</license></syntaxhighlight>
<br />vs<br />
Full license name: <syntaxhighlight lang="xml" inline><license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license></syntaxhighlight>

If your add-on includes multiple licenses:
* Separate license names using <code>|</code> (the pipe or vertical bar character) when there is a choice between licenses:
** <syntaxhighlight lang="xml" inline><license>GPL-2.0-or-later | LGPL-2.0-or-later</license></syntaxhighlight>
* Separate license names using <code>&</code> (ampersand), or <code>,</code> (comma), when multiple licenses exist that cover different parts of the source.
** <syntaxhighlight lang="xml" inline><license>GPL-2.0-or-later & MIT</license></syntaxhighlight>
** <syntaxhighlight lang="xml" inline><license>GPL-2.0-or-later, MIT</license></syntaxhighlight>

====== <forum> ======
The <syntaxhighlight lang="xml" inline><forum></syntaxhighlight> element provides the forum thread URL for this specific add-on. Omit this element if there is no forum thread.

''Example'': <syntaxhighlight lang="xml" inline><forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum></syntaxhighlight>

====== <website> ======
The <syntaxhighlight lang="xml" inline><website></syntaxhighlight> element provides the website URL for this specific add-on.

''Example'': <syntaxhighlight lang="xml" inline><website>https://www.myaddonwebsite.com/</website></syntaxhighlight>

====== <nowiki><source></nowiki> ======
The <syntaxhighlight lang="xml" inline><source></syntaxhighlight> element provides the URL for the source code for this specific add-on.

''Example'': <syntaxhighlight lang="xml" inline><source>https://github.com/someone/myaddon</source></syntaxhighlight>

====== <email> ======
The <syntaxhighlight lang="xml" inline><email></syntaxhighlight> element provides the e-mail address of the author, if they wish to do so for this specific add-on. Here are two examples of how you can format it (the second one is harder for spambots to scrape). This can be left blank if you do not wish to make your e-mail address public.

''Examples'':
* <syntaxhighlight lang="xml" inline><email>foo@bar.com</email></syntaxhighlight>
* <syntaxhighlight lang="xml" inline><email>foo at bar dot com</email></syntaxhighlight>

====== <lifecyclestate> ======
{{Note|Kodi v19 Matrix and later.}}

The <syntaxhighlight lang="xml" inline><lifecyclestate></syntaxhighlight> element will mark the add-on as broken or deprecated in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the add-on installed, so please try to be specific about the underlying reason for the tag. Also, the <syntaxhighlight lang="xml" inline><lifecyclestate></syntaxhighlight> tag presupposes that a version bump has been made to the add-on.

''Example'': <syntaxhighlight lang="xml" inline><lifecyclestate type="deprecated">Description why deprecated</lifecyclestate></syntaxhighlight>

At your discretion, it can also be translated into several languages.

<syntaxhighlight lang="xml" inline><lifecyclestate type="broken" lang="en_GB">Description why broken</lifecyclestate></syntaxhighlight>

{| class="wikitable"
|+ Valid values for <code>type</code> attribute
! scope="col" | Value
! scope="col" | Meaning
|-
! scope="row" | <code>broken</code>
| To mark add-on as broken and no more usable.
|-
! scope="row" | <code>deprecated</code>
| To mark add-on as deprecated and that it has been replaced by another add-on.
|-
! scope="row" | <code>normal</code>
| (Default) To set add-on as normal. This value is not really needed, but made available to be able to declare all possible life paths.
|}

====== <broken> ======
{{Note|Kodi v18 Leia and earlier. For Matrix and later, see [[Addon.xml#.3Clifecyclestate.3E|§ <lifecyclestate>]]}}

The <syntaxhighlight lang="xml" inline><broken></syntaxhighlight> element will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the underlying reason for the tag. Also, the broken tag presupposes that a version bump has been made to the add-on.

''Example'': <syntaxhighlight lang="xml" inline><broken>deprecated</broken></syntaxhighlight>

====== <assets> ======
{{Note|Kodi v17 Krypton and later.}}

The <syntaxhighlight lang="xml" inline><assets></syntaxhighlight> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:
* <syntaxhighlight lang="xml" inline><icon></syntaxhighlight> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <syntaxhighlight lang="xml" inline><fanart></syntaxhighlight> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <syntaxhighlight lang="xml" inline><screenshot></syntaxhighlight> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{Note|Kodi v18 Leia and later.}}
* <syntaxhighlight lang="xml" inline><banner></syntaxhighlight> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <syntaxhighlight lang="xml" inline><clearlogo></syntaxhighlight> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, they will be treated as non-existent/not provided. Of all the above sub-elements, only <syntaxhighlight lang="xml" inline><icon></syntaxhighlight> and <syntaxhighlight lang="xml" inline><fanart></syntaxhighlight> are mandatory for add-ons since Kodi v17 Krypton and later.

''Example'':
<syntaxhighlight lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</syntaxhighlight>

With the above example definition, the files must be placed in the <code>resources</code> folder.

====== <reuselanguageinvoker> ======
{{Note|Kodi v18 Leia and later.}}

The <syntaxhighlight lang="xml" inline><reuselanguageinvoker></syntaxhighlight> element is a feature introduced with Kodi 18.0 "Leia" that changes the way the Python invoker works - specifically, attempting to reuse the invoker instances as much as possible. As a result, the add-on performance should be greatly improved. However, note that for the element to work, some changes may be required in your add-on. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do ''not'' store it as a class variable.

''Example'': <syntaxhighlight lang="xml" inline><reuselanguageinvoker>true</reuselanguageinvoker></syntaxhighlight>

Furthermore, it is advised to set this element to <code>false</code> while developing the add-on, only setting its value to <code>true</code> for the production version (after testing).

== Skin-specific elements ==
{| class="wikitable"
! scope="row" | <syntaxhighlight lang="xml" inline><effectslowdown></syntaxhighlight>
| A multiplier that is applied to all <syntaxhighlight lang="xml" inline><animation></syntaxhighlight> effects lengths in the skin; useful for globally slowing down all animations so that you can better configure timings and see interactions between animating controls.
|-
! scope="row" | <syntaxhighlight lang="xml" inline><debugging></syntaxhighlight>
| When set to <code>true</code>, it will display on-screen debugging information (XML filename, mouse position and focused control type/name) on top of the skin.
|-
! scope="row" | <syntaxhighlight lang="xml" inline><res></syntaxhighlight>
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===
Kodi can run in many different resolutions, and a skin should try and cater to all of them. The easiest way is to develop for one specific resolution and make sure that all controls contain <syntaxhighlight lang="xml" inline><width></syntaxhighlight> and <syntaxhighlight lang="xml" inline><height></syntaxhighlight> tags. That way, Kodi 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 4:3 aspect ratios).

The order that Kodi looks for it's skin files are as follows:
# It first looks in the current <code>screenmode</code> folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current <code>screenmode</code> is 1080i and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''<code>res</code>''' folder.

This allows you to just put any window files that do not require special treatment for 16:9 aspect ratios, etc., in the <syntaxhighlight lang="xml" inline><defaultresolution></syntaxhighlight> folder, preventing needless repetition.

== Examples ==
=== Skin add-on ===
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="3.0.10" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.16.0" />
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<platform>all</platform>
<license>CC BY-SA 4.0, GNU GENERAL PUBLIC LICENSE Version 2.0</license>
<forum>https://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/xbmc/tree/master/addons/skin.estuary</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that {{Red|all tag names are lower case}}. XML tag names are case-sensitive!

=== Script add-on ===
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="script.artwork.downloader" name="Artwork Downloader" version="12.0.28" provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0" />
<import addon="xmbc.json" version="6.0.0" />
<import addon="xbmc.addon" version="12.0.0" />
<import addon="script.module.simplejson" version="3.3.0" />
<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.addon.metadata">
<summary lang="en_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the XBMC forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=114633</forum>
<website>https://kodi.wiki/view/Add-on:Artwork_Downloader</website>
<email>Martijn@kodi.tv</email>
<source>https://github.com/XBMC-Addons/script.artwork.downloader</source>
<news>
v12.0.28
- Don't set simplejson module to optional
v12.0.27
- Fix wrong order of listing using votes for artwork from fanart.tv
…
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

== Common errors ==
If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:
# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
#* .kodi/addons/temp
#* .kodi/temp/temp
#* .kodi/temp/archive_cache

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

{{Updated|20}}

[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Python]]

Nexus

2023-01-23T15:53:08Z

Enen92: Created page with "Nexus is the codename for the v20 release of Kodi."

Nexus is the codename for the v20 release of Kodi.

Addon.xml

2023-01-23T15:52:25Z

Enen92: Add nexus branch

{{Mininav|[[Development]]|[[Add-on development]]}}
<div class="noautonum toclimit-7" style="background: none; clear: right; float: right; margin-bottom: 0.5em; padding: 0.5em 0 0.8em 1.4em; width: auto;">__TOC__</div>

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <samp>addon.xml</samp> file has the same basic structure, this example is for a video plugin:
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0" />
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/2013)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:
* The <syntaxhighlight lang="xml" inline><addon></syntaxhighlight> element must be present, and be the root node. It presents data about the add-on package as a whole. Inside it should be:
** A <syntaxhighlight lang="xml" inline><requires></syntaxhighlight> element, listing all the dependencies that this add-on needs in order to function inside individual <syntaxhighlight lang="xml" inline><import></syntaxhighlight> elements for each one.
** One or more <syntaxhighlight lang="xml" inline><extension></syntaxhighlight> elements, each of which describes a part of Kodi that the add-on extends.
*** Finally, there is a specific extension element, <syntaxhighlight lang="xml" inline><extension point="xbmc.addon.metadata"></syntaxhighlight> that describes the add-on to the user.
**** Image assets such as icons, a banner and screenshots declared inside their own named elements inside of an <syntaxhighlight lang="xml" inline><assets></syntaxhighlight> tag (exclusive to Kodi v18+)

== Core elements ==
=== <addon> ===
The <syntaxhighlight lang="xml" inline><addon></syntaxhighlight> element has 4 attributes, and they are all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>.

''Example'': <syntaxhighlight lang="xml" inline><addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2"></syntaxhighlight>

==== 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 <code><var>type</var>.<var>uniquename</var></code>.

==== version attribute ====
The version attribute is used by Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{Tip|Text should only be added for a beta 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 <syntaxhighlight lang="xml" inline><requires></syntaxhighlight> element contains one or more <syntaxhighlight lang="xml" inline><import></syntaxhighlight> 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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 <syntaxhighlight lang="xml" inline><requires></syntaxhighlight> block that imports two required modules:
<syntaxhighlight lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0" />
<import addon="script.module.elementtree" version="1.2.7" />
</requires>
</syntaxhighlight>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:
<syntaxhighlight lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0" />
</requires>
</syntaxhighlight>

==== <import> ====
Each <syntaxhighlight lang="xml" inline><import></syntaxhighlight> 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, Kodi 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 <syntaxhighlight lang="xml" inline><import></syntaxhighlight> element, since Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.
{| role="presentation" class="wikitable" style="border: 1px solid #000; border-collapse: collapse;"
|+ Current versions
! scope="col" | Kodi version
! scope="col" | xbmc.python
! scope="col" | xbmc.gui
! scope="col" | xbmc.json
! scope="col" | xbmc.metadata
! scope="col" | xbmc.addon
|-
! scope="row" | [[Archive:Dharma Guide|Dharma 10.1]] {{Red|Deprecated}}
| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
! scope="row" | [[Archive:Eden API changes|Eden 11.0]] {{Red|Deprecated}}
| 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
! scope="row" | [[Frodo|Frodo 12.x]] {{Red|Deprecated}}
| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
! scope="row" | [[Archive:Gotham API changes|Gotham 13.x]]
| 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 13.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Archive:Helix|Helix 14.x]]
| 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 14.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Archive:Isengard|Isengard 15.x]]
| 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 15.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Archive:Jarvis|Jarvis 16.x]]
| 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 16.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Archive:Krypton|Krypton 17.x]]
| 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.0.0 (ABI 12.0.0)
|-
! scope="row" | [[Leia|Leia 18.x]]
| 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.9.910 (ABI 12.0.0)
|-
! scope="row" | [[Matrix|Matrix 19.x]]
| 3.0.0 (ABI 3.0.0) || 5.15.0 (ABI 5.14.0) || 11.2.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 19.1.0 (ABI 12.0.0)
|-
! scope="row" | [[Nexus|Nexus 20.x]]
| 3.0.1 (ABI 3.0.0) || 5.16.0 (ABI 5.15.0) || 13.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 20.90.101 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work on Leia 18.x. Same happens for Matrix and Nexus addons. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

===== 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 <syntaxhighlight lang="xml" inline><extension></syntaxhighlight> element describes the technical aspects of this add-on. It will have at least a point attribute which will give the part of Kodi 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.

==== point attribute ====
The various extension points that Kodi provides are given in the list below.
{| role="presentation" class="wikitable"
! scope="col" | Extension point
! scope="col" | Type declaration
|-
! scope="row" | <code>kodi.resource.font</code>
| [[Fonts|Additional fonts]]
|-
! scope="row" | <code>kodi.resource.images</code>
| Additional image files
|-
! scope="row" | <code>kodi.resource.language</code>
| [[Language support|Additional languages]]
|-
! scope="row" | <code>kodi.resource.uisounds</code>
| [[UI sounds add-ons|Additional UI event sounds]]
|-
! scope="row" | <code>[[:Category:Music add-ons|xbmc.addon.audio]]</code>
| [[:Category:Music add-ons|Music add-ons]] <small>(audio)</small>
|-
! scope="row" | <code>[[:Category:Picture add-ons|xbmc.addon.image]]</code>
| [[:Category:Picture add-ons|Picture add-ons]] <small>(images)</small>
|-
! scope="row" | <code>[[Add-on repositories|xbmc.addon.repository]]</code>
| [[Unofficial repositories]]
|-
! scope="row" | <code>[[:Category:Video add-ons|xbmc.addon.video]]</code>
| [[:Category:Video add-ons|Video add-ons]] <small>(video)</small>
|-
! scope="row" | <code>[[Skinning|xbmc.gui.skin]]</code>
| [[Skins]]
|-
! scope="row" | <code>[[:Category:Album scraper add-ons|xbmc.metadata.scraper.albums]]</code>
| [[Scraping Music#Albums|Album information]]
|-
! scope="row" | <code>[[:Category:Artist scraper add-ons|xbmc.metadata.scraper.artists]]</code>
| [[Scraping Music#Artists|Artist information]]
|-
! scope="row" | <code>[[:Category:Scraper|xbmc.metadata.scraper.library]]</code>
| [[Scrapers]]
|-
! scope="row" | <code>[[:Category:Movie scraper add-ons|xbmc.metadata.scraper.movies]]</code>
| Movie information
|-
! scope="row" | <code>[[:Category:Music video scraper add-ons|xbmc.metadata.scraper.musicvideos]]</code>
| [[Music videos|Music video information]]
|-
! scope="row" | <code>[[:Category:TV scraper add-ons|xbmc.metadata.scraper.tvshows]]</code>
| [[TV Shows|TV show information]]
|-
! scope="row" | <code>[[:Category:Music visualization add-ons|xbmc.player.musicviz]]</code>
| Music visualization
|-
! scope="row" | <code>[[:Category:Add-on libraries/modules|xbmc.python.library]]</code>
| [[Python libraries]] {{Note|These don't show up in the add-on browser and are purely to satisfy dependencies.}}
|-
! scope="row" | <code>[[:Category:Lyrics add-ons|xbmc.python.lyrics]]</code>
| [[Script lyrics|Lyrics]]
|-
! scope="row" | <code>[[:Category:Add-on libraries/modules|xbmc.python.module]]</code>
| [[Python development|Additional python library]], mainly for use by script.module add-ons.
|-
! scope="row" | <code>[[Plugin sources|xbmc.python.pluginsource]]</code>
| rowspan="2" | [[:Category:Music add-ons|Music add-ons]] <small>(audio)</small> / [[:Category:Picture add-ons|Picture add-ons]] <small>(images)</small> / [[:Category:Program add-ons|Program add-ons]] <small>(executables)</small> / [[:Category:Video add-ons|Video add-ons]] <small>(video)</small>
|-
! scope="row" | <code>[[Script sources|xbmc.python.script]]</code>
|-
! scope="row" | <code>[[Weather addons|xbmc.python.weather]]</code>
| [[Weather]]
|-
! scope="row" | <code>[[Service add-ons|xbmc.service]]</code>
| [[Service add-ons|Services]]
|-
! scope="row" | <code>[[:Category:Subtitle add-ons|xbmc.subtitle.module]]</code>
| [[Subtitles|Subtitle source]]
|-
! scope="row" | <code>[[:Category:Screensaver add-ons|xbmc.ui.screensaver]]</code>
| [[HOW-TO:Screensaver addon|Screensaver]]
|-
! scope="row" | <code>[[Web interface|xbmc.webinterface]]</code>
| [[Web interface]]
|}
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 <syntaxhighlight lang="xml" inline><extension point="xbmc.python.pluginsource"></syntaxhighlight> 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 <syntaxhighlight lang="xml" inline><provides></syntaxhighlight>, which contains a whitespace separated list of <code>audio</code>, <code>executable</code>, <code>image</code> and/or <code>video</code>. This determines in what area (or context) of the Kodi system your addon will make itself visible in (please note that this applies only to <kbd>pluginsource</kbd> extension points):
{| role="presentation" class="wikitable" style="padding: 0.5em 1em;"
! scope="col" | Provides
! scope="col" | Appears in
|-
| <code>image</code>
| Pictures
|-
| <code>audio</code>
| Music
|-
| <code>video</code>
| Video
|-
| <code>executable</code>
| Programs
|-
| ''(blank)''
| See Note below
|}
{{Note|If the <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> element is not defined, behavior will depend on the structure of your add-on. If it has a single extension point (e.g. a single '''<code>xbmc.python.script</code>''' or '''<code>xbmc.python.pluginsource</code>'''), {{Kodi}} will default to <code>executable</code> (thus your add-on will be shown in Programs). If your add-on has multiple extension points and none specifies a <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> element, different entries for your add-on will be shown in "Programs" (multiple fallbacks to "executable"). If your add-on has multiple extension points and only one (or some) define the <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> tag it really depends on the order of the extension points. If the first extension point (your add-on's '''main extension point''') defines the <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> element, {{Kodi}} will assume all the other (empty) extension points provide the same content. Otherwise, it will set the content for all the extension points that specify the <syntaxhighlight lang="xml" inline><provides></syntaxhighlight> tag and fallback all the others to "executable". '''At the moment, there is no way to hide an add-on from the interface.'''|Reminder}}

''Example'':
<syntaxhighlight lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</syntaxhighlight>

===== 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 Kodi add-on manager. There are several elements that this should contain. Most of these elements are required (except the deprecated tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file.

====== Localization ======
Language specific elements 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. The <code>lang</code> attribute should contain a [[wikipedia:Locale (computer software)|locale identifier]]. If omitted, it defaults to en_GB.
{{Note|Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]}}

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

''Example'': <syntaxhighlight lang="xml" inline><summary lang="en_GB">Hello World script provides some basic examples on how to create your first script.</summary></syntaxhighlight>

====== <description> ======
One or more <syntaxhighlight lang="xml" inline><description></syntaxhighlight> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

''Example'':
<syntaxhighlight lang="xml">
<description lang="en_GB">Hello World script provides some basic examples on how to create your first script and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</syntaxhighlight>

====== <disclaimer> ======
One or more <syntaxhighlight lang="xml" inline><disclaimer></syntaxhighlight> 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.

''Example'': <syntaxhighlight lang="xml" inline><disclaimer lang="en_GB">Feel free to use this script. For information visit the wiki.</disclaimer></syntaxhighlight>

====== <news> ======
{{Note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <syntaxhighlight lang="xml" inline><news></syntaxhighlight> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters); you might want to only include the changes for the last version here.

Here is an example:
<syntaxhighlight lang="xml">
<news>v0.1.2 (2014-01-15)
- Added notification for Ubuntu users checking through apt command</news>
</syntaxhighlight>

====== <platform> ======
The <syntaxhighlight lang="xml" inline><platform></syntaxhighlight> tag specifies which platforms (operating systems, hardware, architecture) 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 space-delimited combination of these is also possible. Currently available options are:
* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</code>

{{Note|Kodi v19 Matrix and later.}}

* <code>tvos</code>
* <code>tvos-aarch64</code>

''Example'': <syntaxhighlight lang="xml" inline><platform>linux osx-x86_64 windows-x86_64</platform></syntaxhighlight>

====== <language> ======
The <syntaxhighlight lang="xml" inline><language></syntaxhighlight> 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, omit it from the addon.xml.

''Example'': <syntaxhighlight lang="xml" inline><language>en de fr</language></syntaxhighlight>

====== <license> ======
The <syntaxhighlight lang="xml" inline><license></syntaxhighlight> element indicates what license is used for this add-on. In general, the [https://spdx.dev/ids/ SPDX License Expression] for the license(s) are preferable to the full license name:

''Examples'':<br />
SPDX License Expression: <syntaxhighlight lang="xml" inline><license>GPL-2.0-or-later</license></syntaxhighlight>
<br />vs<br />
Full license name: <syntaxhighlight lang="xml" inline><license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license></syntaxhighlight>

If your add-on includes multiple licenses:
* Separate license names using <code>|</code> (the pipe or vertical bar character) when there is a choice between licenses:
** <syntaxhighlight lang="xml" inline><license>GPL-2.0-or-later | LGPL-2.0-or-later</license></syntaxhighlight>
* Separate license names using <code>&</code> (ampersand), or <code>,</code> (comma), when multiple licenses exist that cover different parts of the source.
** <syntaxhighlight lang="xml" inline><license>GPL-2.0-or-later & MIT</license></syntaxhighlight>
** <syntaxhighlight lang="xml" inline><license>GPL-2.0-or-later, MIT</license></syntaxhighlight>

====== <forum> ======
The <syntaxhighlight lang="xml" inline><forum></syntaxhighlight> element provides the forum thread URL for this specific add-on. Omit this element if there is no forum thread.

''Example'': <syntaxhighlight lang="xml" inline><forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum></syntaxhighlight>

====== <website> ======
The <syntaxhighlight lang="xml" inline><website></syntaxhighlight> element provides the website URL for this specific add-on.

''Example'': <syntaxhighlight lang="xml" inline><website>https://www.myaddonwebsite.com/</website></syntaxhighlight>

====== <nowiki><source></nowiki> ======
The <syntaxhighlight lang="xml" inline><source></syntaxhighlight> element provides the URL for the source code for this specific add-on.

''Example'': <syntaxhighlight lang="xml" inline><source>https://github.com/someone/myaddon</source></syntaxhighlight>

====== <email> ======
The <syntaxhighlight lang="xml" inline><email></syntaxhighlight> element provides the e-mail address of the author, if they wish to do so for this specific add-on. Here are two examples of how you can format it (the second one is harder for spambots to scrape). This can be left blank if you do not wish to make your e-mail address public.

''Examples'':
* <syntaxhighlight lang="xml" inline><email>foo@bar.com</email></syntaxhighlight>
* <syntaxhighlight lang="xml" inline><email>foo at bar dot com</email></syntaxhighlight>

====== <lifecyclestate> ======
{{Note|Kodi v19 Matrix and later.}}

The <syntaxhighlight lang="xml" inline><lifecyclestate></syntaxhighlight> element will mark the add-on as broken or deprecated in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the add-on installed, so please try to be specific about the underlying reason for the tag. Also, the <syntaxhighlight lang="xml" inline><lifecyclestate></syntaxhighlight> tag presupposes that a version bump has been made to the add-on.

''Example'': <syntaxhighlight lang="xml" inline><lifecyclestate type="deprecated">Description why deprecated</lifecyclestate></syntaxhighlight>

At your discretion, it can also be translated into several languages.

<syntaxhighlight lang="xml" inline><lifecyclestate type="broken" lang="en_GB">Description why broken</lifecyclestate></syntaxhighlight>

{| class="wikitable"
|+ Valid values for <code>type</code> attribute
! scope="col" | Value
! scope="col" | Meaning
|-
! scope="row" | <code>broken</code>
| To mark add-on as broken and no more usable.
|-
! scope="row" | <code>deprecated</code>
| To mark add-on as deprecated and that it has been replaced by another add-on.
|-
! scope="row" | <code>normal</code>
| (Default) To set add-on as normal. This value is not really needed, but made available to be able to declare all possible life paths.
|}

====== <broken> ======
{{Note|Kodi v18 Leia and earlier. For Matrix and later, see [[Addon.xml#.3Clifecyclestate.3E|§ <lifecyclestate>]]}}

The <syntaxhighlight lang="xml" inline><broken></syntaxhighlight> element will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the underlying reason for the tag. Also, the broken tag presupposes that a version bump has been made to the add-on.

''Example'': <syntaxhighlight lang="xml" inline><broken>deprecated</broken></syntaxhighlight>

====== <assets> ======
{{Note|Kodi v17 Krypton and later.}}

The <syntaxhighlight lang="xml" inline><assets></syntaxhighlight> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:
* <syntaxhighlight lang="xml" inline><icon></syntaxhighlight> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <syntaxhighlight lang="xml" inline><fanart></syntaxhighlight> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <syntaxhighlight lang="xml" inline><screenshot></syntaxhighlight> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{Note|Kodi v18 Leia and later.}}
* <syntaxhighlight lang="xml" inline><banner></syntaxhighlight> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <syntaxhighlight lang="xml" inline><clearlogo></syntaxhighlight> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, they will be treated as non-existent/not provided. Of all the above sub-elements, only <syntaxhighlight lang="xml" inline><icon></syntaxhighlight> and <syntaxhighlight lang="xml" inline><fanart></syntaxhighlight> are mandatory for add-ons since Kodi v17 Krypton and later.

''Example'':
<syntaxhighlight lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</syntaxhighlight>

With the above example definition, the files must be placed in the <code>resources</code> folder.

====== <reuselanguageinvoker> ======
{{Note|Kodi v18 Leia and later.}}

The <syntaxhighlight lang="xml" inline><reuselanguageinvoker></syntaxhighlight> element is a feature introduced with Kodi 18.0 "Leia" that changes the way the Python invoker works - specifically, attempting to reuse the invoker instances as much as possible. As a result, the add-on performance should be greatly improved. However, note that for the element to work, some changes may be required in your add-on. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do ''not'' store it as a class variable.

''Example'': <syntaxhighlight lang="xml" inline><reuselanguageinvoker>true</reuselanguageinvoker></syntaxhighlight>

Furthermore, it is advised to set this element to <code>false</code> while developing the add-on, only setting its value to <code>true</code> for the production version (after testing).

== Skin-specific elements ==
{| class="wikitable"
! scope="row" | <syntaxhighlight lang="xml" inline><effectslowdown></syntaxhighlight>
| A multiplier that is applied to all <syntaxhighlight lang="xml" inline><animation></syntaxhighlight> effects lengths in the skin; useful for globally slowing down all animations so that you can better configure timings and see interactions between animating controls.
|-
! scope="row" | <syntaxhighlight lang="xml" inline><debugging></syntaxhighlight>
| When set to <code>true</code>, it will display on-screen debugging information (XML filename, mouse position and focused control type/name) on top of the skin.
|-
! scope="row" | <syntaxhighlight lang="xml" inline><res></syntaxhighlight>
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===
Kodi can run in many different resolutions, and a skin should try and cater to all of them. The easiest way is to develop for one specific resolution and make sure that all controls contain <syntaxhighlight lang="xml" inline><width></syntaxhighlight> and <syntaxhighlight lang="xml" inline><height></syntaxhighlight> tags. That way, Kodi 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 4:3 aspect ratios).

The order that Kodi looks for it's skin files are as follows:
# It first looks in the current <code>screenmode</code> folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current <code>screenmode</code> is 1080i and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''<code>res</code>''' folder.

This allows you to just put any window files that do not require special treatment for 16:9 aspect ratios, etc., in the <syntaxhighlight lang="xml" inline><defaultresolution></syntaxhighlight> folder, preventing needless repetition.

== Examples ==
=== Skin add-on ===
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="3.0.10" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.16.0" />
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<platform>all</platform>
<license>CC BY-SA 4.0, GNU GENERAL PUBLIC LICENSE Version 2.0</license>
<forum>https://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/xbmc/tree/master/addons/skin.estuary</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that {{Red|all tag names are lower case}}. XML tag names are case-sensitive!

=== Script add-on ===
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="script.artwork.downloader" name="Artwork Downloader" version="12.0.28" provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0" />
<import addon="xmbc.json" version="6.0.0" />
<import addon="xbmc.addon" version="12.0.0" />
<import addon="script.module.simplejson" version="3.3.0" />
<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.addon.metadata">
<summary lang="en_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the XBMC forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=114633</forum>
<website>https://kodi.wiki/view/Add-on:Artwork_Downloader</website>
<email>Martijn@kodi.tv</email>
<source>https://github.com/XBMC-Addons/script.artwork.downloader</source>
<news>
v12.0.28
- Don't set simplejson module to optional
v12.0.27
- Fix wrong order of listing using votes for artwork from fanart.tv
…
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

== Common errors ==
If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:
# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
#* .kodi/addons/temp
#* .kodi/temp/temp
#* .kodi/temp/archive_cache

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

{{Updated|19}}

[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Python]]

Internet video and audio streams

2022-09-07T22:28:59Z

Enen92:

{{mininav|[[Video library]] {{l2| [[Music library]] }} }}
{{see also|Add-ons}}
<section begin="intro" />Various internet video and audio streams can be played back in Kodi as if they were locally stored on your media center by using STRM files. As long as the format and streaming-method (network-protocol) is supported by Kodi, stream can be added. These are basic text files that look like <name>.strm and contain a URL to the internet stream. STRM files can also be added to the [[video library]] and can have cover art, summaries, etc.

Some internet sites may have an add-on available that can also access these media streams, rather than having to manually create STRM files. See '''[[Add-ons]]''' for more information on how to find and install add-ons.<section end="intro" />

== Playing Internet Streams ==
There are two ways this can be done, either via a custom .STRM file or a standard [[playlists]] (.PLS or .M3U).

=== The .STRM file method: ===
Create a normal text-file and rename the '''.txt''' extension to '''.strm''' then open it up with a text-editor (like Notepad in Microsoft Windows) and input the the '''direct URL-link''' of the stream.
:This should look like:
'''<nowiki>http://host/path/stream</nowiki>'''
:or
'''<nowiki>mms://host/path/stream</nowiki>'''
:or
'''<nowiki>rtsp://host/path/stream</nowiki>'''
Other protocols are supported such as '''<nowiki>http://host/path/to/somefile.mp3.</nowiki>'''
Then save/copy the .strm file to somewhere where you can open it from Kodi, (like on a SMB/SAMBA, XBMS or UPnP share, or just your local hard drive), like you would with any video/audio file. Open it using '''play''' in Kodi under Videos (if it is a video stream) or Music (if it is an audio stream). If the video stream does not work then the URL-link could be wrong, or possibly the codec/format or the network-protocol it uses it not supported by Kodi.

If you are creating a list of playlists (for example internal and external Shoutcast streams), save the pls or strm files into a directory accessible by Kodi and add the directory as the source, '''not''' the files themselves.

==== Property support: ====

strm files support passing additional properties to affect playback. This is the case for choosing specific [[Category:Input_stream_add-ons|inputstream addons]] or selecting specific protocol based properties. They usually take the form of:

<syntaxhighlight lang="xml">
#KODIPROP:key=value
protocol://host/path/stream
</syntaxhighlight>

where key is the property key and value is the property value.

'''Note''': From Kodi v20 you can affect the rtsp transport protocol by defining the rtsp_transport property. For example, to force tcp transport mode:
<syntaxhighlight lang="xml">
#KODIPROP:rtsp_transport=tcp
rtsp://host:port/mystream
</syntaxhighlight>

=== The standard playlists (.PLS or .M3U) method: ===
Download a supported playlist (like .PLS or .M3U) file from the internet, (these playlist files can often be found on the website of the web-radio stations or TV web-casts websites). For example stream.pls or something else, (you can rename it to whatever you want but keep the same extension). Then save/copy the file to somewhere where you can open it from Kodi, like you would with any video/audio file. You should be able to play the file in Kodi by selecting it ether from Videos -> Files or from the Music "file mode".

If the video stream does not work then the URL-link could be wrong, or possible the codec/format or the network-protocol it uses it not supported by Kodi. You can check and edit playlists with a normal text-editor (like Notepad in Microsoft Windows) and see what the URLs look like.

== Adding STRM files to the library ==
You can associate meta-data, such as cover art and summaries, to a .strm file just like normal entries in a library by using an NFO file, just as you would for a normal video file.

{{Updated|19}}

[[Category:Manual]]
[[Category:Video library]]
[[Category:Music library]]

Internet video and audio streams

2022-09-07T22:28:10Z

Enen92:

{{mininav|[[Video library]] {{l2| [[Music library]] }} }}
{{see also|Add-ons}}
<section begin="intro" />Various internet video and audio streams can be played back in Kodi as if they were locally stored on your media center by using STRM files. As long as the format and streaming-method (network-protocol) is supported by Kodi, stream can be added. These are basic text files that look like <name>.strm and contain a URL to the internet stream. STRM files can also be added to the [[video library]] and can have cover art, summaries, etc.

Some internet sites may have an add-on available that can also access these media streams, rather than having to manually create STRM files. See '''[[Add-ons]]''' for more information on how to find and install add-ons.<section end="intro" />

== Playing Internet Streams ==
There are two ways this can be done, either via a custom .STRM file or a standard [[playlists]] (.PLS or .M3U).

=== The .STRM file method: ===
Create a normal text-file and rename the '''.txt''' extension to '''.strm''' then open it up with a text-editor (like Notepad in Microsoft Windows) and input the the '''direct URL-link''' of the stream.
:This should look like:
'''<nowiki>http://host/path/stream</nowiki>'''
:or
'''<nowiki>mms://host/path/stream</nowiki>'''
:or
'''<nowiki>rtsp://host/path/stream</nowiki>'''
Other protocols are supported such as '''<nowiki>http://host/path/to/somefile.mp3.</nowiki>'''
Then save/copy the .strm file to somewhere where you can open it from Kodi, (like on a SMB/SAMBA, XBMS or UPnP share, or just your local hard drive), like you would with any video/audio file. Open it using '''play''' in Kodi under Videos (if it is a video stream) or Music (if it is an audio stream). If the video stream does not work then the URL-link could be wrong, or possibly the codec/format or the network-protocol it uses it not supported by Kodi.

If you are creating a list of playlists (for example internal and external Shoutcast streams), save the pls or strm files into a directory accessible by Kodi and add the directory as the source, '''not''' the files themselves.

'''Property support:
'''
strm files support passing additional properties to affect playback. This is the case for choosing specific [[Category:Input_stream_add-ons|inputstream addons]] or selecting specific protocol based properties. They usually take the form of:

<syntaxhighlight lang="xml">
#KODIPROP:key=value
protocol://host/path/stream
</syntaxhighlight>

where key is the property key and value is the property value.

'''Note''': From Kodi v20 you can affect the rtsp transport protocol by defining the rtsp_transport property. For example, to force tcp transport mode:
<syntaxhighlight lang="xml">
#KODIPROP:rtsp_transport=tcp
rtsp://host:port/mystream
</syntaxhighlight>

=== The standard playlists (.PLS or .M3U) method: ===
Download a supported playlist (like .PLS or .M3U) file from the internet, (these playlist files can often be found on the website of the web-radio stations or TV web-casts websites). For example stream.pls or something else, (you can rename it to whatever you want but keep the same extension). Then save/copy the file to somewhere where you can open it from Kodi, like you would with any video/audio file. You should be able to play the file in Kodi by selecting it ether from Videos -> Files or from the Music "file mode".

If the video stream does not work then the URL-link could be wrong, or possible the codec/format or the network-protocol it uses it not supported by Kodi. You can check and edit playlists with a normal text-editor (like Notepad in Microsoft Windows) and see what the URLs look like.

== Adding STRM files to the library ==
You can associate meta-data, such as cover art and summaries, to a .strm file just like normal entries in a library by using an NFO file, just as you would for a normal video file.

{{Updated|19}}

[[Category:Manual]]
[[Category:Video library]]
[[Category:Music library]]

Internet video and audio streams

2022-09-07T22:27:39Z

Enen92:

{{mininav|[[Video library]] {{l2| [[Music library]] }} }}
{{see also|Add-ons}}
<section begin="intro" />Various internet video and audio streams can be played back in Kodi as if they were locally stored on your media center by using STRM files. As long as the format and streaming-method (network-protocol) is supported by Kodi, stream can be added. These are basic text files that look like <name>.strm and contain a URL to the internet stream. STRM files can also be added to the [[video library]] and can have cover art, summaries, etc.

Some internet sites may have an add-on available that can also access these media streams, rather than having to manually create STRM files. See '''[[Add-ons]]''' for more information on how to find and install add-ons.<section end="intro" />

== Playing Internet Streams ==
There are two ways this can be done, either via a custom .STRM file or a standard [[playlists]] (.PLS or .M3U).

=== The .STRM file method: ===
Create a normal text-file and rename the '''.txt''' extension to '''.strm''' then open it up with a text-editor (like Notepad in Microsoft Windows) and input the the '''direct URL-link''' of the stream.
:This should look like:
'''<nowiki>http://host/path/stream</nowiki>'''
:or
'''<nowiki>mms://host/path/stream</nowiki>'''
:or
'''<nowiki>rtsp://host/path/stream</nowiki>'''
Other protocols are supported such as '''<nowiki>http://host/path/to/somefile.mp3.</nowiki>'''
Then save/copy the .strm file to somewhere where you can open it from Kodi, (like on a SMB/SAMBA, XBMS or UPnP share, or just your local hard drive), like you would with any video/audio file. Open it using '''play''' in Kodi under Videos (if it is a video stream) or Music (if it is an audio stream). If the video stream does not work then the URL-link could be wrong, or possibly the codec/format or the network-protocol it uses it not supported by Kodi.

If you are creating a list of playlists (for example internal and external Shoutcast streams), save the pls or strm files into a directory accessible by Kodi and add the directory as the source, '''not''' the files themselves.

'''Property support:
'''
strm files support passing additional properties to affect playback. This is the case for choosing specific [[Category:Input_stream_add-ons|inputstream addons]] or selecting specific protocol based properties. They usually take the form of:

<syntaxhighlight lang="xml">
#KODIPROP:key=value
protocol://host/path/stream
</syntaxhighlight>

where key is the property key and value is the property value.

'''Note''': From Kodi v20 you can affect the rtsp transport protocol by defining the rtsp_transport property. For example, to force tcp transport mode:
<syntaxhighlight lang="xml">
#KODIPROP:rtsp_transport=tcp
rtsp://host:port/mystream
</syntaxhighlight>

=== The standard playlists (.PLS or .M3U) method: ===
Download a supported playlist (like .PLS or .M3U) file from the internet, (these playlist files can often be found on the website of the web-radio stations or TV web-casts websites). For example stream.pls or something else, (you can rename it to whatever you want but keep the same extension). Then save/copy the file to somewhere where you can open it from Kodi, like you would with any video/audio file. You should be able to play the file in Kodi by selecting it ether from Videos -> Files or from the Music "file mode".

If the video stream does not work then the URL-link could be wrong, or possible the codec/format or the network-protocol it uses it not supported by Kodi. You can check and edit playlists with a normal text-editor (like Notepad in Microsoft Windows) and see what the URLs look like.

== Adding STRM files to the library ==
You can associate meta-data, such as cover art and summaries, to a .strm file just like normal entries in a library by using an NFO file, just as you would for a normal video file.

{{Matrix updated}}

[[Category:Manual]]
[[Category:Video library]]
[[Category:Music library]]

Internet video and audio streams

2022-09-07T22:27:18Z

Enen92: Property support and v20 addition

{{mininav|[[Video library]] {{l2| [[Music library]] }} }}
{{see also|Add-ons}}
<section begin="intro" />Various internet video and audio streams can be played back in Kodi as if they were locally stored on your media center by using STRM files. As long as the format and streaming-method (network-protocol) is supported by Kodi, stream can be added. These are basic text files that look like <name>.strm and contain a URL to the internet stream. STRM files can also be added to the [[video library]] and can have cover art, summaries, etc.

Some internet sites may have an add-on available that can also access these media streams, rather than having to manually create STRM files. See '''[[Add-ons]]''' for more information on how to find and install add-ons.<section end="intro" />

== Playing Internet Streams ==
There are two ways this can be done, either via a custom .STRM file or a standard [[playlists]] (.PLS or .M3U).

=== The .STRM file method: ===
Create a normal text-file and rename the '''.txt''' extension to '''.strm''' then open it up with a text-editor (like Notepad in Microsoft Windows) and input the the '''direct URL-link''' of the stream.
:This should look like:
'''<nowiki>http://host/path/stream</nowiki>'''
:or
'''<nowiki>mms://host/path/stream</nowiki>'''
:or
'''<nowiki>rtsp://host/path/stream</nowiki>'''
Other protocols are supported such as '''<nowiki>http://host/path/to/somefile.mp3.</nowiki>'''
Then save/copy the .strm file to somewhere where you can open it from Kodi, (like on a SMB/SAMBA, XBMS or UPnP share, or just your local hard drive), like you would with any video/audio file. Open it using '''play''' in Kodi under Videos (if it is a video stream) or Music (if it is an audio stream). If the video stream does not work then the URL-link could be wrong, or possibly the codec/format or the network-protocol it uses it not supported by Kodi.

If you are creating a list of playlists (for example internal and external Shoutcast streams), save the pls or strm files into a directory accessible by Kodi and add the directory as the source, '''not''' the files themselves.

'''Property support:
'''
strm files support passing additional properties to affect playback. This is the case for choosing specific [[Category:Input_stream_add-ons|inputstream addons]] or selecting specific protocol based properties. They usually take the form of:

<syntaxhighlight lang="xml">
#KODIPROP:key=value
protocol://host/path/stream
</syntaxhighlight>

where key is the property key and value is the property value.

'''Note''': From Kodi v20 you can affect the rtsp transport protocol by defining the rtsp_transport property. For example, to force tcp transport mode:
<syntaxhighlight lang="xml">
#KODIPROP:rtsp_transport=tcp
rtsp://host:port/mystream
</syntaxhighlight>

=== The standard playlists (.PLS or .M3U) method: ===
Download a supported playlist (like .PLS or .M3U) file from the internet, (these playlist files can often be found on the website of the web-radio stations or TV web-casts websites). For example stream.pls or something else, (you can rename it to whatever you want but keep the same extension). Then save/copy the file to somewhere where you can open it from Kodi, like you would with any video/audio file. You should be able to play the file in Kodi by selecting it ether from Videos -> Files or from the Music "file mode".

If the video stream does not work then the URL-link could be wrong, or possible the codec/format or the network-protocol it uses it not supported by Kodi. You can check and edit playlists with a normal text-editor (like Notepad in Microsoft Windows) and see what the URLs look like.

== Adding STRM files to the library ==
You can associate meta-data, such as cover art and summaries, to a .strm file just like normal entries in a library by using an NFO file, just as you would for a normal video file.

{{Isengard updated}}

[[Category:Manual]]
[[Category:Video library]]
[[Category:Music library]]

Add-on repositories

2022-02-23T21:32:14Z

Enen92: Note about removal of old dharma compatible structure

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

Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
The repository functionality was first introduced in the Dharma version of Kodi (XBMC at the time)

After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.

== Ingredients for a Repository ==
Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

* An HTTP server. Any should work.
* Some add-ons.
* A master xml file. This file contains metadata about all available add-ons.
* A checksum of the above file.
* A repository add-on for distribution. This allows you to share your repository with others.

== Directory Structure ==
addon.id
addon.id-x.y.z.zip
...
addon2.id
addon2.id-x.y.z.zip
...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.

* addon.id should be the same as the addon's id, which is expected to be unique.
* x.y.z is the addon's version, the same should be listed in its version attribute.

== Addons.xml ==
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addon
id="sample.addon1"
...
</addon>

<addon
id="sample.addon2"
...
</addon>
</addons>
</syntaxhighlight>

== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<dir>
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>sha256</hashes>
</dir>
</extension>
</syntaxhighlight>

The dir block wraps the main repository directory information. You can have multiple dirs defined in the extension point. This can be useful to provide different directories depending on the kodi version as exemplified below:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository" name="Inputstream Adaptive Testing Repository">
<dir maxversion="18.9.0">
<info compressed="false">https://example.com/leia/addons.xml</info>
<checksum>https://example.com/leia/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/leia/</datadir>
<hashes>false</hashes>
</dir>
<dir minversion="19.0.0">
<info compressed="false">https://example.com/matrix/addons.xml</info>
<checksum>https://example.com/matrix/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/matrix/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

In the example above, the first directory will only be served to Kodi Leia while the second will only be served to the Matrix version of Kodi.
There's also another, simpler way to define a repository by adding all the dir items in the root of the extension element. Such definition was supported until Kodi Nexus (v20):

{{note|This was removed in Kodi v20}}

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</extension>
</syntaxhighlight>

=== dir ===
The dir element wraps all the other repository information elements such as info, checksum, datadir or hashes. It supports the additional attributes:
* '''minversion''': the minimum kodi version that supports this directory
* '''maxversion''': the maximum kodi version that supports this directory

{{note|both can be ommited}}

{{note|minversion and maxversion where introduced in Kodi Matrix (v19).}}

=== info ===
URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

=== checksum ===
A text file that identifies the content of <code><info></code>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

=== hashes ===
Hashes is used to control whether to transfer addon zips or not. Since kodi might already have a copy of the package stored locally, it will first issue an head request to the remote server and look for the "content-{hashesvalue}" HTTP header. It'll compare the provided hash (in base64) to the one stored in the database for the addon package. It will only transfer the package if the values differ.

Supported values:
* '''sha256'''
* '''sha512'''
* '''sha1'''
* '''md5'''

For historical reasons the values "false" and "true" are also supported. If "true" is supplied, kodi will default to md5. It's highly recommended '''not to use''' md5 as an option as a security countermeasure. It is somehow broken and only guards against unintentional data corruption.

== Security ==

We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

== Repository Tools ==

Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Add-on development]]

Add-on repositories

2022-02-23T11:25:28Z

Enen92: /* hashes */ documentation

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

Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
The repository functionality was first introduced in the Dharma version of Kodi (XBMC at the time)

After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.

== Ingredients for a Repository ==
Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

* An HTTP server. Any should work.
* Some add-ons.
* A master xml file. This file contains metadata about all available add-ons.
* A checksum of the above file.
* A repository add-on for distribution. This allows you to share your repository with others.

== Directory Structure ==
addon.id
addon.id-x.y.z.zip
...
addon2.id
addon2.id-x.y.z.zip
...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.

* addon.id should be the same as the addon's id, which is expected to be unique.
* x.y.z is the addon's version, the same should be listed in its version attribute.

== Addons.xml ==
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addon
id="sample.addon1"
...
</addon>

<addon
id="sample.addon2"
...
</addon>
</addons>
</syntaxhighlight>

== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<dir>
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>sha256</hashes>
</dir>
</extension>
</syntaxhighlight>

The dir block wraps the main repository directory information. You can have multiple dirs defined in the extension point. This can be useful to provide different directories depending on the kodi version as exemplified below:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository" name="Inputstream Adaptive Testing Repository">
<dir maxversion="18.9.0">
<info compressed="false">https://example.com/leia/addons.xml</info>
<checksum>https://example.com/leia/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/leia/</datadir>
<hashes>false</hashes>
</dir>
<dir minversion="19.0.0">
<info compressed="false">https://example.com/matrix/addons.xml</info>
<checksum>https://example.com/matrix/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/matrix/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

In the example above, the first directory will only be served to Kodi Leia while the second will only be served to the Matrix version of Kodi.
There's also another, simpler way to define a repository by adding all the dir items in the root of the extension element. Such alternative is not recommended and will probably be removed in a future kodi version:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</extension>
</syntaxhighlight>

=== dir ===
The dir element wraps all the other repository information elements such as info, checksum, datadir or hashes. It supports the additional attributes:
* '''minversion''': the minimum kodi version that supports this directory
* '''maxversion''': the maximum kodi version that supports this directory

{{note|both can be ommited}}

{{note|minversion and maxversion where introduced in Kodi Matrix (v19).}}

=== info ===
URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

=== checksum ===
A text file that identifies the content of <code><info></code>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

=== hashes ===
Hashes is used to control whether to transfer addon zips or not. Since kodi might already have a copy of the package stored locally, it will first issue an head request to the remote server and look for the "content-{hashesvalue}" HTTP header. It'll compare the provided hash (in base64) to the one stored in the database for the addon package. It will only transfer the package if the values differ.

Supported values:
* '''sha256'''
* '''sha512'''
* '''sha1'''
* '''md5'''

For historical reasons the values "false" and "true" are also supported. If "true" is supplied, kodi will default to md5. It's highly recommended '''not to use''' md5 as an option as a security countermeasure. It is somehow broken and only guards against unintentional data corruption.

== Security ==

We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

== Repository Tools ==

Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Add-on development]]

Add-on repositories

2022-02-23T11:07:32Z

Enen92: /* Repository Add-on */

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

Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
The repository functionality was first introduced in the Dharma version of Kodi (XBMC at the time)

After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.

== Ingredients for a Repository ==
Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

* An HTTP server. Any should work.
* Some add-ons.
* A master xml file. This file contains metadata about all available add-ons.
* A checksum of the above file.
* A repository add-on for distribution. This allows you to share your repository with others.

== Directory Structure ==
addon.id
addon.id-x.y.z.zip
...
addon2.id
addon2.id-x.y.z.zip
...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.

* addon.id should be the same as the addon's id, which is expected to be unique.
* x.y.z is the addon's version, the same should be listed in its version attribute.

== Addons.xml ==
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addon
id="sample.addon1"
...
</addon>

<addon
id="sample.addon2"
...
</addon>
</addons>
</syntaxhighlight>

== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<dir>
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>sha256</hashes>
</dir>
</extension>
</syntaxhighlight>

The dir block wraps the main repository directory information. You can have multiple dirs defined in the extension point. This can be useful to provide different directories depending on the kodi version as exemplified below:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository" name="Inputstream Adaptive Testing Repository">
<dir maxversion="18.9.0">
<info compressed="false">https://example.com/leia/addons.xml</info>
<checksum>https://example.com/leia/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/leia/</datadir>
<hashes>false</hashes>
</dir>
<dir minversion="19.0.0">
<info compressed="false">https://example.com/matrix/addons.xml</info>
<checksum>https://example.com/matrix/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/matrix/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

In the example above, the first directory will only be served to Kodi Leia while the second will only be served to the Matrix version of Kodi.
There's also another, simpler way to define a repository by adding all the dir items in the root of the extension element. Such alternative is not recommended and will probably be removed in a future kodi version:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</extension>
</syntaxhighlight>

=== dir ===
The dir element wraps all the other repository information elements such as info, checksum, datadir or hashes. It supports the additional attributes:
* '''minversion''': the minimum kodi version that supports this directory
* '''maxversion''': the maximum kodi version that supports this directory

{{note|both can be ommited}}

{{note|minversion and maxversion where introduced in Kodi Matrix (v19).}}

=== info ===
URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

=== checksum ===
A text file that identifies the content of <code><info></code>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

=== hashes ===
Todo

== Security ==

We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

== Repository Tools ==

Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Add-on development]]

Add-on repositories

2022-02-23T11:06:59Z

Enen92: /* Repository Add-on */

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

Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
The repository functionality was first introduced in the Dharma version of Kodi (XBMC at the time)

After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.

== Ingredients for a Repository ==
Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

* An HTTP server. Any should work.
* Some add-ons.
* A master xml file. This file contains metadata about all available add-ons.
* A checksum of the above file.
* A repository add-on for distribution. This allows you to share your repository with others.

== Directory Structure ==
addon.id
addon.id-x.y.z.zip
...
addon2.id
addon2.id-x.y.z.zip
...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.

* addon.id should be the same as the addon's id, which is expected to be unique.
* x.y.z is the addon's version, the same should be listed in its version attribute.

== Addons.xml ==
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addon
id="sample.addon1"
...
</addon>

<addon
id="sample.addon2"
...
</addon>
</addons>
</syntaxhighlight>

== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<dir>
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

The dir block wraps the main repository directory information. You can have multiple dirs defined in the extension point. This can be useful to provide different directories depending on the kodi version as exemplified below:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository" name="Inputstream Adaptive Testing Repository">
<dir maxversion="18.9.0">
<info compressed="false">https://example.com/leia/addons.xml</info>
<checksum>https://example.com/leia/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/leia/</datadir>
<hashes>false</hashes>
</dir>
<dir minversion="19.0.0">
<info compressed="false">https://example.com/matrix/addons.xml</info>
<checksum>https://example.com/matrix/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/matrix/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

In the example above, the first directory will only be served to Kodi Leia while the second will only be served to the Matrix version of Kodi.
There's also another, simpler way to define a repository by adding all the dir items in the root of the extension element. Such alternative is not recommended and will probably be removed in a future kodi version:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</extension>
</syntaxhighlight>

=== dir ===
The dir element wraps all the other repository information elements such as info, checksum, datadir or hashes. It supports the additional attributes:
* '''minversion''': the minimum kodi version that supports this directory
* '''maxversion''': the maximum kodi version that supports this directory

{{note|both can be ommited}}

{{note|minversion and maxversion where introduced in Kodi Matrix (v19).}}

=== info ===
URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

=== checksum ===
A text file that identifies the content of <code><info></code>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

=== hashes ===
Todo

== Security ==

We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

== Repository Tools ==

Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Add-on development]]

Add-on repositories

2022-02-23T11:05:50Z

Enen92: /* Repository Add-on */

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

Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
The repository functionality was first introduced in the Dharma version of Kodi (XBMC at the time)

After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.

== Ingredients for a Repository ==
Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

* An HTTP server. Any should work.
* Some add-ons.
* A master xml file. This file contains metadata about all available add-ons.
* A checksum of the above file.
* A repository add-on for distribution. This allows you to share your repository with others.

== Directory Structure ==
addon.id
addon.id-x.y.z.zip
...
addon2.id
addon2.id-x.y.z.zip
...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.

* addon.id should be the same as the addon's id, which is expected to be unique.
* x.y.z is the addon's version, the same should be listed in its version attribute.

== Addons.xml ==
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addon
id="sample.addon1"
...
</addon>

<addon
id="sample.addon2"
...
</addon>
</addons>
</syntaxhighlight>

== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<dir>
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

The dir block wraps the main repository directory information. You can have multiple dirs defined in the extension point. This can be useful to provide different directories depending on the kodi version as exemplified below:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository" name="Inputstream Adaptive Testing Repository">
<dir maxversion="18.9.0">
<info compressed="false">https://example.com/leia/addons.xml</info>
<checksum>https://example.com/leia/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/leia/</datadir>
<hashes>false</hashes>
</dir>
<dir minversion="19.0.0">
<info compressed="false">https://example.com/matrix/addons.xml</info>
<checksum>https://example.com/matrix/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/matrix/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

In the example above, the first directory will only be served to Kodi Leia while the second will only be served to the Matrix version of Kodi.
There's also another, simpler way to define a repository by adding all the dir items in the root of the extension element. Such alternative is not recommended and will probably be removed in a future kodi version:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</extension>
</syntaxhighlight>

=== dir ===
The dir element wraps all the other repository information elements such as info, checksum, datadir or hashes. It supports the additional attributes:
* '''minversion''': the minimum kodi version that supports this directory
* '''maxversion''': the maximum kodi version that supports this directory

{{note|both can be ommited}}

{{note|minversion and maxversion where introduced in Kodi Matrix (v19).}}

=== info ===
URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

=== checksum ===
A text file that identifies the content of <code><info></code>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

=== hashes ===
Todo

== Security ==

We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

== Repository Tools ==

Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Add-on development]]

Add-on repositories

2022-02-23T11:01:37Z

Enen92: Add {{updated|19}} label

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

Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
The repository functionality was first introduced in the Dharma version of Kodi (XBMC at the time)

After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.

== Ingredients for a Repository ==
Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

* An HTTP server. Any should work.
* Some add-ons.
* A master xml file. This file contains metadata about all available add-ons.
* A checksum of the above file.
* A repository add-on for distribution. This allows you to share your repository with others.

== Directory Structure ==
addon.id
addon.id-x.y.z.zip
...
addon2.id
addon2.id-x.y.z.zip
...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.

* addon.id should be the same as the addon's id, which is expected to be unique.
* x.y.z is the addon's version, the same should be listed in its version attribute.

== Addons.xml ==
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addon
id="sample.addon1"
...
</addon>

<addon
id="sample.addon2"
...
</addon>
</addons>
</syntaxhighlight>

== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<dir>
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

The dir block wraps the main repository directory information. You can have multiple dirs defined in the extension point. This can be useful to provide different directories depending on the kodi version as exemplified below:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository" name="Inputstream Adaptive Testing Repository">
<dir maxversion="18.9.0">
<info compressed="false">https://example.com/leia/addons.xml</info>
<checksum>https://example.com/leia/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/leia/</datadir>
<hashes>false</hashes>
</dir>
<dir minversion="19.0.0">
<info compressed="false">https://example.com/matrix/addons.xml</info>
<checksum>https://example.com/matrix/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/matrix/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

In the example above, the first directory will only be served to Kodi Leia while the second will only be served to the Matrix version of Kodi.
There's also another, simpler way to define a repository by adding all the dir items in the root of the extension element. Such alternative is not recommended and will probably be removed in a future kodi version:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</extension>
</syntaxhighlight>

=== dir ===
The dir element wraps all the other repository information elements such as info, checksum, datadir or hashes. It supports the additional attributes:
* '''minversion''': the minimum kodi version that supports this directory
* '''maxversion''': the maximum kodi version that supports this directory

{{note|both can be ommited}}

{{note|minversion and maxversion where introduced in Kodi Matrix (v19).}}

=== info ===
URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

=== checksum ===
A text file that identifies the content of <code><info></code>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

=== hashes ===
Todo

== Security ==

We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

== Repository Tools ==

Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Add-on development]]

Add-on repositories

2022-02-23T11:01:16Z

Enen92: Update For kodi matrix

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

Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
The repository functionality was first introduced in the Dharma version of Kodi (XBMC at the time)

After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.

== Ingredients for a Repository ==
Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

* An HTTP server. Any should work.
* Some add-ons.
* A master xml file. This file contains metadata about all available add-ons.
* A checksum of the above file.
* A repository add-on for distribution. This allows you to share your repository with others.

== Directory Structure ==
addon.id
addon.id-x.y.z.zip
...
addon2.id
addon2.id-x.y.z.zip
...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.

* addon.id should be the same as the addon's id, which is expected to be unique.
* x.y.z is the addon's version, the same should be listed in its version attribute.

== Addons.xml ==
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addon
id="sample.addon1"
...
</addon>

<addon
id="sample.addon2"
...
</addon>
</addons>
</syntaxhighlight>

== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<dir>
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

The dir block wraps the main repository directory information. You can have multiple dirs defined in the extension point. This can be useful to provide different directories depending on the kodi version as exemplified below:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository" name="Inputstream Adaptive Testing Repository">
<dir maxversion="18.9.0">
<info compressed="false">https://example.com/leia/addons.xml</info>
<checksum>https://example.com/leia/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/leia/</datadir>
<hashes>false</hashes>
</dir>
<dir minversion="19.0.0">
<info compressed="false">https://example.com/matrix/addons.xml</info>
<checksum>https://example.com/matrix/addons.xml.md5</checksum>
<datadir zip="true">https://example.com/matrix/</datadir>
<hashes>false</hashes>
</dir>
</extension>
</syntaxhighlight>

In the example above, the first directory will only be served to Kodi Leia while the second will only be served to the Matrix version of Kodi.
There's also another, simpler way to define a repository by adding all the dir items in the root of the extension element. Such alternative is not recommended and will probably be removed in a future kodi version:

<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
<hashes>false</hashes>
</extension>
</syntaxhighlight>

=== dir ===
The dir element wraps all the other repository information elements such as info, checksum, datadir or hashes. It supports the additional attributes:
* '''minversion''': the minimum kodi version that supports this directory
* '''maxversion''': the maximum kodi version that supports this directory

{{note|both can be ommited}}

{{note|minversion and maxversion where introduced in Kodi Matrix (v19).}}

=== info ===
URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

=== checksum ===
A text file that identifies the content of <code><info></code>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

=== hashes ===
Todo

== Security ==

We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

== Repository Tools ==

Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Add-on development]]

Add-on repositories

2022-02-23T10:31:43Z

Enen92: Move dharma context to the bottom, it's really just a curiosity by now

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

Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
The repository functionality was first introduced in the Dharma version of Kodi (XBMC at the time)

After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.

== Ingredients for a Repository ==
Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

* An HTTP server. Any should work.
* Some add-ons.
* A master xml file. This file contains metadata about all available add-ons.
* A checksum of the above file.
* A repository add-on for distribution. This allows you to share your repository with others.

== Directory Structure ==
addon.id
addon.id-x.y.z.zip
...
addon2.id
addon2.id-x.y.z.zip
...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.

* addon.id should be the same as the addon's id, which is expected to be unique.
* x.y.z is the addon's version, the same should be listed in its version attribute.

== Addons.xml ==
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addon
id="sample.addon1"
...
</addon>

<addon
id="sample.addon2"
...
</addon>
</addons>
</syntaxhighlight>

== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<syntaxhighlight lang="xml" enclose="div">
<extension point="xbmc.addon.repository">
<info>https://example.com/addons/addons.xml</info>
<checksum>https://example.com/addons/addons.xml.md5</checksum>
<datadir>https://example.com/addons/</datadir>
</extension>
</syntaxhighlight>

=== info ===
URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

=== checksum ===
A text file that identifies the content of <code><info></code>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

== Security ==

We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

== Repository Tools ==

Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Add-on development]]

Window Structure

2022-01-30T10:12:31Z

Enen92: Changes for v20

<section begin="main content" />
==About the Window XML Files==
Each window in an Kodi skin is represented by a single .xml file. [[Window IDs|See here for a list of the standard windows and links to their .xml files.]]<br /><br />

The important thing to remember is that each window has a unique identifying name. This is how Kodi identifies the window from within the source code.
The window names are all listed in the Appendix I: List of Windows.

Each .xml file has the same basic structure – it starts with some heading information that pertains to the window as a whole, and then contains a <controls> block within which all the controls that describe the window are defined.
Many of the controls within each window should have a unique id's, unless they're just used as images or labels where navigation is unimportant and Kodi does not need to be able to identify them uniquely.

== Window Header ==
<syntaxhighlight lang="XML" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<window>
<onload>RunScript(script.foobar)</onload>
<onunload>SetProperty(foo,bar)</onunload>
<defaultcontrol always="false">2</defaultcontrol>
<menucontrol>9000</menucontrol>
<backgroundcolor>0xff00ff00</backgroundcolor>
<views>50,51,509,510</views>
<visible>Window.IsActive(Home)</visible>
<animation effect="fade" time="100">WindowOpen</animation>
<animation effect="slide" end="0,576" time="100">WindowClose</animation>
<zorder>1</zorder>
<coordinates>
<left>40</left>
<top>50</top>
<origin x="100" y="50">Window.IsActive(Home)</origin>
</coordinates>
<previouswindow>MyVideos</previouswindow>
<controls>
<control>
</control>
....
</controls>
</window>
</syntaxhighlight>

One thing to note is that all tag names are lower case. '''XML tag names are case sensitive!'''<br /><br />The header contains the following tags:

; onload
: Optional: the [[List_of_built-in_functions|build-in function]] to execute when the window opens
; onunload
: Optional: the [[List_of_built-in_functions|build-in function]] to execute when the window closes
; defaultcontrol
: This specifies the default control of the window. This is the id of the control that will receive focus when the window is first opened. Note that most Kodi windows save the current focus when you leave the window, and will return to the last focused item when you return to a window. This behaviour can be stopped by specifying the attribute always="true".
; menucontrol
: This specifies the control that will be focused when the users presses the 'menu' / 'm' button.
; backgroundcolor
: Specifies whether the window needs clearing prior to rendering, and if so which colour to use. Defaults to clearing to black. Set to 0 (or 0x00000000) to have no clearing at all. If your skin always renders opaque textures over the entire screen (eg using a backdrop image or multiple backdrop images) then setting the background color to 0 is the most optimal value and may improve performance significantly on slow GPUs.
; visible
: Specifies the conditions under which a dialog will be visible. Kodi evaluates this at render time, and shows or hides a dialog depending on the evaluation of this tag. [[Conditional_visibility|See here for more details.]] '''Applies only to type="dialog" windows.'''. By default if a dialog visibility depends on visible condition it will be set as Modeless. A modeless dialog won't be able to catch input as any keystroke/action will be sent to the underlying window. Since v20 you can override this behaviour by setting '''modality="modal"''' on the root element of the window/dialog XML definition.
; animation
: Specifies the animation effect to perform when opening or closing the window. [[Animating_your_skin|See here for more details.]]
; zorder
: This specifies the “depth” that the window should be drawn at. Windows with higher zorder are drawn on top of windows with lower z-order. All dialogs by default have zorder 1, so if you have a particular dialog that you want underneath all others, give it a zorder of 0. (Note that the normal render order is: The base window, then the overlays (music + video), then dialogs. <zorder> only effects the rendering of the dialogs.
; coordinates
: This block is used to specify how Kodi should compute the coordinates of all controls.
; left
: Sets the horizontal “origin” position of the window. Defaults to 0 if not present.
; top
: Sets the vertical “origin” position of the window. Defaults to 0 if not present.
; origin
: Sets a conditional origin for the window. The window will display at (x,y) whenever the origin condition is met. You can have as many origin tags as you like – they are evaluated in the order present in the file, and the first one for which the condition is met wins. If none of the origin conditions are met, we fall back to the <left> and <top> tags.
; previouswindow
: This can be used to specify a window to force Kodi to go to on press of the Back button. Normally Kodi keeps a “window stack” of previous windows to handle this. This tag allows you to override this behaviour. The value is the name of the window.
; views
: This tag lets you use view id's beyond 50 to 59 it also lets you set the order in which they cycle with the change view button in the skin. Only useful in My<Foo>.xml windows.
; controls
: This is the block the defines all controls that will appear on this window.

=== The Different Types of Controls ===

Kodi supports many different types of controls.

[[Controls|Click here for the control types and what they all do.]]

Some of these controls are required on specific windows, as they're necessary for that window to perform it's duty, or, the contents of the control are only valid on a particular window. The mandatory controls for each window are listed [[List of Built In Controls|here]]. While the controls are mandatory, you can ofcourse move them about and change their appearance within the windows to your hearts content!

=== Adding Extra Windows ===

All of the windows in the [[Window IDs|window list]] are defined within the executable of Kodi itself, as most of them have a specific purpose. However, the skinner may add extra windows as and when they are needed or wanted. The only restriction to this is that only controls that do not require specific source code to operate can be used. This is not too much of a restriction though, as many skinners have found out.

To add an extra window, all you need to do is design up the window's .xml file in the usual way, assign it an <id> within the 1100–1199 range (see [[Window IDs|window list]]), and then name the file customN.xml, where N is a number or name. You can have as many as you like, as long as they have unique <id>'s, and are named differently. Then just define the type of window you want, the coordinate system and so on, add the controls and setup the navigation. To activate your window, you can do it by adding a button control elsewhere in the skin, or you can get it to popup on a press of the controller or remote via keymap.xml and so on. Basically you just need to run ActivateWindow(id) from a suitable place.

<section end="main content" />

[[Category:Skin development]]

Advancedsettings.xml

2022-01-11T17:24:36Z

Enen92: /* handlemounting */

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 2 + full smb logging (no on screen display)
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<enablehighqualityhwscalers>true</enablehighqualityhwscalers>
</syntaxhighlight>
| Allow turning on the spline36 and lanczos3 shader (for GL builds).
|-
|
<syntaxhighlight lang=xml>
<dxvaallowhqscaling>false</dxvaallowhqscaling>
</syntaxhighlight>
| Enables high quality video upscaling for Windows.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>
</edl>
</syntaxhighlight>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
Translation table for subtitle and audio names. Contains entries of the form

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of "''[[RegEx_tutorial|regular expressions]]''". For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a ''[[RegEx_tutorial|Regular Expression]]''

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of ''[[RegEx_tutorial|Regular Expressions]]''. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L188 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>[ _\,\.\[\]\-](aka|ac3|dts|custom|dc|remastered|divx|divx5|dsr|dsrip|dutch|dvd|dvd5|dvd9|dvdrip|dvdscr|dvdscreener|screener|dvdivx|cam|fragment|fs|hdtv|hdrip|hdtvrip|internal|limited|multisubs|ntsc|ogg|ogm|pal|pdtv|proper|repack|rerip|retail|r3|r5|bd5|se|svcd|swedish|german|read.nfo|nfofix|unrated|extended|ws|telesync|ts|telecine|tc|brrip|bdrip|480p|480i|576p|576i|720p|720i|1080p|1080i|3d|hrhd|hrhdtv|hddvd|bluray|x264|h264|xvid|xvidvd|xxx|www.www|cd[1-9]|\[.*\])([ _\,\.\[\]\-]|$)</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of ''[[RegEx_tutorial|Regular Expressions]]''

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* Examples of matching regexps for certain filenames can be found on the [[Naming_video_files/TV_shows|TV shows]] page.

:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.

:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of ''[[RegEx_tutorial|Regular Expressions]]''.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of ''[[RegEx_tutorial|Regular Expressions]]''. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of ''[[RegEx_tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains "''[[RegEx_tutorial|Regular Expression]]''" syntax (commonly referred to as "''[[RegEx_tutorial|RegEx]]''" or "''[[RegEx_tutorial|RegExp]]''") to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

==== Extra artwork ====

Applies to Kodi v18 only.

Configuration to expand the artwork automatically added by Kodi to media items in the library, either from local files or online scrapers.

The original basic artwork types are still hardcoded so they don't need to be configured here (and can't be removed). "poster" and "fanart" for movies, movie sets, TV shows, seasons, and music videos; "banner" for TV shows and seasons; and "thumb" for episodes.

<syntaxhighlight lang=xml enclose="div">
<videolibrary>


<tvshowextraart>
<arttype>characterart</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</tvshowextraart>

<tvseasonextraart>
<arttype>landscape</arttype>
</tvseasonextraart>

<episodeextraart>
<arttype>fanart</arttype>
</episodeextraart>

<movieextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</movieextraart>

<moviesetextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</moviesetextraart>

<musicvideoextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
</musicvideoextraart>
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/1a8753d5cd93890dc6a9f9d4b2ce8848066ea5d0/xbmc/pictures/PictureScalingAlgorithm.cpp#L32-L43 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of ''[[RegEx_tutorial|Regular Expressions]]''

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
</network>
</syntaxhighlight>

{{Note|In Kodi v17, the three buffer settings are removed from the <code><network></code> tag and now placed under the new <code><cache></code> tag. See '''[[#cache]]''' for full details.}}

<curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
Set to true if you wish to detect joint ISO9660/UDF disks as UDF.

Default: False

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
Only used in Linux, it defines if Kodi should attempt to mount media drives (via udisks or udisks2).

Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<controllerdeadzone>''' - Removed in v17
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

Advancedsettings.xml

2022-01-11T17:20:30Z

Enen92: handlemounting - This setting was missing from the documentation

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 2 + full smb logging (no on screen display)
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<enablehighqualityhwscalers>true</enablehighqualityhwscalers>
</syntaxhighlight>
| Allow turning on the spline36 and lanczos3 shader (for GL builds).
|-
|
<syntaxhighlight lang=xml>
<dxvaallowhqscaling>false</dxvaallowhqscaling>
</syntaxhighlight>
| Enables high quality video upscaling for Windows.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>
</edl>
</syntaxhighlight>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
Translation table for subtitle and audio names. Contains entries of the form

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of "''[[RegEx_tutorial|regular expressions]]''". For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a ''[[RegEx_tutorial|Regular Expression]]''

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of ''[[RegEx_tutorial|Regular Expressions]]''. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L188 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>[ _\,\.\[\]\-](aka|ac3|dts|custom|dc|remastered|divx|divx5|dsr|dsrip|dutch|dvd|dvd5|dvd9|dvdrip|dvdscr|dvdscreener|screener|dvdivx|cam|fragment|fs|hdtv|hdrip|hdtvrip|internal|limited|multisubs|ntsc|ogg|ogm|pal|pdtv|proper|repack|rerip|retail|r3|r5|bd5|se|svcd|swedish|german|read.nfo|nfofix|unrated|extended|ws|telesync|ts|telecine|tc|brrip|bdrip|480p|480i|576p|576i|720p|720i|1080p|1080i|3d|hrhd|hrhdtv|hddvd|bluray|x264|h264|xvid|xvidvd|xxx|www.www|cd[1-9]|\[.*\])([ _\,\.\[\]\-]|$)</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of ''[[RegEx_tutorial|Regular Expressions]]''

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* Examples of matching regexps for certain filenames can be found on the [[Naming_video_files/TV_shows|TV shows]] page.

:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.

:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of ''[[RegEx_tutorial|Regular Expressions]]''.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of ''[[RegEx_tutorial|Regular Expressions]]''. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of ''[[RegEx_tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains "''[[RegEx_tutorial|Regular Expression]]''" syntax (commonly referred to as "''[[RegEx_tutorial|RegEx]]''" or "''[[RegEx_tutorial|RegExp]]''") to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

==== Extra artwork ====

Applies to Kodi v18 only.

Configuration to expand the artwork automatically added by Kodi to media items in the library, either from local files or online scrapers.

The original basic artwork types are still hardcoded so they don't need to be configured here (and can't be removed). "poster" and "fanart" for movies, movie sets, TV shows, seasons, and music videos; "banner" for TV shows and seasons; and "thumb" for episodes.

<syntaxhighlight lang=xml enclose="div">
<videolibrary>


<tvshowextraart>
<arttype>characterart</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</tvshowextraart>

<tvseasonextraart>
<arttype>landscape</arttype>
</tvseasonextraart>

<episodeextraart>
<arttype>fanart</arttype>
</episodeextraart>

<movieextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</movieextraart>

<moviesetextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</moviesetextraart>

<musicvideoextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
</musicvideoextraart>
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/1a8753d5cd93890dc6a9f9d4b2ce8848066ea5d0/xbmc/pictures/PictureScalingAlgorithm.cpp#L32-L43 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of ''[[RegEx_tutorial|Regular Expressions]]''

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
</network>
</syntaxhighlight>

{{Note|In Kodi v17, the three buffer settings are removed from the <code><network></code> tag and now placed under the new <code><cache></code> tag. See '''[[#cache]]''' for full details.}}

<curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
Set to true if you wish to detect joint ISO9660/UDF disks as UDF.

Default: False

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
Only used in Linux, it defines if Kodi should attempt to mount media drives.

Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<controllerdeadzone>''' - Removed in v17
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

Edit decision list

2022-01-09T21:35:36Z

Enen92: /* Comskip */ FPS in the example file was wrong, it has a factor of 100

{{mininav| [[Video library]] {{l2| [[Live TV]] }} }}
<section begin="intro" />An '''edit decision list''' (EDL) contains information about edits that should be made to the video during playback. Edit decision list information is contained in a separate file to the video that is read by Kodi just before the video is played. Examples of use include can be to skip commercials, cut out content inappropriate for children, or skip over the half hour acid trip in ''2001: A Space Odyssey'' . <section end="intro" />

Inspiration for this functionality came from [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL support].

The internal video player ([[VideoPlayer]]) used by Kodi supports the following types of edits:
* '''Cut''' - the content is completely removed from playback as if it were never in the original video. For example, the total playback time is adjusted and the content is always automatically skipped during playback, seeking, fast forward or rewind.
* '''Mute''' - the audio is muted, video continues playing.
* '''Scene Marker''' - these can be used to seek to points of interest within a video similar to how chapter seeking works for DVDs.
* '''Commercial Break''' - each commercial break is automatically skipped once during playback. Since commercial detection is rarely 100% accurate, commercial breaks that have already been skipped can be re-entered by seeking backwards or rewinding. Note: Scene Markers are placed at the start and end of each commercial break so you can easily jump between the start and end of commbreaks using Scene Marker's builtin actions ('''NextScene''' and '''PreviousScene''')

<br />
{{bigger|{{note|'''If using actual .EDL files the following field must be added to comskip.ini:'''}} }}
<br /><br />

<pre>
edl_skip_field=3
</pre>

By default this value will be 0 in Comskip, and Kodi will see them as '''Cut''' actions and remove the section from the video (i.e. a 30 minute video would appear as 22 minutes with commericals removed). Setting this value overrides this behaviour allowing Kodi to treat it as a '''Commercial Break'''.

With edl_skip_field=3 , the full video file is visible, but Kdoi will skip the marked commercials the first time it attempts to play them. If, after commercials are skipped, you skip back through the recording (into a commercial area), you can then watch the video that was marked as a commercial.

(thanks '''sbthomas''' for the solution)

<br />

= Supported File Formats =

Kodi is able to read edit decision lists from multiple file formats. The EDL file for a video must be in the same folder as the video file and is looked for based on the file extensions for the supported formats.

For example if the video file is called '''The Matrix.avi''' Kodi will look for the following files, in order, until a valid file is found. Note the the file name may be case-sensitive based on the operating system being used.
# '''The Matrix.Vprj''' (VideoReDo)
# '''The Matrix.edl''' (MPlayer EDL)
# '''The Matrix.txt''' (Comskip)
# '''The Matrix.avi.chapters.xml''' (SnapStream BeyondTV)

== MPlayer EDL ==

Classic [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL] files are supported. Kodi also supports an extended version of this file format that allows extra functionality as outlined below. The name of the file must be the same as the video file but with a file extension of '''.edl'''.

The file contains the start and end times of the edits along with the type of action associated with each edit. The file format is:
<pre>
[start time] [end time] [action]
</pre>

Start and end times can be defined as seconds, HH:MM:SS.sss, or frames. To specify frames precede the frame number with the # symbol. The original MPlayer EDL files only support seconds for start and end times.

The actions supported by this file format have also been extended by Kodi to include Scene Marker and Commercial Break actions since the original format only supports Cut and Mute. Supported actions are:
* 0 - Cut
* 1 - Mute
* 2 - Scene Marker (if start and end times are specified, the end time is used)
* 3 - Commercial Break

For example, the following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 420 seconds to 822 seconds. There will be two scene markers. The first at 255.3 seconds and the next at 720.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
420 822 3
1 255.3 2
720.1 2
</pre>

The following .edl file content will skip from frame 127 to frame 170, mute at frame 360, unmute at frame 400, and commercial skip from frame 10080 to frame 19728. There will be two scene markers. The first at frame 6127 and the next at frame 17282. Note that when using frame numbers TS files are not supported, other file formats that correctly provide frame rate will work.
<pre>
#127 #170 0
#360 #400 1
#10080 #19728 3
#1 #6127 2
#17282 2
</pre>

The following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 7 minutes to 13 minutes and 42 seconds. There will be two scene markers. The first at 4 minutes and 15.3 seconds and the next at 12 minutes and 0.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
7:00 13:42 3
1 4:15.3 2
12:00.1 2
</pre>

Seconds and HH:MM:SS.sss can be accurately specified to three decimal places. Currently EDL cuts and mutes are frame accurate when specifying frames. Frames are specified inclusive (specify first frame to cut and last frame to cut).

{{future|19|In Kodi v19, the addition of handling a comment line has been added. These lines are defined as beginning with ##<br>Kodi will ignore any lines beginning with ## and continue processing the EDL file.}}

== VideoReDo ==

[http://www.videoredo.com/ VideoReDo] files are supported. The name of the file must be the same as the video but with a file extension of '''.Vprj'''.

Only lines starting with ''<SceneMarker>'' and ''<Cut>'' are read from the file. The file format is:
<pre>
<Version>[only version 2 is supported]
<Filename>[ignored]
<InputPIDList>
<VideoStreamPID>[ignored]</VideoStreamPID>
<AudioStreamPID>[ignored]</AudioStreamPID>
</InputPIDList>
<SceneMarker [ignored]>[scene marker time] (in ms * 10,000)
<Cut>[start time]:[end time] (both in ms * 10,000)
</pre>

For example,
<pre>
<Version>2
<Filename>C:\Path\To\Video.mpg
<InputPIDList>
<VideoStreamPID>224</VideoStreamPID>
<AudioStreamPID>192</AudioStreamPID>
</InputPIDList>
<SceneMarker 1415932542>4235230000
<SceneMarker 1415932543>4284610000
<SceneMarker 1415932544>4585580000
<SceneMarker 1415932545>5035360000
<Cut>4235230000:5936600000
<Cut>9535530000:11527860000
<Cut>14385710000:16090090000
</pre>

== Comskip ==

[http://www.kaashoek.com/comskip/ Comskip] files are supported. The name of the file must be the same as the video but with a file extension of '''.txt'''.

The file contains the start and end frame numbers for the commercial breaks that were detected. The Comskip file may or may not contain the frame rate. If the frame rate is not found, the detected frame rate of the video is used to convert from the frame numbers to time offsets. Note that for TS files only the version 2 format is supported (where frame rate is suppplied).

The version 1 file format is:
<pre>
FILE PROCESSING COMPLETE
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE
------------------------
12693 17792
28578 34549
43114 48222
</pre>

The version 2 file format is:
<pre>
FILE PROCESSING COMPLETE [number of frames] FRAMES AT [frame rate * 100]
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE 678900 FRAMES AT 2500
------------------------
12693 17792
28578 34549
43114 48222
</pre>

== SnapStream BeyondTV ==

[http://www.snapstream.com/products/beyondtv/ BeyondTV] files are supported. The name of the file must be the same as the video but with '''.chapters.xml''' appended to the filename. E.g. if you have a '''movie.mkv''' file, the corresponding EDL file should be named '''movie.mkv.chapters.xml'''

Each ''<Region>'' within the XML file is treated as a commercial break. The file format is:
<pre>
<cutlist>
<Region>
<start comment="[start time in hh:mm:ss.sssssss format - ignored]">[start time in ms * 10,000]</start>
<end comment="[end time in hh:mm:ss.sssssss format - ignored]">[end time in ms * 10,000]</end>
</Region>
</cutlist>
</pre>

For example,
<pre>
<cutlist>
<Region>
<start comment="0:07:03.0000523">4235230000</start>
<end comment="0:09:53.0000660">5936600000</end>
</Region>
<Region>
<start comment="0:15:53.0000553">9535530000</start>
<end comment="0:19:12.0000786">11527860000</end>
</Region>
<Region>
<start comment="0:23:58.0000571">14385710000</start>
<end comment="0:26:49.0000009">16090090000</end>
</Region>
</cutlist>
</pre>

= Merging or Removing Short Commercial Breaks =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] can be used to:
* Merge commercial breaks within a set of commercials that haven't been detected accurately. Very useful if you find that automatically skipped commercial breaks still end up within a set of commercial breaks.
* Remove commercial breaks that are incorrectly identified outside of a likely set of commercial breaks. Very useful if you find that commercial skipping is happening unexpectedly while watching the TV show or Movie.

= Altering Automatic Skip Timings =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] also can be used to:
* Set how long to wait before automatically skipping when the start of a commercial break is reached. Useful if the automatic skip at the start of a set of commercial breaks is happening slightly too early for your liking, particularly if you aren't ever quite sure if that was a commercial that was about to start.
* Set how long to rewind after automatically skipping to the end of the commercial break. Useful if it's kind of hard to tell if that was in fact the start of the TV show after a block of commercials.

= Showing EDL Information During Playback =
Display of EDL information was removed for v17 and v18 with the redesign of the Codec information windows.
{{Future|19|EDL markers will be visible on the video player OSD. See [https://github.com/xbmc/xbmc/pull/15767 PR15767]}}

= Using Scene Markers =

To use any scene markers that have been read, buttons on the remote need to be configured to go to the next/previous scene marker. These buttons must use the '''NextScene''' and '''PreviousScene''' codes from [[Keymap]].

{{updated|19}}

[[Category:PVR]]
[[Category:Manual]]
[[Category:Video library]]
[[Category:Advanced topics]]

Edit decision list

2022-01-09T19:59:26Z

Enen92: /* SnapStream BeyondTV */

{{mininav| [[Video library]] {{l2| [[Live TV]] }} }}
<section begin="intro" />An '''edit decision list''' (EDL) contains information about edits that should be made to the video during playback. Edit decision list information is contained in a separate file to the video that is read by Kodi just before the video is played. Examples of use include can be to skip commercials, cut out content inappropriate for children, or skip over the half hour acid trip in ''2001: A Space Odyssey'' . <section end="intro" />

Inspiration for this functionality came from [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL support].

The internal video player ([[VideoPlayer]]) used by Kodi supports the following types of edits:
* '''Cut''' - the content is completely removed from playback as if it were never in the original video. For example, the total playback time is adjusted and the content is always automatically skipped during playback, seeking, fast forward or rewind.
* '''Mute''' - the audio is muted, video continues playing.
* '''Scene Marker''' - these can be used to seek to points of interest within a video similar to how chapter seeking works for DVDs.
* '''Commercial Break''' - each commercial break is automatically skipped once during playback. Since commercial detection is rarely 100% accurate, commercial breaks that have already been skipped can be re-entered by seeking backwards or rewinding. Note: Scene Markers are placed at the start and end of each commercial break so you can easily jump between the start and end of commbreaks using Scene Marker's builtin actions ('''NextScene''' and '''PreviousScene''')

<br />
{{bigger|{{note|'''If using actual .EDL files the following field must be added to comskip.ini:'''}} }}
<br /><br />

<pre>
edl_skip_field=3
</pre>

By default this value will be 0 in Comskip, and Kodi will see them as '''Cut''' actions and remove the section from the video (i.e. a 30 minute video would appear as 22 minutes with commericals removed). Setting this value overrides this behaviour allowing Kodi to treat it as a '''Commercial Break'''.

With edl_skip_field=3 , the full video file is visible, but Kdoi will skip the marked commercials the first time it attempts to play them. If, after commercials are skipped, you skip back through the recording (into a commercial area), you can then watch the video that was marked as a commercial.

(thanks '''sbthomas''' for the solution)

<br />

= Supported File Formats =

Kodi is able to read edit decision lists from multiple file formats. The EDL file for a video must be in the same folder as the video file and is looked for based on the file extensions for the supported formats.

For example if the video file is called '''The Matrix.avi''' Kodi will look for the following files, in order, until a valid file is found. Note the the file name may be case-sensitive based on the operating system being used.
# '''The Matrix.Vprj''' (VideoReDo)
# '''The Matrix.edl''' (MPlayer EDL)
# '''The Matrix.txt''' (Comskip)
# '''The Matrix.avi.chapters.xml''' (SnapStream BeyondTV)

== MPlayer EDL ==

Classic [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL] files are supported. Kodi also supports an extended version of this file format that allows extra functionality as outlined below. The name of the file must be the same as the video file but with a file extension of '''.edl'''.

The file contains the start and end times of the edits along with the type of action associated with each edit. The file format is:
<pre>
[start time] [end time] [action]
</pre>

Start and end times can be defined as seconds, HH:MM:SS.sss, or frames. To specify frames precede the frame number with the # symbol. The original MPlayer EDL files only support seconds for start and end times.

The actions supported by this file format have also been extended by Kodi to include Scene Marker and Commercial Break actions since the original format only supports Cut and Mute. Supported actions are:
* 0 - Cut
* 1 - Mute
* 2 - Scene Marker (if start and end times are specified, the end time is used)
* 3 - Commercial Break

For example, the following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 420 seconds to 822 seconds. There will be two scene markers. The first at 255.3 seconds and the next at 720.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
420 822 3
1 255.3 2
720.1 2
</pre>

The following .edl file content will skip from frame 127 to frame 170, mute at frame 360, unmute at frame 400, and commercial skip from frame 10080 to frame 19728. There will be two scene markers. The first at frame 6127 and the next at frame 17282. Note that when using frame numbers TS files are not supported, other file formats that correctly provide frame rate will work.
<pre>
#127 #170 0
#360 #400 1
#10080 #19728 3
#1 #6127 2
#17282 2
</pre>

The following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 7 minutes to 13 minutes and 42 seconds. There will be two scene markers. The first at 4 minutes and 15.3 seconds and the next at 12 minutes and 0.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
7:00 13:42 3
1 4:15.3 2
12:00.1 2
</pre>

Seconds and HH:MM:SS.sss can be accurately specified to three decimal places. Currently EDL cuts and mutes are frame accurate when specifying frames. Frames are specified inclusive (specify first frame to cut and last frame to cut).

{{future|19|In Kodi v19, the addition of handling a comment line has been added. These lines are defined as beginning with ##<br>Kodi will ignore any lines beginning with ## and continue processing the EDL file.}}

== VideoReDo ==

[http://www.videoredo.com/ VideoReDo] files are supported. The name of the file must be the same as the video but with a file extension of '''.Vprj'''.

Only lines starting with ''<SceneMarker>'' and ''<Cut>'' are read from the file. The file format is:
<pre>
<Version>[only version 2 is supported]
<Filename>[ignored]
<InputPIDList>
<VideoStreamPID>[ignored]</VideoStreamPID>
<AudioStreamPID>[ignored]</AudioStreamPID>
</InputPIDList>
<SceneMarker [ignored]>[scene marker time] (in ms * 10,000)
<Cut>[start time]:[end time] (both in ms * 10,000)
</pre>

For example,
<pre>
<Version>2
<Filename>C:\Path\To\Video.mpg
<InputPIDList>
<VideoStreamPID>224</VideoStreamPID>
<AudioStreamPID>192</AudioStreamPID>
</InputPIDList>
<SceneMarker 1415932542>4235230000
<SceneMarker 1415932543>4284610000
<SceneMarker 1415932544>4585580000
<SceneMarker 1415932545>5035360000
<Cut>4235230000:5936600000
<Cut>9535530000:11527860000
<Cut>14385710000:16090090000
</pre>

== Comskip ==

[http://www.kaashoek.com/comskip/ Comskip] files are supported. The name of the file must be the same as the video but with a file extension of '''.txt'''.

The file contains the start and end frame numbers for the commercial breaks that were detected. The Comskip file may or may not contain the frame rate. If the frame rate is not found, the detected frame rate of the video is used to convert from the frame numbers to time offsets. Note that for TS files only the version 2 format is supported (where frame rate is suppplied).

The version 1 file format is:
<pre>
FILE PROCESSING COMPLETE
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE
------------------------
12693 17792
28578 34549
43114 48222
</pre>

The version 2 file format is:
<pre>
FILE PROCESSING COMPLETE [number of frames] FRAMES AT [frame rate]
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE 678900 FRAMES AT 25
------------------------
12693 17792
28578 34549
43114 48222
</pre>

== SnapStream BeyondTV ==

[http://www.snapstream.com/products/beyondtv/ BeyondTV] files are supported. The name of the file must be the same as the video but with '''.chapters.xml''' appended to the filename. E.g. if you have a '''movie.mkv''' file, the corresponding EDL file should be named '''movie.mkv.chapters.xml'''

Each ''<Region>'' within the XML file is treated as a commercial break. The file format is:
<pre>
<cutlist>
<Region>
<start comment="[start time in hh:mm:ss.sssssss format - ignored]">[start time in ms * 10,000]</start>
<end comment="[end time in hh:mm:ss.sssssss format - ignored]">[end time in ms * 10,000]</end>
</Region>
</cutlist>
</pre>

For example,
<pre>
<cutlist>
<Region>
<start comment="0:07:03.0000523">4235230000</start>
<end comment="0:09:53.0000660">5936600000</end>
</Region>
<Region>
<start comment="0:15:53.0000553">9535530000</start>
<end comment="0:19:12.0000786">11527860000</end>
</Region>
<Region>
<start comment="0:23:58.0000571">14385710000</start>
<end comment="0:26:49.0000009">16090090000</end>
</Region>
</cutlist>
</pre>

= Merging or Removing Short Commercial Breaks =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] can be used to:
* Merge commercial breaks within a set of commercials that haven't been detected accurately. Very useful if you find that automatically skipped commercial breaks still end up within a set of commercial breaks.
* Remove commercial breaks that are incorrectly identified outside of a likely set of commercial breaks. Very useful if you find that commercial skipping is happening unexpectedly while watching the TV show or Movie.

= Altering Automatic Skip Timings =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] also can be used to:
* Set how long to wait before automatically skipping when the start of a commercial break is reached. Useful if the automatic skip at the start of a set of commercial breaks is happening slightly too early for your liking, particularly if you aren't ever quite sure if that was a commercial that was about to start.
* Set how long to rewind after automatically skipping to the end of the commercial break. Useful if it's kind of hard to tell if that was in fact the start of the TV show after a block of commercials.

= Showing EDL Information During Playback =
Display of EDL information was removed for v17 and v18 with the redesign of the Codec information windows.
{{Future|19|EDL markers will be visible on the video player OSD. See [https://github.com/xbmc/xbmc/pull/15767 PR15767]}}

= Using Scene Markers =

To use any scene markers that have been read, buttons on the remote need to be configured to go to the next/previous scene marker. These buttons must use the '''NextScene''' and '''PreviousScene''' codes from [[Keymap]].

{{updated|19}}

[[Category:PVR]]
[[Category:Manual]]
[[Category:Video library]]
[[Category:Advanced topics]]

Edit decision list

2022-01-09T19:46:25Z

Enen92: /* VideoReDo */

{{mininav| [[Video library]] {{l2| [[Live TV]] }} }}
<section begin="intro" />An '''edit decision list''' (EDL) contains information about edits that should be made to the video during playback. Edit decision list information is contained in a separate file to the video that is read by Kodi just before the video is played. Examples of use include can be to skip commercials, cut out content inappropriate for children, or skip over the half hour acid trip in ''2001: A Space Odyssey'' . <section end="intro" />

Inspiration for this functionality came from [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL support].

The internal video player ([[VideoPlayer]]) used by Kodi supports the following types of edits:
* '''Cut''' - the content is completely removed from playback as if it were never in the original video. For example, the total playback time is adjusted and the content is always automatically skipped during playback, seeking, fast forward or rewind.
* '''Mute''' - the audio is muted, video continues playing.
* '''Scene Marker''' - these can be used to seek to points of interest within a video similar to how chapter seeking works for DVDs.
* '''Commercial Break''' - each commercial break is automatically skipped once during playback. Since commercial detection is rarely 100% accurate, commercial breaks that have already been skipped can be re-entered by seeking backwards or rewinding. Note: Scene Markers are placed at the start and end of each commercial break so you can easily jump between the start and end of commbreaks using Scene Marker's builtin actions ('''NextScene''' and '''PreviousScene''')

<br />
{{bigger|{{note|'''If using actual .EDL files the following field must be added to comskip.ini:'''}} }}
<br /><br />

<pre>
edl_skip_field=3
</pre>

By default this value will be 0 in Comskip, and Kodi will see them as '''Cut''' actions and remove the section from the video (i.e. a 30 minute video would appear as 22 minutes with commericals removed). Setting this value overrides this behaviour allowing Kodi to treat it as a '''Commercial Break'''.

With edl_skip_field=3 , the full video file is visible, but Kdoi will skip the marked commercials the first time it attempts to play them. If, after commercials are skipped, you skip back through the recording (into a commercial area), you can then watch the video that was marked as a commercial.

(thanks '''sbthomas''' for the solution)

<br />

= Supported File Formats =

Kodi is able to read edit decision lists from multiple file formats. The EDL file for a video must be in the same folder as the video file and is looked for based on the file extensions for the supported formats.

For example if the video file is called '''The Matrix.avi''' Kodi will look for the following files, in order, until a valid file is found. Note the the file name may be case-sensitive based on the operating system being used.
# '''The Matrix.Vprj''' (VideoReDo)
# '''The Matrix.edl''' (MPlayer EDL)
# '''The Matrix.txt''' (Comskip)
# '''The Matrix.avi.chapters.xml''' (SnapStream BeyondTV)

== MPlayer EDL ==

Classic [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL] files are supported. Kodi also supports an extended version of this file format that allows extra functionality as outlined below. The name of the file must be the same as the video file but with a file extension of '''.edl'''.

The file contains the start and end times of the edits along with the type of action associated with each edit. The file format is:
<pre>
[start time] [end time] [action]
</pre>

Start and end times can be defined as seconds, HH:MM:SS.sss, or frames. To specify frames precede the frame number with the # symbol. The original MPlayer EDL files only support seconds for start and end times.

The actions supported by this file format have also been extended by Kodi to include Scene Marker and Commercial Break actions since the original format only supports Cut and Mute. Supported actions are:
* 0 - Cut
* 1 - Mute
* 2 - Scene Marker (if start and end times are specified, the end time is used)
* 3 - Commercial Break

For example, the following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 420 seconds to 822 seconds. There will be two scene markers. The first at 255.3 seconds and the next at 720.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
420 822 3
1 255.3 2
720.1 2
</pre>

The following .edl file content will skip from frame 127 to frame 170, mute at frame 360, unmute at frame 400, and commercial skip from frame 10080 to frame 19728. There will be two scene markers. The first at frame 6127 and the next at frame 17282. Note that when using frame numbers TS files are not supported, other file formats that correctly provide frame rate will work.
<pre>
#127 #170 0
#360 #400 1
#10080 #19728 3
#1 #6127 2
#17282 2
</pre>

The following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 7 minutes to 13 minutes and 42 seconds. There will be two scene markers. The first at 4 minutes and 15.3 seconds and the next at 12 minutes and 0.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
7:00 13:42 3
1 4:15.3 2
12:00.1 2
</pre>

Seconds and HH:MM:SS.sss can be accurately specified to three decimal places. Currently EDL cuts and mutes are frame accurate when specifying frames. Frames are specified inclusive (specify first frame to cut and last frame to cut).

{{future|19|In Kodi v19, the addition of handling a comment line has been added. These lines are defined as beginning with ##<br>Kodi will ignore any lines beginning with ## and continue processing the EDL file.}}

== VideoReDo ==

[http://www.videoredo.com/ VideoReDo] files are supported. The name of the file must be the same as the video but with a file extension of '''.Vprj'''.

Only lines starting with ''<SceneMarker>'' and ''<Cut>'' are read from the file. The file format is:
<pre>
<Version>[only version 2 is supported]
<Filename>[ignored]
<InputPIDList>
<VideoStreamPID>[ignored]</VideoStreamPID>
<AudioStreamPID>[ignored]</AudioStreamPID>
</InputPIDList>
<SceneMarker [ignored]>[scene marker time] (in ms * 10,000)
<Cut>[start time]:[end time] (both in ms * 10,000)
</pre>

For example,
<pre>
<Version>2
<Filename>C:\Path\To\Video.mpg
<InputPIDList>
<VideoStreamPID>224</VideoStreamPID>
<AudioStreamPID>192</AudioStreamPID>
</InputPIDList>
<SceneMarker 1415932542>4235230000
<SceneMarker 1415932543>4284610000
<SceneMarker 1415932544>4585580000
<SceneMarker 1415932545>5035360000
<Cut>4235230000:5936600000
<Cut>9535530000:11527860000
<Cut>14385710000:16090090000
</pre>

== Comskip ==

[http://www.kaashoek.com/comskip/ Comskip] files are supported. The name of the file must be the same as the video but with a file extension of '''.txt'''.

The file contains the start and end frame numbers for the commercial breaks that were detected. The Comskip file may or may not contain the frame rate. If the frame rate is not found, the detected frame rate of the video is used to convert from the frame numbers to time offsets. Note that for TS files only the version 2 format is supported (where frame rate is suppplied).

The version 1 file format is:
<pre>
FILE PROCESSING COMPLETE
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE
------------------------
12693 17792
28578 34549
43114 48222
</pre>

The version 2 file format is:
<pre>
FILE PROCESSING COMPLETE [number of frames] FRAMES AT [frame rate]
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE 678900 FRAMES AT 25
------------------------
12693 17792
28578 34549
43114 48222
</pre>

== SnapStream BeyondTV ==

[http://www.snapstream.com/products/beyondtv/ BeyondTV] files are supported. The name of the file must be the same as the video but with '''.chapters.xml''' appended to the filename.

Each ''<Region>'' within the XML file is treated as a commercial break. The file format is:
<pre>
<cutlist>
<Region>
<start comment="[start time in hh:mm:ss.sssssss format - ignored]">[start time in ms * 10,000]</start>
<end comment="[end time in hh:mm:ss.sssssss format - ignored]">[end time in ms * 10,000]</end>
</Region>
</cutlist>
</pre>

For example,
<pre>
<cutlist>
<Region>
<start comment="0:07:03.0000523">4235230000</start>
<end comment="0:09:53.0000660">5936600000</end>
</Region>
<Region>
<start comment="0:15:53.0000553">9535530000</start>
<end comment="0:19:12.0000786">11527860000</end>
</Region>
<Region>
<start comment="0:23:58.0000571">14385710000</start>
<end comment="0:26:49.0000009">16090090000</end>
</Region>
</cutlist>
</pre>

= Merging or Removing Short Commercial Breaks =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] can be used to:
* Merge commercial breaks within a set of commercials that haven't been detected accurately. Very useful if you find that automatically skipped commercial breaks still end up within a set of commercial breaks.
* Remove commercial breaks that are incorrectly identified outside of a likely set of commercial breaks. Very useful if you find that commercial skipping is happening unexpectedly while watching the TV show or Movie.

= Altering Automatic Skip Timings =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] also can be used to:
* Set how long to wait before automatically skipping when the start of a commercial break is reached. Useful if the automatic skip at the start of a set of commercial breaks is happening slightly too early for your liking, particularly if you aren't ever quite sure if that was a commercial that was about to start.
* Set how long to rewind after automatically skipping to the end of the commercial break. Useful if it's kind of hard to tell if that was in fact the start of the TV show after a block of commercials.

= Showing EDL Information During Playback =
Display of EDL information was removed for v17 and v18 with the redesign of the Codec information windows.
{{Future|19|EDL markers will be visible on the video player OSD. See [https://github.com/xbmc/xbmc/pull/15767 PR15767]}}

= Using Scene Markers =

To use any scene markers that have been read, buttons on the remote need to be configured to go to the next/previous scene marker. These buttons must use the '''NextScene''' and '''PreviousScene''' codes from [[Keymap]].

{{updated|19}}

[[Category:PVR]]
[[Category:Manual]]
[[Category:Video library]]
[[Category:Advanced topics]]

Edit decision list

2022-01-09T19:39:48Z

Enen92: /* VideoReDo */ This is wrong and its not what happens in the code. Cuts are treated as cuts.

{{mininav| [[Video library]] {{l2| [[Live TV]] }} }}
<section begin="intro" />An '''edit decision list''' (EDL) contains information about edits that should be made to the video during playback. Edit decision list information is contained in a separate file to the video that is read by Kodi just before the video is played. Examples of use include can be to skip commercials, cut out content inappropriate for children, or skip over the half hour acid trip in ''2001: A Space Odyssey'' . <section end="intro" />

Inspiration for this functionality came from [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL support].

The internal video player ([[VideoPlayer]]) used by Kodi supports the following types of edits:
* '''Cut''' - the content is completely removed from playback as if it were never in the original video. For example, the total playback time is adjusted and the content is always automatically skipped during playback, seeking, fast forward or rewind.
* '''Mute''' - the audio is muted, video continues playing.
* '''Scene Marker''' - these can be used to seek to points of interest within a video similar to how chapter seeking works for DVDs.
* '''Commercial Break''' - each commercial break is automatically skipped once during playback. Since commercial detection is rarely 100% accurate, commercial breaks that have already been skipped can be re-entered by seeking backwards or rewinding. Note: Scene Markers are placed at the start and end of each commercial break so you can easily jump between the start and end of commbreaks using Scene Marker's builtin actions ('''NextScene''' and '''PreviousScene''')

<br />
{{bigger|{{note|'''If using actual .EDL files the following field must be added to comskip.ini:'''}} }}
<br /><br />

<pre>
edl_skip_field=3
</pre>

By default this value will be 0 in Comskip, and Kodi will see them as '''Cut''' actions and remove the section from the video (i.e. a 30 minute video would appear as 22 minutes with commericals removed). Setting this value overrides this behaviour allowing Kodi to treat it as a '''Commercial Break'''.

With edl_skip_field=3 , the full video file is visible, but Kdoi will skip the marked commercials the first time it attempts to play them. If, after commercials are skipped, you skip back through the recording (into a commercial area), you can then watch the video that was marked as a commercial.

(thanks '''sbthomas''' for the solution)

<br />

= Supported File Formats =

Kodi is able to read edit decision lists from multiple file formats. The EDL file for a video must be in the same folder as the video file and is looked for based on the file extensions for the supported formats.

For example if the video file is called '''The Matrix.avi''' Kodi will look for the following files, in order, until a valid file is found. Note the the file name may be case-sensitive based on the operating system being used.
# '''The Matrix.Vprj''' (VideoReDo)
# '''The Matrix.edl''' (MPlayer EDL)
# '''The Matrix.txt''' (Comskip)
# '''The Matrix.avi.chapters.xml''' (SnapStream BeyondTV)

== MPlayer EDL ==

Classic [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL] files are supported. Kodi also supports an extended version of this file format that allows extra functionality as outlined below. The name of the file must be the same as the video file but with a file extension of '''.edl'''.

The file contains the start and end times of the edits along with the type of action associated with each edit. The file format is:
<pre>
[start time] [end time] [action]
</pre>

Start and end times can be defined as seconds, HH:MM:SS.sss, or frames. To specify frames precede the frame number with the # symbol. The original MPlayer EDL files only support seconds for start and end times.

The actions supported by this file format have also been extended by Kodi to include Scene Marker and Commercial Break actions since the original format only supports Cut and Mute. Supported actions are:
* 0 - Cut
* 1 - Mute
* 2 - Scene Marker (if start and end times are specified, the end time is used)
* 3 - Commercial Break

For example, the following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 420 seconds to 822 seconds. There will be two scene markers. The first at 255.3 seconds and the next at 720.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
420 822 3
1 255.3 2
720.1 2
</pre>

The following .edl file content will skip from frame 127 to frame 170, mute at frame 360, unmute at frame 400, and commercial skip from frame 10080 to frame 19728. There will be two scene markers. The first at frame 6127 and the next at frame 17282. Note that when using frame numbers TS files are not supported, other file formats that correctly provide frame rate will work.
<pre>
#127 #170 0
#360 #400 1
#10080 #19728 3
#1 #6127 2
#17282 2
</pre>

The following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 7 minutes to 13 minutes and 42 seconds. There will be two scene markers. The first at 4 minutes and 15.3 seconds and the next at 12 minutes and 0.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
7:00 13:42 3
1 4:15.3 2
12:00.1 2
</pre>

Seconds and HH:MM:SS.sss can be accurately specified to three decimal places. Currently EDL cuts and mutes are frame accurate when specifying frames. Frames are specified inclusive (specify first frame to cut and last frame to cut).

{{future|19|In Kodi v19, the addition of handling a comment line has been added. These lines are defined as beginning with ##<br>Kodi will ignore any lines beginning with ## and continue processing the EDL file.}}

== VideoReDo ==

[http://www.videoredo.com/ VideoReDo] files are supported. The name of the file must be the same as the video but with a file extension of '''.Vprj'''.

Only lines starting with ''<SceneMarker>'' and ''<Cut>'' are read from the file. The file format is:
<pre>
<Version>[ignored]
<Filename>[ignored]
<InputPIDList>
<VideoStreamPID>[ignored]</VideoStreamPID>
<AudioStreamPID>[ignored]</AudioStreamPID>
</InputPIDList>
<SceneMarker [ignored]>[scene marker time] (in ms * 10,000)
<Cut>[start time]:[end time] (both in ms * 10,000)
</pre>

For example,
<pre>
<Version>2
<Filename>C:\Path\To\Video.mpg
<InputPIDList>
<VideoStreamPID>224</VideoStreamPID>
<AudioStreamPID>192</AudioStreamPID>
</InputPIDList>
<SceneMarker 1415932542>4235230000
<SceneMarker 1415932543>4284610000
<SceneMarker 1415932544>4585580000
<SceneMarker 1415932545>5035360000
<Cut>4235230000:5936600000
<Cut>9535530000:11527860000
<Cut>14385710000:16090090000
</pre>

== Comskip ==

[http://www.kaashoek.com/comskip/ Comskip] files are supported. The name of the file must be the same as the video but with a file extension of '''.txt'''.

The file contains the start and end frame numbers for the commercial breaks that were detected. The Comskip file may or may not contain the frame rate. If the frame rate is not found, the detected frame rate of the video is used to convert from the frame numbers to time offsets. Note that for TS files only the version 2 format is supported (where frame rate is suppplied).

The version 1 file format is:
<pre>
FILE PROCESSING COMPLETE
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE
------------------------
12693 17792
28578 34549
43114 48222
</pre>

The version 2 file format is:
<pre>
FILE PROCESSING COMPLETE [number of frames] FRAMES AT [frame rate]
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE 678900 FRAMES AT 25
------------------------
12693 17792
28578 34549
43114 48222
</pre>

== SnapStream BeyondTV ==

[http://www.snapstream.com/products/beyondtv/ BeyondTV] files are supported. The name of the file must be the same as the video but with '''.chapters.xml''' appended to the filename.

Each ''<Region>'' within the XML file is treated as a commercial break. The file format is:
<pre>
<cutlist>
<Region>
<start comment="[start time in hh:mm:ss.sssssss format - ignored]">[start time in ms * 10,000]</start>
<end comment="[end time in hh:mm:ss.sssssss format - ignored]">[end time in ms * 10,000]</end>
</Region>
</cutlist>
</pre>

For example,
<pre>
<cutlist>
<Region>
<start comment="0:07:03.0000523">4235230000</start>
<end comment="0:09:53.0000660">5936600000</end>
</Region>
<Region>
<start comment="0:15:53.0000553">9535530000</start>
<end comment="0:19:12.0000786">11527860000</end>
</Region>
<Region>
<start comment="0:23:58.0000571">14385710000</start>
<end comment="0:26:49.0000009">16090090000</end>
</Region>
</cutlist>
</pre>

= Merging or Removing Short Commercial Breaks =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] can be used to:
* Merge commercial breaks within a set of commercials that haven't been detected accurately. Very useful if you find that automatically skipped commercial breaks still end up within a set of commercial breaks.
* Remove commercial breaks that are incorrectly identified outside of a likely set of commercial breaks. Very useful if you find that commercial skipping is happening unexpectedly while watching the TV show or Movie.

= Altering Automatic Skip Timings =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] also can be used to:
* Set how long to wait before automatically skipping when the start of a commercial break is reached. Useful if the automatic skip at the start of a set of commercial breaks is happening slightly too early for your liking, particularly if you aren't ever quite sure if that was a commercial that was about to start.
* Set how long to rewind after automatically skipping to the end of the commercial break. Useful if it's kind of hard to tell if that was in fact the start of the TV show after a block of commercials.

= Showing EDL Information During Playback =
Display of EDL information was removed for v17 and v18 with the redesign of the Codec information windows.
{{Future|19|EDL markers will be visible on the video player OSD. See [https://github.com/xbmc/xbmc/pull/15767 PR15767]}}

= Using Scene Markers =

To use any scene markers that have been read, buttons on the remote need to be configured to go to the next/previous scene marker. These buttons must use the '''NextScene''' and '''PreviousScene''' codes from [[Keymap]].

{{updated|19}}

[[Category:PVR]]
[[Category:Manual]]
[[Category:Video library]]
[[Category:Advanced topics]]

List of built-in functions

2022-01-08T17:22:30Z

Enen92: /* GUI built-in's */

{{mininav| [[Python development]] {{l2| [[Add-on development]] }} {{l2| [[Skinning]] }} | [[Built-in scripting]] }}
<section begin="main content" />
Skins can use built-in functions with the <onclick> or <onfocus> tag. Scripts can call built-in functions with <code>xbmc.executebuiltin(function, block)</code>.

The latest up-to-date list of built-in functions can be found in the source code files in [https://github.com/xbmc/xbmc/tree/master/xbmc/interfaces/builtins].

In addition to the following list, for most <onclick> and <onfocus> button actions in the skin you can also use the functions from [[Keyboard.xml]].

<poem>
'''Example:'''
<onclick>VolumeUp</onclick>
<onclick>VolumeDown</onclick>
</poem>

'''You can use parameters with all media windows, as can be seen here:'''
* [[Opening Windows and Dialogs]]

== List of functions ==
<section begin="functions" />

=== Add-on built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>Addon.Default.OpenSettings(extensionpoint)</code>
| Open a settings dialog for the default addon of the given type (extensionpoint)
|
|-
| <code>Addon.Default.Set(extensionpoint)</code>
| Open a select dialog to allow choosing the default addon of the given type (extensionpoint)
|
|-
| <code>Addon.OpenSettings(id)</code>
| Open a settings dialog for the addon of the given id
|
|-
| <code>EnableAddon(id)</code>
| Enables the specified plugin/script
| v19 addition
|-
| <code>InstallAddon(id)</code>
| Will install the addon with the given id.
|
|-
| <code>InstallFromZip</code>
| Opens the "Install from zip"-dialog if "Unknown sources" is enabled. Prompts the warning message if not.
|
|-
| <code>RunAddon(id)</code>
| Runs the specified plugin/script
|
|-
| <code>RunAppleScript(script[,args]*)</code>
| Run the specified AppleScript command
|
|-
| <code>RunPlugin(plugin)</code>
| Runs the plugin. Full path must be specified. Does not work for folder plugins
|
|-
| <code>RunScript(script[,args]*)</code>
| Runs the python script. You must specify the add-on id of the script. As of 2007/02/24, all extra parameters are passed to the script as arguments and can be accessed by python using sys.argv
|
|-
| <code>StopScript(id)</code>
| Stop the script by ID or path, if running
| {{nowrap|v12 Addition}}
|-
| <code>UpdateAddonRepos</code>
| Triggers a forced update of enabled add-on repositories.
|
|-
| <code>UpdateLocalAddons</code>
| Triggers a scan of local add-on directories.
|
|-
|}

=== Android built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>StartAndroidActivity(package,[intent,dataType,dataURI])</code>
| Launch an Android native app with the given package name. Optional parms (in order): intent, dataType, dataURI. example: <nowiki>StartAndroidActivity(com.android.chrome,android.intent.action.VIEW,,http://kodi.tv/)</nowiki>
| {{nowrap|v13 Addition}}
|-
|}

=== Application built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>Extract(archive_url[, destination])</code>
| Extracts a specified archive to an optionally specified 'absolute' path.
|
|-
| <code>Mute</code>
| Mutes (or unmutes) the volume.
|
|-
| <code>NotifyAll(sender, data [, json])</code>
| Notify all connected clients
| {{nowrap|v13 Addition}}
|-
| <code>SetVolume(percent[,showvolumebar])</code>
| Sets the volume to the percentage specified. Optionally, show the Volume Dialog in Kodi when setting the volume.
|
|-
| <code>ToggleDebug</code>
| Enables/disables debug mode
| {{nowrap|v12 Addition}}
|-
| <code>ToggleDPMS</code>
| Toggle DPMS (VESA Display Power Management Signaling) mode manually
|
|-
| <code>WakeOnLan(mac)</code>
| Sends the wake-up packet to the broadcast address for the specified MAC address (Format: FF:FF:FF:FF:FF:FF or FF-FF-FF-FF-FF-FF).
|
|-
|}

=== CEC built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>CECActivateSource</code>
| Wake up playing device via a CEC peripheral
| {{nowrap|v13 Addition}}
|-
| <code>CECStandby</code>
| Put playing device on standby via a CEC peripheral
| {{nowrap|v13 Addition}}
|-
| <code>CECToggleState</code>
| Toggle state of playing device via a CEC peripheral
| {{nowrap|v13 Addition}}
|-
|}

=== EPG built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>EpgGridControl(command)</code>
| supported commands: firstprogramme (jump to the first programme) / currentprogramme (jump to the current programme) / lastprogramme (jump to the last programme) / selectdate (jump to the selected date & time) / +XX (jump XX hours forward) / -XX (jump XX hours back) / firstchannel (jump to the first channel) / playingchannel (jump to the currently playing channel) / lastchannel (jump to the last channel) / previousgroup (switch the epg to the previous group) / nextgroup (switch the epg to the next group) / selectgroup (select a group)
| {{nowrap|v19 Addition}}
|}

=== GUI built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>Action(action[,window])</code>
| Executes an action (same as in keymap) for the given window or the active window if the parameter window is omitted. The parameter window can either be the window's id, or in the case of a standard window, the window's name. See [[Action IDs]] for a list of available actions.
|
|-
| <code>ActivateWindow(window[,dir,return])</code>
| Opens the given window. The parameter window can either be the window's id, or in the case of a standard window, the window's name. See [[Window IDs]] for a list of window names, and their respective ids. If, furthermore, the window is Music, Video, Pictures, or Program files, then the optional dir parameter specifies which folder Kodi should default to once the window is opened. This must be a source as specified in sources.xml, or a subfolder of a valid source. For some windows (MusicLibrary and VideoLibrary), the return parameter may be specified, which indicates that Kodi should use this folder as the "root" of the level, and thus the "parent directory" action from within this folder will return the user to where they were prior to the window activating.
|
|-
| <code>ActivateWindowAndFocus(id1, id2,item1, id3,item2)</code>
| Activate window with id1, first focus control id2 and then focus control id3. if either of the controls is a container, you can specify which item to focus (else, set it to 0).
| {{nowrap|v12 Addition}}
|-
| <code>AlarmClock(name,command,[time,silent,loop])</code>
| Pops up a dialog asking for the length of time (mm:ss) for the alarm (unless the parameter time is specified), and starts a timer. When the timer runs out, it'll execute the built-in command (the parameter command) if it is specified, otherwise it'll pop up an alarm notice. Add silent to hide the alarm notification. Add loop for the alarm to execute the command each time the specified time interval expires. If defining the last optional parameters (silent and loop) both have to be defined for any to take effect. The parameter "time" accepts an integer value (in minutes) or a timestring in the format "hh:mm:ss" or "mm min".
|
|-
| <code>CancelAlarm(name[,silent])</code>
| Cancel a running alarm. Set silent to true to hide the alarm notification.
|
|-
| <code>ClearProperty(key[,id])</code>
| Clears a window property for the current focused window/dialog(key), or the specified window (key,id).
|
|-
| <code>Dialog.Close(dialog[,force])</code>
| Close a dialog. Set force to true to bypass animations. Use (all,true) to close all opened dialogs at once.
|
|-
| <code>NextChannelGroup</code>
| Navigate to the next PVR channel group (in DialogPVRChannelsOSD.xml)
| {{nowrap|v13 Addition}}
|-
| <code>NextStereoMode</code>
| Changes the stereo mode of the GUI to the next available mode.
| {{nowrap|v13 Addition}}
|-
| <code>Notification(header,message[,time,image])</code>
| Will display a notification dialog with the specified header and message, in addition you can set the length of time it displays in milliseconds and a icon image.
|
|-
| <code>PreviousChannelGroup</code>
| Navigate to the previous PVR channel group (in DialogPVRChannelsOSD.xml)
| {{nowrap|v13 Addition}}
|-
| <code>PreviousStereoMode</code>
| Changes the stereo mode of the GUI to the previous available mode.
| {{nowrap|v13 Addition}}
|-
| <code>RefreshRSS</code>
| Reload RSS feeds from RSSFeeds.xml
|
|-
| <code>ReplaceWindow(window,dir)</code>
| Replaces the current window with the given window. This is the same as ActivateWindow() but it doesn't update the window history list, so when you go back from the new window it will not return to the previous window, rather will return to the previous window's previous window.
|
|-
| <code>ReplaceWindowAndFocus(id1, id2,item1, id3,item2)</code>
| Replace window with id1, first focus control id2 and then focus control id3. if either of the controls is a container, you can specify which item to focus (else, set it to 0).
| {{nowrap|v13 Addition}}
|-
| <code>Resolution</code>
| Change Kodi's Resolution.
|
|-
| <code>SetGUILanguage(value)</code>
| Set GUI Language, 'value' is the language file to use. SetGUILanguage(resource.language.de_de)
| {{nowrap|v13 Addition}}
|-
| <code>SetProperty(key,value[,id])</code>
| Sets a window property for the current window (key,value), or the specified window (key,value,id).
|
|-
| <code>SetStereoMode</code>
| Changes the stereo mode of the GUI. Params can be: toggle, next, previous, select, tomono or any of the supported stereomodes (off, split_vertical, split_horizontal, row_interleaved, hardware_based, anaglyph_cyan_red, anaglyph_green_magenta, monoscopic)
| {{nowrap|v13 Addition}}
|-
| <code>settingslevelchange</code>
| Toggles the visible settings (in SettingsCategory.xml) between 'basic', 'standard', 'advanced and 'expert'
| {{nowrap|v13 Addition}}
|-
| <code>TakeScreenshot([filenameandpath,sync])</code>
| Takes a Screenshot. You can optionally specify the filename (including the path). Note: only .png files are supported. Add "sync" parameter to run synchronously (slow).
|
|-
| <code>ToggleDirtyRegionVisualization</code>
| makes dirty regions visible for debugging proposes.
| {{nowrap|v16 Addition}}
|-
| <code>ToggleStereoMode</code>
| Toggle the stereoscopic mode of the GUI (on/off).
| {{nowrap|v13 Addition}}
|-
|}

=== GUI container built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>Container.NextSortMethod</code>
| Change to the next sort method.
|
|-
| <code>Container.NextViewMode</code>
| Select the next view mode.
|
|-
| <code>Container.PreviousSortMethod</code>
| Change to the previous sort method.
|
|-
| <code>Container.PreviousViewMode</code>
| Select the previous view mode.
|
|-
| <code>Container.Refresh</code>
| Refresh current listing.
|
|-
| <code>Container.SetSortMethod(id)</code>
| Change to the specified sort method. (For list of ID's see [[https://kodi.wiki/view/List_of_built-in_functions#List_of_sort_methods list of sort methods]])
|
|-
| <code>Container.SetViewMode(id)</code>
| Set the current view mode (list, icons etc.) to the given container id.
|
|-
| <code>Container.SetSortDirection</code>
| Toggle the sort direction.
|
|-
| <code>Container.Update</code>
| Update current listing. Send Container.Update(path,replace) to reset the path history.
|
|-
|}

=== GUI control built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>Control.Message(id,message,[windowid])</code>
| Sends a given message to a control in a given window (or active window if omitted). Messages can be movedown, moveup, pagedown, pageup, click.
|
|-
| <code>Control.Move(id,offset)</code>
| Will make a Container with the "id" specified in the command move focus by "offset".
|
|-
| <code>Control.SetFocus(id,position[,absolute])</code>
| Will make a list with the "id" specified in the command gain focus at "position" number in its list. Set absolute to focus the first listitem of a container instead of the first visible listitem. Alias SetFocus(id,position)
|
|-
| <code>PageDown</code>
| Send a page down event to the pagecontrol with given id.
|
|-
| <code>PageUp</code>
| Send a page up event to the pagecontrol with given id.
|
|-
| <code>SendClick(windowid,id)</code>
| Sends a click to a control in a given window (or active window if omitted).
|
|-
| <code>SetFocus(id,position[,absolute])</code>
| Will make a list with the "id" specified in the command gain focus at "position" number in its list. Set absolute to focus the first listitem of a container instead of the first visible listitem. Alias Control.SetFocus(id,position)
|
|-
|}

=== Library built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>CleanLibrary(database)</code>
| This funtion will perform a number of 'cleanup' tasks on your video database and can be run if you have moved, deleted or renamed files. Takes either "video" or "music" as a parameter to begin cleaning the corresponding database.
|
|-
| <code>exportlibrary(music,false,filepath)</code>
| The music library will be exported to a single file stored at filepath location.
|
|-
| <code>exportlibrary(video,true,thumbs,overwrite,actorthumbs)</code>
| The video library is exported to multiple files with the given options. Here thumbs, overwrite and actorthumbs are boolean values (true or false).
|
|-
| <code>UpdateLibrary(database,[path])</code>
| Takes either "video" or "music" as a parameter to begin updating the corresponding database. For "video" you can additionally specify a specific path to be scanned.
|
|-
| <code>VideoLibrary.Search</code>
| Brings up a search dialog which will search the library
|
|-
|}

=== Optical container built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>EjectTray()</code>
| Either opens or closes the DVD tray, depending on its current state
|
|-
| <code>RipCD</code>
| Will rip the inserted CD from the DVD-ROM drive.
|
|-
|}

=== Picture built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>RecursiveSlideShow(dir)</code>
| Run a slideshow from the specified directory, including all subdirs
|
|-
| <code>ShowPicture(picture)</code>
| Show a picture by its file path/url.
| {{nowrap|v13 Addition}}
|-
| <code>SlideShow(dir[,recursive][,[not]random][,pause][,beginslide="/path/to/start/slide.jpg"])</code>
| Starts a slideshow of pictures in the folder dir. Optional parameters are 'recursive', 'random' or 'notrandom', 'pause' and 'beginslide="/path/to/some/image.jpg"' parameters. The "recursive" parameter starts a recursive slideshow, adding images from sub-folders. The "random" and "notrandom" parameters override the Randomize setting found in the pictures media window. The "pause" parameter will start the slideshow paused. "beginslide" will start the slideshow with the specified image.
|
|-
|}

=== Player built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>PlayDisc(param)</code>
| Will play the inserted CD or DVD media from the DVD-ROM drive.
|
|-
| <code>PlayerControl(command)</code>
| Allows control of music and videos. The command may be one of Play, Stop, Forward, Rewind, Next, Previous, BigSkipForward, BigSkipBackward, SmallSkipForward, SmallSkipBackward, FrameAdvance(#), TempoUp, TempoDown, Tempo(value), Random, RandomOn, RandomOff, Repeat, RepeatOne, RepeatAll, RepeatOff, Partymode(music) or Partymode(video) or Partymode(path to .xsp file) or Reset.
Play will either pause, resume, or stop ffwding or rewinding. Random toggles random playback and Repeat cycles through the repeat modes (these both take an optional second parameter, Notify, that notifies the user of the new state). Partymode(music/video) toggles the appropriate partymode, defaults to music if no parameter is given, besides the default music or video partymode you can also pass a path to a custom smartplaylist (.xsp) as parameter. Reset only applies to games and will reset the currently playing game.
|
|-
| <code>PlayerResolutionSelect</code>
| Select a different resolution
| v18
|-
| <code>Playlist.Clear</code>
| Clear the current playlist
|
|-
| <code>Playlist.PlayOffset</code>
| Start playing from a particular offset in the playlist
|
|-
| <code>PlayMedia(media[,isdir][,1],[playoffset=xx],[resume],[noresume])</code>
| Plays the media. This can be a playlist, music, or video file, directory, plugin or a url. The optional parameter ",isdir" can be used for playing a directory. ",1" will start the media without switching to fullscreen. If media is a playlist, you can use playoffset=xx where xx is the position to start playback from. Set "resume" to force resuming. Set "noresume" to force not resuming.
|
|-
| <code>PlayWith()</code>
| Play the selected item with the specified player core.
|
|-
| <code>Seek(seconds)</code>
| Seeks to the specified relative amount of seconds within the current playing media. A negative value will seek backward and a positive value forward.
| {{nowrap|v15 Addition}}
|-
|}

=== Profile built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>LoadProfile(profilename,[prompt])</code>
| Load the specified profile. If prompt is not specified, and a password would be required for the requested profile, this command will silently fail. If promp' is specified and a password is required, a password dialog will be shown.
|
|-
| <code>Mastermode</code>
| Runs Kodi in master mode
|
|-
| <code>System.LogOff</code>
| Log off current user.
|
|-
|}

=== PVR built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>PVR.SearchMissingChannelIcons</code>
| Will start a search for missing channel icons
| {{nowrap|v16 Addition}}
|-
| <code>PVR.ToggleRecordPlayingChannel</code>
| Will toggle recording on playing channel, if any
| v18
|-
| <code>PVR.SeekPercentage</code>
| Performs a seek to the given percentage in timeshift buffer, if timeshifting is supported
|
|}

=== Skin built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>ReloadSkin()</code>
| Reloads the current skin – useful for Skinners to use after they upload modified skin files (saves power cycling)
|
|-
| <code>Skin.Reset(setting)</code>
| Resets the skin setting ?setting?. If ?setting? is a bool setting (i.e. set via SetBool or ToggleSetting) then the setting is reset to false. If ?setting? is a string (Set via SetString, SetImage, or SetPath) then it is set to empty.
|
|-
| <code>Skin.ResetSettings</code>
| Resets all the above skin settings to their defaults (toggles all set to false, strings all set to empty.)
|
|-
| <code>Skin.SelectBool(header, label1|setting1, label2|setting2)</code>
| Pops up select dialog to select between multiple skin setting options. Skin.SelectBool(424, 31411|RecentWidget, 31412|RandomWidget, 31413|InProgressWidget)
|
|-
| <code>Skin.SetAddon(string,type)</code>
| Pops up a select dialog and allows the user to select an add-on of the given type to be used elsewhere in the skin via the info tag Skin.String(string). The most common types are xbmc.addon.video, xbmc.addon.audio, xbmc.addon.image, xbmc.addon.executable and kodi.gameclient.
|
|-
| <code>Skin.SetBool(setting)</code>
| Sets the skin setting ?setting? to true, for use with the conditional visibility tags containing Skin.HasSetting(setting). The settings are saved per-skin in settings.xml just like all the other Kodi settings.
|
|-
| <code>Skin.SetFile(string,mask,folderpath)</code>
| Pops up a folder browser and allows the user to select a file off the hard-disk to be used else where in the skin via the info tag Skin.String(string). If the mask parameter is specified, then the file browser will only search for the extension specified (.avi,.mp3,.m3u,.png,.bmp,etc.,etc.). To use multiple extensions separate them using "<nowiki>|</nowiki>" (minus quotes). If the folderpath parameter is set the file browser will start in that folder.
|
|-
| <code>Skin.SetImage(string[,value,path])</code>
| Pops up a file browser and allows the user to select an image file to be used in an image control elsewhere in the skin via the info tag Skin.String(string). If the value parameter is specified, then the file browser dialog does not pop up, and the image path is set directly. the path option allows you to open the file browser in the specified folder.
|
|-
| <code>Skin.SetNumeric(numeric[,value])</code>
| Pops up a keyboard dialog and allows the user to input a numerical.
|
|-
| <code>Skin.SetPath(string[,folderpath])</code>
| Pops up a folder browser and allows the user to select a folder of images to be used in a multi image control else where in the skin via the info tag Skin.String(string). If the folderpath parameter is set the file browser will start in that folder.
|
|-
| <code>Skin.SetString(string[,value])</code>
| Pops up a keyboard dialog and allows the user to input a string which can be used in a label control elsewhere in the skin via the info tag Skin.String(string). If the value parameter is specified, then the keyboard dialog does not pop up, and the string is set directly.
|
|-
| <code>Skin.Theme(1)</code>
| Cycles the skin theme. Skin.Theme(-1) will go backwards.
|
|-
| <code>Skin.ToggleDebug</code>
| Toggles skin debug info on/off
|
|-
| <code>Skin.ToggleSetting(setting)</code>
| Toggles the skin setting ?setting? for use with conditional visibility tags containing Skin.HasSetting(setting).
|
|-
| <code>UnloadSkin()</code>
| Unloads the current skin
|
|-
|}

=== System built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>ActivateScreensaver</code>
| Starts the screensaver
| {{nowrap|v13 Addition}}
|-
| <code>Hibernate</code>
| Hibernate (S4) the System
|
|-
| <code>InhibitIdleShutdown(true/false)</code>
| Prevent the system to shutdown on idle.
| {{nowrap|v12 Addition}}
|-
| <code>InhibitScreensaver(true/false)</code>
| Prevent activation of the screensaver.
| {{nowrap|v19 Addition}}
|-
| <code>Minimize</code>
| Minimizes Kodi
|
|-
| <code>Powerdown</code>
| Powerdown system
|
|-
| <code>Quit</code>
| Quits Kodi
|
|-
| <code>Reboot</code>
| Cold reboots the system (power cycle)
|
|-
| <code>Reset</code>
| Reset the system (same as reboot)
|
|-
| <code>RestartApp</code>
| Restarts Kodi (only implemented under Windows and Linux)
|
|-
| <code>ShutDown</code>
| Trigger default Shutdown action defined in System Settings
|
|-
| <code>Suspend</code>
| Suspends (S3 / S1 depending on bios setting) the System
|
|-
| <code>System.Exec(exec)</code>
| Execute shell commands. The full path to the script has to be placed inside the parentheses.
|
|-
| <code>System.ExecWait(exec)</code>
| Execute shell commands and freezes Kodi until shell is closed. As well as for "System.Exec(exec)", the full path to the script has to be placed inside the parentheses.
|
|-
|}

=== Weather built-in's ===

{| class="prettytable sort sortable" style="width: 100%;"
! style="width: 29%"| Function
! style="width: 66%"| Description
! style="width: 5%"| Version
|-
| <code>Weather.LocationNext</code>
| Switch to next weather location
|
|-
| <code>Weather.LocationPrevious</code>
| Switch to previous weather location
|
|-
| <code>Weather.LocationSet</code>
| Switch to given weather location (parameter can be 1-3)
|
|-
| <code>Weather.Refresh</code>
| Force weather data refresh
|
|}
<section end="functions" />
<section end="main content" />

== Removed functions ==
* <code>LastFM.Love</code> - Removed in v13 Gotham
* <code>LastFM.Ban</code> - Removed in v13 Gotham
* <code>LCD.Suspend</code> - Removed in v13 Gotham
* <code>LCD.Resume</code> - Removed in v13 Gotham
* <code>AllowIdleShutdown</code>
* <code>Help</code>
* <code>LIRC.Send(command)</code>
* <code>LIRC.Start</code>
* <code>LIRC.Stop</code>
* <code>StartPVRManager</code>
* <code>StereoModeToMono</code>
* <code>StopPVRManager</code>

== List of sort methods ==
These ID's can be used with the Container.SetSortMethod(id) function as listed [https://github.com/xbmc/xbmc/blob/75b31098a8800da653b373cd99a025b483029cfc/xbmc/utils/SortUtils.h#L49-L164 here]:
{| class="prettytable"
! ID
! Description
|-
| <code>1</code>
| Name
|-
| <code>2</code>
| Date
|-
| <code>3</code>
| Size
|-
| <code>4</code>
| File
|-
| <code>5</code>
| Path
|-
| <code>6</code>
| DriveType
|-
| <code>7</code>
| Title
|-
| <code>8</code>
| TrackNumber
|-
| <code>9</code>
| Time
|-
| <code>10</code>
| Artist
|-
| <code>11</code>
| ArtistThenYear
|-
| <code>12</code>
| Album
|-
| <code>13</code>
| AlbumType
|-
| <code>14</code>
| Genre
|-
| <code>15</code>
| Country
|-
| <code>16</code>
| Year
|-
| <code>17</code>
| Rating
|-
| <code>18</code>
| UserRating
|-
| <code>19</code>
| Votes
|-
| <code>20</code>
| Top250
|-
| <code>21</code>
| ProgramCount
|-
| <code>22</code>
| PlaylistOrder
|-
| <code>23</code>
| EpisodeNumber
|-
| <code>24</code>
| Season
|-
| <code>25</code>
| NumberOfEpisodes
|-
| <code>26</code>
| NumberOfWatchedEpisodes
|-
| <code>27</code>
| TvShowStatus
|-
| <code>28</code>
| TvShowTitle
|-
| <code>29</code>
| SortTitle
|-
| <code>30</code>
| ProductionCode
|-
| <code>31</code>
| MPAA
|-
| <code>32</code>
| VideoResolution
|-
| <code>33</code>
| VideoCodec
|-
| <code>34</code>
| VideoAspectRatio
|-
| <code>35</code>
| AudioChannels
|-
| <code>36</code>
| AudioCodec
|-
| <code>37</code>
| AudioLanguage
|-
| <code>38</code>
| SubtitleLanguage
|-
| <code>39</code>
| Studio
|-
| <code>40</code>
| DateAdded
|-
| <code>41</code>
| LastPlayed
|-
| <code>42</code>
| Playcount
|-
| <code>43</code>
| Listeners
|-
| <code>44</code>
| Bitrate
|-
| <code>45</code>
| Random
|-
| <code>46</code>
| Channel
|-
| <code>47</code>
| ChannelNumber
|-
| <code>48</code>
| DateTaken
|-
| <code>49</code>
| Relevance
|-
| <code>50</code>
| InstallDate
|-
| <code>51</code>
| LastUpdated
|-
| <code>52</code>
| LastUsed
|}
{{updated|18}}

== See also ==
* [[Action IDs]]

[[Category:Python]]
[[Category:Add-on development]]
[[Category:Skin development]]

Addon.xml

2022-01-04T17:49:02Z

Enen92: Examples (and addons on the repo already use commas) let's allow it anyway

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.15.0 (ABI 5.14.0) || 11.2.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[Service_add-ons|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|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script_sources|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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script_lyrics|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>xbmc.python.library</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.font</code>
|Additional font files
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|-
|<code>kodi.resource.uisounds</code>
|Additional sound files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

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

{{Note|If the '''<provides>''' element is not defined, behaviour will depend on the structure of your addon. If it has a single extension point (e.g. a single '''xbmc.python.script''' or '''xbmc.python.pluginsource'''), kodi will default to "executable" (thus your addon will be shown in programs). If your addon has multiple extension points and none specifies a '''<provides>''' element, different entries for your addon will be shown in "programs" (multiple fallbacks to "executable"). If your addon has multiple extension points and only one (or some) define the '''<provides>''' tag it really depends on the order of the extension points. If the first extension point (your addon '''main extension point''') defines the '''<provides>''' element, kodi will assume all the other (empty) extension points provide the same content. Otherwise it will set the content for all the extension points that specify the '''<provides>''' tag and fallback all the others to "executable". '''At the moment, there is no way to hide an addon from the interface.''' |reminder}}

==== 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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the deprecated tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</code>

{{note|Kodi v19 Matrix and later.}}

* <code>tvos</code>
* <code>tvos-aarch64</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

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

If your add-on includes multiple licenses:

* Separate license names using | (pipe) when there is a choice between licenses:
<source lang="xml">
<license>GPL-2.0-or-later | LGPL-2.0-or-later</license>
</source>
* Separate license names using & (ampersand), or commas, when multiple licenses exist that cover different parts of the source.
<source lang="xml">
<license>GPL-2.0-or-later & MIT</license>
</source>

or

<source lang="xml">
<license>GPL-2.0-or-later, MIT</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" enclose="div">
<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>

===== <lifecyclestate> =====

{{note|Kodi v19 Matrix and later.}}

The <code><lifecyclestate></code> tag will mark the add-on as broken or deprecated in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the related reason. Also, the lifecyclestate tag presupposes that a version bump has been made to the addon.

<source lang="xml">
<lifecyclestate type="deprecated">Description why deprecated</lifecyclestate>
</source>

It can also optionally be translated into several languages.
<source lang="xml">
<lifecyclestate type="broken" lang="en_GB">Description why broken</lifecyclestate>
</source>

Possible types for here:
{| class="prettytable"
| '''broken'''
| To mark addon as broken and no more usable.
|-
| '''deprecated'''
| To mark addon as deprected and to have e.g. replaced by another addon.
|-
| '''normal'''
| To set addon as normal. This value is not really needed, only available to be able to declare all possible life paths.
|}

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

{{note|Kodi v18 Leia and earlier. For matrix and later, see [[Addon.xml#.3Clifecyclestate.3E|lifecyclestate]]}}

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Matrix updated}}

[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Python]]

Addon.xml

2022-01-04T14:57:52Z

Enen92: Multilicense clarification

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.15.0 (ABI 5.14.0) || 11.2.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[Service_add-ons|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|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script_sources|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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script_lyrics|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>xbmc.python.library</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.font</code>
|Additional font files
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|-
|<code>kodi.resource.uisounds</code>
|Additional sound files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

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

{{Note|If the '''<provides>''' element is not defined, behaviour will depend on the structure of your addon. If it has a single extension point (e.g. a single '''xbmc.python.script''' or '''xbmc.python.pluginsource'''), kodi will default to "executable" (thus your addon will be shown in programs). If your addon has multiple extension points and none specifies a '''<provides>''' element, different entries for your addon will be shown in "programs" (multiple fallbacks to "executable"). If your addon has multiple extension points and only one (or some) define the '''<provides>''' tag it really depends on the order of the extension points. If the first extension point (your addon '''main extension point''') defines the '''<provides>''' element, kodi will assume all the other (empty) extension points provide the same content. Otherwise it will set the content for all the extension points that specify the '''<provides>''' tag and fallback all the others to "executable". '''At the moment, there is no way to hide an addon from the interface.''' |reminder}}

==== 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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the deprecated tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</code>

{{note|Kodi v19 Matrix and later.}}

* <code>tvos</code>
* <code>tvos-aarch64</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

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

If your add-on includes multiple licenses:

* Separate license names using | (pipe) when there is a choice between licenses:
<source lang="xml">
<license>GPL-2.0-or-later | LGPL-2.0-or-later</license>
</source>
* Separate license names using & (ampersand) when multiple licenses exist that cover different parts of the source.
<source lang="xml">
<license>GPL-2.0-or-later & MIT</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" enclose="div">
<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>

===== <lifecyclestate> =====

{{note|Kodi v19 Matrix and later.}}

The <code><lifecyclestate></code> tag will mark the add-on as broken or deprecated in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the related reason. Also, the lifecyclestate tag presupposes that a version bump has been made to the addon.

<source lang="xml">
<lifecyclestate type="deprecated">Description why deprecated</lifecyclestate>
</source>

It can also optionally be translated into several languages.
<source lang="xml">
<lifecyclestate type="broken" lang="en_GB">Description why broken</lifecyclestate>
</source>

Possible types for here:
{| class="prettytable"
| '''broken'''
| To mark addon as broken and no more usable.
|-
| '''deprecated'''
| To mark addon as deprected and to have e.g. replaced by another addon.
|-
| '''normal'''
| To set addon as normal. This value is not really needed, only available to be able to declare all possible life paths.
|}

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

{{note|Kodi v18 Leia and earlier. For matrix and later, see [[Addon.xml#.3Clifecyclestate.3E|lifecyclestate]]}}

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Matrix updated}}

[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Python]]

Edit decision list

2022-01-03T12:40:54Z

Enen92:

{{mininav| [[Video library]] {{l2| [[Live TV]] }} }}
<section begin="intro" />An '''edit decision list''' (EDL) contains information about edits that should be made to the video during playback. Edit decision list information is contained in a separate file to the video that is read by Kodi just before the video is played. Examples of use include can be to skip commercials, cut out content inappropriate for children, or skip over the half hour acid trip in ''2001: A Space Odyssey'' . <section end="intro" />

Inspiration for this functionality came from [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL support].

The internal video player ([[VideoPlayer]]) used by Kodi supports the following types of edits:
* '''Cut''' - the content is completely removed from playback as if it were never in the original video. For example, the total playback time is adjusted and the content is always automatically skipped during playback, seeking, fast forward or rewind.
* '''Mute''' - the audio is muted, video continues playing.
* '''Scene Marker''' - these can be used to seek to points of interest within a video similar to how chapter seeking works for DVDs.
* '''Commercial Break''' - each commercial break is automatically skipped once during playback. Since commercial detection is rarely 100% accurate, commercial breaks that have already been skipped can be re-entered by seeking backwards or rewinding. Note: Scene Markers are placed at the start and end of each commercial break so you can easily jump between the start and end of commbreaks using Scene Marker's builtin actions ('''NextScene''' and '''PreviousScene''')

<br />
{{bigger|{{note|'''If using actual .EDL files the following field must be added to comskip.ini:'''}} }}
<br /><br />

<pre>
edl_skip_field=3
</pre>

By default this value will be 0 in Comskip, and Kodi will see them as '''Cut''' actions and remove the section from the video (i.e. a 30 minute video would appear as 22 minutes with commericals removed). Setting this value overrides this behaviour allowing Kodi to treat it as a '''Commercial Break'''.

With edl_skip_field=3 , the full video file is visible, but Kdoi will skip the marked commercials the first time it attempts to play them. If, after commercials are skipped, you skip back through the recording (into a commercial area), you can then watch the video that was marked as a commercial.

(thanks '''sbthomas''' for the solution)

<br />

= Supported File Formats =

Kodi is able to read edit decision lists from multiple file formats. The EDL file for a video must be in the same folder as the video file and is looked for based on the file extensions for the supported formats.

For example if the video file is called '''The Matrix.avi''' Kodi will look for the following files, in order, until a valid file is found. Note the the file name may be case-sensitive based on the operating system being used.
# '''The Matrix.Vprj''' (VideoReDo)
# '''The Matrix.edl''' (MPlayer EDL)
# '''The Matrix.txt''' (Comskip)
# '''The Matrix.avi.chapters.xml''' (SnapStream BeyondTV)

== MPlayer EDL ==

Classic [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL] files are supported. Kodi also supports an extended version of this file format that allows extra functionality as outlined below. The name of the file must be the same as the video file but with a file extension of '''.edl'''.

The file contains the start and end times of the edits along with the type of action associated with each edit. The file format is:
<pre>
[start time] [end time] [action]
</pre>

Start and end times can be defined as seconds, HH:MM:SS.sss, or frames. To specify frames precede the frame number with the # symbol. The original MPlayer EDL files only support seconds for start and end times.

The actions supported by this file format have also been extended by Kodi to include Scene Marker and Commercial Break actions since the original format only supports Cut and Mute. Supported actions are:
* 0 - Cut
* 1 - Mute
* 2 - Scene Marker (if start and end times are specified, the end time is used)
* 3 - Commercial Break

For example, the following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 420 seconds to 822 seconds. There will be two scene markers. The first at 255.3 seconds and the next at 720.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
420 822 3
1 255.3 2
720.1 2
</pre>

The following .edl file content will skip from frame 127 to frame 170, mute at frame 360, unmute at frame 400, and commercial skip from frame 10080 to frame 19728. There will be two scene markers. The first at frame 6127 and the next at frame 17282. Note that when using frame numbers TS files are not supported, other file formats that correctly provide frame rate will work.
<pre>
#127 #170 0
#360 #400 1
#10080 #19728 3
#1 #6127 2
#17282 2
</pre>

The following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 7 minutes to 13 minutes and 42 seconds. There will be two scene markers. The first at 4 minutes and 15.3 seconds and the next at 12 minutes and 0.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
7:00 13:42 3
1 4:15.3 2
12:00.1 2
</pre>

Seconds and HH:MM:SS.sss can be accurately specified to three decimal places. Currently EDL cuts and mutes are frame accurate when specifying frames. Frames are specified inclusive (specify first frame to cut and last frame to cut).

{{future|19|In Kodi v19, the addition of handling a comment line has been added. These lines are defined as beginning with ##<br>Kodi will ignore any lines beginning with ## and continue processing the EDL file.}}

== VideoReDo ==

[http://www.videoredo.com/ VideoReDo] files are supported. The name of the file must be the same as the video but with a file extension of '''.Vprj'''.

Only lines starting with ''<SceneMarker>'' and ''<Cut>'' are read from the file. Each ''<Cut>'' is treated as a commercial break. The file format is:
<pre>
<Version>[ignored]
<Filename>[ignored]
<InputPIDList>
<VideoStreamPID>[ignored]</VideoStreamPID>
<AudioStreamPID>[ignored]</AudioStreamPID>
</InputPIDList>
<SceneMarker [ignored]>[scene marker time] (in ms * 10,000)
<Cut>[start time]:[end time] (both in ms * 10,000)
</pre>

For example,
<pre>
<Version>2
<Filename>C:\Path\To\Video.mpg
<InputPIDList>
<VideoStreamPID>224</VideoStreamPID>
<AudioStreamPID>192</AudioStreamPID>
</InputPIDList>
<SceneMarker 1415932542>4235230000
<SceneMarker 1415932543>4284610000
<SceneMarker 1415932544>4585580000
<SceneMarker 1415932545>5035360000
<Cut>4235230000:5936600000
<Cut>9535530000:11527860000
<Cut>14385710000:16090090000
</pre>

== Comskip ==

[http://www.kaashoek.com/comskip/ Comskip] files are supported. The name of the file must be the same as the video but with a file extension of '''.txt'''.

The file contains the start and end frame numbers for the commercial breaks that were detected. The Comskip file may or may not contain the frame rate. If the frame rate is not found, the detected frame rate of the video is used to convert from the frame numbers to time offsets. Note that for TS files only the version 2 format is supported (where frame rate is suppplied).

The version 1 file format is:
<pre>
FILE PROCESSING COMPLETE
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE
------------------------
12693 17792
28578 34549
43114 48222
</pre>

The version 2 file format is:
<pre>
FILE PROCESSING COMPLETE [number of frames] FRAMES AT [frame rate]
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE 678900 FRAMES AT 25
------------------------
12693 17792
28578 34549
43114 48222
</pre>

== SnapStream BeyondTV ==

[http://www.snapstream.com/products/beyondtv/ BeyondTV] files are supported. The name of the file must be the same as the video but with '''.chapters.xml''' appended to the filename.

Each ''<Region>'' within the XML file is treated as a commercial break. The file format is:
<pre>
<cutlist>
<Region>
<start comment="[start time in hh:mm:ss.sssssss format - ignored]">[start time in ms * 10,000]</start>
<end comment="[end time in hh:mm:ss.sssssss format - ignored]">[end time in ms * 10,000]</end>
</Region>
</cutlist>
</pre>

For example,
<pre>
<cutlist>
<Region>
<start comment="0:07:03.0000523">4235230000</start>
<end comment="0:09:53.0000660">5936600000</end>
</Region>
<Region>
<start comment="0:15:53.0000553">9535530000</start>
<end comment="0:19:12.0000786">11527860000</end>
</Region>
<Region>
<start comment="0:23:58.0000571">14385710000</start>
<end comment="0:26:49.0000009">16090090000</end>
</Region>
</cutlist>
</pre>

= Merging or Removing Short Commercial Breaks =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] can be used to:
* Merge commercial breaks within a set of commercials that haven't been detected accurately. Very useful if you find that automatically skipped commercial breaks still end up within a set of commercial breaks.
* Remove commercial breaks that are incorrectly identified outside of a likely set of commercial breaks. Very useful if you find that commercial skipping is happening unexpectedly while watching the TV show or Movie.

= Altering Automatic Skip Timings =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] also can be used to:
* Set how long to wait before automatically skipping when the start of a commercial break is reached. Useful if the automatic skip at the start of a set of commercial breaks is happening slightly too early for your liking, particularly if you aren't ever quite sure if that was a commercial that was about to start.
* Set how long to rewind after automatically skipping to the end of the commercial break. Useful if it's kind of hard to tell if that was in fact the start of the TV show after a block of commercials.

= Showing EDL Information During Playback =
Display of EDL information was removed for v17 and v18 with the redesign of the Codec information windows.
{{Future|19|EDL markers will be visible on the video player OSD. See [https://github.com/xbmc/xbmc/pull/15767 PR15767]}}

= Using Scene Markers =

To use any scene markers that have been read, buttons on the remote need to be configured to go to the next/previous scene marker. These buttons must use the '''NextScene''' and '''PreviousScene''' codes from [[Keymap]].

{{updated|19}}

[[Category:PVR]]
[[Category:Manual]]
[[Category:Video library]]
[[Category:Advanced topics]]

Edit decision list

2022-01-03T10:31:56Z

Enen92: This functionality was removed in Krypton. Personally I don't think it's important, users can still enter commercial breaks using seeks, rewinding or using custom scene actions "NextScene" or "PrevScene"

{{mininav| [[Video library]] {{l2| [[Live TV]] }} }}
<section begin="intro" />An '''edit decision list''' (EDL) contains information about edits that should be made to the video during playback. Edit decision list information is contained in a separate file to the video that is read by Kodi just before the video is played. Examples of use include can be to skip commercials, cut out content inappropriate for children, or skip over the half hour acid trip in ''2001: A Space Odyssey'' . <section end="intro" />

Inspiration for this functionality came from [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL support].

The internal video player ([[VideoPlayer]]) used by Kodi supports the following types of edits:
* '''Cut''' - the content is completely removed from playback as if it were never in the original video. For example, the total playback time is adjusted and the content is always automatically skipped during playback, seeking, fast forward or rewind.
* '''Mute''' - the audio is muted, video continues playing.
* '''Scene Marker''' - these can be used to seek to points of interest within a video similar to how chapter seeking works for DVDs.
* '''Commercial Break''' - each commercial break is automatically skipped once during playback. Since commercial detection is rarely 100% accurate, commercial breaks that have already been skipped can be re-entered by seeking backwards or rewinding. Note: Scene Markers are placed at the start and end of each commercial break so you can easily jump between the start and end of commbreaks using Scene Marker's builtin actions ('''NextScene''' and '''PreviousScene''')

<br />
{{bigger|{{note|'''If using actual .EDL files the following field must be added to comskip.ini:'''}} }}
<br /><br />

<pre>
edl_skip_field=3
</pre>

By default this value will be 0 in Comskip, and Kodi will see them as '''Cut''' actions and remove the section from the video (i.e. a 30 minute video would appear as 22 minutes with commericals removed). Setting this value overrides this behaviour allowing Kodi to treat it as a '''Commercial Break'''.

With edl_skip_field=3 , the full video file is visible, but Kdoi will skip the marked commercials the first time it attempts to play them. If, after commercials are skipped, you skip back through the recording (into a commercial area), you can then watch the video that was marked as a commercial.

(thanks '''sbthomas''' for the solution)

<br />

= Supported File Formats =

Kodi is able to read edit decision lists from multiple file formats. The EDL file for a video must be in the same folder as the video file and is looked for based on the file extensions for the supported formats.

For example if the video file is called '''The Matrix.avi''' Kodi will look for the following files, in order, until a valid file is found. Note the the file name may be case-sensitive based on the operating system being used.
# '''The Matrix.Vprj''' (VideoReDo)
# '''The Matrix.edl''' (MPlayer EDL)
# '''The Matrix.txt''' (Comskip)
# '''The Matrix.avi.chapters.xml''' (SnapStream BeyondTV)

== MPlayer EDL ==

Classic [http://www.mplayerhq.hu/DOCS/HTML/en/edl.html MPlayer EDL] files are supported. Kodi also supports an extended version of this file format that allows extra functionality as outlined below. The name of the file must be the same as the video file but with a file extension of '''.edl'''.

The file contains the start and end times of the edits along with the type of action associated with each edit. The file format is:
<pre>
[start time] [end time] [action]
</pre>

Start and end times can be defined as seconds, HH:MM:SS.sss, or frames. To specify frames precede the frame number with the # symbol. The original MPlayer EDL files only support seconds for start and end times.

The actions supported by this file format have also been extended by Kodi to include Scene Marker and Commercial Break actions since the original format only supports Cut and Mute. Supported actions are:
* 0 - Cut
* 1 - Mute
* 2 - Scene Marker (if start and end times are specified, the end time is used)
* 3 - Commercial Break

For example, the following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 420 seconds to 822 seconds. There will be two scene markers. The first at 255.3 seconds and the next at 720.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
420 822 3
1 255.3 2
720.1 2
</pre>

The following .edl file content will skip from frame 127 to frame 170, mute at frame 360, unmute at frame 400, and commercial skip from frame 10080 to frame 19728. There will be two scene markers. The first at frame 6127 and the next at frame 17282. Note that when using frame numbers TS files are not supported, other file formats that correctly provide frame rate will work.
<pre>
#127 #170 0
#360 #400 1
#10080 #19728 3
#1 #6127 2
#17282 2
</pre>

The following .edl file content will skip from second 5.3 to second 7.1, mute at 15 seconds, unmute at 16.7 seconds, and commercial skip from 7 minutes to 13 minutes and 42 seconds. There will be two scene markers. The first at 4 minutes and 15.3 seconds and the next at 12 minutes and 0.1 seconds.
<pre>
5.3 7.1 0
15 16.7 1
7:00 13:42 3
1 4:15.3 2
12:00.1 2
</pre>

Seconds and HH:MM:SS.sss can be accurately specified to three decimal places. Currently EDL cuts and mutes are frame accurate when specifying frames. Frames are specified inclusive (specify first frame to cut and last frame to cut).

{{future|19|In Kodi v19, the addition of handling a comment line has been added. These lines are defined as beginning with ##<br>Kodi will ignore any lines beginning with ## and continue processing the EDL file.}}

== VideoReDo ==

[http://www.videoredo.com/ VideoReDo] files are supported. The name of the file must be the same as the video but with a file extension of '''.Vprj'''.

Only lines starting with ''<SceneMarker>'' and ''<Cut>'' are read from the file. Each ''<Cut>'' is treated as a commercial break. The file format is:
<pre>
<Version>[ignored]
<Filename>[ignored]
<InputPIDList>
<VideoStreamPID>[ignored]</VideoStreamPID>
<AudioStreamPID>[ignored]</AudioStreamPID>
</InputPIDList>
<SceneMarker [ignored]>[scene marker time] (in ms * 10,000)
<Cut>[start time]:[end time] (both in ms * 10,000)
</pre>

For example,
<pre>
<Version>2
<Filename>C:\Path\To\Video.mpg
<InputPIDList>
<VideoStreamPID>224</VideoStreamPID>
<AudioStreamPID>192</AudioStreamPID>
</InputPIDList>
<SceneMarker 1415932542>4235230000
<SceneMarker 1415932543>4284610000
<SceneMarker 1415932544>4585580000
<SceneMarker 1415932545>5035360000
<Cut>4235230000:5936600000
<Cut>9535530000:11527860000
<Cut>14385710000:16090090000
</pre>

== Comskip ==

[http://www.kaashoek.com/comskip/ Comskip] files are supported. The name of the file must be the same as the video but with a file extension of '''.txt'''.

The file contains the start and end frame numbers for the commercial breaks that were detected. The Comskip file may or may not contain the frame rate. If the frame rate is not found, the detected frame rate of the video is used to convert from the frame numbers to time offsets. Note that for TS files only the version 2 format is supported (where frame rate is suppplied).

The version 1 file format is:
<pre>
FILE PROCESSING COMPLETE
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE
------------------------
12693 17792
28578 34549
43114 48222
</pre>

The version 2 file format is:
<pre>
FILE PROCESSING COMPLETE [number of frames] FRAMES AT [frame rate]
------------------------
[start frame] [end frame]
</pre>

For example,
<pre>
FILE PROCESSING COMPLETE 678900 FRAMES AT 25
------------------------
12693 17792
28578 34549
43114 48222
</pre>

== SnapStream BeyondTV ==

[http://www.snapstream.com/products/beyondtv/ BeyondTV] files are supported. The name of the file must be the same as the video but with '''.chapters.xml''' appended to the filename.

Each ''<Region>'' within the XML file is treated as a commercial break. The file format is:
<pre>
<cutlist>
<Region>
<start comment="[start time in hh:mm:ss.sssssss format - ignored]">[start time in ms * 10,000]</start>
<end comment="[end time in hh:mm:ss.sssssss format - ignored]">[end time in ms * 10,000]</end>
</Region>
</cutlist>
</pre>

For example,
<pre>
<cutlist>
<Region>
<start comment="0:07:03.0000523">4235230000</start>
<end comment="0:09:53.0000660">5936600000</end>
</Region>
<Region>
<start comment="0:15:53.0000553">9535530000</start>
<end comment="0:19:12.0000786">11527860000</end>
</Region>
<Region>
<start comment="0:23:58.0000571">14385710000</start>
<end comment="0:26:49.0000009">16090090000</end>
</Region>
</cutlist>
</pre>

= Merging or Removing Short Commercial Breaks =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] can be used to:
* Merge commercial breaks within a set of commercials that haven't been detected accurately. Very useful if you find that automatically skipped commercial breaks still end up within a set of commercial breaks.
* Remove commercial breaks that are incorrectly identified outside of a likely set of commercial breaks. Very useful if you find that commercial skipping is happening unexpectedly while watching the TV show or Movie.

= Altering Automatic Skip Timings =

The [[Advancedsettings.xml#.3Cedl.3E|<edl> section of advancedsettings.xml]] also can be used to:
* Set how long to wait before automatically skipping when the start of a commercial break is reached. Useful if the automatic skip at the start of a set of commercial breaks is happening slightly too early for your liking, particularly if you aren't ever quite sure if that was a commercial that was about to start.
* Set how long to rewind after automatically skipping to the end of the commercial break. Useful if it's kind of hard to tell if that was in fact the start of the TV show after a block of commercials.

= Showing EDL Information During Playback =
Display of EDL information was removed for v17 and v18 with the redesign of the Codec information windows.
{{Future|19|EDL markers will be visible on the video player OSD. See [https://github.com/xbmc/xbmc/pull/15767 PR15767]}}

= Using Scene Markers =

To use any scene markers that have been read, buttons on the remote need to be configured to go to the next/previous scene marker. These buttons must use the '''NextScene''' and '''PreviousScene''' codes from [[Keymap]].

{{updated|18}}

[[Category:PVR]]
[[Category:Manual]]
[[Category:Video library]]
[[Category:Advanced topics]]

Submitting Add-ons

2021-12-29T23:06:31Z

Enen92: Don't allow new addons into Leia anymore, only updates to existing addons.

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

=== Submitting a Compliant Add-on to the Kodi.tv Repo ===

After you have read the [[Add-on rules|repository guidelines]] and made sure your addon is compliant with them, you may begin the submission process using the following steps.

=== Allowed submissions ===

We have restricted the allowed submissions of add-ons to past Kodi versions.
Several reasons:
* Kodi code improvements
* Reduce support load for add-on developers
* Reduce workload for repository maintainers

Below is a table of on which submissions are allowed to official Kodi repository.

{| class="prettytable" border="1"
|+ Allowed add-on submissions
! codename !! version !! update !! new
|-
| Dharma || 10.x || no || no
|-
| Eden || 11.x || no || no
|-
| Frodo || 12.x || no || no
|-
| Gotham || 13.x || yes || no
|-
| Helix || 14.x || yes || no
|-
| Isengard || 15.x || yes || no
|-
| Jarvis || 16.x || yes || no
|-
| Krypton || 17.x || yes || no
|-
| Leia || 18.x || yes || no
|-
| Matrix || 19.x || yes || yes
|-
| Nexus || 20.x || yes || yes
|}

Additional feature is that we now use combined repositories. So if your add-on is Gotham/Helix compatible, you only need to send it to Gotham repository.
If it's only Helix compatible you need to send it to Helix repository.
This of course requires that the minimal Kodi dependencies are set accordingly.

{| class="prettytable" border="1"
|+ Which repos are used for Python add-ons (scripts, scrapers and plugins)
! codename !! version !! repos !!colspan="8"| repo
|-
| Dharma || 10.x || Dharma
|-
| Eden || 11.x || Eden
|-
| Frodo || 12.x || Frodo
|-
| Gotham || 13.x || Gotham
|-
| Helix || 14.x || Gotham || Helix
|-
| Isengard || 15.x || Gotham || Helix || Isengard
|-
| Jarvis || 16.x || Gotham || Helix || Isengard || Jarvis
|-
| Krypton || 17.x || Gotham || Helix || Isengard || Jarvis || Krypton
|-
| Leia || 18.x || Gotham || Helix || Isengard || Jarvis || Krypton || Leia
|-
| Matrix|| 19.x || - || - || - || - || - || - || Matrix
|-
| Nexus|| 20.x || - || - || - || - || - || - || Matrix || Nexus
|}

{| class="prettytable" border="1"
|+ Which repos are used for skins
! codename !! version !! repos !!colspan="8"| repo
|-
| Dharma || 10.x || Dharma
|-
| Eden || 11.x || Eden
|-
| Frodo || 12.x || Frodo
|-
| Gotham || 13.x || Gotham
|-
| Helix || 14.x || Gotham || Helix
|-
| Isengard || 15.x || || || Isengard
|-
| Jarvis || 16.x || || || || Jarvis
|-
| Krypton || 17.x || || || || || Krypton
|-
| Leia || 18.x || || || || || || Leia
|-
| Matrix|| 19.x || || || || || || || Matrix
|-
| Nexus|| 20.x || || || || || || || Matrix || Nexus
|}

{| class="prettytable" border="1"
|+ Which repos are used for other add-ons
! codename !! version !! repos !!colspan="8"| repo
|-
| Dharma || 10.x || Dharma
|-
| Eden || 11.x || Eden
|-
| Frodo || 12.x || Frodo
|-
| Gotham || 13.x || Gotham
|-
| Helix || 14.x || Gotham || Helix
|-
| Isengard || 15.x || Gotham || Helix || Isengard
|-
| Jarvis || 16.x || Gotham || Helix || Isengard || Jarvis
|-
| Krypton || 17.x || Gotham || Helix || Isengard || Jarvis || Krypton
|-
| Leia || 18.x || Gotham || Helix || Isengard || Jarvis || Krypton || Leia
|-
| Matrix || 19.x || Gotham || Helix || Isengard || Jarvis || Krypton || Leia || Matrix
|-
| Nexus || 20.x || Gotham || Helix || Isengard || Jarvis || Krypton || Leia || Matrix || Nexus
|}

{{see also|Addon.xml#Dependency_versions}}

=== Github ===

==== Pull requests ====
New add-ons or updates may be submitted directly to the [[Official add-on repository]] on Github as pull requests. We are aware that this requires some initial git knowledge and we strongly suggest to read up on this subject before submitting a pull request.

To reduce size we have split up the git repositories in several locations. Please visit [[Official add-on repository]] to see where they are. Each contains a small readme with a short description of it's contents as well as a link to a short explanation on how to submit using git command line. There are also git tools available that have a graphic interface and the steps above should be done in a similar way. Please consult the manual of those programs.

In addition to the [[Add-on rules|repository guidelines]] the following rules apply when submitting PRs on Github:

* PR should contain one commit only.
* Commit message should have the format "[addonid] version". Example: "[my.cool.addon] 1.0.1"

If Team Kodi reviewers asked you to make some changes in your PR, follow this procedure: [[HOW-TO: Update a pull request to an official addon repository on GitHub]].

Only PRs from the add-on author or his successor will be accepted. Patches should be submitted upstream to the original author first. For an easy way to create PR from your own git repository, see [[HOW-TO: create add-on PRs using Git Subtree Merging]].

==== Issue ticket ====

'''This route is only available for skins in https://github.com/xbmc/repo-skins.
'''

For skins submissions you may also use the "issue" option where you submit a request to get you add-on added. In this ticket you need to provide the basic information needed so our repo maintainers know where to get the correct version.
This consists of
- Add-on name:
- Add-on ID:
- Version number:
- Kodi/repository version:
- Code location URL:
- Revision/tag:
- Branch:

Further information is provide when you initially create the issue on github as comments in the ticket.
Same [[Add-on rules|repository guidelines]] apply here as well.

==== How to submit your add-on and subsequent updates ====
Submitting updates is done the same way as with pull requests or issue ticket.

==== Repository lists ====
You can create pull requests or tickets on the following individual repositories.

https://github.com/xbmc/repo-plugins
https://github.com/xbmc/repo-resources
https://github.com/xbmc/repo-scrapers
https://github.com/xbmc/repo-scripts
https://github.com/xbmc/repo-skins
https://github.com/xbmc/repo-webinterfaces

=== Additional information ===
Note that skin .xbt files will be generated automatically for skins so you do not include this in your pull request or created tickets.
After the add-on has been added or updated it will be available from the Kodi repository in Kodi itself, on http://addons.kodi.tv/ and on the wiki page http://kodi.wiki/index.php?title=Category:All_add-ons.

{{Note|Please locate you add-on in the root of the git repository. This to make sure we can easily pull the add-on into our repository.
Example: https://github.com/XBMC-Addons/service.xbmc.versioncheck}}

{{tip|We automatically combine all repos into one single repo list on our server and provide that list to Kodi. You only need to do a request for the minimum repo your add-on supports.}}

=== The mailing list ===

''' MAILINGLIST IS NOT USED ANYMORE. ALL REQUESTS SHOULD GO THROUGH GITHUB '''

[[Category:Add-on development]]

Subtitles

2021-04-14T08:06:35Z

Enen92: Just a minor rephrase, as gotham is already too old :)

{{mininav|[[Video library]] {{l2| [[Settings]] }}|[[Video playback]] {{l2| [[Settings/Player|Player]] }} }}
<section begin="intro" />Kodi supports both stand-alone subtitle and embedded subtitles. Most major subtitle formats are supported. Kodi can also search and download subtitles directly from full screen playback. <section end="intro" />

== Changing subtitle settings during playback ==
[[File:Estuary-OSD-video-subtitle-selection.png|500px|right|thumb|The audio options are found under the gear icon.]]
{{main|Video playback}}
Various subtitle settings can be changed or they turned On/Off (default is on) via the [[Video_playback#Video_Player_OSD|OSD (On Screen Display)]] while watching a movie by selecting the subtitle menu or audio options.

{{note|To make Kodi '''turn off''' subtitles by default: While playing a video, bring up the on screen display and select the audio options -> Turn off "subtitles" -> scroll down and select "save as default for all videos".}}
{{-}}

=== Settings details ===
[[File:Video Playback OSD 04.jpg|right|500px]]
{{#lst:Video playback|OSD subs}}

== Additional settings ==

=== Main settings ===
{{See also|Settings/Player/Language#Subtitles}}

=== Adjusting subtitles position ===
The position of the subtitles can be adjusted vertically (but not horizontally) in the [[Settings/System/Display#Calibration|Video Calibration]] screen, you can also configure the way that they are displayed though the [[Settings/Player/Language#Subtitles|Subtitles Settings]].<br />
'''Note:''' This does not apply to DVD subtitles as the DVD itself defines their location.

== Subtitle downloader ==
{{Main|HOW-TO:Set_up_subtitle_services}}

* <code>ActivateWindow(subtitlesearch)</code> can be bound to a remote button using [[keymaps]] in order to quickly bring up the subtitle search window.

== Manually downloaded external subtitle files ==
To use stand-alone subtitle files with video files, put them in the same folder as the video file or alternatively go to the [[Settings/Player/Language#Download_Services|Subtitles Settings]] and set a Custom Subtitle Directory. You can also choose to manually browse for the subtitle file via the [[Video_playback#Video_Player_OSD|OSD (On Screen Display)]]. You can configure the way that they are displayed through the [[Settings/Player/Language#Subtitles|Subtitles Settings]], and you can adjust where they are displayed onscreen through the [[Settings/System/Display#Calibration|Video Calibration Screen]].

The subtitle and video files must have the same name, for example:
'''Video File:''' The Matrix.avi
'''Subtitle:''' The Matrix.srt

=== Compressed subtitles ===
Kodi also supports compressed VobSub subtitles. Please note that the subtitles inside the [http://en.wikipedia.org/wiki/Rar RAR] archive still need to have the same name as the video file and requires the rar add-on being installed: See: [[Add-on:RAR_archive_support|RAR archive support]].
'''Video File:''' The Matrix.avi
'''Subtitle:''' The Matrix.rar
Where The Matrix.rar containins the VobSub-file ''The Matrix.sub'' and the ''The Matrix.idx'' VobSub index-file that has been compressed with [http://en.wikipedia.org/wiki/Rar RAR].
If you want Kodi to automatically turn on packed subtitles, you have to turn on the '''Search for Subtitles in RARs''' option in [[Settings/Player/Language#Subtitles|Subtitles Settings]].

=== Using multi language subtitles ===
Kodi supports the use of more than one external subtitle. This of course is most useful when you have more than one subtitle file, (eg. for more than language).

To use this functionality you need to rename the video file and subtitle files as follows:

'''Video File:''' The Matrix.avi
'''Subtitle 1:''' The Matrix.English.srt
'''Subtitle 2:''' The Matrix.French.srt
'''Subtitle 3:''' The Matrix.German.srt

The dot after the filename but before the extension specifies the language (you can use anything here, mix numbers and and letters or just use one or the other).
<br />

You can even mix subtitle formats, eg:

'''Video File:''' Movie Name (2006).avi
'''Subtitle 1:''' Movie Name (2006).Chinese.idx
'''Subtitle 1:''' Movie Name (2006).Chinese.sub
'''Subtitle 2:''' Movie Name (2006).Japanese.idx
'''Subtitle 2:''' Movie Name (2006).Japanese.sub
'''Subtitle 3:''' Movie Name (2006).English.srt
'''Subtitle 4:''' Movie Name (2006).French.smi
'''Subtitle 5:''' Movie Name (2006).German.ssa

== Advanced options ==

=== Adding fonts ===
Additional fonts can be stored in the Kodi folder (one level below [[userdata]]) at <code>Kodi/media/Fonts/</code>

=== Increasing the delay range for subtitle adjustment ===
{{main|advancedsettings.xml}}
If you don't already have an [[advancedsettings.xml]] file, it's very simple to make. Kodi uses this file for advanced settings and features that normal users shouldn't modify without first knowing what they do, as well as for experimental features, etc.

# Create a '''plain text file''' (no rich text formatting, don't use .doc, etc) and save it as '''advancedsettings.xml'''. Make sure that the file extension is ".xml" and '''not''' ".txt" or ".xml.txt".
# Cut and paste this into your new plain text file:
#: <syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<video>
<subsdelayrange>10</subsdelayrange> 
<audiodelayrange>10</audiodelayrange> 
</video>
</advancedsettings>
</syntaxhighlight>
# Change the two values between the tags to fit your situation.
# Save this file in your '''[[Userdata|userdata folder]]'''
#: ''If you have an existing file, make sure the <video></video> tags, and settings we'll add between them, are between the main <advancedsettings></advancedsettings> tags.''

=== Using Forced Subtitles ===
Many movies have subtitles encoded for secondary languages spoken during the film – when these are added to the movie, they are known as forced subtitles and are always visible (despite not being hard encoded). Kodi (since v13 Gotham) recognizes and respects the forced flag for showing subtitles (even if subtitles are turned off by default, the forced flag will trigger them being turned on). This requires that the user have set the default languages in Settings in order to function properly. If there are multiple forced subtitles, Kodi will select the forced subtitles that match the default playback language.

; Internal Forced Subtitles
If you are using an .mkv file, the forced subtitles may be included in the file when originally encoded. If so, Kodi will automatically recognize that they are present and will display them at the appropriate times. If they are not included, or if the header was not properly edited, you will need to use external subtitles.

; External Forced Subtitles
If you are using anything other than an .mkv file, or if your mkv doesn’t have the forced subtitles properly included, the forced flag can be easily added to your external subtitles. Following the same naming conventions listed above, you can then append the forced flag to the end of the subtitle file name. The forced flag can be either upper, lower or mixed case in the filename and can use a “.” (dot), “ “ (space) or “-“ (dash) to separate them from the name of the movie and language of the subtitles. IE:
<syntaxhighlight lang=xml enclose="div">
Movie Name (2006).English.Forced.srt
Movie Name (2006).en.forced.srt
Movie Name (2006).German.Forced.srt
Movie Name (2006)-Swedish-Forced.srt
</syntaxhighlight>

= References =
{{github_link|[https://github.com/xbmc/xbmc/blob/master/xbmc/cores/VideoPlayer/VideoPlayer.cpp#L94 Requirements to load subtitles]}}

{{updated|17}}

[[Category:Video library]]
[[Category:Manual]]
[[Category:Subtitles|*]]

HOW-TO:Debug Python Scripts with Web-PDB

2021-02-26T21:33:26Z

Enen92: /* How To Use Web-PDB for Kodi */

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

[https://github.com/romanvm/kodi.web-pdb Web-PDB] is a remote web-interface to Python's built-in [https://docs.python.org/2/library/pdb.html PDB] debugger with additional convenience features. It is not tied to any IDE or other software, all you need is a common web-browser, e.g. Chrome or Firefox. Web-PDB is compatible with both Python 2 and 3, so you can use it to debug your Python 3 compatible addons.

[[File:web-pdb.png]]

Web-PDB for Kodi is available as an addon in the official Kodi addons repo.

== How To Use Web-PDB for Kodi ==

1. Install Web-PDB addon: '''Kodi Add-on repository > Program add-ons > Web-PDB'''.

2. Add <code>script.module.web-pdb</code> to [[addon.xml]] as a dependency:
<syntaxhighlight lang="xml" enclose="div">
<requires>
...
<import addon="script.module.web-pdb" version="1.5.6"/>
<requires>
</syntaxhighlight>

3. Restart Kodi so that it re-reads addon dependencies.

4. Insert the following line into your addon code at the point where you want to start debugging:
<syntaxhighlight lang="python" enclose="div">
import web_pdb; web_pdb.set_trace()
</syntaxhighlight>

The <code>set_trace()</code> call will suspend your addon and open a web-UI at the default port 5555 (port value can be changed). At the same time a notification will be displayed in Kodi, indicating that a debug session is active. The notification also shows web-UI host/port.

5. Enter in your the address bar of your browser: <code>http://<your Kodi machine hostname or IP>:5555</code>, for example <code>http://monty-python:5555</code>. Use <code>localhost</code> as a hostname if you are connecting from the same machine that runs Kodi. If everything is OK, you should see the Web-PDB UI. Now you can use all PDB commands and features. Additional '''Current file''', '''Globals''' and '''Locals''' information boxes help you better track your program runtime state.

== More Information ==

* [https://github.com/romanvm/kodi.web-pdb Web-PDB for Kodi on GitHub].
* [https://docs.python.org/2/library/pdb.html PDB debugger documentation].

[[Category:Development]]
[[Category:Python]]

Addon.xml

2020-05-22T17:17:56Z

Enen92: Fix documentation of <provides> if an empty value is provided

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.15.0 (ABI 5.14.0) || 11.2.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|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 Kodi 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 Kodi 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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

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

{{Note|If the '''<provides>''' element is not defined, behaviour will depend on the structure of your addon. If it has a single extension point (e.g. a single '''xbmc.python.script''' or '''xbmc.python.pluginsource'''), kodi will default to "executable" (thus your addon will be shown in programs). If your addon has multiple extension points and none specifies a '''<provides>''' element, different entries for your addon will be shown in "programs" (multiple fallbacks to "executable"). If your addon has multiple extension points and only one (or some) define the '''<provides>''' tag it really depends on the order of the extension points. If the first extension point (your addon '''main extension point''') defines the '''<provides>''' element, kodi will assume all the other (empty) extension points provide the same content. Otherwise it will set the content for all the extension points that specify the '''<provides>''' tag and fallback all the others to "executable". '''At the moment, there is no way to hide an addon from the interface.''' |reminder}}

==== 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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the broken tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</code>

{{note|Kodi v19 Matrix and later.}}

* <code>tvos</code>
* <code>tvos-aarch64</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

<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" enclose="div">
<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>

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

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Leia updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Addon.xml

2020-04-28T10:22:25Z

Enen92: Frodo is deprecated so it doesn't require de ABI info anyway

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.15.0 (ABI 5.14.0) || 11.2.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|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 Kodi 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 Kodi 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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the broken tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</code>

{{note|Kodi v19 Matrix and later.}}

* <code>tvos</code>
* <code>tvos-aarch64</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

<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" enclose="div">
<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>

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

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Leia updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Addon.xml

2020-04-28T10:21:50Z

Enen92: Missing ABI versions for xbmc.metadata

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 (ABI 1.0) || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.15.0 (ABI 5.14.0) || 11.2.0 (ABI 6.0.0) || 2.1.0 (ABI 1.0) || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|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 Kodi 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 Kodi 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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the broken tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</code>

{{note|Kodi v19 Matrix and later.}}

* <code>tvos</code>
* <code>tvos-aarch64</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

<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" enclose="div">
<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>

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

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Leia updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Add-on structure

2020-04-09T14:52:28Z

Enen92: Relax requirements for screenshots and banners

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

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

== 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>fanart.jpg</code>, etc. These are all optional, though we encourage you to at least have <code>icon.png</code>. The addon manifest (<code>addon.xml</code>) 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>.kodi/addons/</code> (or <code>.xbmc/addons/</code> for old XBMC-based releases).

== 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi for audio podcasts you might name your directory <code>plugin.audio.gpodder</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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#resources.2Ficon.png|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#resources.2Ffanart.jpg|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png {{anchor|icon_png_element}} ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg {{anchor|fanart_jpg_element}} ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

* It should be 16:9 aspect ratio
* It is intended for the background, so should be simple and without text where reasonable.
* Image must be 1MB or less
* Image must be jpeg or png¹. ¹PNG can only be used with Krypton and later
* Image must be 1280x720, 1920x1080 or 3840x2160
* We recommend a 1280x720 image. It should certainly be no larger than 3840x2160.
* We recommend keeping it as small as is reasonable with respect to file-size. Remember that hundreds of thousands of users are going to be downloading this.

==== resources/screenshot-x.jpg (optional) {{anchor|screenshot_element}} ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screenshot_specifications}}

* Image must be in the jpeg or png formats sized 1280x720 or 1920x1080
* Image must be 750KB or less
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) {{anchor|banner_element}} ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg or png image formats sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) {{anchor|clearlogo_element}} ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

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

{{Updated|18}}
[[Category:Add-on development]]

Addon.xml

2020-04-08T20:36:12Z

Enen92: /* */

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.14.0 || 11.2.0 (ABI 6.0.0) || 2.1.0 || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|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 Kodi 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 Kodi 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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the broken tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</code>

{{note|Kodi v19 Matrix and later.}}

* <code>tvos</code>
* <code>tvos-aarch64</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

<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" enclose="div">
<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>

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

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Leia updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Addon.xml

2020-03-08T21:44:27Z

Enen92: Remove redundant info

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.14.0 || 11.2.0 (ABI 6.0.0) || 2.1.0 || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|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 Kodi 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 Kodi 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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the broken tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

<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" enclose="div">
<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>

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

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)'''

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)'''
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)'''

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Leia updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Addon.xml

2020-03-08T21:42:58Z

Enen92: Fix c/p

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.14.0 || 11.2.0 (ABI 6.0.0) || 2.1.0 || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|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 Kodi 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 Kodi 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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the broken tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

<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" enclose="div">
<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>

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

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements (some optional) are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - '''(optional)''' all screenshot files must be listed here (mandatory since Kodi v17 Krypton)

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - '''(optional)''' image used as banner must be listed here (mandatory since Kodi v18 Leia)
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - '''(optional)''' image used as clearlogo must be listed here (mandatory since Kodi v18 Leia)

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Leia updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Add-on structure

2020-03-08T21:40:03Z

Enen92: Change screenshot anchor

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

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

== 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>fanart.jpg</code>, etc. These are all optional, though we encourage you to at least have <code>icon.png</code>. The addon manifest (<code>addon.xml</code>) 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>.kodi/addons/</code> (or <code>.xbmc/addons/</code> for old XBMC-based releases).

== 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi for audio podcasts you might name your directory <code>plugin.audio.gpodder</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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png {{anchor|icon_png_element}} ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg {{anchor|fanart_jpg_element}} ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.jpg (optional) {{anchor|screenshot_element}} ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screenshot_specifications}}

* Image must be in the jpeg formats sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) {{anchor|banner_element}} ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) {{anchor|clearlogo_element}} ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

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

{{Updated|18}}
[[Category:Add-on development]]

Addon.xml

2020-03-08T21:39:51Z

Enen92: Add links to missing assets

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.14.0 || 11.2.0 (ABI 6.0.0) || 2.1.0 || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|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 Kodi 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 Kodi 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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the broken tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

<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" enclose="div">
<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>

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

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements are:

* <code><icon></code> See [[Add-on_structure#icon_png_element|icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart_jpg_element|fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code> See [[Add-on_structure#screenshot_specifications|screenshots]] - all screenshot files must be listed here (mandatory since Kodi v17 Krypton)

{{note|Kodi v18 Leia and later.}}

* <code><banner></code> See [[Add-on_structure#banner_element|banner.jpg]] - all screenshot files must be listed here (mandatory since Kodi v17 Krypton)
* <code><clearlogo></code> See [[Add-on_structure#clearlogo_element|clearlogo.png]] - all screenshot files must be listed here (mandatory since Kodi v17 Krypton)

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Leia updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Add-on structure

2020-03-08T21:35:03Z

Enen92: Create anchors for external pages

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

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

== 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>fanart.jpg</code>, etc. These are all optional, though we encourage you to at least have <code>icon.png</code>. The addon manifest (<code>addon.xml</code>) 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>.kodi/addons/</code> (or <code>.xbmc/addons/</code> for old XBMC-based releases).

== 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi for audio podcasts you might name your directory <code>plugin.audio.gpodder</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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png {{anchor|icon_png_element}} ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg {{anchor|fanart_jpg_element}} ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.jpg (optional) {{anchor|screenshot_element}} ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg formats sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) {{anchor|banner_element}} ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) {{anchor|clearlogo_element}} ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

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

{{Updated|18}}
[[Category:Add-on development]]

Add-on structure

2020-03-08T21:31:39Z

Enen92: /* resources/settings.xml */

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

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

== 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>fanart.jpg</code>, etc. These are all optional, though we encourage you to at least have <code>icon.png</code>. The addon manifest (<code>addon.xml</code>) 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>.kodi/addons/</code> (or <code>.xbmc/addons/</code> for old XBMC-based releases).

== 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi for audio podcasts you might name your directory <code>plugin.audio.gpodder</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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png {{anchor|icon_png_element}} ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.png (optional) ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg format sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

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

{{Updated|18}}
[[Category:Add-on development]]

Add-on structure

2020-03-08T21:31:09Z

Enen92: /* resources/icon.png */

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

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

== 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>fanart.jpg</code>, etc. These are all optional, though we encourage you to at least have <code>icon.png</code>. The addon manifest (<code>addon.xml</code>) 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>.kodi/addons/</code> (or <code>.xbmc/addons/</code> for old XBMC-based releases).

== 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi for audio podcasts you might name your directory <code>plugin.audio.gpodder</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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png ==== {{anchor|icon_png_element}}

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.png (optional) ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg format sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

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

{{Updated|18}}
[[Category:Add-on development]]

Add-on structure

2020-03-08T21:24:02Z

Enen92: /* Directory Name */

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

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

== 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>fanart.jpg</code>, etc. These are all optional, though we encourage you to at least have <code>icon.png</code>. The addon manifest (<code>addon.xml</code>) 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>.kodi/addons/</code> (or <code>.xbmc/addons/</code> for old XBMC-based releases).

== 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi for audio podcasts you might name your directory <code>plugin.audio.gpodder</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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.png (optional) ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg format sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

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

{{Updated|18}}
[[Category:Add-on development]]

Add-on structure

2020-03-08T21:22:39Z

Enen92: /* Introduction */

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

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

== 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>fanart.jpg</code>, etc. These are all optional, though we encourage you to at least have <code>icon.png</code>. The addon manifest (<code>addon.xml</code>) 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>.kodi/addons/</code> (or <code>.xbmc/addons/</code> for old XBMC-based releases).

== 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi 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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.png (optional) ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg format sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

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

{{Updated|18}}
[[Category:Add-on development]]

Add-on structure

2020-03-08T21:18:13Z

Enen92: Remove cpluff reference

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

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

== 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi 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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.png (optional) ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg format sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

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

{{Updated|18}}
[[Category:Add-on development]]

Add-on structure

2020-03-08T20:56:36Z

Enen92: Add Leia version of 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 third-party developed enhancements to Kodi to be distributed to Kodi users directly from inside the Kodi 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi 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:

=== Kodi v18 Leia and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
banner.jpg ('''optional''' - can be placed anywhere in the addon directory)
clearlogo.png ('''optional''' - can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.png (optional) ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg format sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

==== 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:Add-on development]]

Add-on structure

2020-03-08T20:55:30Z

Enen92: Add more assets to krypton versions

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

This page summarizes the add-ons system introduced in the Dharma release (v10) of XBMC. This system allows third-party developed enhancements to Kodi to be distributed to Kodi users directly from inside the Kodi 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi 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:

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg (can be placed anywhere in the addon directory)
icon.png (can be placed anywhere in the addon directory)
screenshot-1.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-2.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-3.jpg ('''optional''' - can be placed anywhere in the addon directory)
screenshot-4.jpg ('''optional''' - can be placed anywhere in the addon directory)

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.png (optional) ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg format sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

==== 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:Add-on development]]

Add-on structure

2020-03-08T20:52:25Z

Enen92: Add screenshots, banner and clearlogo

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

This page summarizes the add-ons system introduced in the Dharma release (v10) of XBMC. This system allows third-party developed enhancements to Kodi to be distributed to Kodi users directly from inside the Kodi 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi 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:

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg
icon.png

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation/example).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <code><fanart></code> element in '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation/example).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== resources/screenshot-x.png (optional) ====

{{note|Kodi v17 Krypton and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <code><screenshot></code> element of '''[[Addon.xml#<assets>|addon.xml assets]]''' each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in '''[[Addon.xml#<assets>|addon.xml assets]]'''. screenshot-x.png is just an example naming convention.

'''''Specifications''''' {{anchor|screen_specifications}}

* Image must be in the jpeg format sized 1280x720 or 1920x1080
* Image must have '''no transparency'''
* Addons can include a maximum of 10 screenshots
* If the addon includes screenshots, 4 is the recommended number of images to provide,

==== resources/banner.jpg (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><banner></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/banner.jpg is just a recommendation).

'''''Specifications''''' {{anchor|banner_specifications}}

* Images must be in jpeg image format sized '''1000x185''' pixels, no exceptions

==== resources/clearlogo.png (optional) ====

{{note|Kodi v18 Leia and later.}}
This '''optional art type''' helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><clearlogo></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/clearlogo.png is just a recommendation).

'''''Specifications''''' {{anchor|clearlogo_specifications}}

* Image must be png format sized '''400 x 155px''' (non-HD version) or '''800 x 310'''px (HD version)
* Image '''must have transparency'''

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

==== 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:Add-on development]]

Add-on structure

2020-03-08T19:28:42Z

Enen92: Improve icon and fanart information

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

This page summarizes the add-ons system introduced in the Dharma release (v10) of XBMC. This system allows third-party developed enhancements to Kodi to be distributed to Kodi users directly from inside the Kodi 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="prettytable" 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 Kodi addon manager.
|No
|-
|<code>plugin</code>
|A plugin script or module that adds to the functionality of Kodi. 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 Kodi skin definition and its supporting script files.
|No
|-
|<code>resource</code>
|An addon that will provide additional files (language files, images, [[sounds.xml|uisounds]]).
|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="prettytable" 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>program</code>
|A program add-on that will appear in the Add-ons main menu.
|-
|<code>plugin</code>
|<code>weather</code>
|A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
|-
|<code>script</code>
|<code>module</code>{{anchor|script_modules}}
|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 Kodi 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:

=== Kodi v17 Krypton and up===
addon.py
addon.xml
LICENSE.txt
resources/
settings.xml
language/
lib/
data/
media/
fanart.jpg
icon.png

=== Kodi v16 Jarvis and earlier===
addon.py
addon.xml
fanart.jpg
icon.png
LICENSE.txt
changelog.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 Kodi 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 ===

{{note|Deprecated in Kodi v17 Krypton. Replaced by [[Addon.xml#.3Cnews.3E]]}}

A text file that contains a description of the changes you make to the add-on for each release. This is displayed in the Kodi 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:

v0.1.3 (2015-12-25)
- Update with 15.0 Isengard

v0.1.2 (2014-1-15)
- Add notification for Ubuntu users checking through apt command

v0.1.1 (2014-1-1)
- Initial version
</code>

It is recommend to add a date so users know when last update was done. Best is to use YYYY-MM-DD as this is the least confusing way of dat notation.

=== icon.png ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/icon.png>|resources/icon.png]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]''' }}

This is an icon used to represent your add-on in various parts of Kodi. See the [[#icon_specifications|icon.png specifications]].

=== fanart.jpg ===

{{warning|1='''Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory.''' Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for '''[[Add-on_structure#<resources/fanart.jpg>|resources/fanart.jpg]]''') and be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''}}

This helps to keep Kodi graphically rich when browsing and using add-ons. See the [[#fanart_specifications|fanart.jpg specifications]].

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

==== 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/icon.png ====

{{note|Kodi v17 Krypton and later.}}

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. It can be placed anywhere in the addon directory structure as long as the <code><icon></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/icon.png is just a recommendation).

'''''Specifications''''' {{anchor|icon_specifications}}

* The icon size must be 256x256 pixels or 512x512 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 Kodi's logo; it's obvious that we're talking about Kodi 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'').

==== resources/fanart.jpg ====

{{note|Kodi v17 Krypton and later.}}

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in '''[[Addon.xml#<assets>|addon.xml assets]]'''. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as [[#script_modules|<code>script.module</code>]]). It can be placed anywhere in the addon directory structure as long as the <code><fanart></code> '''[[Addon.xml#<assets>|addon.xml asset]]''' points to the right file (resources/fanart.jpg is just a recommendation).

'''''Specifications''''' {{anchor|fanart_specifications}}

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

==== 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 Kodi 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 31000 thru 31999 reserved for skins

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

==== 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:Add-on development]]

Addon.xml

2020-03-08T18:39:45Z

Enen92: Fix SPDX licenses

{{mininav|[[Development]]|[[Add-on development]]}}
{{TOC right}}
<br />

Every skin, script, or plugin in Kodi 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 Kodi. 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.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language>en</language> 
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>https://forum.kodi.tv/showthread.php?tid=xxxx</forum> 
<website>http://myplugin.com</website> 
<email>you@youremail.com</email> 
<source>http://github.com/you/plugin.addon.id</source>
<news>v1.2.3 (01/02/201x)
[new] some new feature
[fix] some fix
</news>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner></banner> 
<clearlogo>resources/clearlogo.png</clearlogo> 
<screenshot></screenshot> 
</assets>
</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 Kodi 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.
* Banners and clearlogos assets exclusive to Kodi v.18+
= 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 Kodi 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.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta 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 Kodi itself, or may be parts of other third-party add-ons.

Kodi 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 Kodi's add-on manager, Kodi 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:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
</requires>
</source>

Here's another example, which will only install on LibreELEC. This occurs because the addon will depend on an addon that only exists in LibreELEC. Hence, Kodi will refuse to install the addon in other platforms due to unmet dependencies:

<source lang="xml">
<requires>
<import addon="os.librelec.tv" version="2.0"/>
</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, Kodi 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 Kodi 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 Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 <font color="red">Deprecated</font>|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 <font color="red">Deprecated</font> || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x <font color="red">Deprecated</font>|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.26.0 (ABI 2.1.0) || 5.14.0 || 9.7.2 (ABI 6.0.0) || 2.1.0 || 17.9.910 (ABI 12.0.0)
|-
| Matrix 19.x || 3.0.0 (ABI 3.0.0) || 5.14.0 || 11.2.0 (ABI 6.0.0) || 2.1.0 || 18.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== 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 Kodi 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 Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|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 Kodi 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 Kodi 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
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.python.module</code>
|Provides an additional python library. mainly for use in script.module.* addons.
|-
|<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)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

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 Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!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 Kodi add-on manager.

==== Available elements ====

There are several elements that this should contain. Most of these elements are required (except the broken tag). However, in case the elements do not apply (e.g. language, website, email) they can be omitted from the addon.xml file. Language specific elements 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. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <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_GB">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_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <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_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (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.)
Please keep it short (it's limited to 1500 characters), you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

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

The <code><platform></code> tag specifies which platforms (operating systems, hardware, architecture) 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>osx-x86_64</code>
* <code>osx32</code>
* <code>osx-i686</code>
* <code>ios</code>
* <code>ios-armv7</code>
* <code>ios-aarch64</code>
* <code>windx</code>
* <code>windows</code>
* <code>windows-i686</code>
* <code>windows-x86_64</code>
* <code>windowsstore</code>
* <code>android</code>
* <code>android-armv7</code>
* <code>android-aarch64</code>
* <code>android-i686</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, omit it from the addon.xml.

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

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

The <code><license></code> element indicates what license is used for this add-on. In general, the [https://spdx.org/licenses/ SPDX identifier] for the license is advised when compared to the full license name:

<source lang="xml">
<license>GPL-2.0-or-later</license> 
</source>

vs

<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" enclose="div">
<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>

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

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. A dialog will be presented to every user that has the addon installed, so please try to be specific about the broken reason. Also, the broken tag presupposes that a version bump has been made to the addon.

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

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements are:

* <code><icon></code> See [[Add-on_structure#icon.png]] - if an icon.png file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><fanart></code> See [[Add-on_structure#fanart.jpg]] - if a fanart.jpg file exists it must be listed here (mandatory since Kodi v17 Krypton)
* <code><screenshot></code>

{{note|Kodi v18 Leia and later.}}

* <code><banner></code>
* <code><clearlogo></code>

If some elements are empty or not specified, it will be treated as non-existing/not provided. From all the above items, only icon and fanart are mandatory for addons since Kodi v17 Krypton and later.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<banner>resources/banner.jpg</banner>
<clearlogo>resources/clearlogo.png</clearlogo>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

===== <reuselanguageinvoker> =====
{{note|Kodi v18 Leia and later.}}

The <code><reuselanguageinvoker></code> element is a feature introduced with Kodi 18.0 that changes the way the python invoker works in Kodi - trying to reuse the invoker instances as much as possible. As a result, the addon performance is greatly improved. However, note that for the element to work some changes may be required in your addon. Namely, since the invoker is reused, make sure <code>sys.argv</code> is always passed to your entrypoint and propagated throughout your codebase. Do not store it as a class variable.

<source lang="xml">
<reuselanguageinvoker>true</reuselanguageinvoker>
</source>

Furthermore, it is advised to set this element to <code>false</code> while developing the addon, making it only <code>true</code> for the production version (and after testing).

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''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 ===

Kodi 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, Kodi 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 Kodi 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 and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' 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" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon id="skin.estuary" version="2.0.22" name="Estuary" provider-name="phil65, Ichabod Fletchman">
<requires>
<import addon="xbmc.gui" version="5.14.0"/>
</requires>
<extension point="xbmc.gui.skin" debugging="false">
<res width="1920" height="1440" aspect="4:3" default="false" folder="xml" />
<res width="1920" height="1280" aspect="3:2" default="false" folder="xml" />
<res width="1920" height="1200" aspect="16:10" default="false" folder="xml" />
<res width="2040" height="1080" aspect="17:9" default="false" folder="xml" />
<res width="1920" height="1080" aspect="16:9" default="true" folder="xml" />
<res width="2560" height="1080" aspect="21:9" default="false" folder="xml" />
<res width="2338" height="1080" aspect="19.5:9" default="false" folder="xml" />
<res width="2160" height="1080" aspect="18:9" default="false" folder="xml" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Estuary skin by phil65. (Kodi's default skin)</summary>
<description lang="en_GB">Estuary is the default skin for Kodi 17.0 and above. It attempts to be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en_GB">Estuary is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>CC-BY-4.0, GPL-2.0-or-later</license>
<forum>http://forum.kodi.tv/</forum>
<source>https://github.com/xbmc/skin.estuary/</source>
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
<screenshot>resources/screenshot-05.jpg</screenshot>
<screenshot>resources/screenshot-06.jpg</screenshot>
<screenshot>resources/screenshot-07.jpg</screenshot>
<screenshot>resources/screenshot-08.jpg</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that <font color="red">all tag names are lower case.</font> XML tag names are case sensitive!

== addon.xml for scripts ==

<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.25.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_GB">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en_GB">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_GB">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<platform>all</platform>
<license>GPL-2.0-or-later</license>
<forum>...</forum>
<website>...</website>
<email>...</email>
<source>...</source>
<news>
v12.0.12:
- Changes ....
</news>
<assets>
<icon>resources/images/icon.png</icon>
<fanart>resources/images/fanart.png</fanart>
<screenshot>resources/images/screenshot.png</screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

=== Common errors ===

If you are getting errors when installing your Kodi addon, then you may have errors in your addon.xml file, which could be any of the following:

# Invalid characters - does any of your description text, addon name, etc. have any of the following? !, ?, -, etc
# Too large description can sometimes cause issues
# You may have an opening tag but not a closing tag further in the file e.g. <description> but not later on </description>
# If you have directly updated your code and are still finding errors which you know you have fixed, it's possible your cache is still holding the previous version. Try clearing contents of the following folders (or if this fails, reboot your Kodi device):
* .kodi/addons/temp
* .kodi/temp/temp
* .kodi/temp/archive_cache

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

{{Leia updated}}

[[Category:Add-on development]]
[[Category:Skin development]]