Sunday, June 2, 2013

Our First Plugin


In this plugin, we will simply play a  live stream video, more specifically France24 in French. I have found some plugins which have France24 in English, but not in French, but in any case, I wanted to access this stream as a top level plugin, and not buried in multiple levels of menu.

Getting Started

We start by creating the folder '' in the addons folder.We then add the three required files, icon.png, created from a logo found from a Google image search, a blank, and an addon.xml with the following content:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id=""
       provider-name="Abed BenBrahim">
   <import addon="xbmc.python" version="2.1"/>
  <extension point="xbmc.python.pluginsource" library="">
  <extension point="xbmc.addon.metadata">
    <summary lang="fr">Les Emissions de France24</summary>
    <description lang="fr">Les Emissions de France24</description>

If xbmc is running, it needs to be restarted so that the new plugin can be detected. It will not be necessary to restart xbmc when we edit our plugin source, as the code is interpreted and the script file is reopened every time the script is run. We should now have an icon named France24, with the the image of the specified icon. Clicking on the icon does nothing since we do not have any code in

The code 

In our first version, we will simply tell the player to play the stream.
import xbmc

link='rtmp:// playpath=f24_livefr app=france24_live/fr'

If you click the France24 icon under Video|Addons, the stream will now play. But you will notice that the caption display's fr and that a default icon is shown. This is not what we want, rather we want something that looks like this:

The play method of xbmc Player takes three parameters, all optional:

  • item: the item to play, either a local file, a network stream or a playlist
  • listitem: information about the item to be played. This is where we can specify the icon and the title.
  • windowed: whether to play the file full screen (value False, the default) or windowed (value True).

The following code creates a list item:

li = xbmcgui.ListItem(label=title, iconImage=icon, thumbnailImage=icon, path=link)
li.setInfo(type='Video', infoLabels={ "Title": title })
The first line defines the title, icon, thumbnail and link of the file to be played. The second line defines detailed information about the media, using info labels. Many info labels can be defined (a full list is here), but for our purposes, the title will suffice.

Now, we need to specify the title and icon. We could hard code the title and icon path, but in the case of the icon, that would not be very portable (it would only work on one machine). We therefore need to get information about the plugin to find out the plugin path:
addon = xbmcaddon.Addon('')
title = addon.getAddonInfo('name')
icon = addon.getAddonInfo('icon')
We create an addon object with our addon's id to retrieve some information about our add-on. We will use the same object later when we deal with add-on settings and localization. Here we retrieve the add-on name and the full path to the icon. More information coud be queried, which you will find in the reference section below, in the API documentation for xbmcaddon.

So now our full code looks like this:
import xbmc, xbmcgui, xbmcaddon

addon = xbmcaddon.Addon('')
title = addon.getAddonInfo('name')
icon = addon.getAddonInfo('icon')
link = 'rtmp:// playpath=f24_livefr app=france24_live/fr'

li = xbmcgui.ListItem(label=title, iconImage=icon, thumbnailImage=icon, path=link)
li.setInfo(type='Video', infoLabels={ "Title": title })
li.setProperty('IsPlayable', 'true')

xbmc.Player().play(item=link, listitem=li)
We could stop right here and call it a day, however, there is code in thia add-on we could reuse in future projects, so we want to extract it to a separate file,, which will expand on future projects, and avoid reinventing the wheel for every new plugin. We will create a function named playMedia in our new script:
import xbmcgui, xbmc

def playMedia(title, thumbnail, link, mediaType='Video') :
    """Plays a video

    title: the title to be displayed
    thumbnail: the thumnail to be used as an icon and thumbnail
    link: the link to the media to be played
    mediaType: the type of media to play, defaults to Video. Known values are Video, Pictures, Music and Programs
    li = xbmcgui.ListItem(label=title, iconImage=thumbnail, thumbnailImage=thumbnail, path=link)
    li.setInfo(type=mediaType, infoLabels={ "Title": title })
    xbmc.Player().play(item=link, listitem=li)
and now looks like this:
import xbmcaddon, util

addon = xbmcaddon.Addon('')

util.playMedia(addon.getAddonInfo('name'), addon.getAddonInfo('icon'), 
               'rtmp:// playpath=f24_livefr app=france24_live/fr')

The complete plugin is available here

More information and references


  1. Sounds good, what do you say about it? Did you use this framework?

  2. Thanks a lot mate. Really useful resource for newbies like me. Hopefully I'll develop my first successful addon soon.

  3. Works great.....How do you put multiple addons in on file??? can someone please help me..... Thanks

  4. So, I have a daft question (sorry if it is silly) but can addons be made that link to say Kisscartoon website, and then one can search via TVMC/Kodi, and play any of the streamed cartoons into tvmc? or does the 3rd party site specifically need an api / service to link to?