Archive:Web Server HTTP API: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Nad
No edit summary
 
(95 intermediate revisions by 21 users not shown)
Line 1: Line 1:
==HTTPAPI DOC==
{{Notice|raw='''<big>THIS API IS DEPRECATED</big>'''<br />
As of the Dharma release of XBMC, this API is deprecated.<br />
As of the Frodo release of XBMC, this API is no longer available.<br />
Use the [[JSON-RPC_API]] interface instead.}}


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


The same set of commands is also available over ASP and from Python (see later section).
This document provides information on XBMC’s Application Programming Interface (API). The API operates over the HyperText Transfer Protocol and hence is called "''HTTPAPI''".


Apart from where indicated by a date indicating when a command was added/modified this documentation describes what's available in XBMC 2.0.0.
The API commands are also available over ASP and from Python (see later sections).


===Getting started===
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.


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 control of XBMC functions.
=== Getting Started ===


The API can be called from and results displayed in a standard web browser which is probably the easiest way to experiment with these commands. Fire up your browser and enter the following into the address field:
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:


<pre><nowiki>
<pre><nowiki>
Line 22: Line 27:


<pre><nowiki>
<pre><nowiki>
http://xbox/xbmcCmds/xbmcHttp?command=setvolume&parameter=80
http://xbox/xbmcCmds/xbmcHttp?command=setvolume(80)
</nowiki></pre>
</nowiki></pre>


Line 29: Line 34:
If you find that the above commands don’t work then check that:
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  
* 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  
* The XBMC web server has been turned on. This setting can be found in Settings, Network, Server.
* You didn’t mistype the command.
* You didn’t mistype the command.


Note: If you are a Windows user, you can configure a name for your Xbox's IP address.
Note: If you are a Windows user, you can configure a name for your Xbox's IP address.
Edit with your favorite text editor the file “hosts” inside C:\WINDOWS\system32\drivers\etc\ and add a line at the end with your xbox 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.


<pre><nowiki>
<pre><nowiki>
Line 41: Line 46:
</nowiki></pre>
</nowiki></pre>


Save it (don't need to restart) and test if the command “ping xbox” works. You should now resolve your Xbox IP address
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.


If you still can’t get them working, try:
Another simple test is to enter xbox as an address in your web browser. Try to visit:


<pre><nowiki>
<pre><nowiki>
Line 49: Line 54:
</nowiki></pre>
</nowiki></pre>


This should display the default XBMC web page. If this does not work then check out other XBMC documentation on the web server and come back when it is working.
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.
Once you have the above working we can look at the structure of the HTTP command line.


All API commands start with the following:
All HTTP API commands start with the following:


<pre><nowiki>
<pre><nowiki>
Line 59: Line 66:
</nowiki></pre>
</nowiki></pre>


(Remember you may need to swap “xbox” for the IP address.)
(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.
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.


If the command takes parameters then "&parameter=" is added after the command.
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).


Finally comes the parameter values. 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.
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.


<pre><nowiki>
<pre><nowiki>
http://xbox/xbmcCmds/xbmcHttp?command=takescreenshot&parameter=test.jpg;300;200;90
http://xbox/xbmcCmds/xbmcHttp?command=takescreenshot(test.jpg;false;0;300;200;90)
</nowiki></pre>
</nowiki></pre>


To pass a semi-colon as a parameter (rather than a seperator) use two semi-colons ";;".  
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 paramter 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).


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 ([http://www.rfc-editor.org/rfc/rfc1738.txt RFC1738]) before passing it to the API.


As of 18th Nov 2006 a more usual function calling syntax is also available. Instead of using the "&parameter" syntax to specify parameters the parameters can be enclosed within brackets. Note that the parameters must still be separated by semic-colons. The above example takescreenshot command would be presented in the new syntax as:
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:


<pre><nowiki>
<pre><nowiki>
http://xbox/xbmcCmds/xbmcHttp?command=takescreenshot(test.jpg;300;200;90)
var url = 'http://xbox/xbmcCmds/xbmcHttp?command=SetPlaylistSong(1)?nocache=' + new Date().getTime();
</nowiki></pre>
</nowiki></pre>


The rest of this document uses the original "&parameter" syntax which of course is still supported.
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:
 
<pre><nowiki>
var url = 'http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying()?nocache=' + new Date().getTime();
</nowiki></pre>


===Response Structure===
=== Response Structure ===


The API returns information in a consistent form but which is dependent on the type of information returned. Those commands which:
The API returns information in a consistent form but which is dependent on the type of information returned. Those commands which:
Line 113: Line 128:
Finally, and to create a valid HTML response, the whole response is top and tailed with the web server’s default header and footer.
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 ===


===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: [http://code.google.com/p/xbmc-http-api-apps/downloads/list 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.


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: [http://sourceforge.net/project/showfiles.php?group_id=87054&package_id=198866 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.


==ASP==
== Accessing the HTTP API ==


The commands are also available as ASP commands using the command "xbmcAPI" just as the current "xbmcCommand" works now (see default.asp in the XBMC web directory). All xbmcAPI commands have an identical name and the same parameters as the commands listed in the document. The response structure is also identical apart from the web server’s default header and footer which will not be present.
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.
e.g.
Line 127: Line 150:
</nowiki></pre>
</nowiki></pre>


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==
=== Python ===


The commands are also callable from Python scripts through the function executehttpapi imported from the xbmc module. All xbmcAPI commands have an identical name and the same parameters as the commands listed in the document. The response structure is also identical apart from the web server’s default header and footer which will not be present.
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.  
e.g.  
Line 137: Line 161:
import xbmc
import xbmc


response = xbmc.executehttpapi("TakeScreenShot(q:\\test.jpg,0,false,200,-1,90)")  
response = xbmc.executehttpapi("TakeScreenShot(special:\\temp\test.jpg,false,0,300,200,90)")  
</nowiki></pre>
</nowiki></pre>


==Broadcast==
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 ===


Added 18th Nov 2006
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 Broadcast functionality is not strictly speaking part of the HttpApi in that it does not use the HTTP protocol. However, it is controlled via HttpApi commands and would typically be used as an adjunct to the HttpApi 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 HttpApi is a “pull” architecture – HttpApi interacts with XBMC by making calls to XBMC. For an HttpApi client to maintain a dynamic up-to-date display, e.g. of the currently playing song, the client needs to 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 provides the opposite approach – XBMC makes calls out (i.e. broadcasts or "pushes") indicating significant events to anything that just happens 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.


The Broadcast facility uses the UDP broadcast protocol with a default port setting of 8278. (8278 was chosen for no other reason than it was the first unregistered port that I stumbled across.) For a client to receive these broadcasts, the client must register to receive the broadcasts (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, i.e. the client will need to be on the local network to receive the broadcasts.
XBMC broadcasts are delimited by <nowiki><b></b></nowiki> 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).


The actual broadcasts are delimited by <nowiki><b></b></nowiki> 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 [http://code.google.com/p/xbmc-http-api-apps/downloads/list here]


An example Windows client (with source code), XBMC Listener, that listens to these broadcasts can be found [http://sourceforge.net/project/showfiles.php?group_id=87054&package_id=198866 here]
== Understanding the Command Tables ==


==The Commands==
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).


This section presents a complete list of HTTP API commands. In the list, after the command name is presented, the text between the parentheses is the list of semi-colon separated parameters for the command.  
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.


Remember to use the syntax:
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:
 
{| border=1 cellspacing=0 cellpadding=5
| '''Command'''
| '''Information'''
| '''Example'''
|-
| SetVolume
| Sets the volume as a percentage of the maximum possible. 
| http://xbox/xbmcCmds/xbmcHttp?command=SetVolume(50) 
|}
 
As a reminder, the function syntax for an HTTP API URL looks like this:


<pre><nowiki>
<pre><nowiki>
http://xbox/xbmcCmds/xbmcHttp?command=setvolume&parameter=80
http://xbox/xbmcCmds/xbmcHttp?command=setvolume(50)
</nowiki></pre>
</nowiki></pre>


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


<pre><nowiki>
<pre><nowiki>
http://xbox/xbmcCmds/xbmcHttp?command=setvolume(80)
http://xbox/xbmcCmds/xbmcHttp?command=setvolume&parameter=50
</nowiki></pre>
</nowiki></pre>


=== 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


A parameter in square brackets is optional. An optional parameter typically specifies an alternative to a default value.
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.


In the following list the Playlist parameter identifies one of the four available playlists by using the values 0..3:
=== 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.  


<pre><nowiki>
=== A Note about Playlists ===
0. Music playlist
In the following tables the Playlist parameter refers to one of the two available media type playlists using the value 0 or 1:
1. Temporary music playlist
2. Video playlist
3. Temporary video playlist
</nowiki></pre>
 
As of 26 Nov 2006 the available playlists and identifiers have changed to:


<pre><nowiki>
<pre><nowiki>
Line 190: Line 229:
1. Video playlist
1. Video playlist
</nowiki></pre>
</nowiki></pre>


These playlists should not be confused with:
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).


The slideshow playlist. The slideshow commands implicitly refer to the latter.
== Command Tables Reference ==
Playlist files e.g m3u files.
 
 
The commands are presented in five sections. Those commands that:
The commands are presented in five sections. Those commands that:
* retrieve information
* retrieve information
* set/modify information
* set/modify information
Line 207: Line 243:
* HTTPAPI commands and examples
* HTTPAPI commands and examples


 
=== Commands that Retrieve Information ===
Assuming you have XBMC running and configured appropriately, clicking on the example link should load the link in your browser window. Then edit the link (if necessary): changing ''xbox'' to your Xbox IP (e.g. 192.168.1.101). As an example:
http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying -> http://192.168.1.101/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying
 
However, the most straightforward approach is to add xbox to your hosts file as described in the Getting Started section, after which you would not need to substiture your Xbox IP for ''xbox''.
 
Some of the examples will work straight off, others, which for example refer to a specific file, will need you to manually modify the link to appropriate values for your environment.
 
'%20' is used in some of the examples which is just an alternative way of indicating a space (' '). The reason for using %20 is just to ensure that the document formatting keeps the entire http:// string as one object. If you are typing the command in manually or using it from your own code then you can either use %20 or a space.
 
 
===Retrieving information commands===


<center>
<center>
Line 227: Line 251:
!width="30%"|Example
!width="30%"|Example
|-  
|-  
| GetMediaLocation(type; [path]; [option])
| GetMediaLocation(type; [path]; [option]; [lineStart; [numLines]])
| ''Type'' is one of music, video, pictures, files.
| ''Type'' is one of music, video, pictures, files.


Line 233: Line 257:


''option'' is one of pathsonly, showdate
''option'' is one of pathsonly, showdate
| http://xbox/xbmcCmds/xbmcHttp?command=GetMediaLocation&parameter=files;f:\;pathsonly
 
''lineStart'' is the first item in the list to return (first entry is 0 not 1) and ''numLines'' is the number of items to return. ''numLines'' cannot be specified without specifying ''lineStart''. If ''numLines'' is not specified then all entries from ''lineStart'' to the end of the list will be returned.
| http://xbox/xbmcCmds/xbmcHttp?command=GetMediaLocation(music;f:\;pathsonly)
Return only the first 10 items:
http://xbox/xbmcCmds/xbmcHttp?command=Getmedialocation(music;f:\music\;0;10)
 
Return the next 10 items:
http://xbox/xbmcCmds/xbmcHttp?command=Getmedialocation(music;f:\music\;10;10)
|-  
|-  
| GetShares(type; [option])
| GetShares(type; [option])
Line 239: Line 270:


''option'' is one of pathsonly, appendone
''option'' is one of pathsonly, appendone
| http://xbox/xbmcCmds/xbmcHttp?command=GetShares&parameter=music
| http://xbox/xbmcCmds/xbmcHttp?command=GetShares(music)
|-  
|-  
| GetCurrentPlaylist
| GetCurrentPlaylist
| Retrieves the current playlist identifier.
| Retrieves the current playlist identifier.
| http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentPlaylist
| http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentPlaylist()
|-  
|-  
| GetCurrentlyPlaying
| GetCurrentlyPlaying([thumbFilename],[nothingPlayingFilename],[onlyIfChanged],[extended],[slideThumbFilename])
| Retrieves the filename, details and status of the currently playing media.
| Retrieves the filename, details and status of the currently playing media.
If ''onlyIfChanged'' = true then information will only be returned if the media's status has changed since the last time this command was called. A tag has been added, Changed, that indicates whether the media has changed since the last time this command was called.
Additional functionality has been added to help simplify a browser based client's display of the current playing media's thumbnail. If ''thumbFilename'' is specified then on calling GetCurrentlyPlaying the current media's thumbnail is saved to the file ''thumbFilename''. This filename should include the absolute path on the XBox (from the perspective of XBMC) to where to store the thumbnail. The location should be such that it is exposed by XBMC's web server e.g. special:\\xbmc\web\thumb.jpg. ''nothingPlayingFilename'' is the thumbnail to display if nothing is currently playing. Again it should include the complete path to an image file from the perspective of XBMC (''nothingPlayingFilename'' is copied to ''thumbFilename'' when GetCurrentlyPlaying is called and nothing is playing). All the client needs to do is point their browser at the served address of ''thumbFilename''.
[Added 10 Feb 2010] If ''extended'' is ''true'' the command is extended to get additional responses while a slideshow and audo is playing. Prior to this extension the information returned (e.g. filename) just refered to the slideshow rather than the audio being played. Setting ''extended'' to ''true'' results in values such as ''SlideFilename'' (as well as ''Filename'') being returned.
| http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying
| http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying
http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying(special:\\xbmc\web\thumb.jpg)
http://xbox/thumb.jpg (this will display the thumbnail generated by the above call)
|-  
|-  
| GetCurrentSlide
| GetCurrentSlide
| Retrieves the file name of the image currently being displayed.
| Retrieves the file name of the image currently being displayed.
| http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentSlide
| http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentSlide()
|-  
|-  
| GetDirectory(directory;[mask];[option])
| GetDirectory(directory;[mask];[option]; [lineStart; [numLines]])
| Retrieves the contents of the directory specified by directory. If the option parameter = 1 then file modified dates will be appended. The mask parameter can take the following form: .mp3 returns just the matching files "*" return just folders all files and folders.
| Retrieves the contents of the directory specified by ''directory''.  
| http://xbox/xbmcCmds/xbmcHttp?command=GetDirectory&parameter=F:\music\;.mp3;1
 
If ''option'' = 1 ( or = showdate) then file modified dates will be appended.
 
''mask'' can take the following form: ''.mp3'' or ''[music]'' (and the obvious corresponding values for other media types and file extensions) and returns just the matching files. (To specify multiple file extensions use the bar "|" character e.g. ''.mp3|.wma''.) ''mask'' can also take the form: "*" or "/" and returns just folders. An empty ''mask'' (i.e."") returns all files and folders.
 
''lineStart'' is the first item in the list to return (first entry is 0 not 1) and ''numLines'' is the number of items to return. ''numLines'' cannot be specified without specifying ''lineStart''. If ''numLines'' is not specified then all entries from ''lineStart'' to the end of the list will be returned.
 
| http://xbox/xbmcCmds/xbmcHttp?command=GetDirectory(F:\music\;.mp3;1)
Return only the first 10 items:
http://xbox/xbmcCmds/xbmcHttp?command=GetDirectory(F:\music\;.mp3;1;0;10)
Return the next 10 items:
http://xbox/xbmcCmds/xbmcHttp?command=GetDirectory(F:\music\;.mp3;1;10;10)
|-  
|-  
| GetGuiDescription
| GetGuiDescription
| Retrieves various GUI values. (Currently just the screen resolution)
| Retrieves various GUI values. (Currently just the screen resolution)
| http://xbox/xbmcCmds/xbmcHttp?command=GetGUIDescription
| http://xbox/xbmcCmds/xbmcHttp?command=GetGUIDescription()
|-  
|-  
| GetGuiSetting(type; name)
| GetGuiSetting(type; name)
| Retrieves the value of GUI setting name. ''type'' specifies whether the setting is of type integer (0), boolean (1) or float (2) which must be set correctly or could cause a crash. ''name'' is the name of the setting to get the value of. For a list of setting names see GUISettings.cpp.
| Retrieves the value of GUI setting name. ''type'' specifies whether the setting is of type integer (0), boolean (1) or float (2) which must be set correctly or could cause a crash. ''name'' is the name of the setting to get the value of. For a list of setting names see GUISettings.cpp.
| http://xbox/xbmcCmds/xbmcHttp?command=getguisetting&parameter=0;system.shutdowntime
| http://xbox/xbmcCmds/xbmcHttp?command=getguisetting(0;system.shutdowntime)
|-
| GetGuiStatus()
| Retrieves various information about the status of the GUI.
| http://xbox/xbmcCmds/xbmcHttp?command=getGUIStatus()
|-
| GetMovieDetails(mediaPath)
| Retrieves details of the movie ''mediaPath''
| http://xbox/xbmcCmds/xbmcHttp?command=getMovieDetails(f:\movies\test.avi)
|-  
|-  
| GetPercentage
| GetPercentage
| Retrieves the current playing position of the currently playing media as a percentage of the media’s length.
| Retrieves the current playing position of the currently playing media as a percentage of the media’s length.
| http://xbox/xbmcCmds/xbmcHttp?command=getpercentage
| http://xbox/xbmcCmds/xbmcHttp?command=getpercentage()
|-  
|-  
| GetPlaylistContents([playlist])
| GetPlaylistContents([playlist])
| Retrieves the contents (file names) of the current playlist or the playlist specified by ''playlist''. Playlist takes one of the following values: 0 – Music playlist, 1 – Temporary music playlist, 2 – Video playlist, 3 – Temporary video playlist. (Since 26 Nov 2006: 0 - Music playlist, 1 - Video playlist)
| Retrieves the contents (file names) of the current playlist or the playlist specified by ''playlist''. Playlist takes one of the following values: 0 – Music playlist, 1 – Temporary music playlist, 2 – Video playlist, 3 – Temporary video playlist. (Since 26 Nov 2006: 0 - Music playlist, 1 - Video playlist)
| http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistContents&parameter=1
| http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistContents(1)
|-  
|-  
| GetPlaylistLength([playlist])
| GetPlaylistLength([playlist])
| Retrieves the length of the current playlist or the playlist specified by ''playlist''. [Added 27 Feb 07.]
| Retrieves the length of the current playlist or the playlist specified by ''playlist''.  
| http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistLength&parameter=0
| http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistLength(0)
|-  
|-  
| GetPlaylistSong([position])
| GetPlaylistSong([position])
| Retrieves the currently playing song number in the playlist. If the optional parameter ''position'' is provided the command will return the file name of the media at location ''position'' in the playlist.
| Retrieves the currently playing song number in the playlist. If the optional parameter ''position'' is provided the command will return the file name of the media at location ''position'' in the playlist.
| http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistSong
| http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistSong()
|-  
|-  
| GetPlaySpeed
| GetPlaySpeed
| Retrieves the current playing speed.
| Retrieves the current playing speed.
| http://xbox/xbmcCmds/xbmcHttp?command=GetPlaySpeed
| http://xbox/xbmcCmds/xbmcHttp?command=GetPlaySpeed()
|-
|-
| GetMusicLabel(item)
| GetMusicLabel(item)
| Retrieves audio information relating to the currently playing media. The specific information to retrieve is specied by ''info'' which is an integer corresponding to one of the MUSICPLAYER_* constants that can be found in GUIInfoManager.h The example retrieves the codec currently being used. [Added  4 Nov 07.]
| Retrieves audio information relating to the currently playing media. The specific information to retrieve is specied by ''info'' which is an integer corresponding to one of the MUSICPLAYER_* constants that can be found in GUIInfoManager.h The example retrieves the codec currently being used.  
| http://xbox/xbmcCmds/xbmcHttp?command=GetMusicLabel&parameter=217
| http://xbox/xbmcCmds/xbmcHttp?command=GetMusicLabel(217)
|-
| GetRecordStatus
| Retrieves whether XBMC is in record mode.
| http://xbox/xbmcCmds/xbmcHttp?command=GetRecordStatus()
|-
|-
| GetVideoLabel(item)
| GetVideoLabel(item)
| Retrieves video information relating to the currently playing media. The specific information to retrieve is specied by ''info'' which is an integer corresponding to one of the VIDEOPLAYER_* constants that can be found in GUIInfoManager.h The example retrieves the rating of the video currently being played. [Added  4 Nov 07.]
| Retrieves video information relating to the currently playing media. The specific information to retrieve is specied by ''info'' which is an integer corresponding to one of the VIDEOPLAYER_* constants that can be found in GUIInfoManager.h The example retrieves the rating of the video currently being played.  
| http://xbox/xbmcCmds/xbmcHttp?command=GetVideoLabel&parameter=270
| http://xbox/xbmcCmds/xbmcHttp?command=GetVideoLabel(270)
|-  
|-  
| GetSlideshowContents
| GetSlideshowContents
| Retrieves the contents (file names) of the slideshow playlist.
| Retrieves the contents (file names) of the slideshow playlist.
| http://xbox/xbmcCmds/xbmcHttp?command=GetSlideshowContents
| http://xbox/xbmcCmds/xbmcHttp?command=GetSlideshowContents()
|-  
|-  
| GetSystemInfo(InfoIds)
| GetSystemInfo(InfoIds)
| Retrives System Information by id number(the information on the system info page in xbmc). You can supply multipal numbers if you wish to retreive a bunch at a time. This sample will get Version of XBMC & Build Date. For a full list of Id's see GUIInfoManager.h.
| Retrives System Information by id number(the information on the system info page in xbmc). You can supply multipal numbers if you wish to retreive a bunch at a time. This sample will get Version of XBMC & Build Date. For a full list of Id's see GUIInfoManager.h.
| http://xbox/xbmcCmds/xbmcHttp?command=GetSystemInfo&parameter=120;121
| http://xbox/xbmcCmds/xbmcHttp?command=GetSystemInfo(120;121)
|-  
|-  
| GetSystemInfoByName(InfoNames)
| GetSystemInfoByName(InfoNames)
| Retrives System Information by name (the information on the system info page in xbmc). You can supply multipal names if you wish to retreive a bunch at a time. Go down to the "CGUIInfoManager::TranslateSingleString" section in GUIInfoManager.cpp and you will find all the InfoNames values
| Retrives System Information by name (the information on the system info page in xbmc). You can supply multipal names if you wish to retreive a bunch at a time. Go down to the "CGUIInfoManager::TranslateSingleString" section in GUIInfoManager.cpp and you will find all the InfoNames values
| http://xbox/xbmcCmds/xbmcHttp?command=GetSystemInfoByName&parameter=weather.location;weather.temperature
| http://xbox/xbmcCmds/xbmcHttp?command=GetSystemInfoByName(weather.location;weather.temperature)
|-  
|-  
| GetTagFromFilename(filename)
| GetTagFromFilename(filename)
| Retrieves information for the audio file ''filename''
| Retrieves information for the audio file ''filename''
| http://xbox/xbmcCmds/xbmcHttp?command=GetTagFromFilename&parameter=F:\music\test.mp3
| http://xbox/xbmcCmds/xbmcHttp?command=GetTagFromFilename(F:\music\test.mp3)
|-  
|-  
| GetThumbFilename(album;location)
| GetThumbFilename(album;location)
| Retrieves the file name of the corresponding thumbnail for the music media file with file name ''album'' and path ''location''
| Retrieves the file name of the corresponding thumbnail for the music media file with file name ''album'' and path ''location''
| http://xbox/xbmcCmds/xbmcHttp?command=GetThumbFilename&parameter=test.mp3;F:\music\
| http://xbox/xbmcCmds/xbmcHttp?command=GetThumbFilename(test.mp3;F:\music\)
|-  
|-  
| GetVolume
| GetVolume
| Retrieves the current volume setting as a percentage of the maximum possible value.
| Retrieves the current volume setting as a percentage of the maximum possible value.
| http://xbox/xbmcCmds/xbmcHttp?command=GetVolume
| http://xbox/xbmcCmds/xbmcHttp?command=GetVolume()
|-
| GetLogLevel
| Retrieves XBMC's current log level
| http://xbox/xbmcCmds/xbmcHttp?command=GetLogLevel()
|-
|-
| QueryMusicDatabase
| QueryMusicDatabase
| [Added 22 Oct 06] Provides a SQL interface to the XBMC Music Database. While this command is described in this section (Retrieving Information) it is possible to use it to modify the data base.  
| Provides a SQL interface to query the XBMC Music Database.
WARNING: The commands that modify the data base can obviously damage and/or lose information within it; but also some of the read commands can be so complex or retrieve so much data that it can impact the operation of XBMC e.g. retrieving all songs from a reasonably large data base can bring xbmc to its knees.
WARNING: Some of the read commands can be so complex or retrieve so much data that it can impact the operation of XBMC e.g. retrieving all songs from a reasonably large data base can bring xbmc to its knees.
| http://xbox/xbmcCmds/xbmcHttp?command=querymusicdatabase&parameter=select%20strArtist%20from%20artist%20order%20by%20strArtist
| http://xbox/xbmcCmds/xbmcHttp?command=querymusicdatabase(select%20strArtist%20from%20artist%20order%20by%20strArtist)


http://xbox/xbmcCmds/xbmcHttp?command=querymusicdatabase&parameter=select%20*%20from%20artist%20where%20strArtist%20LIKE%20'%%the%%'
http://xbox/xbmcCmds/xbmcHttp?command=querymusicdatabase(select%20*%20from%20artist%20where%20strArtist%20LIKE%20'%%the%%')
|-
|-
| QueryVideoDatabase
| QueryVideoDatabase
| [Added 23 Feb 07] Provides a SQL interface to the XBMC Video Database. See QueryMusicDatabase for further information.
| Provides a SQL interface to the XBMC Video Database. See QueryMusicDatabase for further information.
| http://xbox/xbmcCmds/xbmcHttp?command=queryvideodatabase&parameter=select%20path.strpath%20from%20path
| http://xbox/xbmcCmds/xbmcHttp?command=queryvideodatabase(select%20path.strpath%20from%20path)


|}
|}
</center>
</center>


===Setting commands===
=== Commands that Modify Settings ===


{| border=1 cellspacing=0 cellpadding=5
{| border=1 cellspacing=0 cellpadding=5
| <strong>Command</strong>
| '''Command'''
| <strong>Information</strong>
| '''Information'''
| <strong>Example</strong>
| '''Example'''
|-  
|-  
| AddToPlayList(media;[playlist];[mask])  
| AddToPlayList(media;[playlist];[mask];[recursive])  
| Adds a file or folder (media is either a file or a folder) to the current playlist or the playlist specified by ''playlist''. To specify a file mask use ''mask'' e.g. *.mp3.  
| Adds a file or folder (''media'' is either a file or a folder) to the current playlist or the playlist specified by ''playlist''. To specify a file mask use ''mask'' e.g. .mp3<nowiki>|</nowiki>.wma.
| http://xbox/xbmcCmds/xbmcHttp?command=AddToPlayList&parameter=F:/music/test2.mp3;1   
If ''recursive'' = "1" and ''media'' is a folder then all appropriate media within subfolders beneath ''media'' will be added otherwise only media within the folder ''media'' will be added. Default behaviour is to be recursive.
''mask'' can now also be set to one of the following values (including the square brackets) [music], [video], [pictures], [files] in which case XBMC's current set of file extensions for the type specified will be used as the mask.
| http://xbox/xbmcCmds/xbmcHttp?command=AddToPlayList(F:/music/test2.mp3;1)  
|-
| AddToPlayListFromDB(type;statement)
| Adds a set of items to the playlist using an SQL statement. The ''type'' parameter is one of the following: [songs], [movies], [episodes] or [musicvideos]. The ''statement'' is an SQL condition after the WHERE clause.
| http://xbox/xbmcCmds/xbmcHttp?command=AddToPlayListFromDB(songs;idAlbum=362)
|-
|-
| AddToSlideshow(media)  
| AddToSlideshow(media;[mask];[recursive])  
| Adds a file or folder (media is either a file or a folder) to the slideshow ''playlist''.
| Adds a file or folder (''media'' is either a file or a folder) to the slideshow playlist. To specify a file mask use ''mask'' e.g. .jpg<nowiki>|</nowiki>.bmp
| http://xbox/xbmcCmds/xbmcHttp?command=AddToSlideshow&parameter=F:\apps\xbmc\media\   
If ''recursive'' = "1" and ''media'' is a folder then all appropriate media within subfolders beneath ''media'' will be added otherwise only media within the folder ''media'' will be added. Default behaviour is to be recursive.
''mask'' can now also be set to one of the following values (including the square brackets) [music], [video], [pictures], [files] in which case XBMC's current set of file extensions for the type specified will be used as the mask. (Note it only makes much sense for this command to use a value of ''[pictures]''.
| http://xbox/xbmcCmds/xbmcHttp?command=AddToSlideshow(F:\apps\xbmc\media\)  
|-
|-
| ClearPlayList([playlist])  
| ClearPlayList([playlist])  
| Clears the current playlist or the playlist specified by ''playlist''.   
| Clears the current playlist or the playlist specified by ''playlist''.   
| http://xbox/xbmcCmds/xbmcHttp?command=ClearPlayList&parameter=1   
| http://xbox/xbmcCmds/xbmcHttp?command=ClearPlayList(1)  
|-
|-
| ClearSlideshow  
| ClearSlideshow  
| Clears the slideshow playlist.  
| Clears the slideshow playlist.  
| http://xbox/xbmcCmds/xbmcHttp?command=ClearSlideshow   
| http://xbox/xbmcCmds/xbmcHttp?command=ClearSlideshow()  
|-
|-
| RemoveFromPlaylist(filename,[playlist])  
| Mute
| Removes the file filename from the current playlist or from playlist ''playlist''.
| Toggles the sound on/off.
| http://xbox/xbmcCmds/xbmcHttp?command=RemoveFromPlaylist&parameter=f:\test2.mp3,1  
| http://xbox/xbmcCmds/xbmcHttp?command=Mute()
|-
| RemoveFromPlaylist(item,[playlist])  
| Removes media from the current playlist or from playlist ''playlist''. ''item'' can be either an integer specifying the position in the playlist of the item to be removed or the complete path (including filename) of the media to be removed. It is not possible to remove the media if it is currently being played.
| http://xbox/xbmcCmds/xbmcHttp?command=RemoveFromPlaylist(f:\test2.mp3;1)
|-
|-
| SeekPercentage  
| SeekPercentage  
| Sets the playing position of the currently playing media as a percentage of the media’s length.   
| Sets the playing position of the currently playing media as a percentage of the media’s length.   
| http://xbox/xbmcCmds/xbmcHttp?command=SeekPercentage&parameter=50   
| http://xbox/xbmcCmds/xbmcHttp?command=SeekPercentage(50)  
|-
|-
| SeekPercentageRelative  
| SeekPercentageRelative  
| Adds/Subtracts the current percentage on to the current postion in the song   
| Adds/Subtracts the current percentage on to the current postion in the song   
| http://xbox/xbmcCmds/xbmcHttp?command=SeekPercentageRelative&parameter=-10   
| http://xbox/xbmcCmds/xbmcHttp?command=SeekPercentageRelative(-10)  
|-
|-
| SetCurrentPlaylist(playlist)  
| SetCurrentPlaylist(playlist)  
| Sets the current playlist to ''playlist''.   
| Sets the current playlist to ''playlist''.   
| http://xbox/xbmcCmds/xbmcHttp?command=SetCurrentPlaylist&parameter=1   
| http://xbox/xbmcCmds/xbmcHttp?command=SetCurrentPlaylist(1)  
|-
|-
| SetGUISetting(type; name; value)  
| SetGUISetting(type; name; value)  
| Sets the value of GUI setting name to value. ''Type'' specifies whether the setting is of type integer (0), boolean (1) or float (2) which must be set correctly or could cause a crash. For a full list of setting names see GUISettings.cpp.
| Sets the value of GUI setting name to value. ''Type'' specifies whether the setting is of type integer (0), boolean (1) or float (2) which must be set correctly or could cause a crash. For a full list of setting names see GUISettings.cpp.
| http://xbox/xbmcCmds/xbmcHttp?command=SetGUISetting&parameter=0;system.shutdowntime;10
| http://xbox/xbmcCmds/xbmcHttp?command=SetGUISetting(0;system.shutdowntime;10)
|-
|-
| SetPlaylistSong(position)  
| SetPlaylistSong(position)  
| Sets the media at playlist position ''position'' to be the next item to be played. The example sets the position to the 6th song in the playlist  
| Sets the media at playlist position ''position'' to be the next item to be played. The example sets the position to the 6th song in the playlist  
| http://xbox/xbmcCmds/xbmcHttp?command=SetPlaylistSong&parameter=5   
| http://xbox/xbmcCmds/xbmcHttp?command=SetPlaylistSong(5)  
|-
|-
| SetPlaySpeed(speed)  
| SetPlaySpeed(speed)  
| Sets the playing speed to the integer ''speed''.  
| Sets the playing speed to the integer ''speed''.  
| http://xbox/xbmcCmds/xbmcHttp?command=SetPlaySpeed&parameter(speed)   
| http://xbox/xbmcCmds/xbmcHttp?command=SetPlaySpeed(speed)   
|-
|-
| SlideshowSelect(filename)  
| SlideshowSelect(filename)  
| Sets the slideshow playlist position by specifying the file name of the next image to show.   
| Sets the slideshow playlist position by specifying the file name of the next image to show.   
| http://xbox/xbmcCmds/xbmcHttp?command=SlideshowSelect&parameter=filename
| http://xbox/xbmcCmds/xbmcHttp?command=SlideshowSelect(filename)
|-
|-
| SetVolume  
| SetVolume  
| Sets the volume as a percentage of the maximum possible.   
| Sets the volume as a percentage of the maximum possible.   
| http://xbox/xbmcCmds/xbmcHttp?command=SetVolume&parameter=50   
| http://xbox/xbmcCmds/xbmcHttp?command=SetVolume(50)  
|-
| SetLogLevel
| Sets XBMC's log level 
| http://xbox/xbmcCmds/xbmcHttp?command=SetLogLevel(1)
|-
|-
| SetAutoGetPictureThumbs  
| SetAutoGetPictureThumbs  
| If set to True then media thumbnails will be automatically created when required. (Default: True.)  
| If set to True then media thumbnails will be automatically created when required. (Default: True.)  
| http://xbox/xbmcCmds/xbmcHttp?command=SetAutoGetPictureThumbs&parameter=false   
| http://xbox/xbmcCmds/xbmcHttp?command=SetAutoGetPictureThumbs(false)  
|-
| Swapplaylistitems(playlist;item1;item2)
| Here item1 and item2 are either offsets in the playlist, or the path to an item.
| http://xbox/xbmcCmds/xbmcHttp?command=Swapplaylistitems(playlist.pls;5;2)
|}
|}


===Action commands===
=== Commands that Generate Actions ===


{| border=1 cellspacing=0 cellpadding=5
{| border=1 cellspacing=0 cellpadding=5
| <strong>Command</strong>
| '''Command'''
| <strong>Information</strong>
| '''Information'''
| <strong>Example</strong>
| '''Example'''
|-  
|-  
| Action
| Action
| Sends a raw Action ID (see key.h) to xbmc. Be careful with this one since it runs the action on the webserver thread and depending on the action could lock the GUI thread. The example sends ACTION_MOVE_DOWN. [Added 19th June 2007]
| Sends a raw Action ID (see [http://trac.xbmc.org/browser/branches/linuxport/XBMC/guilib/Key.h?rev=16176]) to xbmc. Be careful with this one since it runs the action on the webserver thread and depending on the action could lock the GUI thread. The example sends ACTION_MOVE_DOWN.  
| http://xbox/xbmcCmds/xbmcHttp?command=Action&parameter=4
| http://xbox/xbmcCmds/xbmcHttp?command=Action(4)
|-  
|-  
| Exit  
| Exit  
| Reboots to dashboard  
| Reboots to dashboard  
| http://xbox/xbmcCmds/xbmcHttp?command=Exit   
| http://xbox/xbmcCmds/xbmcHttp?command=Exit() 
|-
| KeyRepeat(rate)
| Sets whether and how fast a key sent using SendKey should repeat. ''rate'' is the repeat rate in milliseconds (e.g. 1000 = 1s). ''rate'' = 0 stops keys repeating.
| http://xbox/xbmcCmds/xbmcHttp?command=KeyRepeat(1000)  
|-
|-
| Move(deltaX, deltaY)  
| Move(deltaX, deltaY)  
| Moves the currently displayed and ZOOMed (see zoom command below) image by the distance specified by deltaX and deltaY. The zoom magnification must be greater than 0 or the command has no effect.
| Moves the currently displayed and ZOOMed (see zoom command below) image by the distance specified by deltaX and deltaY. The zoom magnification must be greater than 0 or the command has no effect.
| http://xbox/xbmcCmds/xbmcHttp?command=Move&parameter=50;20   
| http://xbox/xbmcCmds/xbmcHttp?command=Move(50;20) 
|-
| Pause
| Pauses the currently playing media. If a slideshow and audio is active only the slideshow is paused.
| http://xbox/xbmcCmds/xbmcHttp?command=Pause() 
|-
| PauseExSlide
| [Added 10 Feb 2010] Pauses the currently playing media unless a slideshow and audio is active in which case it just pauses the audio.
| http://xbox/xbmcCmds/xbmcHttp?command=PauseExSlide()  
|-
|-
| PlayListNext  
| PlayListNext  
Line 424: Line 521:
| PlayNext  
| PlayNext  
| Starts playing/showing the next media/image in the current playlist or, if currently showing a slidshow, the slideshow playlist.  
| Starts playing/showing the next media/image in the current playlist or, if currently showing a slidshow, the slideshow playlist.  
| http://xbox/xbmcCmds/xbmcHttp?command=PlayNext   
| http://xbox/xbmcCmds/xbmcHttp?command=PlayNext() 
|-
| PlayNextExSlide
| [Added 10 Feb 2010] Starts playing/showing the next media/image in the current playlist or, if currently showing a slidshow, the audio playlist.
| http://xbox/xbmcCmds/xbmcHttp?command=PlayNextExSlide()  
|-
|-
| PlayPrev  
| PlayPrev  
| Starts playing/showing the previous media/image in the current playlist or, if currently showing a slidshow, the slideshow playlist.  
| Starts playing/showing the previous media/image in the current playlist or, if currently showing a slidshow, the slideshow playlist.  
| http://xbox/xbmcCmds/xbmcHttp?command=PlayPrev   
| http://xbox/xbmcCmds/xbmcHttp?command=PlayPrev() 
|-
| PlayPrevExSlide
| [Added 10 Feb 2010] Starts playing/showing the previous media/image in the current playlist or, if currently showing a slidshow, the audio playlist.
| http://xbox/xbmcCmds/xbmcHttp?command=PlayPrevExSlide()  
|-
|-
| PlaySlideshow([directory];[recursive])  
| PlaySlideshow([directory];[recursive])  
| Starts the slideshow. Directory specifies a folder of images to add to the slideshow playlist. If recursive has a value of True then all directories beneath ''directory'' are searched for images and added to the slideshow playlist.  
| Starts the slideshow. Directory specifies a folder of images to add to the slideshow playlist. If recursive has a value of True then all directories beneath ''directory'' are searched for images and added to the slideshow playlist.  
| http://xbox/xbmcCmds/xbmcHttp?command=PlaySlideshow&parameter=F:\pictures;true   
| http://xbox/xbmcCmds/xbmcHttp?command=PlaySlideshow(F:\pictures;true)  
|-
|-
| PlayFile(filename)  
| PlayFile(filename;[playlist])  
| Starts playing the media file ''filename'' on the current playlist.  
| Starts playing the media file ''filename'' on playlist ''playlist'' or if ''playlist'' is not specified the current playlist.  
| http://xbox/xbmcCmds/xbmcHttp?command=PlayFile&parameter=F:\music\test.mp3
| http://xbox/xbmcCmds/xbmcHttp?command=PlayFile(F:\music\test.mp3)
|-
|-
| Reset  
| Reset  
| Resets XBMC  
| Resets XBMC  
| http://xbox/xbmcCmds/xbmcHttp?command=Reset   
| http://xbox/xbmcCmds/xbmcHttp?command=Reset()  
|-
|-
| Restart  
| Restart  
| Restarts XBOX  
| Restarts XBOX  
| http://xbox/xbmcCmds/xbmcHttp?command=Restart   
| http://xbox/xbmcCmds/xbmcHttp?command=Restart() 
|-
| RestartApp
| Restarts XBMC
| http://xbox/xbmcCmds/xbmcHttp?command=RestartApp()  
|-
|-
| Rotate  
| Rotate  
| Rotates the currently displayed image by 90 degree clockwise.  
| Rotates the currently displayed image by 90 degree clockwise.  
| http://xbox/xbmcCmds/xbmcHttp?command=Rotate   
| http://xbox/xbmcCmds/xbmcHttp?command=Rotate()  
|-
|-
| SendKey(buttoncode;[LeftTrigger];[RightTrigger];[LeftThumbX];[LeftThumbY] ;[RightThumbX];[RightThumbY])  
| SendKey(buttoncode;[LeftTrigger];[RightTrigger];[LeftThumbX];[LeftThumbY] ;[RightThumbX];[RightThumbY])  
| Initiates a button, key or mouse event. Buttoncode specifies the type of event and the other parameters specify additional information that is specific to each buttoncode value. See key.h for the the list of keycodes. The example raises the A button event.  
| Initiates a button, key or mouse event. Buttoncode specifies the type of event and the other parameters specify additional information that is specific to each buttoncode value. See [http://xbmc.svn.sourceforge.net/viewvc/xbmc/trunk/guilib/Key.h?view=markup key.h] for the the list of keycodes. The example calls the shutdown menu.  
* To send a button event just set buttoncode to the appropriate value from Key.h
* To send a button event just set buttoncode to the appropriate value from Key.h
* To send a keyboard event set buttoncode to F100 (hex) and add the required key’s ASCII value.
* To send a virtual keyboard event set buttoncode to 0xF100 (hex) and add the required key’s ASCII value.
* To send a keyboard event set buttoncode to 0xF000 (hex) and add the required key’s ASCII value.
* (Experimental) To send a mouse event set buttoncode to EFFF (hex) , then set the following parameters:
* (Experimental) To send a mouse event set buttoncode to EFFF (hex) , then set the following parameters:
** LeftThumbX – mouse x position
** LeftThumbX – mouse x position
Line 459: Line 569:
** LeftTrigger – indicates a single mouse click and takes a value of one of 1-left button, 2-right button, 3-middle button.
** LeftTrigger – indicates a single mouse click and takes a value of one of 1-left button, 2-right button, 3-middle button.
** RightTrigger– indicates a double mouse click and takes a value of one of 1-left button, 2-right button, 3-middle button.
** RightTrigger– indicates a double mouse click and takes a value of one of 1-left button, 2-right button, 3-middle button.
| http://xbox/xbmcCmds/xbmcHttp?command=SendKey&parameter=256 
| http://xbox/xbmcCmds/xbmcHttp?command=SendKey(0xF053)
http://xbox/xbmcCmds/xbmcHttp?command=SendKey(61523)
|-
|-
| ShowPicture(filename)  
| ShowPicture(filename)  
| Displays the image ''filename''.  
| Displays the image ''filename''.  
| http://xbox/xbmcCmds/xbmcHttp?command=ShowPicture&parameter=F:\apps\xbmc\media\splash.png   
| http://xbox/xbmcCmds/xbmcHttp?command=ShowPicture(F:\apps\xbmc\media\splash.png)  
|-
|-
| Shutdown  
| Shutdown  
| Shutdown XBOX  
| Shutdown XBOX  
| http://xbox/xbmcCmds/xbmcHttp?command=Shutdown   
| http://xbox/xbmcCmds/xbmcHttp?command=Shutdown()  
|-
| SpinDownHardDisk
| If possible stops the hard disk (saves power / quieter)
| http://xbox/xbmcCmds/xbmcHttp?command=SpinDownHardDisk()
|-
| Stop
| Stops the currently playing media. If a slideshow and audio is active only the slideshow is stopped.
| http://xbox/xbmcCmds/xbmcHttp?command=Stop()
|-
| StopExSlide
| [Added 10 Feb 2010] Stops the currently playing media. If a slideshow and audio is active only the audio is stopped.
| http://xbox/xbmcCmds/xbmcHttp?command=StopExSlide()
|-
|-
| TakeScreenshot([filename];[flash];[rotation];[width];[height];[quality];[download];[imgtag])   
| TakeScreenshot([filename];[flash];[rotation];[width];[height];[quality];[download];[imgtag])   
Line 492: Line 615:


NEW: imgtag is new it will put a Convert Base64 to image tag with the Base64 code so in firefox browsers it will show the image instead of the Base64 code.
NEW: imgtag is new it will put a Convert Base64 to image tag with the Base64 code so in firefox browsers it will show the image instead of the Base64 code.
| http://xbox/xbmcCmds/xbmcHttp?command=takescreenshot&parameter=test.jpg;true;0;300;200;90;true;imgtag   
| http://xbox/xbmcCmds/xbmcHttp?command=takescreenshot(test.jpg;true;0;300;200;90;true;imgtag)  
|-
|-
| Zoom(magnification)  
| Zoom(magnification)  
| Zooms the currently displayed image to a level specified by magnifaction. A magnification of 0 is the standard zoom level of none. Magnification can take values up to 8.   
| Zooms the currently displayed image to a level specified by magnifaction. A magnification of 0 is the standard zoom level of none. Magnification can take values up to 8.   
| http://xbox/xbmcCmds/xbmcHttp?command=Zoom&parameter=4   
| http://xbox/xbmcCmds/xbmcHttp?command=Zoom(4)  
|}
|}


===File Commands===
=== Commands that Modify Files ===


{| border=1 cellspacing=0 cellpadding=5
{| border=1 cellspacing=0 cellpadding=5
| <strong>Command</strong>
| '''Command'''
| <strong>Information</strong>
| '''Information'''
| <strong>Example</strong>
| '''Example'''
|-
|-
| FileCopy(sourceFilename, destinationFilename)  
| FileCopy(sourceFilename, destinationFilename)  
| Copies the Xbox file ''sourceFilename'' to the Xbox file ''desitinationFilename''.   
| Copies the Xbox file ''sourceFilename'' to the Xbox file ''desitinationFilename''.   
| http://xbox/xbmcCmds/xbmcHttp?command=FileCopy&parameter=F:\apps\xbmc\media\splash.png;E:\pictures\   
| http://xbox/xbmcCmds/xbmcHttp?command=FileCopy(F:\apps\xbmc\media\splash.png;E:\pictures\)  
|-
|-
| FileDelete(filename)  
| FileDelete(filename)  
| Deletes the Xbox file ''filename''.  
| Deletes the Xbox file ''filename''.  
| http://xbox/xbmcCmds/xbmcHttp?command=FileDelete&parameter=F:\pictures\kim-smith-1024x768–22677.jpg   
| http://xbox/xbmcCmds/xbmcHttp?command=FileDelete(F:\pictures\kim-smith-1024x768–22677.jpg)  
|-
|-
| FileDownload(filename)  
| FileDownload(filename;[bare])  
| Download a file specified by ''filename'' from the Xbox to the client as a base64 stream.
| Download a file specified by ''filename'' from the Xbox to the client as a base64 stream. If the optional parameter 'bare' is specified the webheader and webfooter won't be included which results in just a raw base64 stream.
| http://xbox/xbmcCmds/xbmcHttp?command=FileDownload&parameter=F:\apps\xbmc\default.xbe   
| http://xbox/xbmcCmds/xbmcHttp?command=FileDownload(F:\apps\xbmc\default.xbe)  
|-
|-
| FileDownloadFromInternet(URL;[filename])  
| FileDownloadFromInternet(URL;[filename];[bare])  
| Downloads the file with address ''URL'' to the client as a base64 encoded stream. If the filename parameter is present, the downloaded file is also saved on the Xbox as the file ''filename''.
| Downloads the file with address ''URL'' to the client as a base64 encoded stream. If the filename parameter is present, the downloaded file is also saved on the Xbox as the file ''filename''. If the optional parameter 'bare' is specified the webheader and webfooter won't be included which results in just a raw base64 stream.
| http://xbox/xbmcCmds/xbmcHttp?command=FileDownloadFromInternet&parameter=http://wallpapers.skins.be/kim-smith/kim-smith-1024x768–22677.jpg;F:\pictures\kim-smith-1024x768–22677.jpg <br>
| http://xbox/xbmcCmds/xbmcHttp?command=FileDownloadFromInternet(http://wallpapers.skins.be/kim-smith/kim-smith-1024x768–22677.jpg;F:\pictures\kim-smith-1024x768–22677.jpg) <br />
To test quickly: http://xbox/xbmcCmds/xbmcHttp?command=ShowPicture&parameter=F:\pictures\kim-smith-1024x768–22677.jpg   
To test quickly: http://xbox/xbmcCmds/xbmcHttp?command=ShowPicture(F:\pictures\kim-smith-1024x768–22677.jpg)  
|-
|-
| FileExists(filename)  
| FileExists(filename)  
| Returns True if the Xbox file ''filename'' exists otherwise returns False.   
| Returns True if the Xbox file ''filename'' exists otherwise returns False.   
| http://xbox/xbmcCmds/xbmcHttp?command=FileExists&parameter=F:\pictures\kim-smith-1024x768–22677.jpg   
| http://xbox/xbmcCmds/xbmcHttp?command=FileExists(F:\pictures\kim-smith-1024x768–22677.jpg)  
|-
|-
| FileSize(filename)  
| FileSize(filename)  
| Returns the file size of ''filename''.  
| Returns the file size of ''filename''.  
| http://xbox/xbmcCmds/xbmcHttp?command=FileSize&parameter=F:\pictures\kim-smith-1024x768–22677.jpg   
| http://xbox/xbmcCmds/xbmcHttp?command=FileSize(F:\pictures\kim-smith-1024x768–22677.jpg)  
|-
|-
| FileUpload(filename, contents)  
| FileUpload(filename, contents)  
| Uploads a file encoded as a base64 string ''contents'' to the file ''filename'' on the Xbox. The example creates on the xbox the file f:\test.txt with the contents ''hello''.
| Uploads a file encoded as a base64 string ''contents'' to the file ''filename'' on the Xbox. The example creates on the xbox the file f:\test.txt with the contents ''hello''.
| http://xbox/xbmcCmds/xbmcHttp?command=fileUpload&parameter=f:\test.txt;aGVsbG8%3d  
| http://xbox/xbmcCmds/xbmcHttp?command=fileUpload(f:\test.txt;aGVsbG8%3d)
|}
|}


===Miscellaneous commands===
=== Miscellaneous Commands ===


{| border=1 cellspacing=0 cellpadding=5
{| border=1 cellspacing=0 cellpadding=5
| <strong>Command</strong>
| '''Command'''
| <strong>Information</strong>
| '''Information'''
| <strong>Example</strong>
| '''Example'''
|-   
|-   
| ChooseAlbum(URL)  
| ChooseAlbum(URL)  
| Retrieves the cover image and review text of the album with URL ''URL'' as returned by the LookupAlbum command. The URL must be encoded using the standard %xx format([http://www.rfc-editor.org/rfc/rfc1738.txt RFC1738]) before being passed to the API. The example here is passing the URL http://www.allmusic.com/cg/amg.dll?p=amg&sql=10:7vz1z87a6yvn
| Retrieves the cover image and review text of the album with URL ''URL'' as returned by the LookupAlbum command. The URL must be encoded using the standard %xx format([http://www.rfc-editor.org/rfc/rfc1738.txt RFC1738]) before being passed to the API. The example here is passing the URL http://www.allmusic.com/cg/amg.dll?p=amg&sql=10:7vz1z87a6yvn
| http://xbox/xbmcCmds/xbmcHttp?command=choosealbum&parameter=http%3a%2f%2fwww%2eallmusic%2ecom%2fcg%2famg%2edll%3fp%3damg%26sql%3d10%3a7r6cmpea9f8o   
| http://xbox/xbmcCmds/xbmcHttp?command=choosealbum(http%3a%2f%2fwww%2eallmusic%2ecom%2fcg%2famg%2edll%3fp%3damg%26sql%3d10%3a7r6cmpea9f8o) 
|-
| LookupAlbum(album[;artist;boolRelevance])
|
Looks up the album with name ''album'' on an Internet music site and returns the resulting matches as a list with the format: album_name<@@>album_URL
 
If boolRelevance has a value of ''1'' a relevance score (ranging from 1 (perfect) to 0) will also be returned with the following format: album_name<@@>album_URL<@@@>score
 
When requesting releveance scores it is best to include a value for the artist but it is not necessary.
| http://xbox/xbmcCmds/xbmcHttp?command=lookupalbum(On%20an%20Island)
   
http://xbox/xbmcCmds/xbmcHttp?command=lookupalbum(On%20an%20Island;david%20gilmour;1)
|-
|-
| Config(command; parameters)  
| Config(command; parameters)  
Line 554: Line 688:


http://xbox/xbmcCmds/xbmcHttp?command=Config(getbookmark;music;path;1)   
http://xbox/xbmcCmds/xbmcHttp?command=Config(getbookmark;music;path;1)   
 
|-
| WebServerStatus([status])
| If no parameter is provided the function returns the status of the WebServer (On or Off). Where a parameter is provided ''status'' must be either ''on'' (turns the WebServer on) or ''off'' (turns the WebServer off). Note that only Python scripts can use the version with the parameter.
| http://xbox/xbmcCmds/xbmcHttp?command=WebServerStatus()
|-
|-
| ExecBuiltIn(function)  
| ExecBuiltIn(function)  
| Executes the XBMC ‘built-in’ function ''function''. For the list of available functions see: [[List_of_Built_In_Functions]] OR ExecBuiltIn Functions  
| Executes the XBMC ‘built-in’ function ''function''. For the list of available functions see: the list of Built In Functions OR ExecBuiltIn Functions  
| http://xbox/xbmcCmds/xbmcHttp?command=ExecBuiltIn&parameter=Notification(WARNING,SHUTTING%20DOWN%20SYSTEM!)   
| http://xbox/xbmcCmds/xbmcHttp?command=ExecBuiltIn(Notification(WARNING,SHUTTING%20DOWN%20SYSTEM!))   
|-
|-
| Help  
| Help  
| Displays a list of some (NOT ALL) of the HTTPApi commands  
| Displays a list of some (NOT ALL) of the HTTPApi commands  
| http://xbox/xbmcCmds/xbmcHttp?command=Help
| http://xbox/xbmcCmds/xbmcHttp?command=Help()   
|-
| LookupAlbum(album[;artist;boolRelevance])
| [the form with the optional parameters added 11 Aug 07]
Looks up the album with name ''album'' on an Internet music site and returns the resulting matches as a list with the format: album_name<@@>album_URL
 
If boolRelevance has a value of ''1'' a relevance score (ranging from 1 (perfect) to 0) will also be returned with the following format: album_name<@@>album_URL<@@@>score
 
When requesting releveance scores it is best to include a value for the artist but it is not necessary.
| http://xbox/xbmcCmds/xbmcHttp?command=lookupalbum&parameter=On%20an%20Island
   
http://xbox/xbmcCmds/xbmcHttp?command=lookupalbum&parameter=On%20an%20Island;david%20gilmour;1
|-
|-
|SetResponseFormat(format; value)   
|SetResponseFormat(format; value)   
Line 610: Line 736:




[Added 22 Oct 2006]
 


Additional tags added and their default values (formats the response from the QueryMusicDatabase command):
Additional tags added and their default values (formats the response from the QueryMusicDatabase command):
Line 629: Line 755:


SetResponseFormat without any parameters returns the formatting to the default values (as would restarting xbmc).
SetResponseFormat without any parameters returns the formatting to the default values (as would restarting xbmc).
| http://xbox/xbmcCmds/xbmcHttp?command=SetResponseFormat&parameter=WebHeader;False
| http://xbox/xbmcCmds/xbmcHttp?command=SetResponseFormat(WebHeader;False)
 
[[Added 22 Oct 2006]


The following sets up an XML formatted response (if viewing the output in a browser you will neeed to use the view source command to see the xml tags).
The following sets up an XML formatted response (if viewing the output in a browser you will neeed to use the view source command to see the xml tags).


<nowiki>http://xbox/xbmcCmds/xbmcHttp?command=setresponseformat&parameter=webheader;false;webfooter;false;header;<xml>;footer;</xml>;opentag;<tag>;closetag;</tag>;closefinaltag;true</nowiki>
<nowiki>http://xbox/xbmcCmds/xbmcHttp?command=setresponseformat(webheader;false;webfooter;false;header;<xml>;footer;</xml>;opentag;<tag>;closetag;</tag>;closefinaltag;true)</nowiki>


Then the same for the QueryMusicDatabase response:
Then the same for the QueryMusicDatabase response:


<nowiki>http://xbox/xbmcCmds/xbmcHttp?command=setresponseformat&parameter=openRecordSet;<recordset>;closeRecordSet;</recordset>;openRecord;<record>;closeRecord;</record>;openField;<field>;closeField;</field></nowiki>
<nowiki>http://xbox/xbmcCmds/xbmcHttp?command=setresponseformat(openRecordSet;<recordset>;closeRecordSet;</recordset>;openRecord;<record>;closeRecord;</record>;openField;<field>;closeField;</field>)</nowiki>


Now set everything back to the default:
Now set everything back to the default:


http://xbox/xbmcCmds/xbmcHttp?command=SetResponseFormat
http://xbox/xbmcCmds/xbmcHttp?command=SetResponseFormat()
|-
|-
| getXBETitle(path)
| getXBETitle(path)
| [Added 16 Jan 07] Return the Title/Description of the specifed XBE
| Return the Title/Description of the specifed XBE
| http://xbox/xbmcCmds/xbmcHttp?command=getxbetitle&parameter=Q:\default.xbe
| http://xbox/xbmcCmds/xbmcHttp?command=getxbetitle(special:\\xbmc\default.xbe)
|-
|-
| getXBEid(path)
| getXBEid(path)
| [Added 16 Jan 07] Returns the id of a specifed XBE
| [Returns the id of a specifed XBE
| http://xbox/xbmcCmds/xbmcHttp?command=getxbeid&parameter=Q:\default.xbe
| http://xbox/xbmcCmds/xbmcHttp?command=getxbeid(special:\\xbmc\default.xbe)
|}
|}


===Broadcast Commands===
=== Broadcast Commands ===


{| border=1 cellspacing=0 cellpadding=5
{| border=1 cellspacing=0 cellpadding=5
| <strong>Command</strong>
| '''Command'''
| <strong>Information</strong>
| '''Information'''
| <strong>Example</strong>
| '''Example'''
|-   
|-   
| Broadcast(message;port)  
| Broadcast(message;port)  
| Not sure if there is much point to this command - probably could be used to test a client listening for broadcasts. If the port parameter is not specified then the currently set default port will be used.
| Not sure if there is much point to this command - probably could be used to test a client listening for broadcasts. If the port parameter is not specified then the currently set default port will be used.
| http://xbox/xbmcCmds/xbmcHttp?command=Broadcast&parameter=hello_from_xbmc  
| http://xbox/xbmcCmds/xbmcHttp?command=Broadcast(hello_from_xbmc)
|-
|-
| SetBroadcast(level;port)
| SetBroadcast(level;port)
| Sets the brodcast level and port. Level currently only takes three values: 0 - no broadcasts, 1 - media playback and startup & shutdown events, 2 - "OnAction" events (e.g. buttons) as well as level 1 events. Port is optional and if specified sets the default broadcast port value.
| Sets the brodcast level and port.  
| http://xbox/xbmcCmds/xbmcHttp?command=SetBroadcast&parameter=1
''Leve''l currently takes three values: 0 - no broadcasts, 1 - media playback and startup & shutdown events, 2 - "OnAction" events (e.g. buttons) as well as level 1 events. [Added Jan 2010] In addition adding 128 to this value changes the format of the broadcast to include the IP address of the XBMC box sending the broadcast. [Added 21 March 2010 (rev 28740)] In addition adding 256 to this value changes the format of the broadcast to include the port number (as well as the IP address) of the XBMC box sending the broadcast. (Useful for when there are multiple XBMC boxes present.)
 
''Port'' is optional and if specified sets the default broadcast port value.
| http://xbox/xbmcCmds/xbmcHttp?command=SetBroadcast(1)
|-
|-
| GetBroadcast()
| GetBroadcast()
| Returns the current level and port settings.
| Returns the current level and port settings.
| http://xbox/xbmcCmds/xbmcHttp?command=GetBroadcast
| http://xbox/xbmcCmds/xbmcHttp?command=GetBroadcast()
|}
|}


===Name Changes===
=== Name Changes ===


To make the names of the commands more logical some have been changed. The old names are still recognised but it is strongly advised that the new names are now used.
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.


{| border=1 cellspacing=0 cellpadding=5
{| border=1 cellspacing=0 cellpadding=5
| <strong>Old Name</strong>
| '''Old Name'''
| <strong>New Name</strong>
| '''New Name'''
|-
|-
| CopyFile
| CopyFile
Line 703: Line 830:
| SendKey
| SendKey
|}
|}
[[Category:Inner Workings]]
[[Category:Development]]
[[category:Python]]
[[category:Skin Development]]

Latest revision as of 07:02, 16 July 2020

Emblem-important-yellow.png THIS API IS DEPRECATED

As of the Dharma release of XBMC, this API is deprecated.
As of the Frodo release of XBMC, this API is no longer available.
Use the JSON-RPC_API interface instead.

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 <li>. 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 <li> tag does not require a corresponding close tag i.e. </li> 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 <b></b> 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:

Command Information Example
SetVolume Sets the volume as a percentage of the maximum possible. http://xbox/xbmcCmds/xbmcHttp?command=SetVolume(50)

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

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.

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

Commands that Retrieve Information

Command Information Example
GetMediaLocation(type; [path]; [option]; [lineStart; [numLines]]) Type is one of music, video, pictures, files.

path is the path.

option is one of pathsonly, showdate

lineStart is the first item in the list to return (first entry is 0 not 1) and numLines is the number of items to return. numLines cannot be specified without specifying lineStart. If numLines is not specified then all entries from lineStart to the end of the list will be returned.

http://xbox/xbmcCmds/xbmcHttp?command=GetMediaLocation(music;f:\;pathsonly)

Return only the first 10 items: 

http://xbox/xbmcCmds/xbmcHttp?command=Getmedialocation(music;f:\music\;0;10)

Return the next 10 items: 

http://xbox/xbmcCmds/xbmcHttp?command=Getmedialocation(music;f:\music\;10;10)
GetShares(type; [option]) Type is one of music, video, pictures, files.

option is one of pathsonly, appendone

http://xbox/xbmcCmds/xbmcHttp?command=GetShares(music)
GetCurrentPlaylist Retrieves the current playlist identifier. http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentPlaylist()
GetCurrentlyPlaying([thumbFilename],[nothingPlayingFilename],[onlyIfChanged],[extended],[slideThumbFilename]) Retrieves the filename, details and status of the currently playing media.

If onlyIfChanged = true then information will only be returned if the media's status has changed since the last time this command was called. A tag has been added, Changed, that indicates whether the media has changed since the last time this command was called.

Additional functionality has been added to help simplify a browser based client's display of the current playing media's thumbnail. If thumbFilename is specified then on calling GetCurrentlyPlaying the current media's thumbnail is saved to the file thumbFilename. This filename should include the absolute path on the XBox (from the perspective of XBMC) to where to store the thumbnail. The location should be such that it is exposed by XBMC's web server e.g. special:\\xbmc\web\thumb.jpg. nothingPlayingFilename is the thumbnail to display if nothing is currently playing. Again it should include the complete path to an image file from the perspective of XBMC (nothingPlayingFilename is copied to thumbFilename when GetCurrentlyPlaying is called and nothing is playing). All the client needs to do is point their browser at the served address of thumbFilename. [Added 10 Feb 2010] If extended is true the command is extended to get additional responses while a slideshow and audo is playing. Prior to this extension the information returned (e.g. filename) just refered to the slideshow rather than the audio being played. Setting extended to true results in values such as SlideFilename (as well as Filename) being returned.

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

http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying(special:\\xbmc\web\thumb.jpg)

http://xbox/thumb.jpg (this will display the thumbnail generated by the above call)

GetCurrentSlide Retrieves the file name of the image currently being displayed. http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentSlide()
GetDirectory(directory;[mask];[option]; [lineStart; [numLines]]) Retrieves the contents of the directory specified by directory.

If option = 1 ( or = showdate) then file modified dates will be appended.

mask can take the following form: .mp3 or [music] (and the obvious corresponding values for other media types and file extensions) and returns just the matching files. (To specify multiple file extensions use the bar "|" character e.g. .mp3|.wma.) mask can also take the form: "*" or "/" and returns just folders. An empty mask (i.e."") returns all files and folders.

lineStart is the first item in the list to return (first entry is 0 not 1) and numLines is the number of items to return. numLines cannot be specified without specifying lineStart. If numLines is not specified then all entries from lineStart to the end of the list will be returned.

http://xbox/xbmcCmds/xbmcHttp?command=GetDirectory(F:\music\;.mp3;1) 
Return only the first 10 items:
http://xbox/xbmcCmds/xbmcHttp?command=GetDirectory(F:\music\;.mp3;1;0;10)
Return the next 10 items:
http://xbox/xbmcCmds/xbmcHttp?command=GetDirectory(F:\music\;.mp3;1;10;10)
GetGuiDescription Retrieves various GUI values. (Currently just the screen resolution) http://xbox/xbmcCmds/xbmcHttp?command=GetGUIDescription()
GetGuiSetting(type; name) Retrieves the value of GUI setting name. type specifies whether the setting is of type integer (0), boolean (1) or float (2) which must be set correctly or could cause a crash. name is the name of the setting to get the value of. For a list of setting names see GUISettings.cpp. http://xbox/xbmcCmds/xbmcHttp?command=getguisetting(0;system.shutdowntime)
GetGuiStatus() Retrieves various information about the status of the GUI. http://xbox/xbmcCmds/xbmcHttp?command=getGUIStatus()
GetMovieDetails(mediaPath) Retrieves details of the movie mediaPath http://xbox/xbmcCmds/xbmcHttp?command=getMovieDetails(f:\movies\test.avi)
GetPercentage Retrieves the current playing position of the currently playing media as a percentage of the media’s length. http://xbox/xbmcCmds/xbmcHttp?command=getpercentage()
GetPlaylistContents([playlist]) Retrieves the contents (file names) of the current playlist or the playlist specified by playlist. Playlist takes one of the following values: 0 – Music playlist, 1 – Temporary music playlist, 2 – Video playlist, 3 – Temporary video playlist. (Since 26 Nov 2006: 0 - Music playlist, 1 - Video playlist) http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistContents(1)
GetPlaylistLength([playlist]) Retrieves the length of the current playlist or the playlist specified by playlist. http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistLength(0)
GetPlaylistSong([position]) Retrieves the currently playing song number in the playlist. If the optional parameter position is provided the command will return the file name of the media at location position in the playlist. http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistSong()
GetPlaySpeed Retrieves the current playing speed. http://xbox/xbmcCmds/xbmcHttp?command=GetPlaySpeed()
GetMusicLabel(item) Retrieves audio information relating to the currently playing media. The specific information to retrieve is specied by info which is an integer corresponding to one of the MUSICPLAYER_* constants that can be found in GUIInfoManager.h The example retrieves the codec currently being used. http://xbox/xbmcCmds/xbmcHttp?command=GetMusicLabel(217)
GetRecordStatus Retrieves whether XBMC is in record mode. http://xbox/xbmcCmds/xbmcHttp?command=GetRecordStatus()
GetVideoLabel(item) Retrieves video information relating to the currently playing media. The specific information to retrieve is specied by info which is an integer corresponding to one of the VIDEOPLAYER_* constants that can be found in GUIInfoManager.h The example retrieves the rating of the video currently being played. http://xbox/xbmcCmds/xbmcHttp?command=GetVideoLabel(270)
GetSlideshowContents Retrieves the contents (file names) of the slideshow playlist. http://xbox/xbmcCmds/xbmcHttp?command=GetSlideshowContents()
GetSystemInfo(InfoIds) Retrives System Information by id number(the information on the system info page in xbmc). You can supply multipal numbers if you wish to retreive a bunch at a time. This sample will get Version of XBMC & Build Date. For a full list of Id's see GUIInfoManager.h. http://xbox/xbmcCmds/xbmcHttp?command=GetSystemInfo(120;121)
GetSystemInfoByName(InfoNames) Retrives System Information by name (the information on the system info page in xbmc). You can supply multipal names if you wish to retreive a bunch at a time. Go down to the "CGUIInfoManager::TranslateSingleString" section in GUIInfoManager.cpp and you will find all the InfoNames values http://xbox/xbmcCmds/xbmcHttp?command=GetSystemInfoByName(weather.location;weather.temperature)
GetTagFromFilename(filename) Retrieves information for the audio file filename http://xbox/xbmcCmds/xbmcHttp?command=GetTagFromFilename(F:\music\test.mp3)
GetThumbFilename(album;location) Retrieves the file name of the corresponding thumbnail for the music media file with file name album and path location http://xbox/xbmcCmds/xbmcHttp?command=GetThumbFilename(test.mp3;F:\music\)
GetVolume Retrieves the current volume setting as a percentage of the maximum possible value. http://xbox/xbmcCmds/xbmcHttp?command=GetVolume()
GetLogLevel Retrieves XBMC's current log level http://xbox/xbmcCmds/xbmcHttp?command=GetLogLevel()
QueryMusicDatabase Provides a SQL interface to query the XBMC Music Database.

WARNING: Some of the read commands can be so complex or retrieve so much data that it can impact the operation of XBMC e.g. retrieving all songs from a reasonably large data base can bring xbmc to its knees.

http://xbox/xbmcCmds/xbmcHttp?command=querymusicdatabase(select%20strArtist%20from%20artist%20order%20by%20strArtist)

http://xbox/xbmcCmds/xbmcHttp?command=querymusicdatabase(select%20*%20from%20artist%20where%20strArtist%20LIKE%20'%%the%%')

QueryVideoDatabase Provides a SQL interface to the XBMC Video Database. See QueryMusicDatabase for further information. http://xbox/xbmcCmds/xbmcHttp?command=queryvideodatabase(select%20path.strpath%20from%20path)

Commands that Modify Settings

Command Information Example
AddToPlayList(media;[playlist];[mask];[recursive]) Adds a file or folder (media is either a file or a folder) to the current playlist or the playlist specified by playlist. To specify a file mask use mask e.g. .mp3|.wma.

If recursive = "1" and media is a folder then all appropriate media within subfolders beneath media will be added otherwise only media within the folder media will be added. Default behaviour is to be recursive. mask can now also be set to one of the following values (including the square brackets) [music], [video], [pictures], [files] in which case XBMC's current set of file extensions for the type specified will be used as the mask.

http://xbox/xbmcCmds/xbmcHttp?command=AddToPlayList(F:/music/test2.mp3;1)
AddToPlayListFromDB(type;statement) Adds a set of items to the playlist using an SQL statement. The type parameter is one of the following: [songs], [movies], [episodes] or [musicvideos]. The statement is an SQL condition after the WHERE clause. http://xbox/xbmcCmds/xbmcHttp?command=AddToPlayListFromDB(songs;idAlbum=362)
AddToSlideshow(media;[mask];[recursive]) Adds a file or folder (media is either a file or a folder) to the slideshow playlist. To specify a file mask use mask e.g. .jpg|.bmp

If recursive = "1" and media is a folder then all appropriate media within subfolders beneath media will be added otherwise only media within the folder media will be added. Default behaviour is to be recursive. mask can now also be set to one of the following values (including the square brackets) [music], [video], [pictures], [files] in which case XBMC's current set of file extensions for the type specified will be used as the mask. (Note it only makes much sense for this command to use a value of [pictures].

http://xbox/xbmcCmds/xbmcHttp?command=AddToSlideshow(F:\apps\xbmc\media\)
ClearPlayList([playlist]) Clears the current playlist or the playlist specified by playlist. http://xbox/xbmcCmds/xbmcHttp?command=ClearPlayList(1)
ClearSlideshow Clears the slideshow playlist. http://xbox/xbmcCmds/xbmcHttp?command=ClearSlideshow()
Mute Toggles the sound on/off. http://xbox/xbmcCmds/xbmcHttp?command=Mute()
RemoveFromPlaylist(item,[playlist]) Removes media from the current playlist or from playlist playlist. item can be either an integer specifying the position in the playlist of the item to be removed or the complete path (including filename) of the media to be removed. It is not possible to remove the media if it is currently being played. http://xbox/xbmcCmds/xbmcHttp?command=RemoveFromPlaylist(f:\test2.mp3;1)
SeekPercentage Sets the playing position of the currently playing media as a percentage of the media’s length. http://xbox/xbmcCmds/xbmcHttp?command=SeekPercentage(50)
SeekPercentageRelative Adds/Subtracts the current percentage on to the current postion in the song http://xbox/xbmcCmds/xbmcHttp?command=SeekPercentageRelative(-10)
SetCurrentPlaylist(playlist) Sets the current playlist to playlist. http://xbox/xbmcCmds/xbmcHttp?command=SetCurrentPlaylist(1)
SetGUISetting(type; name; value) Sets the value of GUI setting name to value. Type specifies whether the setting is of type integer (0), boolean (1) or float (2) which must be set correctly or could cause a crash. For a full list of setting names see GUISettings.cpp. http://xbox/xbmcCmds/xbmcHttp?command=SetGUISetting(0;system.shutdowntime;10)
SetPlaylistSong(position) Sets the media at playlist position position to be the next item to be played. The example sets the position to the 6th song in the playlist http://xbox/xbmcCmds/xbmcHttp?command=SetPlaylistSong(5)
SetPlaySpeed(speed) Sets the playing speed to the integer speed. http://xbox/xbmcCmds/xbmcHttp?command=SetPlaySpeed(speed)
SlideshowSelect(filename) Sets the slideshow playlist position by specifying the file name of the next image to show. http://xbox/xbmcCmds/xbmcHttp?command=SlideshowSelect(filename)
SetVolume Sets the volume as a percentage of the maximum possible. http://xbox/xbmcCmds/xbmcHttp?command=SetVolume(50)
SetLogLevel Sets XBMC's log level http://xbox/xbmcCmds/xbmcHttp?command=SetLogLevel(1)
SetAutoGetPictureThumbs If set to True then media thumbnails will be automatically created when required. (Default: True.) http://xbox/xbmcCmds/xbmcHttp?command=SetAutoGetPictureThumbs(false)
Swapplaylistitems(playlist;item1;item2) Here item1 and item2 are either offsets in the playlist, or the path to an item. http://xbox/xbmcCmds/xbmcHttp?command=Swapplaylistitems(playlist.pls;5;2)

Commands that Generate Actions

Command Information Example
Action Sends a raw Action ID (see [1]) to xbmc. Be careful with this one since it runs the action on the webserver thread and depending on the action could lock the GUI thread. The example sends ACTION_MOVE_DOWN. http://xbox/xbmcCmds/xbmcHttp?command=Action(4)
Exit Reboots to dashboard http://xbox/xbmcCmds/xbmcHttp?command=Exit()
KeyRepeat(rate) Sets whether and how fast a key sent using SendKey should repeat. rate is the repeat rate in milliseconds (e.g. 1000 = 1s). rate = 0 stops keys repeating. http://xbox/xbmcCmds/xbmcHttp?command=KeyRepeat(1000)
Move(deltaX, deltaY) Moves the currently displayed and ZOOMed (see zoom command below) image by the distance specified by deltaX and deltaY. The zoom magnification must be greater than 0 or the command has no effect. http://xbox/xbmcCmds/xbmcHttp?command=Move(50;20)
Pause Pauses the currently playing media. If a slideshow and audio is active only the slideshow is paused. http://xbox/xbmcCmds/xbmcHttp?command=Pause()
PauseExSlide [Added 10 Feb 2010] Pauses the currently playing media unless a slideshow and audio is active in which case it just pauses the audio. http://xbox/xbmcCmds/xbmcHttp?command=PauseExSlide()
PlayListNext Starts playing the next media in the current playlist. http://xbox/xbmcCmds/xbmcHttp?command=PlayListNext
PlayListPrev Starts playing the previous media in the current playlist. http://xbox/xbmcCmds/xbmcHttp?command=PlayListPrev
PlayNext Starts playing/showing the next media/image in the current playlist or, if currently showing a slidshow, the slideshow playlist. http://xbox/xbmcCmds/xbmcHttp?command=PlayNext()
PlayNextExSlide [Added 10 Feb 2010] Starts playing/showing the next media/image in the current playlist or, if currently showing a slidshow, the audio playlist. http://xbox/xbmcCmds/xbmcHttp?command=PlayNextExSlide()
PlayPrev Starts playing/showing the previous media/image in the current playlist or, if currently showing a slidshow, the slideshow playlist. http://xbox/xbmcCmds/xbmcHttp?command=PlayPrev()
PlayPrevExSlide [Added 10 Feb 2010] Starts playing/showing the previous media/image in the current playlist or, if currently showing a slidshow, the audio playlist. http://xbox/xbmcCmds/xbmcHttp?command=PlayPrevExSlide()
PlaySlideshow([directory];[recursive]) Starts the slideshow. Directory specifies a folder of images to add to the slideshow playlist. If recursive has a value of True then all directories beneath directory are searched for images and added to the slideshow playlist. http://xbox/xbmcCmds/xbmcHttp?command=PlaySlideshow(F:\pictures;true)
PlayFile(filename;[playlist]) Starts playing the media file filename on playlist playlist or if playlist is not specified the current playlist. http://xbox/xbmcCmds/xbmcHttp?command=PlayFile(F:\music\test.mp3)
Reset Resets XBMC http://xbox/xbmcCmds/xbmcHttp?command=Reset()
Restart Restarts XBOX http://xbox/xbmcCmds/xbmcHttp?command=Restart()
RestartApp Restarts XBMC http://xbox/xbmcCmds/xbmcHttp?command=RestartApp()
Rotate Rotates the currently displayed image by 90 degree clockwise. http://xbox/xbmcCmds/xbmcHttp?command=Rotate()
SendKey(buttoncode;[LeftTrigger];[RightTrigger];[LeftThumbX];[LeftThumbY] ;[RightThumbX];[RightThumbY]) Initiates a button, key or mouse event. Buttoncode specifies the type of event and the other parameters specify additional information that is specific to each buttoncode value. See key.h for the the list of keycodes. The example calls the shutdown menu.
  • To send a button event just set buttoncode to the appropriate value from Key.h
  • To send a virtual keyboard event set buttoncode to 0xF100 (hex) and add the required key’s ASCII value.
  • To send a keyboard event set buttoncode to 0xF000 (hex) and add the required key’s ASCII value.
  • (Experimental) To send a mouse event set buttoncode to EFFF (hex) , then set the following parameters:
    • LeftThumbX – mouse x position
    • LeftThumbY – mouse y position
    • LeftTrigger – indicates a single mouse click and takes a value of one of 1-left button, 2-right button, 3-middle button.
    • RightTrigger– indicates a double mouse click and takes a value of one of 1-left button, 2-right button, 3-middle button.
 http://xbox/xbmcCmds/xbmcHttp?command=SendKey(0xF053)

http://xbox/xbmcCmds/xbmcHttp?command=SendKey(61523)

ShowPicture(filename) Displays the image filename. http://xbox/xbmcCmds/xbmcHttp?command=ShowPicture(F:\apps\xbmc\media\splash.png)
Shutdown Shutdown XBOX http://xbox/xbmcCmds/xbmcHttp?command=Shutdown()
SpinDownHardDisk If possible stops the hard disk (saves power / quieter) http://xbox/xbmcCmds/xbmcHttp?command=SpinDownHardDisk()
Stop Stops the currently playing media. If a slideshow and audio is active only the slideshow is stopped. http://xbox/xbmcCmds/xbmcHttp?command=Stop()
StopExSlide [Added 10 Feb 2010] Stops the currently playing media. If a slideshow and audio is active only the audio is stopped. http://xbox/xbmcCmds/xbmcHttp?command=StopExSlide()
TakeScreenshot([filename];[flash];[rotation];[width];[height];[quality];[download];[imgtag]) Captures the current contents of the Xbox screen.

If no parameters then the action is the same as initiating a regular screenshot command with the image being saved in the screenshot directory.

If filename is provided then the image is saved to filename.

If flash=True the screen will flash as the command executes.

If resolution, width, height and quality are given then those values are used to define the rotation (in degrees), resolution and jpeg quality of the saved image.

If download = True then the image is downloaded to the client as a base64 encoded stream.

The command must conform to one of:

No parameters

Filename, flash, rotation, width, height, quality

Filename, flash, rotation, width, height, quality, download

Filename, flash, rotation, width, height, quality, download, imgtag

NEW: imgtag is new it will put a Convert Base64 to image tag with the Base64 code so in firefox browsers it will show the image instead of the Base64 code.

http://xbox/xbmcCmds/xbmcHttp?command=takescreenshot(test.jpg;true;0;300;200;90;true;imgtag)
Zoom(magnification) Zooms the currently displayed image to a level specified by magnifaction. A magnification of 0 is the standard zoom level of none. Magnification can take values up to 8. http://xbox/xbmcCmds/xbmcHttp?command=Zoom(4)

Commands that Modify Files

Command Information Example
FileCopy(sourceFilename, destinationFilename) Copies the Xbox file sourceFilename to the Xbox file desitinationFilename. http://xbox/xbmcCmds/xbmcHttp?command=FileCopy(F:\apps\xbmc\media\splash.png;E:\pictures\)
FileDelete(filename) Deletes the Xbox file filename. http://xbox/xbmcCmds/xbmcHttp?command=FileDelete(F:\pictures\kim-smith-1024x768–22677.jpg)
FileDownload(filename;[bare]) Download a file specified by filename from the Xbox to the client as a base64 stream. If the optional parameter 'bare' is specified the webheader and webfooter won't be included which results in just a raw base64 stream. http://xbox/xbmcCmds/xbmcHttp?command=FileDownload(F:\apps\xbmc\default.xbe)
FileDownloadFromInternet(URL;[filename];[bare]) Downloads the file with address URL to the client as a base64 encoded stream. If the filename parameter is present, the downloaded file is also saved on the Xbox as the file filename. If the optional parameter 'bare' is specified the webheader and webfooter won't be included which results in just a raw base64 stream. http://xbox/xbmcCmds/xbmcHttp?command=FileDownloadFromInternet(http://wallpapers.skins.be/kim-smith/kim-smith-1024x768–22677.jpg;F:\pictures\kim-smith-1024x768–22677.jpg)

To test quickly: http://xbox/xbmcCmds/xbmcHttp?command=ShowPicture(F:\pictures\kim-smith-1024x768–22677.jpg)

FileExists(filename) Returns True if the Xbox file filename exists otherwise returns False. http://xbox/xbmcCmds/xbmcHttp?command=FileExists(F:\pictures\kim-smith-1024x768–22677.jpg)
FileSize(filename) Returns the file size of filename. http://xbox/xbmcCmds/xbmcHttp?command=FileSize(F:\pictures\kim-smith-1024x768–22677.jpg)
FileUpload(filename, contents) Uploads a file encoded as a base64 string contents to the file filename on the Xbox. The example creates on the xbox the file f:\test.txt with the contents hello. http://xbox/xbmcCmds/xbmcHttp?command=fileUpload(f:\test.txt;aGVsbG8%3d)

Miscellaneous Commands

Command Information Example
ChooseAlbum(URL) Retrieves the cover image and review text of the album with URL URL as returned by the LookupAlbum command. The URL must be encoded using the standard %xx format(RFC1738) before being passed to the API. The example here is passing the URL http://www.allmusic.com/cg/amg.dll?p=amg&sql=10:7vz1z87a6yvn http://xbox/xbmcCmds/xbmcHttp?command=choosealbum(http%3a%2f%2fwww%2eallmusic%2ecom%2fcg%2famg%2edll%3fp%3damg%26sql%3d10%3a7r6cmpea9f8o)
LookupAlbum(album[;artist;boolRelevance])

Looks up the album with name album on an Internet music site and returns the resulting matches as a list with the format: album_name<@@>album_URL

If boolRelevance has a value of 1 a relevance score (ranging from 1 (perfect) to 0) will also be returned with the following format: album_name<@@>album_URL<@@@>score

When requesting releveance scores it is best to include a value for the artist but it is not necessary.

http://xbox/xbmcCmds/xbmcHttp?command=lookupalbum(On%20an%20Island)

http://xbox/xbmcCmds/xbmcHttp?command=lookupalbum(On%20an%20Island;david%20gilmour;1)

Config(command; parameters) Provides access to the ASP configuration commands. command is the ASP command and parameters is a semi-colon separated list of parameters to accompany the command. command is one of bookmarksize, getbookmark, addbookmark, savebookmark, removebookmark. For further information see: XBMCConfiguration.cpp. Note that the WebServer must be running to use this command. [Since 10 Nov 2007 the WebServer does not need to be running] http://xbox/xbmcCmds/xbmcHttp?command=Config(bookmarksize;20)

http://xbox/xbmcCmds/xbmcHttp?command=Config(getbookmark;music;name;1)

http://xbox/xbmcCmds/xbmcHttp?command=Config(getbookmark;music;path;1)

WebServerStatus([status]) If no parameter is provided the function returns the status of the WebServer (On or Off). Where a parameter is provided status must be either on (turns the WebServer on) or off (turns the WebServer off). Note that only Python scripts can use the version with the parameter. http://xbox/xbmcCmds/xbmcHttp?command=WebServerStatus()
ExecBuiltIn(function) Executes the XBMC ‘built-in’ function function. For the list of available functions see: the list of Built In Functions OR ExecBuiltIn Functions http://xbox/xbmcCmds/xbmcHttp?command=ExecBuiltIn(Notification(WARNING,SHUTTING%20DOWN%20SYSTEM!))
Help Displays a list of some (NOT ALL) of the HTTPApi commands http://xbox/xbmcCmds/xbmcHttp?command=Help()
SetResponseFormat(format; value) Sets the format of the response from HTTPApi. Format takes one of the following:

WebHeader – if True then the default web server header will be prepended to the response (ignored for Python and ASP responses).

WebFooter – if True then the default web server footer will be appended (ignored for Python and ASP responses).

Header – A user definable string that will be added after the WebHeader (if present) and before the main body of the response.

Footer – A user definable string that will be before after the WebFooter (if present) and after the main body of the response.

OpenTag – A user definable string that will be inserted before each element of the main response.

CloseTag – A user definable string that will be inserted after each element of the main response. Whether to insert this tag after the final element is defined by the CloseFinalTag setting.

CloseFinalTag – if True then the final element will have a closing tag.


The default format values are:

WebHeader=True

WebFooter=True

Header=””

Footer=””

OpenTag=”<li>”

CloseTag=[carriage return]

CloseFinalTag=False



Additional tags added and their default values (formats the response from the QueryMusicDatabase command):

OpenRecordSet=””

CloseRecordSet=””

OpenRecord=””

CloseRecord=””

OpenField=”<li>”

CloseField=””

It is now possible to specify multiple formats in a single call to SetResponseFormat.

SetResponseFormat without any parameters returns the formatting to the default values (as would restarting xbmc).

http://xbox/xbmcCmds/xbmcHttp?command=SetResponseFormat(WebHeader;False)

The following sets up an XML formatted response (if viewing the output in a browser you will neeed to use the view source command to see the xml tags).

http://xbox/xbmcCmds/xbmcHttp?command=setresponseformat(webheader;false;webfooter;false;header;<xml>;footer;</xml>;opentag;<tag>;closetag;</tag>;closefinaltag;true)

Then the same for the QueryMusicDatabase response:

http://xbox/xbmcCmds/xbmcHttp?command=setresponseformat(openRecordSet;<recordset>;closeRecordSet;</recordset>;openRecord;<record>;closeRecord;</record>;openField;<field>;closeField;</field>)

Now set everything back to the default:

http://xbox/xbmcCmds/xbmcHttp?command=SetResponseFormat()

getXBETitle(path) Return the Title/Description of the specifed XBE http://xbox/xbmcCmds/xbmcHttp?command=getxbetitle(special:\\xbmc\default.xbe)
getXBEid(path) [Returns the id of a specifed XBE http://xbox/xbmcCmds/xbmcHttp?command=getxbeid(special:\\xbmc\default.xbe)

Broadcast Commands

Command Information Example
Broadcast(message;port) Not sure if there is much point to this command - probably could be used to test a client listening for broadcasts. If the port parameter is not specified then the currently set default port will be used. http://xbox/xbmcCmds/xbmcHttp?command=Broadcast(hello_from_xbmc)
SetBroadcast(level;port) Sets the brodcast level and port.

Level currently takes three values: 0 - no broadcasts, 1 - media playback and startup & shutdown events, 2 - "OnAction" events (e.g. buttons) as well as level 1 events. [Added Jan 2010] In addition adding 128 to this value changes the format of the broadcast to include the IP address of the XBMC box sending the broadcast. [Added 21 March 2010 (rev 28740)] In addition adding 256 to this value changes the format of the broadcast to include the port number (as well as the IP address) of the XBMC box sending the broadcast. (Useful for when there are multiple XBMC boxes present.)

Port is optional and if specified sets the default broadcast port value.

http://xbox/xbmcCmds/xbmcHttp?command=SetBroadcast(1)
GetBroadcast() Returns the current level and port settings. http://xbox/xbmcCmds/xbmcHttp?command=GetBroadcast()

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.

Old Name New Name
CopyFile FileCopy
DeleteFile FileDelete
GetInternetFile FileDownloadFromInternet
GetThumb FileDownload
GUISetting SetGUISetting, GetGUISetting
SetFile FileUpload
SetKey SendKey
Retrieved from "https://kodi.wiki/index.php?title=Archive:Web_Server_HTTP_API&oldid=216343"