Official Kodi Wiki - User contributions [en]

Add-on structure

2016-09-24T11:06:54Z

Takoi: remove legacy string ranges. only skins have a reserved range

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

This page summarizes the add-ons system introduced in the Dharma release (v10) of XBMC. This system allows 3rd party-developed enhancements to 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 XBMC. Plugins appear under the relevant media section of the main home menu.
|'''Yes'''
|-
|<code>script</code>
|A runnable program file that will appear in the Program section of the main home menu.
|'''Yes'''
|-
|<code>skin</code>
|An 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>weather</code>
|A weather add-on that will appear in the Weather main menu.
|-
|<code>script</code>
|<code>module</code>
|A script plugin that will not appear under a category or within the Add-ons manager, but provides support for other add-ons.
|-
|<code>script</code>
|<code>service</code>
|A script that will be run at either login or startup
|}

The add-on name is up to you, but be sure that it isn't already in use by another add-on. For instance, if you are creating an add-on that integrates the Gpodder software with 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 ===

This is an icon used to represent your add-on in various parts of XBMC. In order to keep a coherent look and give the skinner a good idea how the icons of the add-ons look, we have defined the following rules:

* The icon size must be 256x256 pixels 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 XBMC'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'').

=== fanart.jpg ===

This helps to keep Kodi graphically rich when browsing and using add-ons. Some simple guidelines:

* It should be 16:9 aspect ratio
* It is intended for the background, so should be simple and without text where reasonable.
* We recommend a 1280x720 JPEG image. It should certainly be no larger than 1920x1080.
* We recommend keeping it as small as is reasonable with respect to file-size. Remember that hundreds of thousands of users are going to be downloading this.

=== LICENSE.txt ===
{{See also|Submitting_Add-ons#Repository_Submission_Guidelines_-_Please_Read_Before_Submitting_Your_Addon|label 1=Repository guidelines}}

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

=== resources/ ===

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

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

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

==== resources/language/ ====

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

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

2016-09-24T10:41:41Z

Takoi: remove old screenshot rules

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

=== Repository Submission Guidelines - Please Read Before Submitting Your Addon ===

Inclusion in the Kodi.org repository is at the sole discretion of Team Kodi. Because maintaining such a large repository is a large task, we have set some guidelines for inclusion. Please ensure that these guidelines are met before submitting request to be added.
In order to be considered for the official repository, the following guidelines must be met:
* All add-ons must be developed as described on the [[Add-on development]] page.
* You ''must'' include a license file (named LICENSE.txt). We recommend the [http://creativecommons.org/choose/non-web-popup?license_code=by-sa&jurisdiction=&version=3.0&lang=en CC-BY-SA 3.0] for skins and the [http://www.gnu.org/licenses/gpl-howto.html GPL v2+] for others, but most copy left licenses will suffice. Please investigate which license suits your needs and you fully understand the contents.
* All files must be free and legal to distribute.
* The add-on must not violate any known copyright laws - if in doubt, let us know and we'll look into it for you.
* All source files must be included. No pre-compiled files will be allowed.
* You acknowledge that you are the maintainer of your add-on.
* Team-Kodi reserves the right to update or remove it at any time as we deem necessary.
* If a new stable Kodi is going to be released no new submissions are accepted to the repository for the previous version. This will start from when the first [http://en.wikipedia.org/wiki/Release_candidate#Release_candidate release candidate (RC)] of the new version is released. Only fixes and updates will be accepted and processed for the previous version (e.g. if the current stable is 13.x, no updates are allowed for 11.x any more). See: [[Submitting Add-ons#Allowed submissions|Allowed submissions]]
* Monetization of add-ons (for instance advertising or paid subscriptions) will not be allowed. We can make an exception in case you own the copyright for the content the add-on provides. Please contact us on the forum (or add-on mailing list) if you believe such an exception may apply to your add-on.
* All xbmc.python.module addons must be used by at least one other add-on in official repository.

=== Updates ===
Keep in mind that add-ons in the official repository should be considered ''stable''. This means that they should be well-tested before you submit them for inclusion.
Because they are for stable users, they should avoid being updated too often. Too often is of course subjective. If your add-on is in rapid development, and features are constantly being added, hold off until you have hit a good stopping point and ''tested'' the current version.

This means that you should ''not'' submit a request every time you change your code. If you are submitting updates more than once per week something is wrong. Once or twice per month is probably a better goal, barring unforeseen conditions (like a content source changing its paths). With good reasons provided we will of course make exceptions as we strive to prove the best user experience.

=== General requirements ===
Here's a list of what basic sanity checks are done by repository maintainer on each submission.

'''Basic file checks:'''

* all strings used by add-ons must be localized, no hard-coded language strings should ever be used
* all paths should be treated as case-sensitive, so that they work on all OSs and file systems.
* all paths and files should be lower-case due to the previous point
** exceptions are README, COPYING, LICENSE.txt that should be upper-case and the "Default" directory in <tt>resources/skins</tt>, for add-ons that need it.
* exception are the translation Language folders with should be first letter capitalised.
* the following file-types are not allowed: .so .dll .pyo .exe .xbt .xpr Thumbs.db and so on<any binary files>
* all text files should use UNIX end-of-line
* all .xml files must pass xml validation
* all .xml files must have xml declaration as header
* all .xml/.txt must have unix style EOL's
* don't use a BOM at the start of your files
* file permissions: files should not be marked as executable
* filenames must have correct encoding (for skins: check your studio logos for corrupt filenames)

'''Things that must be included:'''

* [[Add-on structure#addon.xml|addon.xml]] must contain correct and valid info / version
* [[Add-on structure#icon.png|icon.png]] must be present (256x256) or (512x512)
* [[Add-on structure#fanart.jpg|fanart.jpg]] must be present (1280x720 or 1920x1080)
* [[Add-on structure#LICENSE.txt|LICENCE.txt]] must be present
{{See also|Add-on_structure}}

'''Things that can't be included:'''

* no .xbt files (these will be generated by our repository)
* no other add-ons included (skinners: if you need a script, submit it separately and depend on it)
* don't include unneeded files (.pdf, .doc, thumbs.db, etc...)
* no licensed fonts / background images / anything

=== Requirements for skins ===

'''Basic checks:'''

* The file size must be sane. There is no hard limit, but a 100mb skin is pushing it.
* No mods. Mods are great, and pop up frequently in the forums. But they are only confusing to non-forum-goers. This can be vague, each is evaluated on its own merit. By naming your "mod" different and make it substantial different enough, we will of course take it in consideration.
* Due to a bug in TexturePacker, all graphics files should have a resolution of at least 4x4.
* themes must be in a subfolder of the themes/ folder in the skin root (eg. skin.foo/themes/blue/<files>). The .xbt file will be created by our repo backend.
* If you want to have some images outside of Textures.xbt, then make sure you place those images outside of the media/ folder and reference them using special://skin/backdrops/* or similar. This is most useful for backgrounds - it keeps the size of the packed textures down. Any images you have in the media/ folder will be placed in Textures.xbt in the official repository.
* Please be careful with addon dependencies. Only add dependencies that are needed for the skin to function properly.

'''Code checks:'''

* all labels must be localized
* code should be case-sensitive
* skins should not create warning/errors in the logfile, this can be a lot of things:
:* invalid includes
:* undefined actions
:* unable to evaluate condition
:* undefined vars
:* can't focus 'id'

{{Note|This of course also applies to script add-ons that use skin files}}

==== Optional support ====

This is optional and should not block inclusion in official repo.

* mouse support
* touchscreen support
* peripheral dialogs
* PVR support
* ADSP support
* RDS support

=== Requirements for scripts and plugins ===

* all special:// paths should be translated using xbmc.translatePath("special://foo/bar")
* xbmc.translatePath(xbmcaddon.Addon().getAddonInfo('path')).decode('utf-8') should be used for files included with the add-on
* xbmc.translatePath(xbmcaddon.Addon().getAddonInfo('profile')).decode('utf-8') should be used for storing add-on related files
* direct access to the Kodi database is '''not''' allowed. You must use [[JSON RPC]] for this.
* directly using analytics (Google Analytics for example) from within add-ons is not allowed. This should be handled server side by using user-agent.
* addons should use the xbmc.log() method to write to the logfile and use the debug logging level only. print statements should not be used.
* add-ons should store all their data in their own subfolder inside the addon_data directory. Access (read/write/delete) to any other files / folders is not allowed by default.
''Exceptions to this rule may be granted in specific cases only. Please contact Team XBMC's add-on repository maintainers via the add-on mailing list if your add-on needs access to such files.''
In case we grant such an exception for your addon, access (read/write/delete) to other files/directories must be opt-in by the user, and be clear for the user to understand what is being accessed.

=== Requirements for scrapers ===
* scraper must return the following minimum information: movie title, year, plot, cast, poster, fanart
* use 'chain function' for calling functions in common scrapers
* remove the deprecated XML tags from the scraper header in case you use a scraper editor made for pre-Dharma versions of XBMC

[[Category:Add-on development]]
[[Category:Team Kodi specific notes]]

Archive:Create a repository for add-ons

2016-08-21T09:52:39Z

Takoi:

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

{{outdated}}

See [[Add-on_repositories]] for up-to-date reference documentation.

When you have created your repository, feel free to add it to the [[3rd party add-on repositories]] list.

== Things you will require ==
* Any HTTP server. A popular method is to use the svn or git source code servers of googlecode, gitorious and github.
** In your code project page, make sure you set up the correct version control system (source tab). Most skins use SVN.
** This will get you the right checkout address (link) and folder structure.
* A folder containing one or more add-on.
** Start by installing an svn program (like Tortoisesvn).
** Right click the empty folder, choose 'SVN Checkout' to let it build a folder structure inside.
** Make sure you get asked for authentication (!), the folders look like your source code server.
** If you don't get asked for authentication check your server settings and http vs https links.
** Make a test.txt file in the trunk, right click to mark it as 'add' and use and use 'SVN Commit' on top folder.
* Make the following two files using the python code below. These 2 files are made from the addon.xml files in the folders below (from the addons). Where you can have your addon unzipped (or zipped as long as there is an addon.xml file next to it, that is always up to date with the one in the zip).
** A master addon'''s'''.xml file. This file contains metadata about all available add-ons.
** A checksum of the above file (this file only contains a hash of addons.xml).
* A zipped repository add-on for distribution. This allows you to share your repository with others.
** Easiest way is to have a look at another repository file and change the name, info and links.
** You can also have a look at how other repos set up their folder structure.

You can use the <tt>create_repository.py</tt> script to generate the <tt>addons.xml</tt> metadata and the signature. The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.

* For Windows users: Install the latest version of <tt>Python.msi</tt> (from their website) in its default directory. Python (.py) files should now be associated with python.exe and can be run like a program.
* [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 on 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.

== Repository Files ==
Repositories are distributed just like any other add-on. In order for you to browse one in XBMC, you'll need to [[Add-ons_for_XBMC_(Developement)|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 and icons required for an icon, you'll need an <extension> block specfically pointing to your repository.
Use the addon.xml of any of the [[3rd party add-on repositories]] as a template.
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).

== Tips ==
=== Using your repo to host images ===
You may as a developer need to host images from time to time.
Something like photobucket or flickr may work, but you can also use your repo.
Commit an image to it, and then form the url to it as you would if you were accessing the image via git or svn (like below):

http://xbmc-adult.googlecode.com/svn/trunk/repository.xbmc-adult/icon.png

This can then be accessed easily from python code, or even embedded on the XBMC forums.

=== How to make an add-on self-updating without distributing a repository file ===
This is optional.
You still need a repository for this, you just distribute the actual zipped plugin or script, as opposed to the repository file.
First you need to have a working repository file.
Copy the equivalent of this code from the addon.xml of your repository file:
<source lang="xml">
<extension point="xbmc.addon.repository"
name="Official XBMC.org Add-on Repository">
<info compressed="true">http://mirrors.xbmc.org/addons/dharma-pre/addons.xml</info>
<checksum>http://mirrors.xbmc.org/addons/dharma-pre/addons.xml.md5</checksum>
<datadir zip="true">http://mirrors.xbmc.org/addons/dharma-pre</datadir>
</extension>
</source>
Then simply add it under the other <extension point> entries of your add-on's addon.xml
The name= part of this repository extension must never be the same as your add-on.

==More Video Tutorials==
===Update Your Repository===
{{youtube|tXzPUs9FaF8}}

[https://youtu.be/tXzPUs9FaF8 Video's Description.]

===Add more Add-ons to your Repository===
{{youtube|2OPjwdbBSkw}}

[https://youtu.be/2OPjwdbBSkw Video's Description.]

==See also==
* [[3rd party add-on repositories]]
'''Development:'''
* [[Add-on development]]
* [[Add-on repositories]]

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

Add-on repositories

2016-08-21T09:49:42Z

Takoi:

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

{{see also|HOW-TO: Create a Repository to host your Add-on}}

Beginning with Dharma, 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]] is included with Kodi by default and is maintained by the Kodi team.

After you have created your repository, consider adding it to the [[3rd party 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-ons for Kodi (Developement)|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>http://example.com/addons/addons.xml</info>
<checksum>http://example.com/addons/addons.xml.md5</checksum>
<datadir>http://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 does 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).

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

[[Category:Add-on development]]
[[Category:Team Kodi specific notes]]

Add-on repositories

2016-08-21T09:41:55Z

Takoi:

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

{{see also|HOW-TO: Create a Repository to host your Add-on}}

Beginning with Dharma, 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]] is included with Kodi by default and is maintained by the Kodi team.

After you have created your repository, consider adding it to the [[3rd party 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
changelog-x.y.z.txt
fanart.jpg
icon.png
addon2.id
addon2.id-x.y.z.zip
changelog-x.y.z.txt
fanart.jpg
icon.png

* 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-ons for Kodi (Developement)|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" name="My development repository">
<info>http://example.com/addons/addons.xml</info>
<checksum>http://example.com/addons/addons.xml.md5</checksum>
<datadir>http://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 does 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).

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

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

[[Category:Add-on development]]
[[Category:Team Kodi specific notes]]

Add-on structure

2016-08-21T08:55:44Z

Takoi: /* changelog.txt */

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

This page summarizes the add-ons system introduced in the Dharma release (v10) of XBMC. This system allows 3rd party-developed enhancements to 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 XBMC. Plugins appear under the relevant media section of the main home menu.
|'''Yes'''
|-
|<code>script</code>
|A runnable program file that will appear in the Program section of the main home menu.
|'''Yes'''
|-
|<code>skin</code>
|An 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>weather</code>
|A weather add-on that will appear in the Weather main menu.
|-
|<code>script</code>
|<code>module</code>
|A script plugin that will not appear under a category or within the Add-ons manager, but provides support for other add-ons.
|-
|<code>script</code>
|<code>service</code>
|A script that will be run at either login or startup
|}

The add-on name is up to you, but be sure that it isn't already in use by another add-on. For instance, if you are creating an add-on that integrates the Gpodder software with 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:

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

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

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

=== addon.py ===

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

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

<code>addon.xml</code> gives 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 ===

This is an icon used to represent your add-on in various parts of XBMC. In order to keep a coherent look and give the skinner a good idea how the icons of the add-ons look, we have defined the following rules:

* The icon size must be 256x256 pixels.
* File format is PNG.
* Background must be 100% solid. That doesn't mean one color, it also can be a gradient or a low contrast texture. Just make sure there is no transparency.
* Keep the logo as simple a possible, no exaggerated 3D effects or high contrast textures.
* Use a padding of at least 25px for your logo (not the background!). Excepted are large text logos (see icon for themoviedb.org).
* Keep text to a minimum. However, a text logo along with the graphical logo is recommended in order to easily recognize the addon.
* Don't mix logos with XBMC's logo; it's obvious that we're talking about 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'').

=== fanart.jpg ===

This helps to keep Kodi graphically rich when browsing and using add-ons. Some simple guidelines:

* It should be 16:9 aspect ratio
* It is intended for the background, so should be simple and without text where reasonable.
* We recommend a 1280x720 JPEG image. It should certainly be no larger than 1920x1080.
* We recommend keeping it as small as is reasonable with respect to file-size. Remember that hundreds of thousands of users are going to be downloading this.

=== LICENSE.txt ===
{{See also|Submitting_Add-ons#Repository_Submission_Guidelines_-_Please_Read_Before_Submitting_Your_Addon|label 1=Repository guidelines}}

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

=== resources/ ===

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

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

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

==== resources/language/ ====

'''Translation tools:'''
* [[Language support]]
* [[Translation System]]
* Convert .xml to .po: [https://github.com/alanwww1/xbmc-xml2po xbmc-xml2po]
* Check for .po files: [https://github.com/alanwww1/xbmc-checkpo xbmc-checkpo]
* Utility for keeping 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 30000 thru 30999 reserved for plugins and plugin settings
* strings 31000 thru 31999 reserved for skins
* strings 32000 thru 32999 reserved for scripts
* strings 33000 thru 33999 reserved for common strings used in add-ons

'''strings.po'''

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

==== resources/lib/ ====

Put any module definitions or third party software libraries into this directory.

==== resources/data/ ====

Store any other static data structures your application requires here. Examples might be
XLT/XSD files or static XML files that contain lookup tables etc.

==== resources/media/ ====

Store any static media (picture, audio, video etc.) files in this directory.

== Getting started ==

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

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

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

[[Category:Add-on development]]

Addon.xml

2016-08-21T08:53:40Z

Takoi: fix lang documentation

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

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.1.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></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

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

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of 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.

= 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.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

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

<source lang="xml">
<requires>
<import addon="os.openelec.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 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 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.11.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 17.0.0 (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>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<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.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. 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.)

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) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

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

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

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

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

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

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

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

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

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

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

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

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

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

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

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" 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. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

<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 asserts the add-on provides and where they are located. Supported sub-elements are:

* <code><icon></code> See [[Add-on_structure#icon.png]]
* <code><fanart></code> See [[Add-on_structure#fanart.jpg]]
* <code><screenshot></code>

If some elements are empty or not specified, it will be treated as non-existing/not provided.

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

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

== 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.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="4.0.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

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

{{frodo updated}}

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

Addon.xml

2016-08-21T08:44:48Z

Takoi: document <assets>

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

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.1.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></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

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

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of 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.

= 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.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

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

<source lang="xml">
<requires>
<import addon="os.openelec.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 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 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.11.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 17.0.0 (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>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<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.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

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

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

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

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

Note: Kodi v15 uses [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifiers] for the lang attribute, v14 and older uses ISO 639-1.

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

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) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

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

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

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

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

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

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

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

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

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

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

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

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

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

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

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" 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. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

<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 asserts the add-on provides and where they are located. Supported sub-elements are:

* <code><icon></code> See [[Add-on_structure#icon.png]]
* <code><fanart></code> See [[Add-on_structure#fanart.jpg]]
* <code><screenshot></code>

If some elements are empty or not specified, it will be treated as non-existing/not provided.

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

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

== 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.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="4.0.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

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

{{frodo updated}}

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

Addon.xml

2016-08-21T08:20:56Z

Takoi: add note about forward compatibility

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

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.1.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></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

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

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of 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.

= 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.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

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

<source lang="xml">
<requires>
<import addon="os.openelec.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 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 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.11.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 17.0.0 (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>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<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.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

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

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

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

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

Note: Kodi v15 uses [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifiers] for the lang attribute, v14 and older uses ISO 639-1.

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

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) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

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

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

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

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

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

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

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

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

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

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

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

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

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

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

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" 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. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

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

== 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.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="4.0.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

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

{{frodo updated}}

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

Addon.xml

2016-08-21T08:19:28Z

Takoi: remove old stuff

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

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.1.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></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

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

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of 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.

= 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.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

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

<source lang="xml">
<requires>
<import addon="os.openelec.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 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 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.11.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 17.0.0 (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>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<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.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

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

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

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

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

Note: Kodi v15 uses [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifiers] for the lang attribute, v14 and older uses ISO 639-1.

===== <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|For Kodi v17 Krypton and later only.}}

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

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) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

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

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

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

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

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

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

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

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

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

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

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

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

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

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

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" 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. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

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

== 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.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="4.0.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

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

{{frodo updated}}

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

Addon.xml

2016-06-19T12:15:08Z

Takoi: /* */

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

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.1.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></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

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

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of 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.

= 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.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

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

<source lang="xml">
<requires>
<import addon="os.openelec.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 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 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.11.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 17.0.0 (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>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<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.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

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

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

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

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

From Kodi v15 Isengard we recommend you use

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

From Kodi v15 Isengard we recommend you use

<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">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

From Kodi v15 Isengard we recommend you use

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

===== <news> =====

{{note|For Kodi v17 Krypton and later only.}}

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

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) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

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

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

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

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

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

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

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

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

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

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

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

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

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

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

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" 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. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

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

== 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.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="4.0.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

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

{{frodo updated}}

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

Context Item Add-ons

2016-03-12T10:58:36Z

Takoi: update to jarvis api

Context item add-ons allows the [[context menu]] in Kodi to be extended. Add-ons must provide the <code>kodi.context.item</code> extension point and a <menu> definition.

Example:

<syntaxhighlight lang="xml">
<extension point="kodi.context.item">
<menu id="kodi.core.main">
<item library="contextitem.py">
<label>30000</label>
<visible>true</visible>
</item>
</menu>
</extension>
</syntaxhighlight>

The first <menu> element defines which top level menu to attach to. In core, there are two available: <code>kodi.core.main</code> and <code>kodi.core.manage</code>. Add-on may attach to menu defined by other add-ons as well. Next, the <item> element defines the action to add to the menu. <code>library</code> is the file to execute, <label> a string or an ID from the language file to show in the context menu.

<visible> (required) should contain a [[Conditional visibility|visibility expression]] and will determine when the item is be visible in the [[context menu]].

This feature requires at least version 2.23.0 of the Python API (Jarvis), which should be specified in the [[Addon.xml#<requires>]] element:
<syntaxhighlight lang="xml">
<import addon="xbmc.python" version="2.23.0"/>
</syntaxhighlight>

{{Note|Keep in mind that there is limited space in the [[context menu]]. Attaching context menu to an add-on will force the user to have all of them enabled at the same time. Consider using [[#submenus]] or a creating a separate add-on.}}

== Submenus ==

<menu> and <item> elements may be mixed and nested to created submenus. Example:

<syntaxhighlight lang="xml">
<menu id="kodi.core.main">
<menu>
<label>My submenu</label>
<item library="contextitem1.py">
<label>Item 1</label>
<visible>true</visible>
</item>
<item library="contextitem2.py">
<label>Item 2</label>
<visible>true</visible>
</item>
<menu>
<label>Subsubmenu</label>
<item library="contextitem3.py">
<label>Item 3</label>
<visible>true</visible>
</item>
</menu>
</menu>
</syntaxhighlight>

== Accessing information about selected item ==

The <code>sys.listitem</code> attribute contains a copy of the item the context menu was opened on. It is an instance of <code>xbmcgui.ListItem</code>. See http://mirrors.xbmc.org/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem for available properties.

Example script:

<syntaxhighlight lang="python">
import sys
import xbmc

if __name__ == '__main__':
message = "Clicked on '%s'" % sys.listitem.getLabel()
xbmc.executebuiltin("Notification(\"Hello context items!\", \"%s\")" % message)
</syntaxhighlight>

== v15 Isengard (deprecated) ==
Isengard, API version 2.20.0, does not support <menu> definition and can only define a single item as follows:
<syntaxhighlight lang="xml">
<extension point="kodi.context.item" library="addon.py">
<item>
<label>Hello World</label>
<visible>!IsEmpty(ListItem.Genre)</visible>
<parent>kodi.core.manage</parent>
</item>
</extension>
</syntaxhighlight>

This syntax is considered deprecated and will be removed in future versions.

Note: Both syntaxes are '''backwards''' and '''forward''' compatible. Add-ons may use both the old <item> and the new <menu> at the same time for comparability with v15 Isengard and v16 Jarvis.

[[Category:Add-on development]]

Audio-video add-on tutorial

2016-01-13T13:29:02Z

Takoi: Same. This page is not at place to dump links to external tutorials

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

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

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

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

= Hello, World! =

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

<syntaxhighlight lang="python" enclose="div">
import sys
import xbmcgui
import xbmcplugin

addon_handle = int(sys.argv[1])

xbmcplugin.setContent(addon_handle, 'movies')

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

xbmcplugin.endOfDirectory(addon_handle)
</syntaxhighlight>

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

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

= Navigating between pages =

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

== Retrieving arguments ==

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

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

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

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

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

== Passing arguments ==

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

<syntaxhighlight lang="python" enclose="div">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

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

xbmcplugin.setContent(addon_handle, 'movies')

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

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

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

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

xbmcplugin.endOfDirectory(addon_handle)

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

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

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

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

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

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

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

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

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

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon()
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</syntaxhighlight>

= Showing additional metadata =

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

== Icons, thumbnails and artwork ==

Our previous examples already showed how to set an icon, but you can also set a thumbnail, fanart (full-screen background images) and other artwork. They can be set with the <code>ListItem.setArt</code> method:

<syntaxhighlight lang="python" enclose="div">
li = xbmcgui.ListItem(label='My video')
li.setIconImage('icon.png')
li.setArt({'thumb': 'thumbnail.jpg', 'poster': 'poster.jpg' 'fanart': 'fanart.jpg'})
</syntaxhighlight>

{{Note|In Kodi Isengard and earlier the 'icon' type is not available for setArt. You must use <code>ListItem.setIconImage(...)</code>}}

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setArt({'fanart': my_addon.getAddonInfo('fanart')})
</syntaxhighlight>

== Info labels ==

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

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

For a full list of the available info labels, consult the documentation for <code>[http://mirrors.kodi.tv/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem-setInfo ListItem.setInfo]</code>.

== Stream info ==

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

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

For complete documentation about this function, see <code>[http://mirrors.kodi.tv/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem-addStreamInfo ListItem.addStreamInfo]</code>.

= Adding context menus =

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

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

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

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

[[Category:Add-on development|*]]

HOW-TO:Video addon

2016-01-13T13:27:28Z

Takoi: This page is not at place to dump links to external tutorials

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

=Introduction=
This tutorial will explain how to write your first Kodi/XBMC video plugin Add-on 

=Tools=
Assuming you have already followed the Hello World Add-on you will have a text editor already setup. Since we are dealing with videos this time its probably a good idea to have a video player setup. We recommend another great open source project for this

- VLC http://www.videolan.org/vlc/

=Installing=
For this example we will use 2 nice basic video Add-on tutorials You can find the source-code here:

https://github.com/romanvm/plugin.video.example

You can either download as a zip and install both of these inside the kodi GUI from the install from zip feature. Or extract the zip into your userdata/add-ons folder.

=Testing=
You can first give the add-on a test run by going to:
System >> Add-Ons >> Enabled Add-Ons >> Video Add-Ons >> Example Kodi video Plugin. You should now be able to watch some test videos hosted from an internet web server.

[[File:Videotutorial1.jpg]]

=Explanation=
So whats happening in this add-on?

Basically the Add-on is checking a website for the hosted videos. In this example we are directly linking to the videos, but there are possibilities for dynamic content and scraping of just about any online source

Once the video link is sent to Kodi, our video player takes over and buffers, then plays the video just like any other media.

=Structure=
main.py <-- This is the actual python code for your Add-On

addon.xml <-- This is the Add-Ons metadata

icon.png <-- A PNG icon for the add-on. It can be 256x256 or 512x512 pixels big. Try to make it look nice!

Readme.md <-- The readme text file with a description of the Add-on and install instructions. This shows on the front of the GitHub page and helps users to understand your Add-on before downloading.

=The Code=
So now we come to the actual Add-On code, this is where most of your Add-on is written and is a simple text file containing python code.

First we initialize the Add-on and import and bits we need

<syntaxhighlight lang="python" enclose="div">
import sys
from urlparse import parse_qsl
import xbmcgui
import xbmcplugin
</syntaxhighlight>

Now we do something else...

<syntaxhighlight lang="python" enclose="div">
# Get the plugin url in plugin:// notation.
__url__ = sys.argv[0]
# Get the plugin handle as an integer number.
__handle__ = int(sys.argv[1])
</syntaxhighlight>

Here we use a fixed set of properties simply for demonstrating purposes. In a "real life" plugin you will need to get info and links to video files/streams from some web-site or online service.

<syntaxhighlight lang="python" enclose="div">
VIDEOS = {'Animals': [{'name': 'Crab',
'thumb': 'http://www.vidsplay.com/vids/crab.jpg',
'video': 'http://www.vidsplay.com/vids/crab.mp4',
'genre': 'Animals'},
{'name': 'Alligator',
'thumb': 'http://www.vidsplay.com/vids/alligator.jpg',
'video': 'http://www.vidsplay.com/vids/alligator.mp4',
'genre': 'Animals'},
{'name': 'Turtle',
'thumb': 'http://www.vidsplay.com/vids/turtle.jpg',
'video': 'http://www.vidsplay.com/vids/turtle.mp4',
'genre': 'Animals'}
],
'Cars': [{'name': 'Postal Truck',
'thumb': 'http://www.vidsplay.com/vids/us_postal.jpg',
'video': 'http://www.vidsplay.com/vids/us_postal.mp4',
'genre': 'Cars'},
{'name': 'Traffic',
'thumb': 'http://www.vidsplay.com/vids/traffic1.jpg',
'video': 'http://www.vidsplay.com/vids/traffic1.avi',
'genre': 'Cars'},
{'name': 'Traffic Arrows',
'thumb': 'http://www.vidsplay.com/vids/traffic_arrows.jpg',
'video': 'http://www.vidsplay.com/vids/traffic_arrows.mp4',
'genre': 'Cars'}
],
'Food': [{'name': 'Chicken',
'thumb': 'http://www.vidsplay.com/vids/chicken.jpg',
'video': 'http://www.vidsplay.com/vids/bbqchicken.mp4',
'genre': 'Food'},
{'name': 'Hamburger',
'thumb': 'http://www.vidsplay.com/vids/hamburger.jpg',
'video': 'http://www.vidsplay.com/vids/hamburger.mp4',
'genre': 'Food'},
{'name': 'Pizza',
'thumb': 'http://www.vidsplay.com/vids/pizza.jpg',
'video': 'http://www.vidsplay.com/vids/pizza.mp4',
'genre': 'Food'}
]}
</syntaxhighlight>
And now we define something else...

<syntaxhighlight lang="python" enclose="div">
def get_categories():
"""
Get the list of video categories.
Here you can insert some parsing code that retrieves
the list of video categories (e.g. 'Movies', 'TV-shows', 'Documentaries' etc.)
from some site or server.
:return: list
"""
return VIDEOS.keys()
</syntaxhighlight>
And now we define something else...

<syntaxhighlight lang="python" enclose="div">
def get_videos(category):
"""
Get the list of videofiles/streams.
Here you can insert some parsing code that retrieves
the list of videostreams in a given category from some site or server.
:param category: str
:return: list
"""
return VIDEOS[category]
</syntaxhighlight>
And now we define the list of categories

<syntaxhighlight lang="python" enclose="div">
def list_categories():
"""
Create the list of video categories in the Kodi interface.
:return: None
"""
# Get video categories
categories = get_categories()
# Create a list for our items.
listing = []
# Iterate through categories
for category in categories:
# Create a list item with a text label and a thumbnail image.
list_item = xbmcgui.ListItem(label=category, thumbnailImage=VIDEOS[category][0]['thumb'])
# Set a fanart image for the list item.
# Here we use the same image as the thumbnail for simplicity's sake.
list_item.setProperty('fanart_image', VIDEOS[category][0]['thumb'])
# Set additional info for the list item.
# Here we use a category name for both properties for for simplicity's sake.
# setInfo allows to set various information for an item.
# For available properties see the following link:
# http://mirrors.xbmc.org/docs/python-docs/15.x-isengard/xbmcgui.html#ListItem-setInfo
list_item.setInfo('video', {'title': category, 'genre': category})
# Create a URL for the plugin recursive callback.
# Example: plugin://plugin.video.example/?action=listing&category=Animals
url = '{0}?action=listing&category={1}'.format(__url__, category)
# is_folder = True means that this item opens a sub-list of lower level items.
is_folder = True
# Add our item to the listing as a 3-element tuple.
listing.append((url, list_item, is_folder))
# Add our listing to Kodi.
# Large lists and/or slower systems benefit from adding all items at once via addDirectoryItems
# instead of adding one by ove via addDirectoryItem.
xbmcplugin.addDirectoryItems(__handle__, listing, len(listing))
# Add a sort method for the virtual folder items (alphabetically, ignore articles)
xbmcplugin.addSortMethod(__handle__, xbmcplugin.SORT_METHOD_LABEL_IGNORE_THE)
# Finish creating a virtual folder.
xbmcplugin.endOfDirectory(__handle__)
</syntaxhighlight>

And here we list the videos

<syntaxhighlight lang="python" enclose="div">
def list_videos(category):
"""
Create the list of playable videos in the Kodi interface.
:param category: str
:return: None
"""
# Get the list of videos in the category.
videos = get_videos(category)
# Create a list for our items.
listing = []
# Iterate through videos.
for video in videos:
# Create a list item with a text label and a thumbnail image.
list_item = xbmcgui.ListItem(label=video['name'], thumbnailImage=video['thumb'])
# Set a fanart image for the list item.
# Here we use the same image as the thumbnail for simplicity's sake.
list_item.setProperty('fanart_image', video['thumb'])
# Set additional info for the list item.
list_item.setInfo('video', {'title': video['name'], 'genre': video['genre']})
# Set 'IsPlayable' property to 'true'.
# This is mandatory for playable items!
list_item.setProperty('IsPlayable', 'true')
# Create a URL for the plugin recursive callback.
# Example: plugin://plugin.video.example/?action=play&video=http://www.vidsplay.com/vids/crab.mp4
url = '{0}?action=play&video={1}'.format(__url__, video['video'])
# Add the list item to a virtual Kodi folder.
# is_folder = False means that this item won't open any sub-list.
is_folder = False
# Add our item to the listing as a 3-element tuple.
listing.append((url, list_item, is_folder))
# Add our listing to Kodi.
# Large lists and/or slower systems benefit from adding all items at once via addDirectoryItems
# instead of adding one by ove via addDirectoryItem.
xbmcplugin.addDirectoryItems(__handle__, listing, len(listing))
# Add a sort method for the virtual folder items (alphabetically, ignore articles)
xbmcplugin.addSortMethod(__handle__, xbmcplugin.SORT_METHOD_LABEL_IGNORE_THE)
# Finish creating a virtual folder.
xbmcplugin.endOfDirectory(__handle__)
</syntaxhighlight>

Now we tell Kodi how to find the video path to play the videos

<syntaxhighlight lang="python" enclose="div">
def play_video(path):
"""
Play a video by the provided path.
:param path: str
:return: None
"""
# Create a playable item with a path to play.
play_item = xbmcgui.ListItem(path=path)
# Pass the item to the Kodi player.
xbmcplugin.setResolvedUrl(__handle__, True, listitem=play_item)
</syntaxhighlight>

This is the router function

<syntaxhighlight lang="python" enclose="div">
def router(paramstring):
"""
Router function that calls other functions
depending on the provided paramstring
:param paramstring:
:return:
"""
# Parse a URL-encoded paramstring to the dictionary of
# {<parameter>: <value>} elements
params = dict(parse_qsl(paramstring[1:]))
# Check the parameters passed to the plugin
if params:
if params['action'] == 'listing':
# Display the list of videos in a provided category.
list_videos(params['category'])
elif params['action'] == 'play':
# Play a video from a provided URL.
play_video(params['video'])
else:
# If the plugin is called from Kodi UI without any parameters,
# display the list of video categories
list_categories()
</syntaxhighlight>

Call the router function

<syntaxhighlight lang="python" enclose="div">
if __name__ == '__main__':
# Call the router function and pass the plugin call parameters to it.
router(sys.argv[2])
</syntaxhighlight>

=Changing the code=

Hopefully by now you have managed to run the Add-On, understand the structure and can see what the code can do. Now lets trying changing it a little!

Since we already have the Add-on installed we can go directly to the Kodi userdata folder and edit the python directly. You can also have Kodi open at this time ready to run the Add-on when required. Just switch between your text editor and Kodi any time.

Now open up the main.py file from your userdata folder and lets change what the text says.

'Cars': [{'name': 'Postal Truck',
'thumb': 'http://www.vidsplay.com/vids/us_postal.jpg',
'video': 'http://www.vidsplay.com/vids/us_postal.mp4',
'genre': 'Cars'},

Try changing some of the links to another jpeg file or hosted online video. Also try to change the genre and see how that effects the view in Kodi.

Click save on your text editor and now try running the Add-On inside Kodi. You should see the new video links and navigation right away.

Congratulations! you've just played an online video from your very own Video Add-on

=Final Thoughts=

Writing a Video Add-on is actually pretty simple once you get the basic structure correct. You can scrape most online sources with Regex, or host your own videos on the web. You can also play youtube clips or vevo videos using some additional easy to use modules.

If you have any questions about this tutorial, feel free to discuss it on our forums here: http://forum.kodi.tv/showthread.php?tid=248774

=Extra info=

Just a reminder...
IMPORTANT!!!!!!! Do not mix tabs and spaces in python

[[Category:Add-on development]]

Audio-video add-on tutorial

2015-10-31T11:13:26Z

Takoi: xbmc -> kodi

Audio-video add-on tutorial

2015-10-31T11:11:52Z

Takoi: update documentation links

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

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

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

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

= Hello, World! =

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

<syntaxhighlight lang="python" enclose="div">
import sys
import xbmcgui
import xbmcplugin

addon_handle = int(sys.argv[1])

xbmcplugin.setContent(addon_handle, 'movies')

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

xbmcplugin.endOfDirectory(addon_handle)
</syntaxhighlight>

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

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

= Navigating between pages =

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

== Retrieving arguments ==

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

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

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

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

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

== Passing arguments ==

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

<syntaxhighlight lang="python" enclose="div">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

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

xbmcplugin.setContent(addon_handle, 'movies')

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

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

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

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

xbmcplugin.endOfDirectory(addon_handle)

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

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

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

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

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

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

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

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

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

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon()
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</syntaxhighlight>

= Showing additional metadata =

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

== Icons, thumbnails and artwork ==

Our previous examples already showed how to set an icon, but you can also set a thumbnail, fanart (full-screen background images) and other artwork. They can be set with the <code>ListItem.setArt</code> method:

<syntaxhighlight lang="python" enclose="div">
li = xbmcgui.ListItem(label='My video')
li.setIconImage('icon.png')
li.setArt({'thumb': 'thumbnail.jpg', 'poster': 'poster.jpg' 'fanart': 'fanart.jpg'})
</syntaxhighlight>

{{Note|In Kodi Isengard and earlier the 'icon' type is not available for setArt. You must use <code>ListItem.setIconImage(...)</code>}}

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setArt({'fanart': my_addon.getAddonInfo('fanart')})
</syntaxhighlight>

== Info labels ==

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

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

For a full list of the available info labels, consult the documentation for <code>[http://mirrors.kodi.tv/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem-setInfo ListItem.setInfo]</code>.

== Stream info ==

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

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

For complete documentation about this function, see <code>[http://mirrors.kodi.tv/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem-addStreamInfo ListItem.addStreamInfo]</code>.

= Adding context menus =

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

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

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

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

[[Category:Add-on development|*]]

Audio-video add-on tutorial

2015-10-31T11:07:26Z

Takoi: improve code formatting

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

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

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

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

= Hello, World! =

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

<syntaxhighlight lang="python" enclose="div">
import sys
import xbmcgui
import xbmcplugin

addon_handle = int(sys.argv[1])

xbmcplugin.setContent(addon_handle, 'movies')

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

xbmcplugin.endOfDirectory(addon_handle)
</syntaxhighlight>

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

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

= Navigating between pages =

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

== Retrieving arguments ==

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

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

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

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

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

== Passing arguments ==

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

<syntaxhighlight lang="python" enclose="div">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

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

xbmcplugin.setContent(addon_handle, 'movies')

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

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

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

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

xbmcplugin.endOfDirectory(addon_handle)

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

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

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

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

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

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

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

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

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

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon()
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</syntaxhighlight>

= Showing additional metadata =

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

== Icons, thumbnails and artwork ==

Our previous examples already showed how to set an icon, but you can also set a thumbnail, fanart (full-screen background images) and other artwork. They can be set with the <code>ListItem.setArt</code> method:

<syntaxhighlight lang="python" enclose="div">
li = xbmcgui.ListItem(label='My video')
li.setIconImage('icon.png')
li.setArt({'thumb': 'thumbnail.jpg', 'poster': 'poster.jpg' 'fanart': 'fanart.jpg'})
</syntaxhighlight>

{{Note|In Kodi Isengard and earlier the 'icon' type is not available for setArt. You must use <code>ListItem.setIconImage(...)</code>}}

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setArt({'fanart': my_addon.getAddonInfo('fanart')})
</syntaxhighlight>

== Info labels ==

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

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

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

== Stream info ==

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

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

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

= Adding context menus =

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

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

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

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

[[Category:Add-on development|*]]

Audio-video add-on tutorial

2015-10-31T11:00:38Z

Takoi: /* Icons and thumbnails */

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

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

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

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

= Hello, World! =

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

<syntaxhighlight lang="python" enclose="div">
import sys
import xbmcgui
import xbmcplugin

addon_handle = int(sys.argv[1])

xbmcplugin.setContent(addon_handle, 'movies')

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

xbmcplugin.endOfDirectory(addon_handle)
</syntaxhighlight>

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

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

= Navigating between pages =

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

== Retrieving arguments ==

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

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

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

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

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

== Passing arguments ==

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

<syntaxhighlight lang="python" enclose="div">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

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

xbmcplugin.setContent(addon_handle, 'movies')

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

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

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

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

xbmcplugin.endOfDirectory(addon_handle)

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

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

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

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

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

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

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

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

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

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon()
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</syntaxhighlight>

= Showing additional metadata =

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

== Icons, thumbnails and artwork ==

Our previous examples already showed how to set an icon, but you can also set a thumbnail, fanart (full-screen background images) and other artwork. They can be set with the <code>ListItem.setArt</code> method:

<syntaxhighlight lang="python" enclose="div">
li = xbmcgui.ListItem(label='My video')
li.setIconImage('icon.png')
li.setArt({'thumb': 'thumbnail.jpg', 'poster': 'poster.jpg' 'fanart': 'fanart.jpg'})
</syntaxhighlight>

{{Note|In Kodi Isengard and earlier the 'icon' type is not available for setArt. You must use <code>ListItem.setIconImage(...)</code>}}

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setArt({'fanart': my_addon.getAddonInfo('fanart')})
</syntaxhighlight>

== Info labels ==

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

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

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

== Stream info ==

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

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

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

= Adding context menus =

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

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

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

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

[[Category:Add-on development|*]]

Audio-video add-on tutorial

2015-10-31T10:59:20Z

Takoi: remove use of deprecated methods

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

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

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

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

= Hello, World! =

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

<syntaxhighlight lang="python" enclose="div">
import sys
import xbmcgui
import xbmcplugin

addon_handle = int(sys.argv[1])

xbmcplugin.setContent(addon_handle, 'movies')

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

xbmcplugin.endOfDirectory(addon_handle)
</syntaxhighlight>

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

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

= Navigating between pages =

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

== Retrieving arguments ==

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

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

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

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

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

== Passing arguments ==

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

<syntaxhighlight lang="python" enclose="div">
import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

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

xbmcplugin.setContent(addon_handle, 'movies')

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

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

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

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

xbmcplugin.endOfDirectory(addon_handle)

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

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

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

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

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

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

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

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

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

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon()
my_setting = my_addon.getSetting('my_setting') # returns the string 'true' or 'false'
my_addon.setSetting('my_setting', 'false')
</syntaxhighlight>

= Showing additional metadata =

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

== Icons and thumbnails ==

Our previous examples already showed how to set an icon, but you can also set a thumbnail, fanart (full-screen background images) and other artwork. They can be set with the <code>ListItem.setArt</code> method:

<syntaxhighlight lang="python" enclose="div">
li = xbmcgui.ListItem(label='My video')
li.setIconImage('icon.png')
li.setArt({'thumb': 'thumbnail.jpg', 'poster': 'poster.jpg' 'fanart': 'fanart.jpg'})
</syntaxhighlight>

{{Note|In Kodi Isengard and earlier the 'icon' type is not available for setArt. You must use <code>ListItem.setIconImage(...)</code>}}

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

<syntaxhighlight lang="python" enclose="div">
my_addon = xbmcaddon.Addon('plugin.video.myaddon')
# ...
li.setArt({'fanart': my_addon.getAddonInfo('fanart')})
</syntaxhighlight>

== Info labels ==

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

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

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

== Stream info ==

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

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

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

= Adding context menus =

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

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

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

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

[[Category:Add-on development|*]]

Archive:Jarvis API changes

2015-10-20T08:42:45Z

Takoi: remove boilerplate

{{Isengard}}
{{notice|Kodi v15 (Isengard) final was just recently released, so please keep in mind that a v16 (Jarvis) release is still far away into the future. As such, these API changes is a placeholder containing API changes to the current Kodi mainline (the git master tree repository on GitHub). It is a very much a work in progress, this is only listing API changes commited to the master branch after Isengard branching, and many many many APIs are subject to future change.}}
{{incomplete}}

{{see also|Kodi v16 (Jarvis) FAQ|Kodi v16 (Jarvis) changelog|Releases}}

=Addons=

== PVR ==
* Update the PVR Addon API version to 4.0.0 for Kodi v16 (Jarvis)<ref>https://github.com/xbmc/xbmc/pull/7408</ref><ref>https://github.com/xbmc/xbmc/pull/7626</ref><ref>https://github.com/xbmc/xbmc/pull/8005</ref>
==== PVR API ====
* ?

== Python ==

* Changed: ListItem no longer sets media type based on "tvshowtitle", "episode" and "season" provided via ListItem::setInfo. May affect appearance of info dialog. Use the new "mediatype" info label instead. <ref>https://github.com/xbmc/xbmc/pull/7683</ref>
* Removed depricated xbmcgui.lock() and xbmcgui.unlock()
* Deprecated ListItem.setIconImage, use setArt
* Deprecated ListItem.setThumbnailImage, use setArt
* Deprecated "iconImage" and "thumbnailImage" parameters for ListItem, use setArt
* Added xbmcgui.Dialog.textviewer <ref>https://github.com/xbmc/xbmc/pull/7271</ref>
* Added xbmcgui.ControlFadeLabel.setScrolling <ref>https://github.com/xbmc/xbmc/pull/7454</ref>
* Added xbmcgui.Dialog.multiselect
* Added ListItem.setContentLookup
* Added "mediatype" info label for videos
* Added "userrating" info label for videos
* Added "icon" support to ListItem.setArt

=Skins=
See http://forum.kodi.tv/showthread.php?tid=231270

== References ==
<references/>

==See also==
* [[Development]]
{{Changelogs}}

{{Isengard updated}}

[[Category:Development|*]]
[[Category:Add-on development]]
[[Category:J|*]]

Archive:Jarvis API changes

2015-10-20T08:39:05Z

Takoi: /* Python */

{{Isengard}}
{{notice|Kodi v15 (Isengard) final was just recently released, so please keep in mind that a v16 (Jarvis) release is still far away into the future. As such, these API changes is a placeholder containing API changes to the current Kodi mainline (the git master tree repository on GitHub). It is a very much a work in progress, this is only listing API changes commited to the master branch after Isengard branching, and many many many APIs are subject to future change.}}
{{incomplete}}

{{see also|Kodi v16 (Jarvis) FAQ|Kodi v16 (Jarvis) changelog|Releases}}

=Addons=

== PVR ==
* Update the PVR Addon API version to 4.0.0 for Kodi v16 (Jarvis)<ref>https://github.com/xbmc/xbmc/pull/7408</ref><ref>https://github.com/xbmc/xbmc/pull/7626</ref><ref>https://github.com/xbmc/xbmc/pull/8005</ref>
==== PVR API ====
{{incomplete}}
* ?

== Python ==

* Changed: ListItem no longer sets media type based on "tvshowtitle", "episode" and "season" provided via ListItem::setInfo. May affect appearance of info dialog. Use the new "mediatype" info label instead. <ref>https://github.com/xbmc/xbmc/pull/7683</ref>
* Removed depricated xbmcgui.lock() and xbmcgui.unlock()
* Deprecated ListItem.setIconImage, use setArt
* Deprecated ListItem.setThumbnailImage, use setArt
* Deprecated "iconImage" and "thumbnailImage" parameters for ListItem, use setArt
* Added xbmcgui.Dialog.textviewer <ref>https://github.com/xbmc/xbmc/pull/7271</ref>
* Added xbmcgui.ControlFadeLabel.setScrolling <ref>https://github.com/xbmc/xbmc/pull/7454</ref>
* Added xbmcgui.Dialog.multiselect
* Added ListItem.setContentLookup
* Added "mediatype" info label for videos
* Added "userrating" info label for videos
* Added "icon" support to ListItem.setArt

== Builtins ==
{{incomplete}}
* ?

==== New ====
{{incomplete}}
* ?

==== Changed ====
{{incomplete}}
* ?

== Changes to python path ==
{{incomplete}}
* ?

= JSON-RPC =
{{main|JSON-RPC API}}
==== Changed Methods ====
{{incomplete}}
* ?

==== New Methods ====
{{incomplete}}
* ?

=Webserver=
{{incomplete}}
* ?

=Scrapers=
{{incomplete}}
* ?

=Screensavers and visualizations=
{{incomplete}}
* ?

= Window IDs =
See [[Window IDs]]

=Skins=
== Changes to the skinning engine ==
See http://forum.kodi.tv/showthread.php?tid=231270

== References ==
<references/>

==See also==
* [[Development]]
{{Changelogs}}

{{Isengard updated}}

[[Category:Development|*]]
[[Category:Add-on development]]
[[Category:J|*]]

Archive:Jarvis API changes

2015-08-22T12:33:07Z

Takoi: /* Python */

{{Isengard}}
{{notice|Kodi v15 (Isengard) final was just recently released, so please keep in mind that a v16 (Jarvis) release is still far away into the future. As such, these API changes is a placeholder containing API changes to the current Kodi mainline (the git master tree repository on GitHub). It is a very much a work in progress, this is only listing API changes commited to the master branch after Isengard branching, and many many many APIs are subject to future change.}}
{{incomplete}}

{{see also|Kodi v16 (Jarvis) FAQ|Kodi v16 (Jarvis) changelog|Releases}}

=Addons=

== PVR ==

==== PVR API ====
{{incomplete}}
* ?

== Python ==
{{incomplete}}

* Changed: ListItem no longer sets media type based on "tvshowtitle", "episode" and "season" provided via ListItem::setInfo. May affect appearance of info dialog. Use the new "mediatype" info label instead. <ref>https://github.com/xbmc/xbmc/pull/7683</ref>
* Deprecated ListItem.setIconImage, use setArt
* Deprecated ListItem.setThumbnailImage, use setArt
* Deprecated "iconImage" and "thumbnailImage" parameters for ListItem, use setArt
* Added xbmcgui.Dialog.textviewer <ref>https://github.com/xbmc/xbmc/pull/7271</ref>
* Added xbmcgui.ControlFadeLabel.setScrolling <ref>https://github.com/xbmc/xbmc/pull/7454</ref>
* Added xbmcgui.Dialog.multiselect
* Added ListItem.setContentLookup
* Added "mediatype" info label for videos
* Added "icon" support to ListItem.setArt

== Builtins ==
{{incomplete}}
* ?

==== New ====
{{incomplete}}
* ?

==== Changed ====
{{incomplete}}
* ?

== Changes to python path ==
{{incomplete}}
* ?

= JSON-RPC =
{{main|JSON-RPC API}}
==== Changed Methods ====
{{incomplete}}
* ?

==== New Methods ====
{{incomplete}}
* ?

=Webserver=
{{incomplete}}
* ?

=Scrapers=
{{incomplete}}
* ?

=Screensavers and visualizations=
{{incomplete}}
* ?

= Window IDs =
See [[Window IDs]]

=Skins=
== Changes to the skinning engine ==
See http://forum.kodi.tv/showthread.php?tid=231270

== References ==
<references/>

==See also==
* [[Development]]
{{Changelogs}}

{{Isengard updated}}

[[Category:Development|*]]
[[Category:Add-on development]]
[[Category:J|*]]

Archive:Jarvis API changes

2015-08-15T11:39:07Z

Takoi:

{{Isengard}}
{{notice|Kodi v15 (Isengard) final was just recently released, so please keep in mind that a v16 (Jarvis) release is still far away into the future. As such, these API changes is a placeholder containing API changes to the current Kodi mainline (the git master tree repository on GitHub). It is a very much a work in progress, this is only listing API changes commited to the master branch after Isengard branching, and many many many APIs are subject to future change.}}
{{incomplete}}

{{see also|Kodi v16 (Jarvis) FAQ|Kodi v16 (Jarvis) changelog|Releases}}

=Addons=

== PVR ==

==== PVR API ====
{{incomplete}}
* ?

== Python ==
{{incomplete}}

* Changed: ListItem no longer sets media type based on "tvshowtitle", "episode" and "season" provided via ListItem::setInfo. May affect appearance of info dialog. Use the new "mediatype" info label instead. <ref>https://github.com/xbmc/xbmc/pull/7683</ref>
* Deprecated ListItem.setIconImage, use setArt
* Deprecated ListItem.setThumbnailImage, use setArt
* Deprecated "iconImage" and "thumbnailImage" arguments for ListItem, use setArt
* Added xbmcgui.Dialog.textviewer <ref>https://github.com/xbmc/xbmc/pull/7271</ref>
* Added xbmcgui.ControlFadeLabel.setScrolling <ref>https://github.com/xbmc/xbmc/pull/7454</ref>
* Added ListItem.setContentLookup
* Added "mediatype" info label for videos
* Added "icon" support to ListItem.setArt

== Builtins ==
{{incomplete}}
* ?

==== New ====
{{incomplete}}
* ?

==== Changed ====
{{incomplete}}
* ?

== Changes to python path ==
{{incomplete}}
* ?

= JSON-RPC =
{{main|JSON-RPC API}}
==== Changed Methods ====
{{incomplete}}
* ?

==== New Methods ====
{{incomplete}}
* ?

=Webserver=
{{incomplete}}
* ?

=Scrapers=
{{incomplete}}
* ?

=Screensavers and visualizations=
{{incomplete}}
* ?

= Window IDs =
See [[Window IDs]]

=Skins=
== Changes to the skinning engine ==
See http://forum.kodi.tv/showthread.php?tid=231270

== References ==
<references/>

==See also==
* [[Development]]
{{Changelogs}}

{{Isengard updated}}

[[Category:Development|*]]
[[Category:Add-on development]]
[[Category:J|*]]

Archive:Jarvis API changes

2015-08-15T11:38:09Z

Takoi: /* Python */

{{Isengard}}
{{notice|Kodi v15 (Isengard) final was just recently released, so please keep in mind that a v16 (Jarvis) release is still far away into the future. As such, these API changes is a placeholder containing API changes to the current Kodi mainline (the git master tree repository on GitHub). It is a very much a work in progress, this is only listing API changes commited to the master branch after Isengard branching, and many many many APIs are subject to future change.}}
{{incomplete}}

{{see also|Kodi v16 (Jarvis) FAQ|Kodi v16 (Jarvis) changelog|Releases}}

=Addons=

== PVR ==

==== PVR API ====
{{incomplete}}
* ?

== Python ==
{{incomplete}}

* Changed: ListItem no longer sets media type based on "tvshowtitle", "episode" and "season" provided via ListItem::setInfo. May affect appearance of info dialog. Use the new "mediatype" info label instead. <ref>https://github.com/xbmc/xbmc/pull/7683</ref>
* Deprecated ListItem.setIconImage, use setArt
* Deprecated ListItem.setThumbnailImage, use setArt
* Deprecated "iconImage" and "thumbnailImage" arguments for ListItem, use setArt
* Added xbmcgui.Dialog.textviewer <ref>https://github.com/xbmc/xbmc/pull/7271</ref>
* Added xbmcgui.ControlFadeLabel.setScrolling <ref>https://github.com/xbmc/xbmc/pull/7454</ref>
* Added ListItem.setContentLookup
* Added "mediatype" info label for videos
* Added "icon" support to ListItem.setArt

== Builtins ==
{{incomplete}}
* ?

==== New ====
{{incomplete}}
* ?

==== Changed ====
{{incomplete}}
* ?

== Changes to python path ==
{{incomplete}}
* ?

= JSON-RPC =
{{main|JSON-RPC API}}
==== Changed Methods ====
{{incomplete}}
* ?

==== New Methods ====
{{incomplete}}
* ?

=Webserver=
{{incomplete}}
* ?

=Scrapers=
{{incomplete}}
* ?

=Screensavers and visualizations=
{{incomplete}}
* ?

= Window IDs =
See [[Window IDs]]

=Skins=
== Changes to the skinning engine ==
See http://forum.kodi.tv/showthread.php?tid=231270

==See also==
* [[Development]]
{{Changelogs}}

{{Isengard updated}}

[[Category:Development|*]]
[[Category:Add-on development]]
[[Category:J|*]]

Add-on:Extras

2015-08-11T15:55:25Z

Takoi:

{{Addon
|Name=Extras
|provider-name=takoi
|ID=context.item.extras
|latest-version=1.0.0
|extension point=kodi.context.item
|provides=
|Summary=Browse extras from the video library
|Description=This add-on lets you view your movie and TV show extras/special features directly from the library. To access extras, open the context menu on a video in the library and click 'Extras'.

By default, the add-on will look in the ".extras" sub-directory for content (can be changed in settings).
|Platform=all
|Language=
|License=GNU GENERAL PUBLIC LICENSE. Version 3, 29 June 2007
|Forum=
|Website=
|Source=https://github.com/tamland/kodi-addon-extras
|Email=
|broken=
|icon url=http://mirrors.kodi.tv/addons/isengard/context.item.extras/icon.png}}

== Preventing extras from being added to library ==
See [[Set_content_and_scan#Excluding_directories.2Ffolders|Excluding directories/folders]]

[[Category:Isengard add-on repository]]

Context Item Add-ons

2015-03-05T11:47:25Z

Takoi:

Context item add-ons allows the [[context menu]] in Kodi to be extended. Add-ons must provide the <code>kodi.context.item</code> extension point and a <item> definition. Example:

<syntaxhighlight lang="xml">
<extension point="kodi.context.item" library="addon.py">
<item>
<label>Hello World</label>
<visible>!IsEmpty(ListItem.Genre)</visible>
<parent>kodi.core.manage</parent>
</item>
</extension>
</syntaxhighlight>

<label>: Required. The label to show in the context menu. String or an ID from the language file.

<visible>: Required. A [[Conditional visibility|visibility expression]] that determines when the item will be visible in the [[context menu]].

<parent>: Optional. The parent group for the context item. If "kodi.core.manage" the item will be added under the "Manage" sub-menu. If not specified, it will be added to the top level.

It is currently only possible to provide one item per add-on.

{{Note|Before adding a context menu extension to existing add-on, keep in mind that there is limited space in the [[context menu]] and that having multiple extension in and add-on will force the user to have all of them enabled at the same time.}}

This feature requires at least version 2.20.0 of the Python API, which should be specified in the [[Addon.xml#<requires>]] element:
<syntaxhighlight lang="xml">
<import addon="xbmc.python" version="2.20.0"/>
</syntaxhighlight>

The item the context menu was opened on can be accessed in python via the <code>sys.listitem</code> attribute. The attribute is an instance of <code>xbmcgui.ListItem</code>.

== Example python script ==

This example script will display a notification message showing the name of item the context menu was opened on:

<syntaxhighlight lang="python">
import sys
import xbmc

if __name__ == '__main__':
message = "Clicked on '%s'" % sys.listitem.getLabel()
xbmc.executebuiltin("Notification(\"Hello context items!\", \"%s\")" % message)
</syntaxhighlight>

[[Category:Add-on development]]

Context Item Add-ons

2015-03-02T15:08:25Z

Takoi: Created page with " Context item add-ons allows the Context menu in Kodi to be extended. Add-ons must provide the <code>kodi.context.item</code> extension point and a item definition as foll..."

Context item add-ons allows the [[Context menu]] in Kodi to be extended. Add-ons must provide the <code>kodi.context.item</code> extension point and a item definition as follows:

<syntaxhighlight lang="xml">
<item>
<label></label>
<visible></visible>
<parent></parent>
</item>
</syntaxhighlight>

<label>: Required. The label to show in the context menu. String or an ID from the language file.

<visible>: Required. A [[Conditional visibility|visibility expression]] that determines when the item will be visible in the [[context menu]].

<parent>: Optional. The parent group for the context item. If "kodi.core.manage" the item will be added under the "Manage" sub-menu. If not specified, it will be added to the top level.

It is currently only possible to provide one item per add-on.

{{Note|Before adding a context menu extension to existing add-on, keep in mind that there is limited space in the [[context menu]] and that having multiple extension in and add-on will force the user to have all of them enabled at the same time.}}

== Example <code>addon.xml</code> definition: ==

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="context.item.hello.world" name="Hello World" version="1.0.0" provider-name="your-name">
<requires>
<import addon="xbmc.python" version="2.20.0"/>
</requires>
<extension point="kodi.context.item" library="addon.py">
<item>
<label>Hello World</label>
<visible>!IsEmpty(ListItem.Genre)</visible>
</item>
</extension>
<extension point="kodi.addon.metadata">
<platform>all</platform>
<summary></summary>
<description></description>
</extension>
</addon>
</syntaxhighlight>

== Example python script: ==

The item the context menu was opened on can be accessed in python via the <code>sys.listitem<code/> attribute. The attribute is an instance of <code>xbmcgui.ListItem</code>. The following example script will display a notification message showing the name of item:

<syntaxhighlight lang="python">
import sys
import xbmc

if __name__ == '__main__':
message = "Clicked on '%s'" % sys.listitem.getLabel()
xbmc.executebuiltin("Notification(\"Hello context items!\", \"%s\")" % message)
</syntaxhighlight>

Add-on settings

2015-01-19T09:25:15Z

Takoi:

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

{{see also|Python development}}

== Description ==

settings.xml is a XML file that contains the current configuration for the addon and should be placed in the resources direcory. If your addon has
configurable items that are set by the user, put them here. This file defines what the user sees
when they click on Addon settings for your addon. You don't need to do any coding to utilise this functionality.
The format for the settings file is relatively straightforward as can be seen in the following example:

Example code:
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
<category label="32001">
<setting label="32011" type="text" id="username" default=""/>
<setting label="32012" type="text" id="password" option="hidden" enable="!eq(-1,)" default=""/>
<setting label="32053" type="slider" id="limit" subsetting="true" default="20" range="5,5,100" option="int" />
<setting type="sep"/>
<setting id="debug" type="bool" label="32013" default="false"/>
</category>
<category label="32010">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

You need to supply at least one category element.
The label attribute of both categories and settings should be the id of a language string in your language files or the one of the main XBMC language file.

== Different types ==

'''Setting type and additional attributes can be one in the following table:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| source="" || "video", "music", "pictures", "programs", "files", "local" or blank." if source is blank it will use the type for shares if it is a valid share if not a valid share it will use, both local and network drives.
|-
| visible="" || "true", "false" or conditional." Determines if the setting is displayed in the settings dialog (default = 'true')" You can also use a conditional statement: visible="System.HasAddon(plugin.video.youtube)"
|-
| enable="" || Allows you to determine whether this setting should be shown based on the value of another setting. 3 comparators are available:"
* eq() Equal to
* gt() Greater than
* lt() Less than

You can AND the comparators using the + symbol and negate it using the ! symbol (e.g. !eq() ). Each comparator takes 2 operands:
* Relative position of setting to compare
* Value to compare against

Thus if we place settings in our file in this order:
: myFirst setting
: mySecondSetting
: myThirdSetting

for the third setting we might add the option: 
enable="gt(-2,3) + lt(-2,10)" 
You can also use a conditional statement: enable="System.HasAddon(plugin.video.youtube)"
|}

== Elements ==

=== Line separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32053" type="slider" id="limit" default="20" range="5,5,100" option="int" />
<setting label="32053" type="slider" id="limit" default="20" range="0,100"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

* Selecting the value "One" will return the int value "0", selecting the value "Two" will return the int value "1", etc.

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Execute action ===

Separator adds a label as separator between other element

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on development

2015-01-15T12:50:23Z

Takoi:

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

{{-}}
----
{| cellpadding="0" cellspacing="0"
|-
!colspan="2" | General
|-
| width="50%" valign="top" |
*[[About Add-ons]]
*[[Add-on structure]]
*[[Add-on settings]]
*[[Development Tools]]
| width="50%" valign="top" |
*[[Special protocol]]
*[[Translation System]]
*[[Python libraries]]
*[[Add-on unicode paths|Unicode]]
|-
! colspan="2" | Tutorials
|-
| valign="top" |
*[[HOW-TO:HelloWorld addon|Hello World]]
*[[Audio/video add-on tutorial]]
| valign="top" |
*[[HOW-TO:Debug Python Scripts with Eclipse]]
*[[HOW-TO:Debug python scripts with WinPDB]]
|-
! colspan="2" | Add-on types
|-
| valign="top" |
*[[Plugin sources]]
*[[Script sources|Scripts]]
*[[Script Subtitles|Subtitle add-ons]]
*[[Service addons|Service add-ons]]
| valign="top" |
*[[Script lyrics|Lyrics]]
*[[HOW-TO:Create a repository for add-ons|Repository add-ons]]
*[[Scrapers]] ([[HOW-TO:Write media scrapers|alt]])
*[[Skin development|Skins]]
|-
! colspan="2" | Documentation
|-
| valign="top" |
*[http://mirrors.xbmc.org/docs/python-docs PyDocs]
*[[JSON-RPC API]]
*[[Helix API changes]]
*[[List of built-in functions]]
| valign="top" |
*[[InfoLabels|List of info labels]]
*[[Window IDs|List of window IDs]]
*[[List of boolean conditions]]
|-
! colspan="2" | Publishing
|-
| valign="top" |
*[[Add-on rules]]
*[[Official add-on repository]]
| valign="top" |
*[[Submitting Add-ons]]
|}

[[Category:Add-on development|*]]

Python libraries

2015-01-13T18:02:35Z

Takoi:

XBMC Python comes with all the standard modules from Python 2.6 or later. See https://docs.python.org/2.6/library/ for reference.

== Built-in modules ==
In addition to the standard libraries, XBMC Python uses a handful of custom modules to expose XBMC functionality to Python.

Up to date documentation about these modules can be found at http://mirrors.xbmc.org/docs/python-docs/

{| border=1 cellspacing=0 cellpadding=5
| '''Module'''
| '''Description'''
|-
| xbmc
| Offers classes and functions that provide information about the media currently playing and that allow manipulation of the media player (such as starting a new song). You can also find system information using the functions available in this library.
|-
| xbmcgui
| Offers classes and functions that manipulate the Graphical User Interface through windows, dialogs, and various control widgets.
|-
| xbmcplugin
| Offers classes and functions that allow a developer to present information through XBMC's standard menu structure. While plugins don't have the same flexibility as scripts, they boast significantly quicker development time and a more consistent user experience.
|-
| xbmcaddon
| Offers classes and functions that manipulate the add-on settings, information and localization.
|-
| xbmcvfs
| Offers classes and functions offers acces to the Virtual File Server (VFS) which you can use to manipulate files and folders.
|}

== Third-party modules ==
Numerous python modules are already packages as add-ons that can be imported by other add-on. See [[:Category:Add-on_libraries/modules]] for a list of available modules. To use any of these modules with your add-on, add the relevant line to [[Addon.xml#.3Crequires.3E|Addon.xml]]

== Installing additional modules ==
Additional modules may be installed by simply adding the module to the root folder of your add-on.

A common way to organized third-party modules that are not part of add-on source code itself, is to add a <code>lib</code> directory and place an <code>__init__.py</code> file and other third-party modules inside it. These modules may then normally be imported using <code>from lib import somemodule</code>.

[[Category:Add-on development]]

Python libraries

2015-01-13T17:59:37Z

Takoi:

XBMC Python comes with all the standard modules from Python 2.6 or later. See https://docs.python.org/2.6/library/ for reference.

== Built-in modules ==
In addition to the standard libraries, XBMC Python uses a handful of custom modules to expose XBMC functionality to Python.

Up to date documentation about these modules can be found at http://mirrors.xbmc.org/docs/python-docs/

{| border=1 cellspacing=0 cellpadding=5
| '''Module'''
| '''Description'''
|-
| xbmc
| Offers classes and functions that provide information about the media currently playing and that allow manipulation of the media player (such as starting a new song). You can also find system information using the functions available in this library.
|-
| xbmcgui
| Offers classes and functions that manipulate the Graphical User Interface through windows, dialogs, and various control widgets.
|-
| xbmcplugin
| Offers classes and functions that allow a developer to present information through XBMC's standard menu structure. While plugins don't have the same flexibility as scripts, they boast significantly quicker development time and a more consistent user experience.
|-
| xbmcaddon
| Offers classes and functions that manipulate the add-on settings, information and localization.
|-
| xbmcvfs
| Offers classes and functions offers acces to the Virtual File Server (VFS) which you can use to manipulate files and folders.
|}

== Third-party modules ==
Numerous python modules are already packages as add-ons that can be imported by other add-on. See [[Category:Add-on_libraries/modules]] for a list of available modules. To use any of these modules with your add-on, add the relevant line to [[Addon.xml#.3Crequires.3E|Addon.xml]]

== Installing additional modules ==
Additional modules may be installed by simply adding the module to the root folder of your add-on.

A common way to organized third-party modules that are not part of add-on source code itself, is to add a <code>lib</code> directory and place an <code>__init__.py</code> file and other third-party modules inside it. These modules may then normally be imported using <code>from lib import somemodule</code>.

[[Category:Add-on development]]

HOW-TO:Create add-on PRs using Git Subtree Merging

2015-01-13T17:17:42Z

Takoi:

=== First time setup ===

First fork and clone the relevant [[official add-on repository]]. In this example we use the plugins repo:
<pre>
git clone git@github.com:me/repo-plugins.git
cd repo-plugins
</pre>

Add the git repository where your addon resides as a remote:
<pre>
git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon
</pre>

Create a new branch for the addon:
<pre>
git checkout -b myaddon_branch myaddon/master
</pre>

The current directory should contain the files from the myaddon repository. To switch back to gotham branch of the "repo-plugins" repository:

<pre>
git checkout gotham
</pre>

'''Note:''' If your addon already exist in repo, it must first be removed with:
<pre>
git rm -r plugin.my.addon/
</pre>

Now we use subtree merge to pull myaddon into the gotham branch of repo-plugins:
<pre>
git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
</pre>

To see the changes that are about to be committed:
<pre>
git diff --staged
</pre>

Finally, commit the changes:
<pre>
git commit -m "[plugin.my.addon] 1.0.1"
git push origin gotham
</pre>

You can now open a PR on Github.

'''Note:''' Remember to send the PR to the correct branch. If you have pushed to gotham branch, you should request pull to the gotham branch in repo.

=== Updating addon to a new version ===

Updating the addon is now easy. For this example we pull the master branch from myaddon:

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon master
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>

For more info about Subtree Merging see http://git-scm.com/book/en/v1/Git-Tools-Subtree-Merging

Submitting Add-ons

2015-01-13T17:13:15Z

Takoi: update link

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

=== Submitting a Compliant Add-on to the XBMC.org 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 || 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
! codename !! version !! repo !! repo !! repo
|-
| Dharma || 10.x || Dharma || ||
|-
| Eden || 11.x || Eden || ||
|-
| Frodo || 12.x || Frodo || ||
|-
| Gotham || 13.x || Frodo || Gotham ||
|-
| Helix || 14.x || Frodo || Gotham || Helix
|}

{{see also|Addon.xml#Dependency_versions}}

=== The mailing list ===
We ask that all Add-on authors subscribe to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List].
This is done for several reasons.
:* This is where all updates and important information will be announced.
:* This way we can contact you regarding your add-ons if necessary.
:* You can see what other devs are requesting to be added so you know if possibly you need to check compatibility of the add-on you depend on.
:* You may find new and interesting add-ons this way on which you can get inspiration from or may depend on.

After you have subscribed to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List] you will be send a conformation e-mail. Be sure to accept this before you can submit to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Mailing List].

All pull requests should be sent to this list so that repository maintainers will be notified that you want to add of update your add-on. They will do a sanity check if all seems ok and you are following the Kodi guidelines for add-ons. If any issues or questions arise they will contact you through the e-mail you registered with.
Once all checks out fine your add-on is added to repository and you will receive a confirmation e-mail that it is added.

{{tip|To un-subscribe from the mailinglist follow the same link as [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List] and there's the option to unsubscribe at the bottom}}

==== How to submit your add-on and subsequent updates ====

In order to submit your addon, you must send a request that we add or update your add-on to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List] (We call this a "pull request."). Each request will require a version bump in the [[addon.xml]]. We ask that you also keep a [[Add-on_structure#changelog.txt|changelog.txt]] up to date so that users may easily see what has changed.

Note that .xbt files will be generated automatically for skins so you do not include this in your pull request.

There are several ways to request that we add or update your add-on. Please preface threads using the following conventions:

{| class="prettytable" border="1"
! Type !! Description
|-
| [Git Pull]|| Submit a request that we pull from your repo. This should include a url, branch/tag/revision, and the addon to pull. HEAD is NOT a revision.
|-
| [SVN Pull]|| Same as [Git Pull]
|-
| [Zip Pull]|| By far the least used but still a valid way. Submit a link where the add-on zip can be downloaded from.
For example you can just give us the link to .zip in your dropbox account. We do not want to download it from a public download site that holds questionable content or is filled with ads.
|-
| [Patch]|| Sometimes you may wish to submit a patch to the author for review.
Under most circumstances we will not merge this directly, it should go to the upstream maintainer first.
|}

After you have send it to the mailing list please keep an eye out for any reply from our repository maintainers if there are any remarks or changes needed or a simple confirmation it has been added. Do note it might take some time to process the request.

After it has been added or updated it will be available from the Kodi repository in Kodi itself, on http://addons.xbmc.org/ and on the wiki page http://wiki.xbmc.org/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}}

==== Example e-mail ====

Subject:
[Git Pull] my cool plugin
Body:
*addon - my.cool.plugin
*version - 1.1.0
*url - git://some.where.git
*revision - a241345a
*branch - master
*xbmc version - helix

{{Note|If you want to request multiple add-ons to be added you can just do this in one e-mail as long as you provide the "Body" part each time for every add-on and every Kodi version you want it to be included to. In this case the subject field doesn't need to contain the add-on name. Do provide the "[Git Pull]" part at least.}}

{{tip|At this moment Frodo/Gotham/Helix combine all repos into one single repo list in Kodi. You only need to do a request for the minimum repo your add-on supports.}}

=== Github ===

Alternatively, add-on updates may be submitted directly to the [[Official add-on repository]] on Github as pull requests. 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"

As with mailing list, only PRs from add-on author will be accepted. Patches should be submitted upstream. For an easy way to create PR from your own git repository, see [[HOW-TO: create add-on PRs using Git Subtree Merging]].

[[Category:Add-on development]]

Submitting Add-on updates on Github

2015-01-13T17:12:23Z

Takoi: Takoi moved page Submitting Add-on updates on Github to HOW-TO:Create add-on PRs using Git Subtree Merging

#REDIRECT [[HOW-TO:Create add-on PRs using Git Subtree Merging]]

HOW-TO:Create add-on PRs using Git Subtree Merging

2015-01-13T17:12:23Z

Takoi: Takoi moved page Submitting Add-on updates on Github to HOW-TO:Create add-on PRs using Git Subtree Merging

=== First time setup ===

Clone the XBMC addon repository:
<pre>
git clone git@github.com:xbmc/repo-plugins.git
cd repo-plugins
</pre>

For this example we will use an addon named "myaddon". Add the git repo where you addon resides as a remote:
<pre>
git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon
</pre>

Create a new branch for the addon:
<pre>
git checkout -b myaddon_branch myaddon/master
</pre>

The current directory should contain the files from the myaddon repository. To switch back to gotham branch of the "repo-plugins" repository:

<pre>
git checkout gotham
</pre>

'''Note:''' If your addon already exist in repo, it must first be removed with:
<pre>
git rm -r plugin.my.addon/
</pre>

Now we use subtree merge to pull myaddon into the gotham branch of repo-plugins:
<pre>
git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
</pre>

To see the changes that are about to be committed:
<pre>
git diff --staged
</pre>

Finally, commit the changes:
<pre>
git commit -m "[plugin.my.addon] 1.0.1"
git push origin gotham
</pre>

You can now open a PR on Github.

'''Note:''' Remember to send the PR to the correct branch. If you have pushed to gotham branch, you should request pull to the gotham branch in repo.

=== Updating addon to a new version ===

Updating the addon is now easy. For this example we pull the master branch from myaddon:

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon master
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>

For more info about Subtree Merging see http://git-scm.com/book/en/v1/Git-Tools-Subtree-Merging

HOW-TO:Create add-on PRs using Git Subtree Merging

2015-01-13T17:11:42Z

Takoi: moved to Submitting Add-ons page

Submitting Add-ons

2015-01-13T17:10:05Z

Takoi: add github notes

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

=== Submitting a Compliant Add-on to the XBMC.org 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 || 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
! codename !! version !! repo !! repo !! repo
|-
| Dharma || 10.x || Dharma || ||
|-
| Eden || 11.x || Eden || ||
|-
| Frodo || 12.x || Frodo || ||
|-
| Gotham || 13.x || Frodo || Gotham ||
|-
| Helix || 14.x || Frodo || Gotham || Helix
|}

{{see also|Addon.xml#Dependency_versions}}

=== The mailing list ===
We ask that all Add-on authors subscribe to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List].
This is done for several reasons.
:* This is where all updates and important information will be announced.
:* This way we can contact you regarding your add-ons if necessary.
:* You can see what other devs are requesting to be added so you know if possibly you need to check compatibility of the add-on you depend on.
:* You may find new and interesting add-ons this way on which you can get inspiration from or may depend on.

After you have subscribed to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List] you will be send a conformation e-mail. Be sure to accept this before you can submit to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Mailing List].

All pull requests should be sent to this list so that repository maintainers will be notified that you want to add of update your add-on. They will do a sanity check if all seems ok and you are following the Kodi guidelines for add-ons. If any issues or questions arise they will contact you through the e-mail you registered with.
Once all checks out fine your add-on is added to repository and you will receive a confirmation e-mail that it is added.

{{tip|To un-subscribe from the mailinglist follow the same link as [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List] and there's the option to unsubscribe at the bottom}}

==== How to submit your add-on and subsequent updates ====

In order to submit your addon, you must send a request that we add or update your add-on to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List] (We call this a "pull request."). Each request will require a version bump in the [[addon.xml]]. We ask that you also keep a [[Add-on_structure#changelog.txt|changelog.txt]] up to date so that users may easily see what has changed.

Note that .xbt files will be generated automatically for skins so you do not include this in your pull request.

There are several ways to request that we add or update your add-on. Please preface threads using the following conventions:

{| class="prettytable" border="1"
! Type !! Description
|-
| [Git Pull]|| Submit a request that we pull from your repo. This should include a url, branch/tag/revision, and the addon to pull. HEAD is NOT a revision.
|-
| [SVN Pull]|| Same as [Git Pull]
|-
| [Zip Pull]|| By far the least used but still a valid way. Submit a link where the add-on zip can be downloaded from.
For example you can just give us the link to .zip in your dropbox account. We do not want to download it from a public download site that holds questionable content or is filled with ads.
|-
| [Patch]|| Sometimes you may wish to submit a patch to the author for review.
Under most circumstances we will not merge this directly, it should go to the upstream maintainer first.
|}

After you have send it to the mailing list please keep an eye out for any reply from our repository maintainers if there are any remarks or changes needed or a simple confirmation it has been added. Do note it might take some time to process the request.

After it has been added or updated it will be available from the Kodi repository in Kodi itself, on http://addons.xbmc.org/ and on the wiki page http://wiki.xbmc.org/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}}

==== Example e-mail ====

Subject:
[Git Pull] my cool plugin
Body:
*addon - my.cool.plugin
*version - 1.1.0
*url - git://some.where.git
*revision - a241345a
*branch - master
*xbmc version - helix

{{Note|If you want to request multiple add-ons to be added you can just do this in one e-mail as long as you provide the "Body" part each time for every add-on and every Kodi version you want it to be included to. In this case the subject field doesn't need to contain the add-on name. Do provide the "[Git Pull]" part at least.}}

{{tip|At this moment Frodo/Gotham/Helix combine all repos into one single repo list in Kodi. You only need to do a request for the minimum repo your add-on supports.}}

=== Github ===

Alternatively, add-on updates may be submitted directly to the [[Official add-on repository]] on Github as pull requests. 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"

As with mailing list, only PRs from add-on author will be accepted. Patches should be submitted upstream. For an easy way to create PR from your own git repository, see [[Submitting_Add-on_updates_on_Github#Example_git_setup_using_Subtree_merging|HOW-TO: create add-on PRs using Git Subtree Merging]].

[[Category:Add-on development]]

Add-on development

2015-01-13T16:30:33Z

Takoi:

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

{{-}}
----
{| cellpadding="0" cellspacing="0"
|-
!colspan="2" | General
|-
| width="50%" valign="top" |
*[[About Add-ons]]
*[[Add-on structure]]
*[[Add-on settings]]
*[[Development Tools]]
| width="50%" valign="top" |
*[[Special protocol]]
*[[Translation System]]
*[[Python libraries]]
*[[Add-on unicode paths|Unicode]]
|-
! colspan="2" | Tutorials
|-
| valign="top" |
*[[HOW-TO:HelloWorld addon|Hello World]]
*[[Audio/video add-on tutorial]]
| valign="top" |
*[[HOW-TO:Debug Python Scripts with Eclipse]]
*[[HOW-TO:Debug python scripts with WinPDB]]
|-
! colspan="2" | Add-on types
|-
| valign="top" |
*[[Plugin sources]]
*[[Script sources|Scripts]]
*[[Script Subtitles|Subtitle add-ons]]
*[[Service addons|Service add-ons]]
| valign="top" |
*[[Script lyrics|Lyrics]]
*[[HOW-TO:Create a repository for add-ons|Repository add-ons]]
*[[HOW-TO:Write media scrapers|Scrapers]]
*[[Skin development|Skins]]
|-
! colspan="2" | Documentation
|-
| valign="top" |
*[http://mirrors.xbmc.org/docs/python-docs PyDocs]
*[[JSON-RPC API]]
*[[Helix API changes]]
*[[List of built-in functions]]
| valign="top" |
*[[InfoLabels|List of info labels]]
*[[Window IDs|List of window IDs]]
*[[List of boolean conditions]]
|-
! colspan="2" | Publishing
|-
| valign="top" |
*[[Add-on rules]]
*[[Official add-on repository]]
| valign="top" |
*[[Submitting Add-ons]]
|}

[[Category:Add-on development|*]]

Add-on development

2015-01-13T16:28:34Z

Takoi: add more links and remove duplicated/non-development ones. sorry, don't have time for images

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

{{-}}
----
{| cellpadding="0" cellspacing="0"
|-
!colspan="2" | General
|-
| width="50%" valign="top" |
*[[About Add-ons]]
*[[Add-on structure]]
*[[Add-on settings]]
*[[Development Tools]]
| width="50%" valign="top" |
*[[Special protocol]]
*[[Translation System]]
*[[Python libraries]]
*[[Add-on unicode paths|Unicode]]
|-
! colspan="2" | Tutorials
|-
| valign="top" |
*[[HOW-TO:HelloWorld addon]]
*[[Audio/video add-on tutorial]]
| valign="top" |
*[[HOW-TO:Debug Python Scripts with Eclipse]]
*[[HOW-TO:Debug python scripts with WinPDB]]
|-
! colspan="2" | Add-on types
|-
| valign="top" |
*[[Plugin sources]]
*[[Script sources|Scripts]]
*[[Script Subtitles|Subtitle add-ons]]
*[[Service addons|Service add-ons]]
| valign="top" |
*[[Script lyrics|Lyrics]]
*[[HOW-TO:Create a repository for add-ons|Repository add-ons]]
*[[HOW-TO:Write media scrapers|Scrapers]]
*[[Skin development|Skins]]
|-
! colspan="2" | Documentation
|-
| valign="top" |
*[http://mirrors.xbmc.org/docs/python-docs PyDocs]
*[[JSON-RPC API]]
*[[Helix API changes]]
*[[List of built-in functions]]
| valign="top" |
*[[InfoLabels|List of info labels]]
*[[Window IDs|List of window IDs]]
*[[List of boolean conditions]]
|-
! colspan="2" | Publishing
|-
| valign="top" |
*[[Add-on rules]]
*[[Official add-on repository]]
| valign="top" |
*[[Submitting Add-ons]]
|}

[[Category:Add-on development|*]]

Service add-ons

2014-12-14T14:00:37Z

Takoi:

Service addons will be automatically started when XBMC starts. These addons must offer the '''xbmc.service''' extension point. You can specify when you want your addon to start, using the '''start''' tag. If it's isn't here, your addon will automatically start after user login. If you want it to start on XBMC startup, you need to set the '''start''' tag to ''startup''. Here's a typical example of the addon.xml the addon needs to provide:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="service.example"
name="Example service"
version="1.0.0"
provider-name="">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
</requires>
<extension point="xbmc.service" library="service.py" start="login" />
<extension point="xbmc.addon.metadata">
<platform>all</platform>
<summary lang="en"></summary>
</extension>
</addon>
</source>

If your addon is meant to be run while XBMC is running, you need to periodically check if XBMC is exiting. The addon is responsible for terminating when XBMC wants to exit. This can be checked by creating a <code>xbmc.Monitor</code> instance and calling the <code>abortRequested()</code> method. To wait for this event instead, call <code>waitForAbort()</code>.

Example service that prints "hello addon!" every 10 second until XBMC exits:

<source lang="python">
import time
import xbmc

if __name__ == '__main__':
monitor = xbmc.Monitor()

while True:
# Sleep/wait for abort for 10 seconds
if monitor.waitForAbort(10):
# Abort was requested while waiting. We should exit
break
xbmc.log("hello addon! %s" % time.time(), level=xbmc.LOGDEBUG)
</source>

== Gotham and earlier ==
<code>abortRequested()</code> and <code>waitForAbort()</code> are new in Helix. In Gotham and earlier, use <code>xbmc.sleep</code> and check the <code>xbmc.abortRequested</code> attribute periodically.

Example:

<source lang="python">
import xbmc

if __name__ == '__main__':
while True:
if xbmc.abortRequested:
break
# some code
xbmc.sleep(500)
</source>

[[Category:How-to]]
[[Category:Add-on development]]

Service add-ons

2014-12-14T13:59:56Z

Takoi:

Service addons will be automatically started when XBMC starts. These addons must offer the '''xbmc.service''' extension point. You can specify when you want your addon to start, using the '''start''' tag. If it's isn't here, your addon will automatically start after user login. If you want it to start on XBMC startup, you need to set the '''start''' tag to ''startup''. Here's a typical example of the addon.xml the addon needs to provide:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="service.example"
name="Example service"
version="1.0.0"
provider-name="">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
</requires>
<extension point="xbmc.service" library="service.py" start="login" />
<extension point="xbmc.addon.metadata">
<platform>all</platform>
<summary lang="en"></summary>
</extension>
</addon>
</source>

If your addon is meant to be run while XBMC is running, you need to periodically check if XBMC is exiting. The addon is responsible for terminating when XBMC wants to exit. This can be checked by creating a <code>xbmc.Monitor</code> instance and calling the <code>abortRequested()</code> method. To wait for this event instead, call <code>waitForAbort()</code>.

Example service that prints "hello addon!" every 10 second until XBMC exits:

<source lang="python">
import time
import xbmc

if __name__ == '__main__':
monitor = xbmc.Monitor()

while True:
# Sleep/wait for abort for 10 seconds
if monitor.waitForAbort(10):
# Abort was requested while waiting. We should exit
break
xbmc.log("hello addon! %s" % time.time(), level=xbmc.LOGDEBUG)
</source>

== Gotham an earlier ==

<code>abortRequested()</code> and <code>waitForAbort()</code> are new in Helix. In Gotham and earlier, use <code>xbmc.sleep</code> and check the <code>xbmc.abortRequested</code> attribute periodically.

Example:

<source lang="python">
import xbmc

if __name__ == '__main__':
while True:
if xbmc.abortRequested:
break
# some code
xbmc.sleep(500)
</source>

[[Category:How-to]]
[[Category:Add-on development]]

Service add-ons

2014-12-14T13:57:18Z

Takoi:

Service addons will be automatically started when XBMC starts. These addons must offer the '''xbmc.service''' extension point. You can specify when you want your addon to start, using the '''start''' tag. If it's isn't here, your addon will automatically start after user login. If you want it to start on XBMC startup, you need to set the '''start''' tag to ''startup''. Here's a typical example of the addon.xml the addon needs to provide:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="service.example"
name="Example service"
version="1.0.0"
provider-name="">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
</requires>
<extension point="xbmc.service" library="service.py" start="login">
</extension>
<extension point="xbmc.addon.metadata">
<platform>all</platform>
<summary lang="en"></summary>
</extension>
</addon>
</source>

If your addon is meant to be run while XBMC is running, you need to periodically check if XBMC is exiting. The addon is responsible for terminating when XBMC wants to exit. This can be checked by creating a '''xbmc.Monitor''' instance and calling the <code>abortRequested()</code> method. To wait for this event instead, call '''waitForAbort()'''.

Example service that prints "hello addon!" every 10 second until XBMC exits:

<source lang="python">
import time
import xbmc

if __name__ == '__main__':
monitor = xbmc.Monitor()

while True:
# Sleep/wait for abort for 10 seconds
if monitor.waitForAbort(10):
# Abort was requested while waiting. We should exit
break
xbmc.log("hello addon! %s" % time.time(), level=xbmc.LOGDEBUG)
</source>

== Gotham an earlier ==
''abortRequested()'' and ''waitForAbort()'' are new in Helix. In Gotham, use ''xbmc.sleep'' and check the ''xbmc.abortRequested'' attribute periodically.

Example:

<source lang="python">
import xbmc

if __name__ == '__main__':
while True:
if xbmc.abortRequested:
break
# some code
xbmc.sleep(500)
</source>

[[Category:How-to]]
[[Category:Add-on development]]

HOW-TO:Create add-on PRs using Git Subtree Merging

2014-12-02T10:50:22Z

Takoi: /* First time setup */

== Guidelines ==
General [[Add-on rules]] apply. Additional rules 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"

As with mailing list, only PRs from add-on author will be accepted. Patches should be submitted upstream.

== Example git setup using Subtree merging ==

=== First time setup ===

Clone the XBMC addon repository:
<pre>
git clone git@github.com:xbmc/repo-plugins.git
cd repo-plugins
</pre>

For this example we will use an addon named "myaddon". Add the git repo where you addon resides as a remote:
<pre>
git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon
</pre>

Create a new branch for the addon:
<pre>
git checkout -b myaddon_branch myaddon/master
</pre>

The current directory should contain the files from the myaddon repository. To switch back to gotham branch of the "repo-plugins" repository:

<pre>
git checkout gotham
</pre>

'''Note:''' If your addon already exist in repo, it must first be removed with:
<pre>
git rm -r plugin.my.addon/
</pre>

Now we use subtree merge to pull myaddon into the gotham branch of repo-plugins:
<pre>
git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
</pre>

To see the changes that are about to be committed:
<pre>
git diff --staged
</pre>

Finally, commit the changes:
<pre>
git commit -m "[plugin.my.addon] 1.0.1"
git push origin gotham
</pre>

You can now open a PR on Github.

'''Note:''' Remember to send the PR to the correct branch. If you have pushed to gotham branch, you should request pull to the gotham branch in repo.

=== Updating addon to a new version ===

Updating the addon is now easy. For this example we pull the master branch from myaddon:

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon master
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>

For more info about Subtree Merging see http://git-scm.com/book/en/v1/Git-Tools-Subtree-Merging

HOW-TO:Create add-on PRs using Git Subtree Merging

2014-12-02T10:44:33Z

Takoi: /* Guidelines */

== Guidelines ==
General [[Add-on rules]] apply. Additional rules 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"

As with mailing list, only PRs from add-on author will be accepted. Patches should be submitted upstream.

== Example git setup using Subtree merging ==

=== First time setup ===

Clone the XBMC addon repository:
<pre>
git clone git@github.com:xbmc/repo-plugins.git
cd repo-plugins
</pre>

For this example we will use an addon named "myaddon". Add the git repo where you addon resides as a remote:
<pre>
git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon
</pre>

Create a new branch for the addon:
<pre>
git checkout -b myaddon_branch myaddon/master
</pre>

The current directory should contain the files from the myaddon repository. To switch back to gotham branch of the "repo-plugins" repository:

<pre>
git checkout gotham
</pre>

'''Note:''' If your addon already exist in repo, it must first be removed with:
<pre>
git rm -r plugin.my.addon/
</pre>

Now we use subtree merge to pull myaddon into the gotham branch of repo-plugins:
<pre>
git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
</pre>

To see the changes that are about to be committed:
<pre>
git diff --staged
</pre>

Finally, commit the changes:
<pre>
git commit -m "[plugin.my.addon] 1.0.1"
git push origin gotham
</pre>

=== Updating addon to a new version ===

Updating the addon is now easy. For this example we pull the master branch from myaddon:

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon master
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>

For more info about Subtree Merging see http://git-scm.com/book/en/v1/Git-Tools-Subtree-Merging

HOW-TO:Create add-on PRs using Git Subtree Merging

2014-11-30T14:26:24Z

Takoi: Takoi moved page How to submit add-on and subsequent updates on Github to Submitting Add-on updates on Github: Martijn didn't like it:(

== Guidelines ==

== Example git setup using Subtree merging ==

=== First time setup ===

Clone the XBMC addon repository:
<pre>
git clone git@github.com:xbmc/repo-plugins.git
cd repo-plugins
</pre>

For this example we will use an addon named "myaddon". Add the git repo where you addon resides as a remote:
<pre>
git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon
</pre>

Create a new branch for the addon:
<pre>
git checkout -b myaddon_branch myaddon/master
</pre>

The current directory should contain the files from the myaddon repository. To switch back to gotham branch of the "repo-plugins" repository:

<pre>
git checkout gotham
</pre>

'''Note:''' If your addon already exist in repo, it must first be removed with:
<pre>
git rm -r plugin.my.addon/
</pre>

Now we use subtree merge to pull myaddon into the gotham branch of repo-plugins:
<pre>
git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
</pre>

To see the changes that are about to be committed:
<pre>
git diff --staged
</pre>

Finally, commit the changes:
<pre>
git commit -m "[plugin.my.addon] 1.0.1"
git push origin gotham
</pre>

=== Updating addon to a new version ===

Updating the addon is now easy. For this example we pull the master branch from myaddon:

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon master
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>

For more info about Subtree Merging see http://git-scm.com/book/en/v1/Git-Tools-Subtree-Merging

HOW-TO:Create add-on PRs using Git Subtree Merging

2014-11-30T14:22:18Z

Takoi:

HOW-TO:Create add-on PRs using Git Subtree Merging

2014-11-30T14:20:43Z

Takoi:

== Guidelines ==

== Example git setup using Subtree merging ==

=== First time setup ===

Clone the XBMC addon repository:
<pre>
git clone git@github.com:xbmc/repo-plugins.git
cd repo-plugins
</pre>

For this example we will use an addon named "myaddon". Add the git repo where you addon resides as a remote:
<pre>
git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon
</pre>

Create a new branch for the addon:
<pre>
git checkout -b myaddon_branch myaddon/master
</pre>

The current directory should contain the files from the myaddon repository. To switch back to gotham branch of the "repo-plugins" repository:

<pre>
git checkout gotham
</pre>

'''Note:''' If your addon already exist in repo, it must first be removed with:
<pre>
git rm -r plugin.my.addon/
</pre>

Now we use subtree merge to pull myaddon into the gotham branch of repo-plugins:
<pre>
git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
</pre>

To see the changes that are about to be committed:
<pre>
git diff --staged
</pre>

Finally, commit the changes:
<pre>
git commit -m "[plugin.my.addon] 1.0.1"
git push origin gotham
</pre>

=== Updating addon to a new version ===

Updating the addon is now easy. For this example we pull the master branch from myaddon:

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon master
git diff --staged
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>

For more info about Subtree Merging see http://git-scm.com/book/en/v1/Git-Tools-Subtree-Merging

HOW-TO:Create add-on PRs using Git Subtree Merging

2014-11-30T14:12:56Z

Takoi:

== Guidelines ==

== Example git setup using Subtree merging ==

<pre>
git clone git@github.com:xbmc/repo-plugins.git
cd repo-plugins
</pre>

For this example we will use an addon named "myaddon". Add the git repo where you addon resides as a remote:
<pre>
git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon
</pre>

Create a new branch for the addon:
<pre>
git checkout -b myaddon_branch myaddon/master
</pre>

The current directory should contain the files from the myaddon repository. To switch back to gotham branch of the "repo-plugins" repository:

<pre>
git checkout gotham
</pre>

'''Note:''' If your addon already exist in repo, it must first be removed with:
<pre>
git rm -r plugin.my.addon/
</pre>

Now we use subtree merge to pull myaddon into the gotham branch of repo-plugins:
<pre>
git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
</pre>

The see the changes that are about to be committed:
<pre>
git diff --staged
</pre>

Then commit the changes:
<pre>
git commit -m "[plugin.my.addon] 1.0.1"
</pre>

=== Pulling Updates ===

Updating the addon is now easy. For this example we pull the master branch from myaddon:

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon master
git diff --staged
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>

HOW-TO:Create add-on PRs using Git Subtree Merging

2014-11-30T13:59:47Z

Takoi:

== Guidelines ==

== Example git setup using Subtree merging ==

<pre>
git clone git@github.com:xbmc/repo-plugins.git
cd repo-plugins
</pre>

For this example we will use an addon named "myaddon". Add the git repo where you addon resides as a remote:
<pre>
git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon
</pre>

Create a new branch for the addon:
<pre>
git checkout -b myaddon_branch myaddon/master
</pre>

The current directory should contain the files from the myaddon repository. To switch back to gotham branch of the "repo-plugins" repository:

<pre>
git checkout gotham
</pre>

'''Note:''' If your addon already exist in repo, remove it with:
<pre>
git rm -r plugin.my.addon/
</pre>

Now we use subtree merge to pull myaddon into the gotham branch of repo-plugins:
<pre>
git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
</pre>

The see the changes that are about to be committed:
<pre>
git diff --staged
</pre>

Then commit the changes:
<pre>
git commit -m "[plugin.my.addon] 1.0.1"
</pre>

=== Pulling Updates ===

Updating the addon is now easy. For this example we pull the master branch from myaddon:

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon master
git diff --staged
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>

HOW-TO:Create add-on PRs using Git Subtree Merging

2014-11-30T13:32:59Z

Takoi: Created page with " == Guidelines == == Example git setup using Subtree merging == <pre> git clone git@github.com:xbmc/repo-plugins.git git remote add myaddon git@github.com:me/myaddon.git ..."

== Guidelines ==

== Example git setup using Subtree merging ==

<pre>
git clone git@github.com:xbmc/repo-plugins.git

git remote add myaddon git@github.com:me/myaddon.git
git fetch myaddon

git checkout -b myaddon_branch myaddon/master
git checkout gotham

First time setup if your addon already exist in repo:
git rm -r plugin.my.addon/

git read-tree --prefix=plugin.my.addon/ -u myaddon_branch
git diff --staged
git commit -m "[plugin.my.addon] 1.0.1"
</pre>

=== Updates ===

<pre>
git checkout gotham
git pull --strategy subtree --squash myaddon v1.0.2
git commit -m "[plugin.my.addon] 1.0.2"
git push origin gotham
</pre>