HOW-TO:Write Python Scripts

XBMC features a Python Scripts Engine and WindowXML application framework (a XML-based widget toolkit for creating GUI window structure) in a similar fashion to Apple Mac OS X Dashboard Widgets and Microsoft Gadgets in Windows Sidebar. So normal users can add new functionality to XBMC themselves (using the easy to learn Python programming language) without an illegal copy of the XDK and without knowledge of the complex C/C++ programming language. Current plugin scripts include functions like Internet-TV and movie-trailer browsers, weather forecast and cinemaguides, TV-guides (EPG), e-mail clients, instant messaging, train-timetables, scripts to front-end control PVR software and hardware (like: MediaPortal, MythTV, TiVo, ReplayTV, Dreambox/DBox2), Internet-radio-station browsers (example SHOUTcast, Xm radio, Sirius Satellite Radio), P2P file-sharing downloaders (BitTorrent), IRC, also casual games (sometimes also referred to as mini-games or party-games) such as Tetris, Snake, Space Invaders, Sudoku, and much more.

Please feel free to add more samples of simple scripting functions with comments that you know or figure out while you're learning to script. Adding anything at all no matter how basic, if its not already here add it! someone will more than likely benefit from it. The more difficult your snippet please heavily comment it with "#" don't be stingy on the comments you can never have too much information, what's simple to you may make no sense at all to someone else, also URLs that were helpful to what you were doing would be great to add to your snippet or to the bookmark section (python sites, chatrooms, etc):

Python Example
Description: Python won't run the lines that we put a '#' in front of they are considered as “commented out” python will skip them.

Python resources, guides and documentation directly related to XBMC

 * XBMC Online Manual Python related sections:
 * XBMC Manual – Python Basics
 * XBMC Manual – Built-in Scripting
 * Web-Server HTTP-API (HTTPAPI)
 * XBMC Manual – List of Built In Functions
 * XBMC Manual – Labels Available In XBMC (InfoLabels)
 * HOW-TO write Python Scripts for XBMC, a Tutorial
 * This HOW-TO tutorial should be the perfect place if you about to start making your first python script for XBMC and you do not yet know very much about python, (note though that this tutorial could now be considered a little old-fashioned, but it is still a very good starting point).


 * Other XBMC Python related articles:
 * XBMC Python Documentation - Updated from XBMC SVN on a regular bases
 * XBMC HTTP API Commands (quick overview, with link to doc)
 * xbmc api
 * xbmcgui api
 * XBMC Python emulator for Windows PC (BETA)
 * XBMC Forum – Python Scripts Development
 * XBMC Forum – Python Scripts Support and Requests
 * XBMC Python scripts – Help for French users and coders

Other python resources (indirectly related to XBMC scripting)

 * Python Documentation on python.org
 * PLEAC-Python
 * An Introduction to Python - A Brief Tour of Python
 * Based on presentation materials by David Beazley (author of Python Essential Reference)
 * Snyppets - Python snippets

IRC Channels
/server irc.freenode.net /join #xbmc-scripting /server irc.freenode.net /join #python /server irc.freenode.net /join #python-cleese /server irc.freenode.net /join #python-gilliam

Basic Information
To code python all you basically need is notepad or any other form of texteditor its not very hard to figure out the basics with the documents in Bookmark section above, have a run through them first if you have no clue whats going on in the code snippets to enlighten yourself a bit. – I would suggest looking at the ALEX's Tutorial below first to start, and remember python is all about indents...

Structure

 * Please keep all your files related to your script in its own folder.
 * Name the Main File default.py
 * If you want a thumbnail call it default.tbn (tbn can be jpg or png)

Use this code to find the path you want The Above line will return a folder so its like q:\\scripts\\GoogleScript\\ or where ever the script is located

As of the 13th of July, MyScripts now flatterns meaning it will it will no longer shows the folders and their contents if there is a default.py in the folder (won't let you view any deeper)

Another nice way to have all your files inside your app is to put them inside a lib/ dir inside it, so "the first level" can only have the default.py and default.tbn files. To have all your sub-scripts in that way you have to put at the head of your script something similar to this code: so you'll be able to import your files as if them were on the root directory of your python app.

Basic Steps

 * 1) Open a text document.
 * 2) Paste some code in there. Read this tutorial: HOW-TO write Python Scripts for XBMC
 * 3) Save it to any name you wish with .py on the end for the file extension. (myscript.py)
 * 4) FTP it to the scripts folder in XBMC (F:/xbmc/scripts/)
 * 5) In XBMC go to the submenu naturally beside the power button on the skin in Project Mayhem 1.
 * 6) Click scripts in the submenu.
 * 7) Find the script you uploaded and run it.
 * 8) “White Button” on the controller for Python debug whilst in scripts window (Added:13-02-05)

To find out a lot of stuff of what there is available to control in XBMC take a look at these documents from the CVS: XBMC python documentation

Code Snippets
(Warning: Some code may require you to first create a window or something along those lines but might not be specified)

Thanks to the following contributors:
 * ThreeZee (on EFNet: ThreeZee)
 * EnderW
 * alexsolex
 * Donno

Play A File
If you want to play a file this is how, you dont need to make it a variable but it makes your code a little more cleaner. (this code doesnt need a window but import your xbmc libraries as normal)

Fetching artist name and song title from currently playing song
By using the code example below you can get the song title and artist name of the song currently playing in XBMC.

XBMC GUI
Also see WindowXML GUI Toolkit/WindowXML

Adding Buttons the Nice Way
Using The following addButton and setupButtons

Scaling your script using setCoordinateResolution
Example: Skinned for PAL resolution

Scaling your script for any size screen
Based on NTSC 720x480

Check if text is in a string
Note this is case sensitive, so you may want to use mystring.lower and have the “world” all in lower case.

File Exist
Check to see if file exists on harddrive

Read URLS from a web page
The following code will search a page for all Description and store all the urls in one list array and all the descriptions in another

Download Files with Progressbar
Download a url from the net and saves to a file and shows the progressbar. Usage: to call the function use DownloaderClass(url,dest)

Passing Arguments to a Script
As of 2007/02/24, arguments can be passed into a script using the builtin command XBMC.RunScript. The first parameter this builtin takes is the absolute location of the python script and all additional parameters are passed as arguments to the script.

Using Arguments from sys.argv
The arguments can be accessed from a different script using sys.argv. This is a list of strings that is populated when the script is launched using the builtin command. sys.argv[0] is the name of the script while the rest of the list, sys.argv[1:], are the arguments passed to the script.

Script install path
This tips is usefull to let user the opportunity to install the script in the path of their choice. The tricks is to store the path where the script has just been launched

Control Types
There are four Control Types available to map in XBMC:

Controller, Remote, Mouse, & Keyboard

Control Type: Remote
The Remote is the another Control Type that has two methods you can use to map actions to your Xbox conroller button(s):

Button Codes & Action Codes (see Key.h for a full list of codes)

Button Code Reference
To obtain an updated list of Action & Button Codes, please see: key.h