Add-on structure

From Official Kodi Wiki
Jump to navigation Jump to search
Home icon grey.png   ▶ Development ▶ Add-on development ▶ Add-on structure

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

Introduction

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

When installed, the whole add-on folder will be placed inside .kodi/addons/ (or .xbmc/addons/ for old XBMC-based releases).

Directory Name

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

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.

addon-type is one of the following:

Add-on Type Description Media Type Required?
repository A repository definition file that allows users to add new repositories to the Kodi addon manager. No
plugin A plugin script or module that adds to the functionality of Kodi. Plugins appear under the relevant media section of the main home menu. Yes
script A runnable program file that will appear in the Program section of the main home menu. Yes
skin An Kodi skin definition and its supporting script files. No
resource An addon that will provide additional files (language files, images, fonts, uisounds). No

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

Add-on Type Media Type Description
plugin audio A music add-on that will appear in the Music main menu.
plugin video A video add-on that will appear in the Video main menu.
plugin picture A picture add-on that will appear in the Pictures main menu.
plugin program A program add-on that will appear in the Add-ons main menu.
plugin weather A weather add-on that will appear in the Weather main menu. You can omit the Add-on Type in the directory name and addon-id
script module A script plugin that will not appear under a category or within the Add-ons manager, but provides support for other add-ons.
script service 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 plugin.audio.gpodder. If you are creating a screen scraper to present TV shows from MyGreatTv.com. It might be plugin.video.my-great-tv-com. A script to ping all your friends on twitter to tell them you are home might be called script.service.ping-twits-i-am-home.

Directory structure

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

Kodi v18 Leia and up

addon.py
addon.xml
LICENSE.txt
resources/
  settings.xml
  language/
  lib/
  data/
  media/
  fanart.jpg (can be placed anywhere in the addon directory)
  icon.png (can be placed anywhere in the addon directory)
  banner.jpg (optional - can be placed anywhere in the addon directory)
  clearlogo.png (optional - can be placed anywhere in the addon directory)
  screenshot-1.jpg (optional - can be placed anywhere in the addon directory)
  screenshot-2.jpg (optional - can be placed anywhere in the addon directory)
  screenshot-3.jpg (optional - can be placed anywhere in the addon directory)
  screenshot-4.jpg (optional - can be placed anywhere in the addon directory)

Kodi v17 Krypton and up

addon.py
addon.xml
LICENSE.txt
resources/
  settings.xml
  language/
  lib/
  data/
  media/
  fanart.jpg (can be placed anywhere in the addon directory)
  icon.png (can be placed anywhere in the addon directory)
  screenshot-1.jpg (optional - can be placed anywhere in the addon directory)
  screenshot-2.jpg (optional - can be placed anywhere in the addon directory)
  screenshot-3.jpg (optional - can be placed anywhere in the addon directory)
  screenshot-4.jpg (optional - can be placed anywhere in the addon directory)

Kodi v16 Jarvis and earlier

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

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

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

addon.xml

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

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

Stop hand.png Only addons for versions of Kodi below v17 Krypton must contain the icon.png file in the root of the addon directory. Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for resources/icon.png) and be listed in addon.xml assets


This is an icon used to represent your add-on in various parts of Kodi. See the icon.png specifications.

fanart.jpg

Stop hand.png Only addons for versions of Kodi below v17 Krypton must contain the fanart.jpg file in the root of the addon directory. Kodi 17 Krypton and above is able to use any other directory in the addon structure (preference for resources/fanart.jpg) and be listed in addon.xml assets


This helps to keep Kodi graphically rich when browsing and using add-ons. See the fanart.jpg specifications.

LICENSE.txt

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

resources/

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo file are missing from this folder. Try copying it from another addon.

resources/settings.xml

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

resources/icon.png

Note: Kodi v17 Krypton and later.

This is an icon used to represent your add-on in various parts of Kodi. Icon is a mandatory art type; "icon" must be listed in addon.xml assets. It can be placed anywhere in the addon directory structure (and named anything rather than icon.png) as long as the <icon> addon.xml asset points to the right file (resources/icon.png is just a recommendation/example).

Specifications

  • The icon size must be 256x256 pixels or 512x512 pixels.
  • File format is PNG.
  • Background must be 100% solid. That doesn't mean one color, it also can be a gradient or a low contrast texture. Just make sure there is no transparency.
  • Keep the logo as simple a possible, no exaggerated 3D effects or high contrast textures.
  • Use a padding of at least 25px for your logo (not the background!). Excepted are large text logos (see icon for themoviedb.org).
  • Keep text to a minimum. However, a text logo along with the graphical logo is recommended in order to easily recognize the addon.
  • Don't mix logos with Kodi's logo; it's obvious that we're talking about Kodi here.
  • Don't add borders or any overlays, that's the skinner's job. However, if borders are an element of your logo, make sure there is enough padding.
  • It is suggested that a logo on a plain background (non-transparent) is best in many situations (e.g. for addons that retrieve media from an online service, use that service's logo as long as you are free to do so).

resources/fanart.jpg

Note: Kodi v17 Krypton and later.

This helps to keep Kodi graphically rich when browsing and using add-ons. if this file exists, "fanart" must be listed in addon.xml assets. Fanart is almost all the time mandatory for plugins and scripts (exception for addons such as script.module). It can be placed anywhere in the addon directory structure (and named anything rather than fanart.jpg) as long as the <fanart> element in addon.xml asset points to the right file (resources/fanart.jpg is just a recommendation/example).

Specifications

  • It should be 16:9 aspect ratio
  • It is intended for the background, so should be simple and without text where reasonable.
  • Image must be 1MB or less
  • Image must be jpeg or png¹. ¹PNG can only be used with Krypton and later
  • Image must be 1280x720, 1920x1080 or 3840x2160
  • We recommend a 1280x720 image. It should certainly be no larger than 3840x2160.
  • We recommend keeping it as small as is reasonable with respect to file-size. Remember that hundreds of thousands of users are going to be downloading this.

resources/screenshot-x.jpg (optional)

Note: Kodi v17 Krypton and later. This optional art type helps to keep Kodi graphically rich when using the addon browser or the addon website. Addons can define up to 10 screenshots (4 is advised). This is accomplished through the repetition of the <screenshot> element of addon.xml assets each pointing to a different image. Screenshot images can be placed anywhere in the addon directory (and have any arbitrary name) as long as they point to an existing file in addon.xml assets. screenshot-x.png is just an example naming convention.

Specifications

  • Image must be in the jpeg or png formats sized 1280x720 or 1920x1080
  • Image must be 750KB or less
  • Image must have no transparency
  • Addons can include a maximum of 10 screenshots
  • If the addon includes screenshots, 4 is the recommended number of images to provide,

resources/banner.jpg (optional)

Note: Kodi v18 Leia and later. This optional art type helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "banner" must be listed in addon.xml assets. It can be placed anywhere in the addon directory structure as long as the <banner> addon.xml asset points to the right file (resources/banner.jpg is just a recommendation).

Specifications

  • Images must be in jpeg or png image formats sized 1000x185 pixels, no exceptions

resources/clearlogo.png (optional)

Note: Kodi v18 Leia and later. This optional art type helps to keep Kodi graphically rich when browsing and using add-ons for any skins implementing this art type in the skin views. if this file exists, "clearlogo" must be listed in addon.xml assets. It can be placed anywhere in the addon directory structure as long as the <clearlogo> addon.xml asset points to the right file (resources/clearlogo.png is just a recommendation).


Specifications

  • Image must be png format sized 400 x 155px (non-HD version) or 800 x 310px (HD version)
  • Image must have transparency


resources/language/

Translation tools:

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

Stop hand.png Strings.xml support was completely removed from v19 Matrix. Addons should update and comply to the strings.po file from now on.


resources/lib/

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

If you are having errors running the application (e.g. kodi.log shows addon.py isn't found) then a possible cause may be the __init__.pyo & __init__.py files are missing in this folder. Try copying it from another addon.

resources/data/

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

resources/media/

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

Getting started

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

See also

Development: