Web Server HTTP API

HTTP API Overview
This document provides information on XBMC’s Application Programming Interface (API). The API operates over the HyperText Transfer Protocol and hence is called "HTTPAPI".

The API commands are also available over ASP and from Python (see later sections).

Unless otherwise noted, this documentation describes what's available in XBMC 8.10. Any commands that were added or modified at a different version will show a date indicating when.

Getting Started
The XBMC HTTP API provides a mechanism for a networked device (e.g. a PC or a PDA with WiFi) to interact with XBMC. The API provides access to XBMC status information and allows control of XBMC functions.

The API can be called from a standard web browser, which will also display any results. This method is probably the easiest way to experiment with the API commands. Fire up your browser and enter the following into the address field:

http://xbox/xbmcCmds/xbmcHttp?command=getcurrentlyplaying

Information about the media currently being played by XBMC will be displayed, if nothing is being played then "[Nothing Playing]" will be displayed.

If you want to control the volume of XBMC enter the following into your browser’s address field:

http://xbox/xbmcCmds/xbmcHttp?command=setvolume(80)

"OK" will be displayed and the volume will be set to 80% which you will probably find is rather quiet.

If you find that the above commands don’t work then check that:


 * XBMC is running.
 * The XBMC web server has been turned on. This setting can be found in Settings, Network, Server.
 * The address "xbox" is understood by your browser to point to your Xbox’s address. You may need to enter the full IP address e.g. 192.168.0.1
 * You didn’t mistype the command.

Note: If you are a Windows user, you can configure a name for your Xbox's IP address. Use your favorite text editor to edit the file “hosts” inside C:\WINDOWS\system32\drivers\etc\ and add a line at the end with your Xbox's IP address.

192.168.0.1 xbox

Save it (you don't need to restart). Windows should now redirect "xbox" to your Xbox's IP address. You can check to see if it works by typing “ping xbox” at the command line.

Another simple test is to enter xbox as an address in your web browser. Try to visit:

http://xbox

This should display the default XBMC web page. If this does not work you may encounter an error, or your browser might redirect to Microsoft's xbox.com. If you can't get http://xbox to redirect, you can always replace "xbox" in the following examples with your Xbox's IP address.

Function Syntax
Once you have the above working we can look at the structure of the HTTP command line.

All HTTP API commands start with the following:

http://xbox/xbmcCmds/xbmcHttp?command=

(Remember you may need to replace “xbox” with your Xbox's IP address.)

The next part of the line is the command itself, which in the two examples above are "getCurrentlyPlaying" and "setVolume". The command is not case sensitive: "SetVolume", "setvolume" and "SETVOLUME" can also be used.

Many commands take parameter values. To provide command parameters enclose them in parentheses -- "(" and ")" (also note that the old syntax of appending with "&parameter=" still works).

Depending on the command the parameter values may or may not be case sensitive. It is always safest to assume the values are case sensitive. If there are multiple parameters then each value is separated by a semi-colon ";". The following is an example of a command with 4 parameters.

http://xbox/xbmcCmds/xbmcHttp?command=takescreenshot(test.jpg;false;0;300;200;90)

To pass a semi-colon as a parameter (rather than a separator) use two semi-colons ";;".

To pass an empty parameter insert a space between the semi-colons "; ;".

To pass an empty parameter as the last (right most) parameter use "%20" (if just a space is appended to the end, the browser will remove it and XBMC will not detect the final parameter).

You may encounter similar unexpected behavior with other characters besides the space. You can encode any character that is causing problems using the standard %xx format (RFC1738) before passing it to the API.

We recommend using the new function syntax (passing parameters within parentheses, rather than appending them to the URL with the old "&parameter=" syntax) because it is easier for XBMC to recognize the end of the command (i.e. the closing bracket). This is important when issuing commands from a browser environment (e.g. using Javascript), because a typical way of ensuring the browser does not use a cached response from a previous initiation of a command is to use the syntax:

var url = 'http://xbox/xbmcCmds/xbmcHttp?command=SetPlaylistSong(1)?nocache=' + new Date.getTime;

The date.getTime always ensures a unique number is included in the generated URL, which ensures that the browser won't use a previously cached response. (XBMC ignores everything after the ")" and hence doesn't get confused by the rest of the line.)

We also recommend the function syntax for commands without parameters:

var url = 'http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying?nocache=' + new Date.getTime;

Response Structure
The API returns information in a consistent form but which is dependent on the type of information returned. Those commands which:


 * don’t return a value e.g. SetVolume return the standard response OK
 * return a single value e.g. GetVolume return just the value
 * return multiple values e.g. GetCurrentlyPlaying return multiple lines with each line having the format
 * name:value

An error in the execution of a command, for example a missing parameter, is indicated by the response:

Error[:Reason]

i.e. all errors are indicated by returning "Error" and depending on the error there may be additional information provided.

e.g. Error:Missing parameter

The following is the default response format. To change the format see the command SetResponseFormat.

Every line in the response is prefixed by the HTML tag . The only exception to this is the GetThumb command where a prefix is not included. The use of this prefix means that the responses are displayed clearly within a browser but the  tag does not require a corresponding close tag i.e.  is not required.

Finally, and to create a valid HTML response, the whole response is top and tailed with the web server’s default header and footer.

Sample Code
Probably the easiest way to get up to speed with a new API is to have a look at code. Several of the applications that can be found here: HTTPAPI client apps come with source code. In particular look for the file XBMCHttpInterface.vb which wraps up the majority of the HTTP API within a .Net class. The file can be found within the package XBMCControl. There are also examples that show how to call the HTTP API from an Excel spreadsheet and from Visual Basic 6.

Accessing the HTTP API
The easiest way to access the HTTP API is to type the URL into a web browser, as described in the overview. This method allows you to tweak your command and parameters and receive immediate visual feedback.

To get the most out of the API, though, you'll probably want to incorporate it into a more powerful tool. The web browser HTTP API is available to ASP, Python (for both scripts and plugins), and can be broadcast to control other clients.

Each access method uses a slightly different context, but the commands and parameters are the same. Once you've learned how to use the HTTP API in the environment of your choice, all the commands listed below are available to you.

ASP
Access HTTP API commands with ASP using the command "xbmcAPI" in the same way you would use "xbmcCommand" (see default.asp in the XBMC web directory for more information). Pass the HTTP API command to xbmcAPI as a string, containing exactly the same name and the same parameters you would use to call the command from the URL. The only difference is that parameters should be separated with commas instead of semi-colons.

e.g. Response = xbmcAPI("GetCurrentlyPlaying");

The response structure is also identical (formatted as an HTML document) except that the web server’s default header and footer will not be present.

Python
Access HTTP API commands with Python using the function executehttpapi (imported from the xbmc module). Pass the HTTP API command to executehttpapi as a string, containing exactly the same name and the same parameters you would use to call the command from the URL. The only difference is that parameters should be separated with commas instead of semi-colons, just as you would do in a regular Python function call.

e.g.

import xbmc

response = xbmc.executehttpapi("TakeScreenShot(special:\\temp\test.jpg,false,0,300,200,90)")

The response structure is also identical (formatted as an HTML document) except that the web server’s default header and footer will not be present.

Broadcast
The Broadcast functionality is not, strictly speaking, part of the HTTP API because it does not use the HTTP protocol. However, it is controlled via HTTP API commands and would typically be used as an adjunct to the HTTP API and so is presented here.

The HTTP API is a “pull” architecture -- that means HTTP API interacts with XBMC by making calls to XBMC. For an HTTP API client to maintain a dynamic up-to-date display (e.g. showing the currently playing song), the client must continually poll XBMC for its status.

The Broadcast facility provides the opposite approach -– XBMC makes calls out (i.e. broadcasts or "pushes") to indicate significant events to any clients that happen to be listening.

The Broadcast facility uses the UDP broadcast protocol with a default port setting of 8278. (We chose 8278 for no other reason than that it was the first unregistered port we stumbled across.) For a client to receive these broadcasts, the client must register to receive them. (The method of doing so will depend on the language/technology of the client). XBMC broadcasts on the IP address 255.255.255.255 which is the limited broadcast address. Sending a UDP datagram to this address delivers the message to any host on that broadcast network. Because routers never forward messages sent to this address, only hosts on the connected network see these broadcasts. In other words, the client must be on the local network to receive XBMC broadcasts.

XBMC broadcasts are delimited by  and may consist of a numerical or textual description of the event (depening on the event) followed by ";" and the level of the event (e.g. 1 or 2).

An example Windows client (with source code), XBMC Listener, that listens to these broadcasts can be found here

Understanding the Command Tables
This section presents a complete list of HTTP API commands, divided into tables based on functionality. In the tables, each command gets its own three-column row. The first column contains the function name, followed by parentheses. Inside the parentheses are the function's parameters (if any). When calling these functions, each parameter should be included in order, separated by semi-colons (for HTTP API URLs) or commas (for Python or ASP calls).

In the first column, any parameter name in square brackets is optional. Optional parameters typically have default values, but you can override these by supplying a different value for custom performance.

The second column contains a brief description of the function, and the third column contains an example URL.

A sample entry from the tables below looks like this:

As a reminder, the function syntax for an HTTP API URL looks like this:

http://xbox/xbmcCmds/xbmcHttp?command=setvolume(50)

If you prefer, you can still use the old syntax:

http://xbox/xbmcCmds/xbmcHttp?command=setvolume&parameter=50

Example Links
In the third column you'll find a sample URL for the function. Assuming you have XBMC running and configured appropriately, clicking on the example link should load the link in your browser window. Depending on your setup and the command you're using, you may need to edit the link in your browser's address bar and try again. One of the most common necessary changes is replacing "xbox' with your Xbox's IP address (e.g. 192.168.1.101). As an example: http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying -> http://192.168.1.101/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying

(For instructions on simplifying this process, see the Getting Started above.)

Once the URL is pointing to your Xbox, most of the examples will work as is. Others (which may refer to a specific file, for example), will require you to manually modify the link to appropriate values for your environment.

A Note about URL Formatting
Some of the examples use the code "%20" in place of spaces (" "). This is a standard URL code (or "token") that helps URL interpreters recognize the true end of a URL. In the case of this wiki, it helps the document formatting keep the entire http:// string as a single, active link. If you are manually typing the command into a web browser address bar, or using it from your own code, then you usually type spaces without any problems. For more information, click here.

A Note about Playlists
In the following tables the Playlist parameter refers to one of the two available media type playlists using the value 0 or 1:

0. Music playlist 1. Video playlist

These playlists should not be confused with:
 * The slideshow playlist. The slideshow commands implicitly refer to the latter.
 * User-defined playlist files (e.g m3u files).

Command Tables Reference
The commands are presented in five sections. Those commands that:
 * retrieve information
 * set/modify information
 * perform/initiate an action
 * perform an action on a file
 * don’t fit into one of the above and hence are miscellaneous
 * HTTPAPI commands and examples

Name Changes
To make the names of the commands more logical some have been changed. The old names are still recognised but we strongly advise that you use the new names.