XBMC Plugin Tutorial (Hello World)

Goal

To create a XBMC plugin that works with the Raspberry Pi.

Prerequisites

Install XBMC on the Raspberry Pi  (Raspbmc is a popular option)

Code

Creating a plugin (or add on) for XBMC isn’t hard, but it does require a directory and a couple of files.

The first thing that we are going to do is create a directory to store our new plugin in. This directory needs to be created in:

/home/pi/.xbmc/addon

And we are going to call our directory:

plugin.video.helloworld

There are three parts to the name, separated by periods.  The first part is what type of extension to XBMC that we are going to create. In this case, we are going to create a plugin.  The second part is what menu it will live in.  In this case we are going to create a plugin in the video section.  The last part is the name our plugin, which in this case is helloworld.  More information about the other options can be found here.

Now inside of that directory, we are going to create four files:

1. addon.xml
2. changelog.txt
3. helloworld.py
4. icon.png

These four files tell XBMC how to handle our plugin and contain the logic when our plugin is executed. Let’s dive into these in more detail.

addon.xml

This file is required and it is the primary mechanism for telling XBMC about your plugin.  Here is an example:

<?xml version="1.0" encoding="UTF-8"?>

<addon id="helloworld" version="0.0.1" name="Hello World" provider-name="oneleggedredcow">

<requires></requires>

<extension point="xbmc.python.pluginsource" library="helloworld.py">

<provides>video</provides>

</extension>

<extension point="xbmc.addon.metadata">

<summary>Hello World</summary>

<description>Simple program to say hello.</description>

<platform>all</platform>

</extension>

</addon>

The first line simply states that this is an XML file.

The second line tells XBMC that we would like to create an add on.  The id attribute must be a unique identifier for our plugin. Something descriptive like helloworld seems to fit the bill.  The name attribute is the name that is displayed in XBMC for our plugin.  The provider-name is the name of the author of the plugin.

The third line contains a list of libraries that the plugin depends on.  In this case, we don’t have any dependencies.

Next we need two sections to describe how we are intending to extend XBMC.  The first extension tells XBMC that we are going to create a plugin and that the logic of our plugin is contained within the library helloworld.py.  The provides tag specifies that we want our plugin to be displayed within the video section.

The second extension provides more information (metadata) to XBMC about how to display the plugin within the menu.  It provides information such as a summary, a description, and what platforms the plugin works on.

changelog.txt

This file isn’t required, but it is highly encouraged.  So, to get in a good habit, we’ll create one now.  Here’s what the file looks like:

0.0.1

- First Attempt!

Nothing exciting in there since our program is so small.  However, this is a good place to tell users about what features have been added and what bugs have been fixed.

helloworld.py

This is a python script that contains the logic for our plugin.  The file looks like this:

import xbmc

import xbmcaddon

__addon__       = xbmcaddon.Addon(id='plugin.video.helloworld')

__addonname__   = __addon__.getAddonInfo('name')

__icon__        = __addon__.getAddonInfo('icon')

title = "Hello World"

text = "This is some text"

time = 5000  # ms

xbmc.executebuiltin('Notification(%s, %s, %d, %s)'%(title, text, time, __icon__))

The first two lines just import in libraries that we will be using.

The next three lines query for information about our plugin.  Trying to get its name and icon.

The next three lines set up the information that will be displayed when our plugin runs and how long it will be displayed for.

The final line displays a pop up notification window that displays our custom message: Hello World.

icon.png

The final file contains an icon to be displayed in the XBMC menu.  This file is not required, but sure is nice to have.

Running the Plugin

Once you have created all of the files, simply restart XBMC and navigate to the video add on section to run it!

Here’s a short video of the plugin up and running: