|Development||Add-on development||HOW-TO:Script addon|
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 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.
1 Before we get started
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.
script.my-addon, 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:
2 The addon.xml file
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):
<?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>
3 Your default.py file
- See also: 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.
# 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') # 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): # 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) # now we are going to add all the items we have defined to the container self.addItems(listitems) # give kodi a bit of (processing) time to add all items to the list 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 (or six or more - optional) arguments: # 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 window that will list music / videos / pictures), set to False otherwise # 6 [optional] if you need to pass additional items to your window, simply add them (as many as you need) to the list ui = GUI('script-testwindow.xml', CWD, 'default', '1080p', 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 fully script exits del ui # the end!
4 Your script-testwindow.xml file
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.
<?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> <font>font13</font> <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> <font>font13</font> <label>$INFO[ListItem.Label]</label> <textcolor>orange</textcolor> </control> </focusedlayout> </control> </controls> </window>