HOW-TO install and use scripts in XBMC

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 features a Python Scripts Engine and WindowXML application framework (a XML-based widget toolkit for creating GUI windows) 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 python scripts for XBMC include functions like cinema guides, 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 instant messaging chat, also casual games (sometimes also referred to as mini-games or party-games) such as Tetris, Snake, Space Invaders, Sudoku, and much more.

About Scripts

Scripts are located in the scripts folder of XBMC, see the subsection Finding and Adding Scripts below. They are written using a regular text editor, and they are ready to be used when saved. Scripts can be run from the XBMC Home Screen, from the "Scripts" button between Settings and File-Manager.

Python plugin versus script confusion

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

Integrating Scripts

Scripts can not be added as a playable source under e.g. My Programs or My Videos as they are not playable elements per se, but actual folders. Which is why they are featured in a separate list somewhere on the screen, depending on the selected skin you are using. In the default skin Project Mayhem III (PMIII), by Chokemaniac, your scripts can be run from the XBMC Home Screen, from the "Scripts" button between Settings and Filemanager).

XBMC Python Setup

Note: If you already have a [XBMC]/system/python folder in your XBMC Installation directory on your XBox then you can skip the following steps.

The first thing you want to do to get XBMC Python scripts running in XBMC is to go to the XBMC SourceForge SVN at this location

From there you will need to download python27.zlib and the Lib & Spyce folders. Once you have these files & folders, you can FTP them to your xbox into the [XBMC]/system/python folder. After doing this, XBMC will be ready to run most of the available scripts.

Finding and Adding Scripts

When you download and compile the XBMC SVN source code, there will already be some scripts inside of the scripts folder. The scripts folder is located on your XBox where the XBMC Installation directory is. You may leave these scripts alone or delete them if you want.
If you want more scripts that you may have heard of or seen somewhere, they can be found at the XBMC.org Addons section.
Most of these scripts come in either a RAR or ZIP package, meaning you will need WinRAR to extract the files. Most scripts come with a ReadMe or special instructions file, this should be read before anything else is done. Some scripts also have their instructions or configuration contained in the Python .py script file itself.
After extracting the files and reading the included documentation, FTP them to your xbox into the scripts folder. The script(s) are now cosidered “Installed” and ready to use.
To talk about and request more scripts visit the Python Scripts Support and Requests Forum.

Removing Pre-Installed Scripts

Several scripts could be packaged with your XBMC by default, this depends on the build/package you have. To remove these pre-installed scripts delete them from the script folder. However, as the scripts also could be listed in the script section of your currently selected skin, you will also have to edit the xml file that is linking the script if you want to remove the script completely.

For e.g. PAL 4:3 users of PMIII, this skinned list of scripts are found under XBMC/skin/Project Mayhem III/PAL/DialogSubMenu.xml.

Running Scripts from within XBMC

There are several ways to launch a script in XBMC.

The first is to have certain scripts set to automatically execute when XBMC starts. It is recommended that you only start one or maybe two scripts max when XBMC is loaded. There is not enough memory on the xbox to go around and you will notice a degradation in performance running more than that. For this to function a special script called autoexec.py can be installed in the XBMC\Scripts directory, in this script you can specify a couple of things for XBMC todo when it firsts starts (such as execute one or two different scripts). Here is an example of the autoexec.py file: <python>

1. auto execute scripts when xbmc starts, place this file in xbmchome\scripts\
2. note: - do not execute more than one script at a time which asks for user input!
3. import xbmc

xbmc.executescript('q:\\scripts\\medusa\\medusa.py') xbmc.executescript('q:\\scripts\\StartUpMP3\\mp3.py') </python> The example above of the autoexec.py is set to automatically start a script named medusa.py and mp3.py when XBMC starts.
You can learn more about what you can put in this file and learn more about scripting your own XBMC Python scipts by visiting the Python Scripts Development Forum.

Another way to launch scripts is to use the My Files tab, of your XBMC main menu. Once in the My Files section, you simply browse to your XBMC Installation directory or select the Q:/ directory (which is your XBMC Installation directory), then open the scripts directory, where you will see all of the scripts you have installed. You can run any of these scripts by scrolling onto it's name and pressing the “A” button on your Xbox controller or the button on your remote control that is used to execute highlighted items.

The final way of launching installed scripts, which is launching them through a skins sub-menu, is broken into two parts. There is the basic way and a customized advanced way. The basic way will be covered for now, and the advanced way will be added at a later point when time permits. The basic way should cover the needs of most XBMC users, once you have been using XBMC for a period of time and better understand XML and other things used by XBMC, you may wish to use the customized advanced way of launching scripts.

The basic way of launching a script through a skin's sub-menu button, is to go to the sub-menu button (located in the bottom right hand corner and looks like a little box, in the default skin) and when inside the sub-menu (it will open when you press the “A” button on your Xbox controller or the button on your remote control that is used to execute highlighted items) select the entry “Scripts” the same way. This will take you to the “Scripts” directory of your XBMC folder.
You may notice other items in this sub-menu called “Movie Trailers” and “Web Radio” for example. Once you are viewing the scripts directory, you will see all of the scripts installed on your xbox and can execute them with the controller or remote, the same way you highlight and execute other items in XBMC.

Using Profile Scripts

You have the ability to choose to display scripts on a per-profile basis, as well as globally. This functionality allows you to block other users from using scripts that contain objectionable material.

In order to use this functionality, simply place the scripts that you would like available to all users in the XBMC/Scripts folder. All per-user scripts should be placed in a /Scripts folder within the profile's data folder.

Note: The global scripts folder is available as Q:\scripts, while the scripts folder for the currently loaded profile is available as P:\scripts.

Building Scripts

You can find an detailed explanation of how to build python scripts for XBMC yourself here.