About Add-ons: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
m (Krypton and grammatical corrections)
(→‎PyDocs: Removed links that were pointing to pages with no contents.)
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{mininav|[[Development]]|[[Add-on development]]}}
{{mininav|[[Development]]|[[Add-on development]]}}


{{cleanup}}


'''About'''
== About Addons ==


Kodi Add-ons are extensions that can be run from inside the Kodi GUI. They are usually written by third party developers and published to our official repository. Add-ons can also be published in other repositories or as stand alone zip files anywhere on the internet. Examples of Add-ons include video website streams, scrapers, skins and scripts.
Kodi Add-ons are extensions that can be run from inside the Kodi GUI. They are usually written by third party developers and published to our official repository. Add-ons can also be published in other repositories or as stand alone zip files anywhere on the internet. Examples of Add-ons include video website streams, scrapers, skins and scripts.


Kodi Add-ons are typically written in python.
Add-ons should work with the latest Krypton Release. Each time a new version of Kodi is released we add new features which may lead to a break compatibility. It is up to the author to update their add-on to remain compatible.
== Addon system using python ==
Kodi includes a built-in [http://en.wikipedia.org/wiki/Python_%28programming_language%29 Python interpreter] that allows users to develop add-ons (scripts and plugins) that interface easily and cleanly with the Kodi dashboard. These add-ons can extend the functionality of Kodi without requiring extensive programming experience or ability. While you may not feel comfortable browsing the Kodi source code and submitting patches (or even bug reports), you can learn how to write a script or plugin with just a few hours' practice, using the information available in these pages.
This page is intended as an introduction to Kodi Python for new developers, and a quick reference for more experienced programmers. If you're not interested in programming, you might want to visit [[Add-ons|this page]] for information about installing and using Python add-ons as an end user. If you're already familiar with Kodi Python, you can probably skip on down to the [[Python Development#Environment details|environment details]] or the [[Python Development#Resource links|resource links]] below for quick reference material.
== PyDocs ==
The very latest Kodi python API documentation "''PyDocs''" with classes and functions is automatically generated from XBMC's source code and can be found here (not all functions are available in previous versions): https://codedocs.xyz/xbmc/xbmc/group__python.html (for Kodi 17.x Krypton and onwards)
== Python plugins versus scripts ==
Please do not confuse "Plugins" and "Scripts". It is '''very''' important to understand the difference between them before you start coding your addon.
Unlike Scripts (which can basically perform any action), Plugins do not really provide new functionality to Kodi, instead what they do is provide
a directory listing (for instance, like your movie library) to Kodi. This listing can contain folders as well as files. When a user clicks on a folder,
kodi will run the plugin again to retrieve another listing. If a file is clicked, kodi will either play the file directly or call the addon to retrieve a playable url.
Another difference is that scripts can create their own gui (skin) while plugins can't. Plugin listings are presented in the current skin.
Do not try to mix and match script and plugin functionality as that will only give you weird error messages.
== Script development ==
If you're new to Python programming (or just new to Kodi Python), the easiest way to get started is with a script. The traditional Hello World program, written as an Kodi Python script, would look like this:
<pre><nowiki>print("Hello World!")</nowiki></pre>
That's the same code you would enter at the Python command line, because Kodi runs a full-featured, standard Python interpreter (for more information concerning the current version number and included modules see the [[#Environment details|environment details]] below). If you're already familiar with Python programming, the only new challenge is learning the [[#PyDocs|custom modules]] that allow you to gather information from Kodi and manipulate the Graphical User Interface (GUI).
There are some excellent tutorials available to introduce you to Kodi scripting (and Python in general). See the [[HOW-TO write Python Scripts|HOW-TO]] included in the Kodi Online Manual, or visit Alexpoet's Kodi Scripting site for a popular beginner's tutorial (PDF).
== Plugin development ==
While scripts offer you flexibility and full control over the Kodi GUI, plugins allow you to quickly and consistently present information to the user through the standard Kodi menu structure.
When a user launches a plugin, the plugin generates a list of menu items and hands them to Kodi to draw on the screen (regardless of screen resolution, skin, or any other user setting). While plugin developers lose some amount of control over the presentation, they no longer have to make up their own UIs, or worry about creating a usable look and feel across multiple displays.
Plugins are most commonly used to scrape websites for links to streaming videos, displaying the video list in Kodi just like it would movie files on the local hard drive.
== Resource links ==
While the three custom libraries give you control over the Kodi GUI, you'll eventually want to be able to interact with other parts of the system. Much of Kodi's functionality is exposed to Python, one way or another. These are some of the systems you can use to make your Python add-ons more useful.
=== Must read ===
A must read for developers is [http://www.python.org/dev/peps/pep-0008/ style guide] for writing python.
This contains the do's and dont's when starting to write code.
=== List of built-in functions ===
You can call any of the Kodi Built-in Commands using the function xbmc.executebuiltin().
[[List of Built In Functions]]
=== Kodi databases (media metadata libraries) ===
Kodi uses [[Music Library|Music]] and [[Video Library|Video]] Libraries, stored in a SQL (SQLite) database, to store massive amounts of additional meta data concerning local media files (assuming the user has enabled the libraries and chosen the right Content and scraper for each of his sources). Although there's no direct access from Python to the Kodi Database, you can gain access to the databases from Python through the [[JSON RPC]]. Read more about that [[The Kodi Database#Accessing the Databases with Kodi Python|here]].
{{tip|See [[Databases]] for database layout}}
=== InfoLabels ===
Kodi uses InfoLabels to display media file information (such as Artist and Album for a song, or Title and Cast list for a movie or TV show). This information shows up in the browsing menu (when using Library Mode), as well as in the Now Playing details when the media player is active.
You can get the currently-playing InfoLabel using the getInfoLabel function in xbmc. You can also set the InfoLabel information for any menu items you create in a plugin, making a much more versatile user experience.
{{see|InfoLabels}}
=== Other python pages ===
There are several other pages in the Kodi Online Manual dedicated to Python development. You can find a comprehensive list by clicking "Python" in the Categories list at the bottom of any Python page.
Definitely check out following pages with tons of great sample code.
* [[HOW-TO write Python Scripts]]
* [[HOW-TO:Write_Python_Scripts_for_XBMC]]


* [[HOW-TO write plugins for XBMC]]


* [[HOW-TO:Upgrade Python interpreter on Linux]]


'''Language'''
* [[HOW-TO:Debug Python Scripts with Eclipse|HOW-TO:Debug_Python_Scripts_with_Eclipse]]


Kodi Add-ons are typically written in python.
* [[HOW-TO:HelloWorld_addon]]
 
* [[HOW-TO:DebugAndDevelopPythonScriptsWithVisualStudio|HOW-TO:Debug and Develop Python Scripts with Visual Studio]]
 
* [[HOW-TO:Debug Python Scripts with Web-PDB]]
 
* [[Script Lyrics]]
 
* [[Script Sources]]
 
* [[Add-on unicode paths]]
 
Need to clean this up:
 
* [http://forum.kodi.tv/showthread.php?tid=99082| GUIDE HOW TO ADD A LOGIN FUNCTION TO YOUR ADDON]
 
* [http://passion-xbmc.org/index.php?page=python Passion list of pydocs]
 
* [http://translate.google.com/translate?hl=en&sl=auto&tl=en&u=http%3A%2F%2Fpassion-xbmc.org%2Fdocumentation-python%2Fcode-snippet-%28exemples%29%2F|Code Snippet]
 
* [http://forum.kodi.tv/showthread.php?tid=100167 python interface for google's JSON api]
 
* [http://forum.kodi.tv/showthread.php?tid=129401 addons_xml_generator.py for repository owners]
 
* [http://forum.kodi.tv/showthread.php?tid=36900 Tips for coding python scripts / plugins compatible with Linux, Mac, Windows AND Xbox]
 
* [http://forum.kodi.tv/showthread.php?tid=24839 WindowXML GUI Toolkit (replaces GUIBuilder for Kodi python scripts for GUI coding)]
 
* [http://forum.kodi.tv/showthread.php?tid=29577 HOW-TO write GUI settings for Kodi python plugins and scripts (addons)]
 
'''General Python Info:'''
 
* http://www.python.org/doc/
 
* http://www.diveintopython.net/toc/index.html
 
* http://pound-python.org/
 
* http://stackoverflow.com/questions/tagged/python
 
* http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html#id10
 
 
'''A few useful libs for scraping websites:'''
 
* http://pypi.python.org/pypi/simplejson/ (included in py2.6 + )
 
* http://effbot.org/zone/pythondoc-elementtree-ElementTree.htm (included in py2.6 + )
 
* http://www.crummy.com/software/BeautifulSoup/
 
* http://www.feedparser.org/
 
* http://wwwsearch.sourceforge.net/mechanize/
 
* http://wwwsearch.sourceforge.net/ClientForm/
 
== Environment details ==
{{see also|HOW-TO:Upgrade Python interpreter on Linux}}
 
Kodi comes with Python 2.7


== Migration to Python 3 ==


[[Migration to Python 3]]


== Out of Date ==
:With the release of Eden 11.0, some functions are out of date. Please view http://kodi.wiki/view/Eden_API_changes for the latest on incorporating Python scripts.
:With the release of Frodo 12.0, some functions are out of date. Please view http://kodi.wiki/view/Frodo_API_changes for the latest on incorporating Python scripts.
:With the release of Gotham 13.0, some functions are out of date. Please view http://kodi.wiki/view/Gotham_API_changes for the latest on incorporating Python scripts.
:With the release of Helix 14.0, some functions are out of date. Please view http://kodi.wiki/view/Helix_API_changes for the latest on incorporating Python scripts.
:With the release of Isengard 15.0, some functions are out of date. Please view http://kodi.wiki/view/Isengard_API_changes for the latest on incorporating Python scripts.
:With the release of Jarvis 16.0, some functions are out of date. Please view http://kodi.wiki/view/Jarvis_API_changes for the latest on incorporating Python scripts.


'''Compatibility'''
== See also ==
* [[Add-ons]]
* [[:Category:All add-ons]]
* [[Unofficial add-on repositories]]
'''Development:'''
* [[Add-on development]]
* [[Skinning]]
* [[Add-on repositories]]
* [[Official add-on repository]]


Add-ons should work with the latest Krypton Release. Each time a new version of Kodi is released we add new features which may lead to a break compatibility. It is up to the author to update their add-on to remain compatible.
[[Category:Add-on development]]
[[Category:Development]]
[[Category:Python]]

Revision as of 21:43, 14 January 2019

Home icon grey.png   ▶ Development ▶ Add-on development ▶ About Add-ons
Cleanup.png This page or section may require cleanup, updating, spellchecking, reformatting and/or updated images. Please improve this page if you can. The discussion page may contain suggestions.


About Addons

Kodi Add-ons are extensions that can be run from inside the Kodi GUI. They are usually written by third party developers and published to our official repository. Add-ons can also be published in other repositories or as stand alone zip files anywhere on the internet. Examples of Add-ons include video website streams, scrapers, skins and scripts.

Kodi Add-ons are typically written in python.

Add-ons should work with the latest Krypton Release. Each time a new version of Kodi is released we add new features which may lead to a break compatibility. It is up to the author to update their add-on to remain compatible.

Addon system using python

Kodi includes a built-in Python interpreter that allows users to develop add-ons (scripts and plugins) that interface easily and cleanly with the Kodi dashboard. These add-ons can extend the functionality of Kodi without requiring extensive programming experience or ability. While you may not feel comfortable browsing the Kodi source code and submitting patches (or even bug reports), you can learn how to write a script or plugin with just a few hours' practice, using the information available in these pages.

This page is intended as an introduction to Kodi Python for new developers, and a quick reference for more experienced programmers. If you're not interested in programming, you might want to visit this page for information about installing and using Python add-ons as an end user. If you're already familiar with Kodi Python, you can probably skip on down to the environment details or the resource links below for quick reference material.

PyDocs

The very latest Kodi python API documentation "PyDocs" with classes and functions is automatically generated from XBMC's source code and can be found here (not all functions are available in previous versions): https://codedocs.xyz/xbmc/xbmc/group__python.html (for Kodi 17.x Krypton and onwards)

Python plugins versus scripts

Please do not confuse "Plugins" and "Scripts". It is very important to understand the difference between them before you start coding your addon. Unlike Scripts (which can basically perform any action), Plugins do not really provide new functionality to Kodi, instead what they do is provide a directory listing (for instance, like your movie library) to Kodi. This listing can contain folders as well as files. When a user clicks on a folder, kodi will run the plugin again to retrieve another listing. If a file is clicked, kodi will either play the file directly or call the addon to retrieve a playable url.

Another difference is that scripts can create their own gui (skin) while plugins can't. Plugin listings are presented in the current skin.

Do not try to mix and match script and plugin functionality as that will only give you weird error messages.

Script development

If you're new to Python programming (or just new to Kodi Python), the easiest way to get started is with a script. The traditional Hello World program, written as an Kodi Python script, would look like this:

print("Hello World!")

That's the same code you would enter at the Python command line, because Kodi runs a full-featured, standard Python interpreter (for more information concerning the current version number and included modules see the environment details below). If you're already familiar with Python programming, the only new challenge is learning the custom modules that allow you to gather information from Kodi and manipulate the Graphical User Interface (GUI).

There are some excellent tutorials available to introduce you to Kodi scripting (and Python in general). See the HOW-TO included in the Kodi Online Manual, or visit Alexpoet's Kodi Scripting site for a popular beginner's tutorial (PDF).

Plugin development

While scripts offer you flexibility and full control over the Kodi GUI, plugins allow you to quickly and consistently present information to the user through the standard Kodi menu structure.

When a user launches a plugin, the plugin generates a list of menu items and hands them to Kodi to draw on the screen (regardless of screen resolution, skin, or any other user setting). While plugin developers lose some amount of control over the presentation, they no longer have to make up their own UIs, or worry about creating a usable look and feel across multiple displays.

Plugins are most commonly used to scrape websites for links to streaming videos, displaying the video list in Kodi just like it would movie files on the local hard drive.

Resource links

While the three custom libraries give you control over the Kodi GUI, you'll eventually want to be able to interact with other parts of the system. Much of Kodi's functionality is exposed to Python, one way or another. These are some of the systems you can use to make your Python add-ons more useful.

Must read

A must read for developers is style guide for writing python. This contains the do's and dont's when starting to write code.


List of built-in functions

You can call any of the Kodi Built-in Commands using the function xbmc.executebuiltin().

List of Built In Functions

Kodi databases (media metadata libraries)

Kodi uses Music and Video Libraries, stored in a SQL (SQLite) database, to store massive amounts of additional meta data concerning local media files (assuming the user has enabled the libraries and chosen the right Content and scraper for each of his sources). Although there's no direct access from Python to the Kodi Database, you can gain access to the databases from Python through the JSON RPC. Read more about that here.

Tip Tip: See Databases for database layout

InfoLabels

Kodi uses InfoLabels to display media file information (such as Artist and Album for a song, or Title and Cast list for a movie or TV show). This information shows up in the browsing menu (when using Library Mode), as well as in the Now Playing details when the media player is active.

You can get the currently-playing InfoLabel using the getInfoLabel function in xbmc. You can also set the InfoLabel information for any menu items you create in a plugin, making a much more versatile user experience.

See: InfoLabels

Other python pages

There are several other pages in the Kodi Online Manual dedicated to Python development. You can find a comprehensive list by clicking "Python" in the Categories list at the bottom of any Python page. Definitely check out following pages with tons of great sample code.

Need to clean this up:

General Python Info:


A few useful libs for scraping websites:

Environment details

Kodi comes with Python 2.7

Migration to Python 3

Migration to Python 3

Out of Date

With the release of Eden 11.0, some functions are out of date. Please view http://kodi.wiki/view/Eden_API_changes for the latest on incorporating Python scripts.
With the release of Frodo 12.0, some functions are out of date. Please view http://kodi.wiki/view/Frodo_API_changes for the latest on incorporating Python scripts.
With the release of Gotham 13.0, some functions are out of date. Please view http://kodi.wiki/view/Gotham_API_changes for the latest on incorporating Python scripts.
With the release of Helix 14.0, some functions are out of date. Please view http://kodi.wiki/view/Helix_API_changes for the latest on incorporating Python scripts.
With the release of Isengard 15.0, some functions are out of date. Please view http://kodi.wiki/view/Isengard_API_changes for the latest on incorporating Python scripts.
With the release of Jarvis 16.0, some functions are out of date. Please view http://kodi.wiki/view/Jarvis_API_changes for the latest on incorporating Python scripts.

See also

Development: