Python Development

Return to: XBMC Online Manual

• • Types of Media Sources
  • Sharing Media from Your PC
    • SMB/Samba/CIFS
    • UPnP
    • XBMSP
    • ITunes (DAAP)
    • FTP
  • NAS (Network Attached Storage)
  • TuxBox
  • User Profiles
    • Manually Edit Profiles
  • The UserData Folder
  • Special protocol
  • MythTV
  • RSS Feeds
  • RSS feed Control
  • Playlists
  • Advanced Configuration
  • Log file
  • Add-ons
    • Install Plugins
    • Install Scripts
    • Install Skins
  • USB Mass Storage in Xbox
  • Error Recovery Mode
  • Import - Export Library
• FAQ'S
  • What is XBMC & What Can it Do?
  • Using XBMC
  • XBMC for Xbox specific FAQ
  • Frequently Asked Questions
  • Troubleshooting
• XBMC's Inner Workings
  • Development Notes
  • Python Development
    • HOW-TO write plugins for XBMC
    • HOW-TO write Python Scripts
  • Skinning XBMC
  • List of Built In Functions
  • Web Server HTTP API
  • The XBMC Database
  • Audio Players
  • Video Players
  • Scrapers
  • HOW-TO write Media Scrapers
  • Regular Expression Tutorial
  • PAPlayer
  • MPlayer
  • DVDPlayer
  • Appendixes
  • References
  • Point Releases
  • HOW-TO's / Tips & Tricks
  • Mods to XBMC and Xbox
  • Disclaimer
  • Thanks

<<Edit this toc>>

XBMC includes a built-in Python interpreter that allows users to develop add-ons (scripts and plugins) that interface easily and cleanly with the XBMC dashboard. These add-ons can extend the functionality of XBMC without requiring extensive programming experience or ability. While you may not feel comfortable browsing the XBMC 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 XBMC 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 XBMC Python, you can probably skip on down to the environment details or the resource links below for quick reference material.

The main 'HOW-TO' articles for making your own plugins and scripts can be found here:

• HOW-TO write plugins for XBMC
• HOW-TO write Python Scripts

The very latest XBMC python API documentation with classes and functions is automatically generated from XBMC's source code and can be found here:

• XBMC Python Docs: xbmc
• XBMC Python Docs: xbmcgui
• XBMC Python Docs: xbmcplugin

Python plugins versus scripts

Please do not confuse "Plugins" with "Scripts". Unlike the Scripts, Plugins are not meant to be directly invoked by the user. Instead, Plugins are automatically invoked when the user enters such a virtual folder. Do not try to run Plugins files from the scripts window as that will only give you a weird error message. Plugins, unlike Scripts, do not really provide new functionality to XBMC, instead what they do do is provide an easy way to present content listings in XBMC through the native GUI interface.

Script Development

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

print "Hello World!"

That's the same code you would enter at the Python command line, because XBMC 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 XBMC and manipulate the Graphical User Interface (GUI).

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

Plugin Development

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

Plugins are still scripts written in Python, but they perform a specific function and should be saved in the appropriate /plugins/ folder of your XBMC installation (instead of the /scripts/ folder, where general scripts are stored).

When a user launches a plugin, the plugin generates a list of menu items and hands them to XBMC 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 XBMC just like it would movie files on the local hard drive, but a plugin can be used anywhere a script could, as long as the menu structure is a sufficient GUI for the add-on's needs.

Also, note that a script can launch a plugin, and a plugin can launch a script (and, for that matter, it can call all the same functions available to a script) so the distinction is more theoretical than practical.

Resource Links

While the three custom libraries give you you control over the XBMC GUI, you'll eventually want to be able to interact with other parts of the system. Much of XBMC'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.

List of Built-In Functions

You can call any of the XBMC Built-in Commands using the function executebuiltin from xbmc.

List of Built-In Functions

Web Server HTTP API

XBMC offers a Web Server to provide remote control over HTTP. You can call any of the HTTP API commands using the function executehttp from xbmc.

Web Server HTTP API

The XBMC Databases (Media Metadata Libraries)

XBMC 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 XBMC Database, you can gain access to the databases from Python through the HTTP API or by installing a SQLite module. Read more about that here.

The XBMC Database

InfoLabels

XBMC 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.

InfoLabels

Other Python Pages

There are several other pages in the XBMC 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 HOW-TO write Python Scripts, though. It's a tutorial (linked above) with tons of great sample code.

Environment Details

Version

XBMC Python is an implementation of Python 2.7 (specifically, 2.7.13, as of latest revision).

Libraries

XBMC Python comes with all the standard modules from Python 2.7. If you need to find a list of them, you can use the following command to generate a list of built-ins:

import sys
print sys.builtin_module_names

For a list of the other standard libraries, find the file "python27.zlib" in your XBMC installations /system/python/ folder, and open it with an archive viewer such as WinRAR or 7-zip.

Custom Libraries

In addition to the built-ins and standard libraries, XBMC Python uses a handful of custom libraries to expose XBMC functionality to Python.

Module	Description
xbmc	Offers classes and functions that provide information about the media currently playing and that allow manipulation of the media player (such as starting a new song). You can also find system information using the functions available in this library.
xbmcgui	Offers classes and functions that manipulate the Graphical User Interface through windows, dialogs, and various control widgets.
xbmcplugin	Offers classes and functions that allow a developer to present information through XBMC's standard menu structure. While plugins don't have the same flexibility as scripts, they boast significantly quicker development time and a more consistent user experience.

Installing Additional Libraries

Additional libraries can be installed by adding them to the /system/python/Lib folder of your XBMC installation. A Python module placed in this folder can be called from any script or plugin within XBMC.

Of course, you can also place the library files you want to import in your script or plugin folder, directly in the root or in a subfolder. A popular method is to add a "resources" subfolder to your script's folder, and add it to the path within your script.

Example: Adding SQLite Support as a Module

The Apple QuickTime Movie Trailers provides a good example.