>Martijn |
|
| (102 intermediate revisions by 19 users not shown) |
| Line 1: |
Line 1: |
| {{DevsHeader|'''XBMC Add-on development'''}} | | {{mininav|[[Development]]}} |
| {{frodo updated}}
| | [[File:Wiki logo.png|150px|link=|left]] |
| | <section begin="intro" />This area contains information, tutorials, and links for creating add-ons (and plug-ins) for Kodi.<section end="intro" /> |
|
| |
|
| This page summarizes the new addons system introduced in the Dharma release (v10) of XBMC.
| | {{-}} |
| | ---- |
| | {{huge|'''{{color|black|General}}'''}} |
| | {| width="100%" |
| | |- valign="top" |
| | | width="16%" align="center" | {{Main page icon|image=Nuvola apps kthememgr.png|link=About Add-ons}} |
| | | width="17%" align="center" | {{Main page icon|image=Administration.png|link=Add-on settings}} |
| | | width="16%" align="center" | {{Main page icon|image=Applications-development.png|link=Add-on structure|title=Add-on Structure}} |
| | | width="17%" align="center" | {{Main page icon|image=Tool-box-icon.png|link=Development Tools}} |
| | | width="18%" align="center" | {{Main page icon|image=Translation - Noun project 987.png|link=Language portal|title=Languages & Translations}} |
| | | width="16%" align="center" | {{Main page icon|image=60.jpg|link=Special protocol}} |
| | |} |
|
| |
|
| XBMC has introduced an addons system. This allows 3rd party developed enhancements to XBMC to be distributed to XBMC users direct from inside the XBMC interface.
| | ---- |
| | {{huge|'''{{color|black|Add-on Types}}'''}} |
| | {| width="100%" |
| | |- valign="top" |
| | | width="12.5%" align="center" | {{Main page icon|image=Nuvola apps kthememgr.png|link=Plugin sources}} |
| | | width="12.5%" align="center" | {{Main page icon|image=Misc-Misc-Box-icon.png|link=Add-on_repositories|title=Repository add-ons}} |
| | | width="12.5%" align="center" | {{Main page icon|image=Web-icon.png|link=Scrapers|title=Scraper add-ons}} |
| | | width="12.5%" align="center" | {{Main page icon|image=Applications-development.png|link=Script sources|title=Scripts}} |
| | | width="12.5%" align="center" | {{Main page icon|image=Administration.png|link=Script subtitles|title=Subtitle scripts}} |
| | | width="12.5%" align="center" | {{Main page icon|image=Gnome-system-run.png|link=Service add-ons}} |
| | | width="12.5%" align="center" | {{Main page icon|image=Weather_addon.png|link=Weather addons|title=Weather add-ons}} |
| | | width="12.5%" align="center" | {{Main page icon|image=UI_sounds.png|link=UI sounds add-ons}} |
| | |} |
|
| |
|
| The addons system is based on the plugin library [http://www.c-pluff.org c-pluff].
| | ---- |
| | {{huge|'''{{color|black|Tutorials}}'''}} |
|
| |
|
| | | {| width="100%" |
| | | |- valign="top" |
| ==Anatomy of an addon== | | | width="12.5%" align="center" | {{Main page icon|image=music-icon.png|link=HOW-TO:Audio_addon|title=Audio Tutorial}} |
| | | | width="12.5%" align="center" | {{Main page icon|image=context-menu-icon.png|link=Context_Item_Add-ons|title=Context Item Tutorial}} |
| Each add-on is kept in it's own folder, and is described via an XML file named addon.xml. In addition, some other files can also come with the add-on, namely icon.png, changelog.txt, and fanart.jpg. These are all optional, though we encourage you to at least have icon.png. All of these 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.
| | | width="12.5%" align="center" | {{Main page icon|image=Addons-icon.png|link=Audio-video_add-on_tutorial|title=General Add-on Tutorial}} |
| | | | width="12.5%" align="center" | {{Main page icon|image=Translation - Noun project 987.png|link=HOW-TO:HelloWorld_addon|title=Hello World Tutorial}} |
| | | | width="12.5%" align="center" | {{Main page icon|image=Screensaver-icon.png|link=HOW-TO:Screensaver_addon|title=Screensaver Tutorial}} |
| ===Directory Name=== | | | width="12.5%" align="center" | {{Main page icon|image=script-icon.png|link=HOW-TO:Script_addon|title=Script Tutorial}} |
| | | | width="12.5%" align="center" | {{Main page icon|image=Visualisation-icon.jpg|link=HOW-TO:Visualisation_addon|title=Visualisation Tutorial}} |
| Your directory name should follow this convention2;
| | | width="12.5%" align="center" | {{Main page icon|image=video-icon.png|link=HOW-TO:Video_addon|title=Video Addon Tutorial}} |
| <addonType>[.<mediaType>].<yourPluginName>
| | |} |
| | | ---- |
| The name parts are case sensitive and must be in lower case. The dot character separates each
| | {{huge|'''{{color|black|Advanced}}'''}} |
| name part – you can use further dot's to separate things in your plugin name if you wish,
| | {| width="100%" |
| alternatively you may use a hyphen (-). No other non-alphanumeric characters should be used.
| | |- valign="top" |
| | | | width="12.5%" align="center" | {{Main page icon|image=Unicode icon.jpg|link=Add-on unicode paths}} |
| The addonType is one from the following list
| | | width="12.5%" align="center" | {{Main page icon|image=501159.png|link=JSON-RPC API}} |
| | | | width="12.5%" align="center" | {{Main page icon|image=Book icon 1.png|link=Python_libraries|title=Kodi Python Libraries}} |
| {| class="wikitable" border="1" | | | width="12.5%" align="center" | {{Main page icon|image=Boolean_operation_icon.jpg|link=List of boolean conditions}} |
| ! Addon Type Name !! Description
| | | width="12.5%" align="center" | {{Main page icon|image=Apps-Brackets-B-icon.png|link=List of built-in functions}} |
| |- | | | width="12.5%" align="center" | {{Main page icon|image=shopping-list-generator-icon.png|link=InfoLabels|title=List of info labels}} |
| | repository || A repository definition file that allows users to add new repositories to | | | width="12.5%" align="center" | {{Main page icon|image=Web-pdb-icon.png|link=Python_debugging|title=Python Debugging}} |
| the XBMC addon manager. Media type is not required.
| | | width="12.5%" align="center" | {{Main page icon|image=Windowsicon.png|link=Window IDs|title=Window IDs}} |
| |- | |
| | plugin || A plugin script or module that adds to the functionality of XBMC. | |
| Plugins appear under the relevant media section of the main home menu.
| |
| |- | |
| | script || A runnable program file that will appear in the Program section of the | |
| main home menu.
| |
| |- | |
| | skin || An XBMC skin definition and its supporting script files. Media type is not required. | |
| |} | | |} |
|
| |
|
| The mediaType is not required in all cases. The following table describes the available
| | ---- |
| mediaTypes for the available addon types. Your addon may provide more than one mediaType if
| | {{huge|'''{{color|black|Publishing}}'''}} |
| you wish, whereby it will appear in more than one section. In most cases, however, a single
| | {| width="100%" |
| media type will suffice, and it may be preferable to have multiple addons each providing a single
| | |- valign="top" |
| media type rather than one addon that tries to do it all.
| | | width="25%" align="center" | {{Main page icon|image=Thumbs up font awesome.png|link=Add-on rules}} |
| | | | width="25%" align="center" | {{Main page icon|image=Upload-128.png|link=Submitting Add-ons}} |
| | | | width="25%" align="center" | {{Main page icon|image=Thumbnail-symbol-transparent.png|link=Official_add-on_repository|title=Official Add-on Repository}} |
| {| class="wikitable" border="1" | | | width="25%" align="center" | {{Main page icon|image=Box_icon.png|link=Unofficial add-on repositories|title=Third-party Add-on Repositories}} |
| ! Addon !! Media Type Name!! Description
| |
| |- | |
| | plugin || audio || A music addon that will appear in the main menu music | |
| |-
| |
| | plugin || video || A video addon that will appear in the main menu video | |
| |- | |
| | plugin || picture || A picture addon that will appear in the main menu picture | |
| |-
| |
| | plugin || weather || A weather addon that will appear in the main menu weather | |
| |-
| |
| | script || module || A script plugin that will not appear under a category or
| |
| within the Addons manager, but provides support for other
| |
| addons
| |
| |-
| |
| | script|| service || A script that will be run at either login or startup
| |
| |} | | |} |
| | ---- |
|
| |
|
|
| |
|
| See section on [[Add-on_development#addon.xml|addon.xml]] for further information
| | [[Category:Add-on development|*]] |
| | |
| The plugin name is up to you, but beware that others haven't used it before you.
| |
| So for instance, if you are creating an addon that integrates the Gpodder software with XBMC
| |
| for audio podcasts you might name your directory;
| |
| plugin.audio.gpodder-xbmc3
| |
| 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.ping-twits-i-am-home
| |
| Having settled on your name create the directory under the .xbmc/addons directory.
| |
| | |
| ==Directory structure==
| |
| | |
| Your directory contains all the resources needed to operate your addon. The directory must be
| |
| considered read-only and should not be used for storing intersession or transient data. Other
| |
| mechanisms are available to do that (more later.)
| |
| The directory must contain the follwing files and directories.
| |
| | |
| addon.py
| |
| addon.xml
| |
| changelog.txt
| |
| fanart.jpg
| |
| icon.png
| |
| LICENSE.txt
| |
| /resources
| |
| settings.xml
| |
| /language/
| |
| /lib/
| |
| /media/
| |
| | |
| Other files may be required to run your addon, if your addon becomes more complex.
| |
| It is also considered good practice to place various addon resources and support code modules in the /lib folder.
| |
| If those libs are more commonly used by different addons consider them to add as a separate script.module.foo
| |
| | |
| i.e. everything that shouldn't be in the root of your directory is considered a resource and should
| |
| be placed in that sub-directory or a sub-directory from /resources.
| |
| | |
| | |
| ===File contents===
| |
| | |
| ====addon.py====
| |
| | |
| This will contain your main addon python code. It may be named differently as you will define this python file in addon.xml as your main script file.
| |
| | |
| ====addon.xml====
| |
| | |
| The addon.xml tells XBMC
| |
| :*what the addon provides
| |
| :*what the addon relies on to work
| |
| :*what script to run when it is fired up (if it is meant to be started.)
| |
| | |
| More information on formatting can be found here: [[addon.xml]]
| |
| | |
| ====changelog.txt====
| |
| A text file that contains a description of each release change that you make to the system. This is
| |
| displayed in the XBMC addon installation/update system. 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 addons 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.)
| |
| resources/settings.xml
| |
| An XML file that contains the current configuration for the addon. If your addon has
| |
| configurable items that are set by the user, put them here. This file drives what the user sees
| |
| when they click on Addon settings for your addon in the various places in XBMC that it can
| |
| appear. You need do no coding to utilise this functionality
| |
| | |
| ====icon.png====
| |
| | |
| This used to to be displayed in various parts of XBMC.
| |
| In order to keep a coherent look and give the skinner a good idea how the icons of the add-ons look, we have defined the following rules:
| |
| | |
| * The icon size must be 256x256 pixels.
| |
| * File format is PNG.
| |
| * Background must be 100% solid. That doesn't mean one color, it also can be a gradient or a low contrast texture. Just make sure there is no transparency.
| |
| * Keep the logo as simple a possible, no exaggerated 3D effects or high contrast textures.
| |
| * Use a padding of at least 25px for your logo (not the background!). Excepted are large text logos (see icon for themoviedb.org).
| |
| * Keep text to a minimum. However, a text logo along with the graphical logo is recommended in order to easily recognize the addon.
| |
| * Don't mix logos with XBMC's logo, it's obvious that we're talking about XBMC here.
| |
| * Don't add borders or any overlays, that's the skinner's job. However, if borders are an element of your logo, make sure there is enough padding.
| |
| * It is suggested that a logo on a plain background (non-transparent) is best in many situations
| |
| (e.g. for addons that retrieve media from an online service, use that service's logo [as long as
| |
| you are free to do so]).
| |
| | |
| ====fanart.jpg====
| |
| This helps to keep XBMC graphically rich when browsing and using addons.
| |
| 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 JPG image. It should certainly be no larger than 1920x1080.
| |
| * We recommend keeping it as small as is reasonable with respect to file-size. Remember that hundreds of thousands of users are going to be downloading this.
| |
| | |
| ====/resources/settings.xml====
| |
| | |
| This contains the settings that will be available for your add-on. This file should be located in
| |
| /resources/settings.xml
| |
| | |
| See following link for all programmable options [[Addon_Settings]]
| |
| | |
| ====/resources/language/====
| |
| | |
| LANGUAGE THINGS
| |
| | |
| Translation tools:
| |
| *[[Language support]]
| |
| *[[Translation System]]
| |
| *Convert .xml to .po: [https://github.com/alanwww1/xbmc-xml2po xbmc-xml2po]
| |
| *Check for .po files: [https://github.com/alanwww1/xbmc-checkpo xbmc-checkpo]
| |
| *Utility for keeping XBMC upstream language files and the language files hosted on transifex.com in sync: [https://github.com/alanwww1/xbmc-txupdate xbmc-txupdate]
| |
| | |
| '''strings.po'''
| |
| | |
| {{frodo|raw=strings.xml will be deprecated after the release of Frodo. Frodo will still be back worths compatible with .xml}}
| |
| | |
| ====/resources/lib/====
| |
| | |
| Put any module definitions or third party software libraries into this directory
| |
| resources/data.
| |
| | |
| Store any other static data structures your application requires here. Examples might be
| |
| XLT/XSD files or static XML files that contain lookup tables etc.
| |
| | |
| ====/resources/media/====
| |
| | |
| store any static media (picture, audio, video etc.) files in this directory
| |
| Remember, the above is a recommended outline for your addon – if you need fewer or more
| |
| directories to organise your work, just change it. Like sins are addons that will require more directories than this.
| |
| | |
| ==See also==
| |
| * [[Add-ons]]
| |
| * [[:Category:All add-ons]]
| |
| * [[3rd party add-on repositories]]
| |
| '''Development:'''
| |
| * [[Addon Settings]]
| |
| * [[Python development]]
| |
| * [[Skinning]] | |
| * [[Add-on repositories]]
| |
| * [[Official add-on repository]]
| |
| | |
| [[Category:Add-ons]]
| |
| [[Category:Addon Development]]
| |
| [[Category:Skin Development]]
| |
| [[Category:Development]]
| |
Development
