Archive:Web Server HTTP API
Webserver Commands (HTTPAPI)
The list below is an active updated list of all the httpapi commands availible but if you wish to view the outdated one it can be downloaded from: http://prdownloads.sourceforge.net/xbmc/apiDoc.doc?download
This page is currently in the process of being built so commands with no explination have not yet been fully tested or else I'm still trying to figure out what exactly they do if anything :) please bare with while I figure them out. -TeknoJuce
I, the author of the HTTPAPI, have just started the continuation of TeknoJuce's porting of my original Word documentation of the API,apiDoc.doc. I'll fix, update and expand as I go along. Nad
HTTPAPI DOC
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.
The same set of commands is now also available over ASP and from Python.
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 control of XBMC functions.
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:
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¶meter=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:
- 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.
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.
192.168.0.1 xbox
Save it (don't need to restart) and test if the command “ping xbox” works. You should now resolve your Xbox IP address
If you still can’t get them working, try:
http://xbox
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.
Once you have the above working we can look at the structure of the http command line.
All API commands start with the following:
http://xbox/xbmcCmds/xbmcHttp?command=
(Remember you may need to swap “xbox” for the 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.
If the command takes parameters then "¶meter=" is added after the command.
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.
http://xbox/xbmcCmds/xbmcHttp?command=takescreenshot¶meter=test.jpg,300,200,90
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.
ASP
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.
e.g.
Response = xbmcAPI("GetCurrentlyPlaying");
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.
e.g.
import xbmc response = xbmc.executehttpapi("TakeScreenShot(q:\\test.jpg,0,false,200,-1,90)")
The Commands
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.
Remember to use the syntax:
http://xbox/xbmcCmds/xbmcHttp?command=setvolume¶meter=80
and not
http://xbox/xbmcCmds/xbmcHttp?command=setvolume(80)
A parameter in square brackets is optional. An optional parameter typically specifies an alternative to a default value.
In the following list the Playlist parameter identifies one of the four available playlists by using the values 0..3:
0. Music playlist 1. Temporary music playlist 2. Video playlist 3. Temporary video playlist
These playlists should not be confused with:
The slideshow playlist. The slideshow commands implicitly refer to the latter. Playlist files e.g m3u files.
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
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.
Retrieving information commands
Command | Information | Example |
GetMediaLocation | music, video, pictures, files; PATH; pathsonly | http://xbox/xbmcCmds/xbmcHttp?command=GetMediaLocation¶meter=files;smb:\\F\;pathsonly |
GetMediaShare | music, video, pictures, files; Pathsonly (0,1) | http://xbox/xbmcCmds/xbmcHttp?command=GetMediaShare¶meter=music;1 |
GetCurrentPlaylist | Retrieves the current playlist identifier. | http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentPlaylist |
GetCurrentlyPlaying | Retrieves the filename, details and status of the currently playing media. | http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentlyPlaying |
GetCurrentSlide | Retrieves the file name of the image currently being displayed. | http://xbox/xbmcCmds/xbmcHttp?command=GetCurrentSlide |
GetDirectory | directory;[mask];[option]
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. |
http://xbox/xbmcCmds/xbmcHttp?command=GetDirectory¶meter=F:\music\;.mp3;1 |
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). |
http://xbox/xbmcCmds/xbmcHttp?command=getguisetting¶meter=0;settingname |
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. 0 – Music playlist, 1 – Temporary music playlist, 2 – Video playlist, 3 – Temporary video playlist (I pretty much use 1 for everything doesnt seem to make much of a difference except that the temp list xbmc seems to use is 1 I've noticed.) |
http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistContents¶meter=1 |
GetPlaylistSong | [position]
Retrieves the currently playing song number in the playlist (basically just a number) |
http://xbox/xbmcCmds/xbmcHttp?command=GetPlaylistSong |
GetPlaySpeed | Retrieves the current playing speed. | http://xbox/xbmcCmds/xbmcHttp?command=GetPlaySpeed |
GetSlideshowContents | Retrieves the contents (file names) of the slideshow playlist. | http://xbox/xbmcCmds/xbmcHttp?command=GetSlideshowContents |
GetSystemInfo | InfoID's
Retrives System Information like anything from the system info page in xbmc you can supply multipal numbers if you wish to retreive a bunch at a time GuiInfoManager This sample will get Version of XBMC & Build Date |
http://xbox/xbmcCmds/xbmcHttp?command=GetSystemInfo¶meter=120;121 |
GetSystemInfoByName | infonames
Go down to the "CGUIInfoManager::TranslateSingleString" section and you will find all the strings GuiInfoManager |
http://xbox/xbmcCmds/xbmcHttp?command=GetSystemInfoByName¶meter=weather.location;weather.temperature |
GetTagFromFilename | filename
Retrieves information for the audio file filename |
http://xbox/xbmcCmds/xbmcHttp?command=GetTagFromFilename¶meter=F:\music\test.mp3 |
GetThumbFilename | album;filename
Retrieves the file name of the corresponding thumbnail for the music media file with album name album and file name filename |
http://xbox/xbmcCmds/xbmcHttp?command=GetThumbFilename¶meter=album;F:\music\test.mp3 |
GetVolume | Retrieves the current volume setting as a percentage of the maximum possible value. | http://xbox/xbmcCmds/xbmcHttp?command=GetVolume |
Setting commands
Command | Information | Example |
AddToPlayList(file/folder;[playlist];[mask]) | Adds a file or folder to the current playlist or the playlist specified by playlist. To specify a file mask use mask. | http://xbox/xbmcCmds/xbmcHttp?command=AddToPlayList¶meter=F:/music/test2.mp3;1 |
AddToSlideshow(file/directory) | Adds a file or directory file/directory to the slideshow playlist. | http://xbox/xbmcCmds/xbmcHttp?command=AddToSlideshow¶meter=F:\apps\xbmc\media\ |
ClearPlayList([playlist]) | Clears the current playlist or the playlist specified by playlist. | http://xbox/xbmcCmds/xbmcHttp?command=ClearPlayList¶meter=1 |
ClearSlideshow | Clears the slideshow playlist. | http://xbox/xbmcCmds/xbmcHttp?command=ClearSlideshow |
RemoveFromPlaylist(filename,[playlist]) | Removes the file filename from the current playlist or from playlist playlist. | http://xbox/xbmcCmds/xbmcHttp?command=RemoveFromPlaylist¶meter=f:\test2.mp3,1 <— need to know filenames in playlist |
SeekPercentage | Sets the playing position of the currently playing media as a percentage of the media’s length. | http://xbox/xbmcCmds/xbmcHttp?command=SeekPercentage¶meter=50 |
SeekPercentageRelative | Adds/Subtracts the current percentage on to the current postion in the song | http://xbox/xbmcCmds/xbmcHttp?command=SeekPercentageRelative¶meter=-10 |
SetCurrentPlaylist(playlist) | Sets the current playlist to the playlist with identifier{1} playlist. | http://xbox/xbmcCmds/xbmcHttp?command=SetCurrentPlaylist¶meter=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). | http://xbox/xbmcCmds/xbmcHttp?command=SetGUISetting(type;name;value) (havnt tried yet) |
SetPlaylistSong(position) | Sets the media at playlist position position to be the next item to be played. play 6th song in playlist --> | http://xbox/xbmcCmds/xbmcHttp?command=SetPlaylistSong¶meter=5 |
SetPlaySpeed(speed) | Sets the playing speed to the integer speed. | http://xbox/xbmcCmds/xbmcHttp?command=SetPlaySpeed¶meter(speed) (havnt tried currently) |
SlideshowSelect(filename) | Sets the slideshow playlist position. Filename specifies the next image to show. | http://xbox/xbmcCmds/xbmcHttp?command=SlideshowSelect¶meter=filename (didnt try it) |
SetVolume | Sets the volume as a percentage of the maximum possible volume value. | http://xbox/xbmcCmds/xbmcHttp?command=SetVolume¶meter=50 |
SetAutoGetPictureThumbs | If set to True then media thumbnails will be automatically created when required. (Default: True.) | http://xbox/xbmcCmds/xbmcHttp?command=SetAutoGetPictureThumbs¶meter=false |
Action commands
Command | Information | Example |
Exit | Reboots to dashboard | http://xbox/xbmcCmds/xbmcHttp?command=Exit |
Move(deltaX, deltaY) | Moves the currently displayed image in the direction specified by deltaX and deltaY. | http://xbox/xbmcCmds/xbmcHttp?command=Move¶meter=200;200 (Didnt work) |
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 |
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 |
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¶meter=F:\pictures;true |
PlayerPlayFile(filename) | Starts playing the media file filename on the current playlist. | BROKEN |
Reset | Resets XBMC | http://xbox/xbmcCmds/xbmcHttp?command=Reset |
Restart | Restarts XBOX | http://xbox/xbmcCmds/xbmcHttp?command=Restart |
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. key.h{keycodes} (A button) --> | http://xbox/xbmcCmds/xbmcHttp?command=SendKey¶meter=256 |
ShowPicture(filename) | Displays the image filename. | http://xbox/xbmcCmds/xbmcHttp?command=ShowPicture¶meter=F:\apps\xbmc\media\splash.png |
Shutdown | Shutdown XBOX | http://xbox/xbmcCmds/xbmcHttp?command=Shutdown |
TakeScreenshot([filename];[flash];[rotation];[width];[height];[quality];[download];[imgtag]) | o 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. No parameters 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¶meter=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¶meter=4 |
File Commands
Command | Information | Example |
FileCopy(sourceFilename, destinationFilename) | Copies the Xbox file sourceFilename to the Xbox file desitinationFilename. | http://xbox/xbmcCmds/xbmcHttp?command=FileCopy¶meter=F:\apps\xbmc\media\splash.png;E:\pictures\ |
FileDelete(filename) | Deletes the Xbox file filename. | http://xbox/xbmcCmds/xbmcHttp?command=FileDelete¶meter=F:\pictures\kim-smith-1024x768–22677.jpg |
FileDownload(filename) | Download a file specified by filename from the Xbox to the client as a base64 stream. | http://xbox/xbmcCmds/xbmcHttp?command=FileDownload¶meter=F:\apps\xbmc\default.xbe |
FileDownloadFromInternet(URL;[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. | http://xbox/xbmcCmds/xbmcHttp?command=FileDownloadFromInternet¶meter=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¶meter=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¶meter=F:\pictures\kim-smith-1024x768–22677.jpg |
FileSize(filename) | Returns the file size of filename. | http://xbox/xbmcCmds/xbmcHttp?command=FileSize¶meter=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. | http://xbox/xbmcCmds/xbmcHttp?command=FileUpload¶meter=filename;16A5B43225BF (N.B. this example does not include a complete base64 string) |
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¶meter=http%3a%2f%2fwww%2eallmusic%2ecom%2fcg%2famg%2edll%3fp%3damg%26sql%3d10%3a7r6cmpea9f8o |
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. For further information see: XBMCConfiguration.cpp | http://xbox/xbmcCmds/xbmcHttp?command=Config(command;parameters) |
ExecBuiltIn(function) | Executes the XBMC ‘built-in’ function function. For the list of available functions see: Manual:builtin functions OR ExecBuiltIn Functions | http://xbox/xbmcCmds/xbmcHttp?command=ExecBuiltIn¶meter=Notification(WARNING,SHUTTING%20DOWN%20SYSTEM!) |
Help | Displays a list of some (NOT ALL) of the HTTPApi commands | http://xbox/xbmcCmds/xbmcHttp?command=Help |
LookupAlbum(album) | 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 | http://xbox/xbmcCmds/xbmcHttp?command=lookupalbum¶meter=On%20an%20Island |
SetResponseFormat(format; value) | o 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). WebHeader=True CloseTag=[carriage return] CloseFinalTag=False |
http://xbox/xbmcCmds/xbmcHttp?command=SetResponseFormat¶meter=WebHeader;False (and no you can't specify multipal formats only one after another) |
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.
Old Name | New Name |
CopyFile | FileCopy |
DeleteFile | FileDelete |
GetInternetFile | FileDownloadFromInternet |
GetThumb | FileDownload |
GUISetting | SetGUISetting, GetGUISetting |
SetFile | FileUpload |
SetKey | SendKey |