Official add-on repository: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
 
(22 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{mininav|[[Development]]|[[Add-on development]]}}
{{Mininav|[[Development]]|[[Add-on development]]}}<br />
<br />
XBMC includes an interface to browse remote [http://en.wikipedia.org/wiki/Software_repository repositories] from where add-ons can be retrieved. The model is similar to the way many current [http://en.wikipedia.org/wiki/Linux Linux] [http://en.wikipedia.org/wiki/Linux_distribution distributions] work, whereby there is a main repository that is the default, and additional ones may be added by the user. XBMC has two official repositories that are included by default (''XBMC.org Add-ons'' and ''XBMC.org PVR Add-ons'') and are maintained by the  [[Team XBMC|XBMC team]] (''Team XBMC''). This page outlines how to submit your add-on to the official repositories and keep it up to date.<br />


Kodi includes an interface to browse remote [[wikipedia:Software repository|software repositories]] from which a wide array of add-ons can be installed to provide new features or enhance existing ones. The model is similar to the way many current [[wikipedia:Linux|Linux]] [[wikipedia:Linux distribution|distributions]] work, whereby there is a carefully curated main repository enabled by default during installation and more may then be added by the user. Kodi has two official repositories that are included by default: ''Kodi.tv Add-ons'' and ''Kodi.tv PVR Add-ons'', both maintained by [[Archive:Team Kodi|Team Kodi]]. This page outlines how to submit an add-on for initial inclusion in the official repositories and how to update it once accepted.
== List of add-ons ==
{{Main|:Category:All add-ons|l1=All Add-ons category}}


== The repositories ==
== The repositories ==
=== General add-ons ===
Browsing add-ons can be done from within Kodi through the built-in [[add-ons]] browser. From here you can install any add-on that is listed in the [[Official add-on repository|Kodi.tv official repository]]. They are structured so each [[Releases|codenamed release]] accesses only the add-ons that are compatible with that specific version. Manual installation of add-ons from a [[wikipedia:Zip (file format)|zip archive file]] is also possible, but at that point it becomes <span style="text-decoration: underline;">the user's responsibility</span> to verify that they are compatible with the Kodi release being used.


=== XBMC.org Add-ons ===
Kodi uses the [[wikipedia:Git (software)|Git]] [[wikipedia:Version control|version control system]] to manage the official repositories. The list below details their organizational structures. The Git commands following each link will download a copy of that repository for you to use in creating a changeset which adds your prospective add-on to it. The changeset is what is needed to propose a new add-on for inclusion in the official repositories, for which the submission and subsequent review takes the form of a Git [[wikipedia:Pull request|pull request]].
 
{| style="margin-left: 2em;"
Browsing add-ons can be done from within XBMC through the built-in [[add-ons]] browser. From here you can install any add-on that is listed in the XBMC.org official repository.  
  | style="text-align: right;" | '''[https://github.com/xbmc/repo-plugins Plugins]:'''
For the time being each version of XBMC will have its own repo which contain only add-ons that are compatible with that specific version of XBMC. Manually installing add-ons is possible but remember to check if these are compatible for your XBMC version.
   | <kbd style="background-color: #f4f4f4; border: 1px solid #ddd; border-left: 4px solid #e04a2a; border-radius: 5px; color: #333; margin: 1em 0; padding: 2px 0.8em;">git clone <nowiki>https://github.com/xbmc/repo-plugins.git</nowiki></kbd>
 
  |-
XBMC uses [http://en.wikipedia.org/wiki/Git_(software) Git] to manage the official repository. See below for the list of git repositories that comprise it. This information is only useful for ''Team XBMC'' members who have repository pushing rights. You should not do any pull requests using these repositories. This is merely for information purpose only.
   | style="text-align: right;" | '''[https://github.com/xbmc/repo-scrapers Scrapers]:'''
 
   | <kbd style="background: #f4f4f4; color: #333; border: 1px solid #ddd; border-left: 4px solid #e04a2a; border-radius: 5px; padding: 2px 0.8em; margin: 1em 0">git clone <nowiki>https://github.com/xbmc/repo-scrapers.git</nowiki></kbd>
   git clone ssh://''sourceforge_username''@git.code.sf.net/p/xbmc/plugins
  |-
   git clone ssh://''sourceforge_username''@git.code.sf.net/p/xbmc/scrapers
  | style="text-align: right;" | '''[https://github.com/xbmc/repo-scripts Scripts]:'''
   git clone ssh://''sourceforge_username''@git.code.sf.net/p/xbmc/screensavers
   | <kbd style="background: #f4f4f4; color: #333; border: 1px solid #ddd; border-left: 4px solid #e04a2a; border-radius: 5px; padding: 2px 0.8em; margin: 1em 0">git clone <nowiki>https://github.com/xbmc/repo-scripts.git</nowiki></kbd>
   git clone ssh://''sourceforge_username''@git.code.sf.net/p/xbmc/scripts
   |-
   git clone ssh://''sourceforge_username''@git.code.sf.net/p/xbmc/skins
  | style="text-align: right;" | '''[https://github.com/xbmc/repo-skins Skins]:'''
   git clone ssh://''sourceforge_username''@git.code.sf.net/p/xbmc/visualizations
   | <kbd style="background: #f4f4f4; color: #333; border: 1px solid #ddd; border-left: 4px solid #e04a2a; border-radius: 5px; padding: 2px 0.8em; margin: 1em 0">git clone <nowiki>https://github.com/xbmc/repo-skins.git</nowiki></kbd>
   git clone ssh://''sourceforge_username''@git.code.sf.net/p/xbmc/webinterfaces
  |-
  | style="text-align: right;" | '''[https://github.com/xbmc/repo-webinterfaces Web Interfaces]:'''
   | <kbd style="background: #f4f4f4; color: #333; border: 1px solid #ddd; border-left: 4px solid #e04a2a; border-radius: 5px; padding: 2px 0.8em; margin: 1em 0">git clone <nowiki>https://github.com/xbmc/repo-webinterfaces.git</nowiki></kbd>
  |}


All current add-ons can be downloaded as ZIP files from the [http://mirrors.xbmc.org/addons/ repository server].
All current add-ons can be downloaded as ZIP files from the [https://mirrors.kodi.tv/addons/ repository server]. Feel free to see which ones there are and perhaps you they might give you some ideas for creating your own. These are also great examples for getting started and see how things are done in more extensive add-ons.
Feel free to see which ones there are and perhaps you they might give you some ideas for creating your own. These are also great examples for getting started and see how things are done in more extensive add-ons.


=== XBMC.org PVR Add-ons ===
=== PVR add-ons ===
 
:{{Main|PVR}}
For more info on PVR see here: [[PVR]]


=== Repo Branches ===
=== Repo Branches ===
For each version of XBMC there will be a specific branch of the XBMC.org add-on repository. As development progresses for the next version of XBMC, a repository for that next version will also be made. These repositories are automatically selected depending on which version of XBMC (stable or development) that the user is using. When the development XBMC repository is open we ask that add-on developers still maintain versions of their add-ons for the stable XBMC repository until that next development version of XBMC is released and becomes the new stable. When both repositories are open add-on developers will need to follow submission and update procedures individually to be in both. It is highly recommended to take advantage of the development XBMC repository so that your add-on is prepared for the next version of XBMC.
For each version of Kodi there will be a specific branch of the Kodi add-on repository. As development progresses for the next version of Kodi, a repository for that next version will also be made. These repositories are automatically selected depending on which version of Kodi (stable or development) that the user is using. When the development Kodi repository is open we ask that add-on developers still maintain versions of their add-ons for the stable Kodi repository until that next development version of Kodi is released and becomes the new stable. When both repositories are open add-on developers will need to follow submission and update procedures individually to be in both. It is highly recommended to take advantage of the development Kodi repository so that your add-on is prepared for the next version of Kodi.
 
== Repository Submission Guidelines - Please Read Before Submitting Your Addon ==
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 copyleft licenses will suffice.
* 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 or skins will be allowed.
* You acknowledge that you are the maintainer of your addon, but the XBMC team reserves the right to update or remove it at any time as we deem necessary.
* If a new stable XBMC 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 12.0 no updates are allowed for 10.1 any more).
* Add-ons that contain advertising will not be allowed
 
=== 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. 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 per month is probably a better goal, barring unforeseen conditions (like a content source changing its paths).
 
=== General requirements ===
 
* 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 filesystems.
* All paths and files should be lower-case due to the previous point (except for README / COPYING / LICENSE.txt that should be upper-case).
* The following file-types are not allowed: .so .dll .pyo .exe .xbt .xpr Thumbs.db <binary files>
* All text files should use UNIX end-of-line
 
=== Requirements for skins ===
* 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.
 
* All skins must be 100% valid XML. You should validate your code before submitting. Windows users can use the Notepad++ plugin for this.
* Skins must not include any scripts or plugins. If you need a script, submit it separately and depend on it.
* Any themes must be in a subfolder of the themes/ in the skin root. This is to ensure that TexturePacker picks them up correctly.
* Due to a bug in TexturePacker, all graphics files should have a resolution of at least 4x4.
* All paths should be treated as case-sensitive, so that they work on all OSs and filesystems.
* 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.
* All skins starting with Frodo must have a fanart.jpg included in the root dir. This must be a 1280x720 or 1920x1080 sized jpeg image.
* All skins starting with Eden must have a _screenshots folder included in the root dir and filled with 5-10 reasonably sized 1280x720 jpeg screenshots. For ex: skin.sample/_screenshots/screenshot01.jpg
* Note that .xbt files will be generated automatically for skins so you do not include this in your request.
 
==== Optional support ====
 
This is optional and should not block inclusion in official repo.
 
* mouse support
* touchscreen support
* karaoke dialogs
* peripheral dialogs
* pvr support
 
 
==== Basic sanity checks ====
Here's a list of what basic sanity checks are done by repo maintainer on each submission.
 
'''Basic file checks:'''
 
* 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 (check your studio logos for corrupt filenames)
 
 
'''Things that must be included:'''
 
* addon.xml must contain correct and valid info / versioning
* LICENCE.txt must be present
* icon.png must be present (256x256)
* fanart.jpg must be present (1280x720 or 1920x1080)
* _screenshots folder must be present, containing max. 10 .jpg screenshots (1280x720)
 
 
'''Things that can't be included:'''
 
* no .xbt files
* no scripts included
* don't include unneeded files (.pdf, .doc, thumbs.db, etc...)
* no licensed fonts / background images / anything
 
 
'''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'
 
=== Requirements for scripts and plugins ===
* all .xml files must have xml declaration as header
* os.getcwd() is deprecated, please use getAddonInfo('path') instead
* all special:// paths should be translated using xbmc.translatePath("special://foo/bar")
* All scripts starting with Eden must have a fanart.jpg included in the root dir with a 1280x720 / 1920x1080 sized jpeg screenshot.
* Direct access to the XBMC database is '''not''' allowed. You must use [[JSON RPC]] for this.
* Directly using analytics (Google Analytics for example) from within addons is not allowed. This should be handled server side by using user-agent.
* Addons should store all their data in their own subfolder inside the addon_data directory. All access (read/write/delete) to any files outside this folder is '''not''' allowed. (exceptions to this rule my apply in very specific cases only, please contact us on the add-on mailing list if your addon needs access to external files/folders)
 
=== 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
* all .xml files must have xml declaration as header
 
== Submitting a Compliant Add-on to the XBMC.org Repo ==
 
After you have read the above repository guidelines and made sure your addon is compliant with them, you may begin the submission process using the following steps.
 
=== 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.
 
All pull requests should be sent to this list so that repo 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 XBMC 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 repo 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 development#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="wikitable" 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.
|}
 
=== 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 - frodo
 
 
{{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 XBMC 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|You have to do separate pull requests for each repository (Eden, Frodo/Gotham).}}


{{tip|At this moment Frodo and Gotham share the same repo so doing one request for Frodo/Gotham is enough.}}
== Submitting add-ons ==
:{{Main|Submitting Add-ons}}


== See also ==
== See also ==
* [[Add-ons]]
* [[Add-ons]]
* [[:Category:All add-ons]]
* [[:Category:All add-ons]]
* [[3rd party add-on repositories]]
* [[Unofficial add-on repositories]]
'''Development:'''
'''Development:'''
* [[Add-on development]]
* [[Add-on development]]
Line 209: Line 50:




[[Category:XBMC Manual]]
[[Category:Add-on development]]
[[Category:Add-ons]]
[[Category:Manual]]
[[Category:Team XBMC specific notes]]
[[Category:Repositories]]

Latest revision as of 08:26, 2 September 2022

Home icon grey.png   ▶ Development ▶ Add-on development ▶ Official add-on repository


Kodi includes an interface to browse remote software repositories from which a wide array of add-ons can be installed to provide new features or enhance existing ones. The model is similar to the way many current Linux distributions work, whereby there is a carefully curated main repository enabled by default during installation and more may then be added by the user. Kodi has two official repositories that are included by default: Kodi.tv Add-ons and Kodi.tv PVR Add-ons, both maintained by Team Kodi. This page outlines how to submit an add-on for initial inclusion in the official repositories and how to update it once accepted.

List of add-ons

The repositories

General add-ons

Browsing add-ons can be done from within Kodi through the built-in add-ons browser. From here you can install any add-on that is listed in the Kodi.tv official repository. They are structured so each codenamed release accesses only the add-ons that are compatible with that specific version. Manual installation of add-ons from a zip archive file is also possible, but at that point it becomes the user's responsibility to verify that they are compatible with the Kodi release being used.

Kodi uses the Git version control system to manage the official repositories. The list below details their organizational structures. The Git commands following each link will download a copy of that repository for you to use in creating a changeset which adds your prospective add-on to it. The changeset is what is needed to propose a new add-on for inclusion in the official repositories, for which the submission and subsequent review takes the form of a Git pull request.

Plugins: git clone https://github.com/xbmc/repo-plugins.git
Scrapers: git clone https://github.com/xbmc/repo-scrapers.git
Scripts: git clone https://github.com/xbmc/repo-scripts.git
Skins: git clone https://github.com/xbmc/repo-skins.git
Web Interfaces: git clone https://github.com/xbmc/repo-webinterfaces.git

All current add-ons can be downloaded as ZIP files from the repository server. Feel free to see which ones there are and perhaps you they might give you some ideas for creating your own. These are also great examples for getting started and see how things are done in more extensive add-ons.

PVR add-ons

Repo Branches

For each version of Kodi there will be a specific branch of the Kodi add-on repository. As development progresses for the next version of Kodi, a repository for that next version will also be made. These repositories are automatically selected depending on which version of Kodi (stable or development) that the user is using. When the development Kodi repository is open we ask that add-on developers still maintain versions of their add-ons for the stable Kodi repository until that next development version of Kodi is released and becomes the new stable. When both repositories are open add-on developers will need to follow submission and update procedures individually to be in both. It is highly recommended to take advantage of the development Kodi repository so that your add-on is prepared for the next version of Kodi.

Submitting add-ons

See also

Development: