Official Kodi Wiki - User contributions [en]

HOW-TO:Script addon

2024-01-17T13:21:59Z

NahsiN: tutorial link points to python3 which is now default in kodi

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

This page will outline the basics of creating your first Python script for Kodi. It assumes you're at least familiar with the basics of Python. 
If not, we recommend visiting the [https://docs.python.org/3/tutorial/index.html Python tutorial] first, and then returning here.

While a python script can do many things, this tutorial is aimed at creating a window in Kodi.

= 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>script.my-addon</code>, this should be the same as your addon id. 
Once these are done, you can get started writing the actual code for your add-on!

The structure of our addon will look like this:

[[File:script_testwindow_structure.jpg]]

= The addon.xml file =
{{See also|Addon.xml}}

In the addon.xml file you define the (unique) id of your addon and the name of the addon. 
It will also tell Kodi what type of addon it is. Since we're going to create a script type addon, we need to set our extension point to 'xbmc.python.script'. 
Also define your python file in the 'library' field. This is the file Kodi will execute when you run your script.

This is what your addon.xml will need to look like (the bare minimum):
<syntaxhighlight lang=xml enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="script.testwindow" name="test window" version="0.0.1" provider-name="me">
<requires>
<import addon="xbmc.python" version="2.25.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">window demo script</summary>
<description lang="en_GB">a demo script to create a window</description>
<language></language>
<platform>all</platform>
</extension>
</addon>
</syntaxhighlight>

= Your default.py file =
:''See also: [https://codedocs.xyz/xbmc/xbmc/group__python.html '''kodi python api''']''

Your python code will look like this, please see the in-line comments for a full explanation of what each line does. 
Remember these are just the bare basics to get you started, many more options are available to enhance your window.

<syntaxhighlight lang=python enclose="div">
# import the kodi python modules we are going to use
# see the kodi api docs to find out what functionality each module provides
import xbmc
import xbmcgui
import xbmcaddon

# create a class for your addon, we need this to get info about your addon
ADDON = xbmcaddon.Addon()
# get the full path to your addon, decode it to unicode to handle special (non-ascii) characters in the path
CWD = ADDON.getAddonInfo('path').decode('utf-8')
#CWD = ADDON.getAddonInfo('path') # for kodi 19 and up..

# add a class to create your xml based window
class GUI(xbmcgui.WindowXML):
# [optional] this function is only needed of you are passing optional data to your window
def __init__(self, *args, **kwargs):
# get the optional data and add it to a variable you can use elsewhere in your script
self.data = kwargs['optional1']

# until now we have a blank window, the onInit function will parse your xml file
def onInit(self):
# select a view mode, '50' in our case, as defined in the skin file
xbmc.executebuiltin('Container.SetViewMode(50)')
# define a temporary list where we are going to add all the listitems to
listitems = []
# this will be the first item in the list. 'my first item' will be the label that is shown in the list
listitem1 = xbmcgui.ListItem('my first item')
# add this item to our temporary list
listitems.append(listitem1)
# let's create another item
listitem2 = xbmcgui.ListItem('my second item')
# and add it to the temporary list as well
listitems.append(listitem2)
# by default the built-in container already contains one item, the 'up' (..) item, let's remove that one
self.clearList()
# now we are going to add all the items we have defined to the (built-in) container
self.addItems(listitems)
# give kodi a bit of (processing) time to add all items to the container
xbmc.sleep(100)
# this puts the focus on the top item of the container
self.setFocusId(self.getCurrentContainerId())

# this is the entry point of your addon, execution of your script will start here
if (__name__ == '__main__'):
# define your xml window and pass these five arguments (more optional items can be passed as well):
# 1 'the name of the xml file for this window',
# 2 'the path to your addon',
# 3 'the name of the folder that contains the skin',
# 4 'the name of the folder that contains the skin xml files'
# 5 set to True for a media window (a single list window that will list music / videos / pictures), set to False otherwise
# 6 [optional] if you need to pass additional data to your window, simply add them to the list
# you'll have to add them as key=value pairs: key1=value1, key2=value2, etc...
ui = GUI('script-testwindow.xml', CWD, 'default', '1080i', True, optional1='some data')
# now open your window. the window will be shown until you close your addon
ui.doModal()
# window closed, now cleanup a bit: delete your window before the script fully exits
del ui

# the end!
</syntaxhighlight>

= Your script-testwindow.xml file =
{{See also|Skinning_Manual}}

This is the xml code for the window your script will open. Basically all you need to define is a container (list) which your script will fill with listitems. 
If you are using images in your xml file, put the inside the 'media' folder of your addon.

The subject of skinning is outside of the scope of this tutorial, so please refer for the kodi skinning manual for details.

<syntaxhighlight lang=xml enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<window>
<views>50</views>
<controls>
<control type="list" id="50">
<left>500</left>
<top>200</top>
<width>1000</width>
<height>500</height>
<viewtype label="535">list</viewtype>
<itemlayout height="100" width="1000">
<control type="label">
<left>20</left>
<top>0</top>
<height>50</height>
<width>960</width>
font13
<label>$INFO[ListItem.Label]</label>
</control>
</itemlayout>
<focusedlayout height="100" width="1000">
<control type="image">
<left>0</left>
<top>0</top>
<width>1000</width>
<height>50</height>
<texture>testwindow-focus.png</texture>
</control>
<control type="label">
<left>20</left>
<top>0</top>
<height>50</height>
<width>960</width>
font13
<label>$INFO[ListItem.Label]</label>
<textcolor>orange</textcolor>
</control>
</focusedlayout>
</control>
</controls>
</window>
</syntaxhighlight>

= Other options =

I'm sure you're familiar with the 'all roads lead to Rome' saying and, as such, there is another way to handle containers in your window. 
But, if you're happy with the way above... you can stop reading now.

Each python window has a built-in container (the one we used in the example above) but it is not mandatory to use the built-in container. 
you can also define your own container, and as many of them as you need.

Here's is an example of a window with two custom containers (only commenting on the differences to the example above):

<syntaxhighlight lang=python enclose="div">
import xbmc
import xbmcgui
import xbmcaddon

ADDON = xbmcaddon.Addon()
CWD = ADDON.getAddonInfo('path').decode('utf-8')

class GUI(xbmcgui.WindowXML):
def onInit(self):
# define two temporary lists where we are going to add our the listitems to
list1 = []
list2 = []
# create and add some items to the first temporary list
listitem1 = xbmcgui.ListItem('my first item')
list1.append(listitem1)
listitem2 = xbmcgui.ListItem('my second item')
list1.append(listitem2)
# create and add some items to the second temporary list
listitem3 = xbmcgui.ListItem('this is one item')
list2.append(listitem3)
listitem4 = xbmcgui.ListItem('this is another item')
list2.append(listitem4)
# now define your two containers, the id's refer to the container id's you use in your xml file
self.cont1 = self.getControl(100)
self.cont2 = self.getControl(200)
# add all the items in the first list to container 1
self.cont1.addItems(list1)
# and the items in the second list to container 2
self.cont2.addItems(list2)
xbmc.sleep(100)
# this puts the focus on the first listitem in the first container
self.setFocus(self.cont1)

if (__name__ == '__main__'):
# media windows only have one builtin list and we need two, therefor we're not using the built-in container, so do not set the fifth argument (it defaults to False)
ui = GUI('script-testwindow.xml', CWD, 'default', '1080p')
ui.doModal()
del ui
</syntaxhighlight>

The xml code you need for two containers looks like this:
<syntaxhighlight lang=xml enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<window>
<controls>
<control type="list" id="100">
...
</control>
<control type="list" id="200">
...
</control>
</controls>
</window>
</syntaxhighlight>

= Download =

You can download this test addon here: 
[https://gitlab.com/ronie/script.testwindow script.testwindow]

Syncing and sharing

2023-10-15T19:15:30Z

NahsiN:

{{mininav}}

== Sharing the library ==
This includes sharing video files, watched status, and some settings.

=== Local network ===

;[[Add-on:Emby for Kodi|Emby for {{kodi}}]]
:{{intro|Add-on:Emby for Kodi}}

;[https://jellyfin.org/docs/general/clients/kodi/#jellyfin-for-kodi Jellyfin for Kodi]
Similar to PlexKodiConnect, this add-on syncs metadata from your Jellyfin server into the local Kodi database

;[https://jellyfin.org/docs/general/clients/kodi/#jellycon Jellycon]
JellyCon behaves like a standard Kodi streaming add-on without touching Kodi's databases.

;[https://github.com/Conceiva/MezzmoKodiPlugin/wiki Mezzmo]
:Kodi client with Mezzmo backend server for sharing video, music and photos. Background automatic Mezzmo / Kodi database sync process, resume point / play count sharing, metadata, artwork and much more. Fully integrates with Kodi but totally friendly with other addons, Kodi data and local Kodi file shares.

;[[MySQL]]
:{{intro|MySQL}}
:{{#lst:MySQL|MariaDB}}

;[https://github.com/croneter/PlexKodiConnect PlexKodiConnect]
:Uses Plex server as a backend, integrating directly into the Kodi video database.

;[[Add-on:PleXBMC|PleXBMC]]
:Allows Kodi to play media from a Plex Media Server on Windows, Linux, Raspberry Pi, OSX and more.

;[[UPnP]]
:{{intro|UPnP}}

=== Over the internet ===
;[[Add-on:Emby for Kodi|Emby for {{kodi}}]]
:{{intro|Add-on:Emby for Kodi}}

;[https://jellyfin.org/docs/general/clients/kodi/#jellyfin-for-kodi Jellyfin for Kodi]
Similar to PlexKodiConnect, this his add-on syncs metadata from your Jellyfin server into the local Kodi database

;[https://jellyfin.org/docs/general/clients/kodi/#jellycon Jellycon]
JellyCon behaves like a standard Kodi streaming add-on without touching Kodi's databases.

;[https://github.com/Conceiva/MezzmoKodiPlugin/wiki Mezzmo]
:Share your video, music and photo media with a browser using Mezzmo. Interent or local library sharing. Fully integrated with Kodi.

;[[MySQL]]
:{{intro|MySQL}}
:{{#lst:MySQL|MariaDB}}

;[https://github.com/croneter/PlexKodiConnect PlexKodiConnect]
:Uses Plex server as a backend, integrating directly into the Kodi video database.

;[[Add-on:PleXBMC|PleXBMC]]
:Allows Kodi to play media from a Plex Media Server on Windows, Linux, Raspberry Pi, OSX and more.

== Files ==
* [[File sharing]]
* [[SMB]]
* [[UPnP]]

== Watched status ==
* [[Add-on:WatchedList]] - local backup/restore of watched list, but can be used with multiple devices.
* [[Add-on:Trakt]]
* [[Add-on:MyEpisodes]]
* [[Add-on:TVShow Time]]
* [[Add-on:MyEpisodeCalendar]]
* [[MySQL]]
* [https://github.com/4lb3rtO/service.nfo.watchedstate.updater Watched state updater add-on] - Update your watchedstate in the nfo files as soon as this happens in the library

== Beaming video, audio, and pictures ==
* [[AirPlay]]
* [[UPnP]] (aka DLNA)

== Pictures ==
* [[Add-on:iPhoto]]
* [[Add-on:Flickr]]

== Related topics ==
* [[Profiles]] - for using one Kodi install for multiple users
* [[Backup]] - this page includes info about copying settings from one device to another, in addition to general backup info.

{{Updated|16}}
[[Category:Manual]]

Syncing and sharing

2023-10-15T19:15:08Z

NahsiN: Add Jellyfin addons to the page and improve spacing

{{mininav}}

== Sharing the library ==
This includes sharing video files, watched status, and some settings.

=== Local network ===

;[[Add-on:Emby for Kodi|Emby for {{kodi}}]]
:{{intro|Add-on:Emby for Kodi}}

;[https://jellyfin.org/docs/general/clients/kodi/#jellyfin-for-kodi Jellyfin for Kodi]
Similar to PlexKodiConnect, this his add-on syncs metadata from your Jellyfin server into the local Kodi database

;[https://jellyfin.org/docs/general/clients/kodi/#jellycon Jellycon]
JellyCon behaves like a standard Kodi streaming add-on without touching Kodi's databases.

;[https://github.com/Conceiva/MezzmoKodiPlugin/wiki Mezzmo]
:Kodi client with Mezzmo backend server for sharing video, music and photos. Background automatic Mezzmo / Kodi database sync process, resume point / play count sharing, metadata, artwork and much more. Fully integrates with Kodi but totally friendly with other addons, Kodi data and local Kodi file shares.

;[[MySQL]]
:{{intro|MySQL}}
:{{#lst:MySQL|MariaDB}}

;[https://github.com/croneter/PlexKodiConnect PlexKodiConnect]
:Uses Plex server as a backend, integrating directly into the Kodi video database.

;[[Add-on:PleXBMC|PleXBMC]]
:Allows Kodi to play media from a Plex Media Server on Windows, Linux, Raspberry Pi, OSX and more.

;[[UPnP]]
:{{intro|UPnP}}

=== Over the internet ===
;[[Add-on:Emby for Kodi|Emby for {{kodi}}]]
:{{intro|Add-on:Emby for Kodi}}

;[https://jellyfin.org/docs/general/clients/kodi/#jellyfin-for-kodi Jellyfin for Kodi]
Similar to PlexKodiConnect, this his add-on syncs metadata from your Jellyfin server into the local Kodi database

;[https://jellyfin.org/docs/general/clients/kodi/#jellycon Jellycon]
JellyCon behaves like a standard Kodi streaming add-on without touching Kodi's databases.

;[https://github.com/Conceiva/MezzmoKodiPlugin/wiki Mezzmo]
:Share your video, music and photo media with a browser using Mezzmo. Interent or local library sharing. Fully integrated with Kodi.

;[[MySQL]]
:{{intro|MySQL}}
:{{#lst:MySQL|MariaDB}}

;[https://github.com/croneter/PlexKodiConnect PlexKodiConnect]
:Uses Plex server as a backend, integrating directly into the Kodi video database.

;[[Add-on:PleXBMC|PleXBMC]]
:Allows Kodi to play media from a Plex Media Server on Windows, Linux, Raspberry Pi, OSX and more.

== Files ==
* [[File sharing]]
* [[SMB]]
* [[UPnP]]

== Watched status ==
* [[Add-on:WatchedList]] - local backup/restore of watched list, but can be used with multiple devices.
* [[Add-on:Trakt]]
* [[Add-on:MyEpisodes]]
* [[Add-on:TVShow Time]]
* [[Add-on:MyEpisodeCalendar]]
* [[MySQL]]
* [https://github.com/4lb3rtO/service.nfo.watchedstate.updater Watched state updater add-on] - Update your watchedstate in the nfo files as soon as this happens in the library

== Beaming video, audio, and pictures ==
* [[AirPlay]]
* [[UPnP]] (aka DLNA)

== Pictures ==
* [[Add-on:iPhoto]]
* [[Add-on:Flickr]]

== Related topics ==
* [[Profiles]] - for using one Kodi install for multiple users
* [[Backup]] - this page includes info about copying settings from one device to another, in addition to general backup info.

{{Updated|16}}
[[Category:Manual]]