[% pagetitle = 'Squeezebox Server Web Interface' %] [% techinfo = '1' %] [% lefttoright = '1' %] [% PROCESS helpheader.html %]

#### Overview

This document describes the interface to the HTTP server that's built into the Squeezebox Server.

The Squeezebox Server provides an HTTP server that can be used to:

1. Browse the music library.
2. View the status and playlist of the player.
3. Control the player.
4. Configure the server.

When the Squeezebox Server is started, it starts listening for HTTP connections on the default port of 9000.

The HTTP server may be accessed by the user with a traditional web browser to navigate around the music library and control the player. The HTTP server may also be used in conjunction with another software application (wget or curl, for example) as a way to access and control the player via HTTP. The server can return XML instead of HTML for such "automation" uses (see The XML Skin documentation.)

In the examples in this document the Squeezebox Server is running on a computer with the IP address of 10.0.1.201.

#### HTTP Access

To access the main page to control the player via a web browser use this URL:

    http://10.0.1.201:9000/

This provides a frameset containing two pages, one for browsing the music library:

    http://10.0.1.201:9000/browse.html

Navigation through the browser to subdirectories in the music library uses a URL parameter called "dir" to specify a subdirectory, for example:

    http://10.0.1.204:9000/browse.html?dir=%2fAl%20Green%2fGreatest%20Hits

provides access to browse the subdirectory "Greatest Hits" directory within the "Al Green" subdirectory under the main music directory. There are additional web pages and URLs used to browse the music library by genre, artist and album as well as configuration and user preference settings and online help.

The other frame within the main frameset is at this URL:

    http://10.0.1.201:9000/status.html

Which displays the status of the player, including the current song and playlist.

Control of the player uses another set of URLs, all of which may return some status information. They are in the format:

    http://10.0.1.201:9000/status.suffix?p0=param&p1=param1&p2=param2&p3=param3

where "status" indicates that player status will be returned, and p0,p1, p2, p3, and p4 are parameters used that command.

If the "suffix" is .html then the response will be the current player's status in HTML. If the "suffix" is .m3u then the response will be the player's current playlist as an .m3u file. If the suffix is ".txt" then the response will consist of two lines of text corresponding to the text on the player's display. If the suffix is omitted, then the response will be the empty.

Note: Commands that use paths to songs or playlists can use relative paths from the root of the Music Library folder to specify songs. For example, if the Music Library is specified as "D:\mymusic" and you'd like to refer to a song in that folder named "foo.mp3" you can specify just "foo.mp3" in the command parameter. Likewise, to refer to items in the Saved Playlist folder, you can use a prefix of "__playlists/" before the path. For example, to refer to the saved playlist "bar.m3u" in the Saved Playlists folder, you can specify a path of "__playlists/bar.m3u".

#### Commands

The following is a summary of the supported commands. Additional information about the command set is available in the Squeezebox Server Command Line Interface documentation.

p0 | p1 | p2 | p3 | p4 | Description
play |  |  |  |  | Start the player playing
pause | (0|1|) |  |  |  | Pause/unpause player. p1=1 to pause, p1=0 to unpause, omit p1 to toggle
stop |  |  |  |  | Stop the player
sleep | (0..n) |  |  |  | (Play for p1 seconds and then sleep
playlist | play | <item> |  |  | Replace the current playlist with the song, playlist or directory specified by p2
playlist | add | <item> |  |  | Append the song, playlist or directory specified by p2 to the end of the current playlist
playlist | insert | <item> |  |  | Insert the song, playlist or directory specified by p2 to be played immediately after the current song.
playlist | resume | <playlist> |  |  | Replace the current playlist with the playlist specified by p2, starting at the song that was playing when the file was saved. (Resuming works only with M3U files saved with the playlist save command below.) Shortcut: use a bare playlist name (without leading directories or trailing .m3u suffix to load a playlist in the saved playlists folder.
playlist | loadalbum | <genre> | <artist> | <album> | Replace the current playlist with all songs for a given genre, artist, and album. Use a value of "*" for p2, p3, or p4 as a wildcard. Note: the server's cache must contain the items for this to work.
playlist | save | <playlist> |  |  | Save a playlist file in the saved playlists directory. Accepts a playlist filename (without .m3u suffix) and saves in the top level of the playlists directory.
playlist | addalbum | <genre> | <artist> | <album> | Add all songs for a given genre, artist, and album. Use a value of "*" for p2, p3, or p4 as a wildcard. Note: the server's cache must contain the items for this to work.
playlist | clear |  |  |  | Clear the current playlist
playlist | repeat | (0|1|2|) |  |  | Change the repeat mode. p1=0 no repeat, stop at the end of the playlist, p1=1 repeat the current song, p1=2 repeat the entire playlist. Omit p1 to cycle through values.
playlist | shuffle | (0|1|2|) |  |  | Shuffle the playlist. p1=0 no shuffle, p1=1 shuffle songs in the playlist, p1=2 shuffle albums in the playlist. Omit p1 to toggle shuffle mode.
playlist | move | <fromoffset> | <tooffset> |  | Move the song in the offset specified by p2 to the offset specified by p3 in the playlist.
playlist | delete | <songoffset> |  |  | Delete the song in the playlist at the offset specified by p2
playlist | jump | <index> |  |  | Make the song at the offset specified by p2 in the playlist the currently playing song
mixer | volume | (0 .. 100)|(-100 .. +100) |  |  | Adjust the volume as specified by p2 within the range 0 to 100. Prefix the number with a + or - to make the change relative.
mixer | balance | (0 .. 100)|(-100 .. +100) |  |  | (not implemented) Adjust the volume as specified by p2 within the range 0 (most left) to 100 (most right). Prefix the number with a + or - to make the change relative. A value 50 means no balance adjustment.
mixer | base | (0 .. 100)|(-100 .. +100) |  |  | (not implemented) Adjust the base boost/cut as specified by p2 within the range 0 to 100. Prefix the number with a + or - to make the change relative. A value of 50 means no boost or cut.
mixer | treble | (0 .. 100)|(-100 .. +100) |  |  | (not implemented) Adjust the treble boost/cut as specified by p2 within the range 0 to 100. Prefix the number with a + or - to make the change relative. A value of 50 means no boost or cut.
status |  |  |  |  | Return the current status of the player without any change.
display | <line1> | <line2> | <duration> |  | Put text on the player's display. line 1 is specified by p1, line 2 is specified by p2. The text is displayed for a number of seconds as specified by p3. If p3 is omitted, then a default time is used of approximately 1.5 seconds.
button | <code> |  |  |  | Simulate a button press from the infrared remote, where <code> is a function name per the Default.map file.
rescan |  |  |  |  | Start a rescan of the music library
pref | <name> | <value> |  |  | Set the value of a preference. Use a value of "?" to get the value in the returned p2 header
pref | <name> | ? |  |  | Get the value of a preference. The value is returned in the returned p2 header
playerpref | <name> | <value> |  |  | Set the value of a player specific preference. Use a value of "?" to get the value in the returned p2 header
playerpref | <name> | ? |  |  | Get the value of a player-specific preference. The value is returned in the returned p2 header
debug | <flag> | <value> |  |  | Set the value of a debugging variable, for example, set "d_ir" to "1" to have infrared debugging output.

#### CSRF Security Measures

To protect against "Cross Site Request Forgery" (CSRF) security threats, Squeezebox Server applies special scrutiny to HTTP requests for functions that can make changes to your system or manipulate playlists or players. This scrutiny is important to understand if you want to "bookmark" such a URL, or control Squeezebox Server via the HTTP interface. Squeezebox Server requires one of four things to be true in order to allow such control-oriented URLs to be accepted:

Referer request header matches Squeezebox Server URL
  Squeezebox Server will accept an HTTP URL/command if the request includes a "Referer" request header that matches the "Host" request header. If you're using a web browser and clicking on links in the web interface (for instance, the Previous/Skip/Play/Pause links on the right-hand player pane), your browser will send a Referer header that tells Squeezebox Server it's following a link you clicked on from a Squeezebox Server page, and the request will be accepted. If you are using custom software to make the HTTP requests, simply make sure the HTTP request includes a Referer header with the same value as the URL you are requesting, and a Host header that includes the :port information (as described in the HTTP standard) and all will be fine.
Submission includes form-specific token
  Squeezebox Server embeds special authorization tokens in most settings pages in the web interface. If a request includes a valid form authorization token, it will be processed.
"cauth" URL parameter presented and valid
  If you're using a Bookmark/Favorite, no Referer request header is sent. In such a case, Squeezebox Server cannot tell if your request is legitimate, or your browser following an <IMG> tag in a hostile web page or HTML email. In such cases, you will see a "403 Forbidden" error page. On this page you'll see a URL similar to what you requested, but with a ";cauth=" parameter added to the end, e.g. when denying a bookmarked request for `http://10.0.1.201:9000/status.html?p0=rescan`, Squeezebox Server will offer you a clickable link with a URL like
  `http://10.0.1.201:9000/status.html?p0=rescan;cauth=aa2d378f7e9f18611e951e7c6b30eea8`
  By clicking on this link, you can execute your HTTP command. If you want to bookmark a URL that gives such an error, bookmark the "cauth" URL displayed on the error page. "cauth" URIs are unique for each Squeezebox Server installation. They are based on a special "securitySecret" that is randomly assigned the first time you start the Squeezebox Server software. This allows the same URL like `http://10.0.1.201:9000/status.html?p0=rescan;cauth=aa2d378f7e9f18611e951e7c6b30eea8` to always work on your Squeezebox Server installation (so you can bookmark it or use it in your home automation system), but not work on another Squeezebox Server setup. This unpredicatbility makes it virtually impossible for a hostile web site to trick your Squeezebox Server into doing something you don't want.
  By default, the same "cauth" value is accepted for any URI. So once you note the "cauth" value for your system, you can use that same value with any URI/command documented here. This is the "MEDIUM" level for the "csrfProtectionLevel" server preference. If you have trouble using the web interface -- for instance, some non-standard browsers do not send "Referer" headers with their requests -- you may change your csrfProtectionLevel to "NONE". This is generally not recommended, but is available to you.
  If you want greater protection against CSRF attacks, you may set your csrfProtectionLevel server preference to "HIGH" so that each different command/URI will insist on a unique (but reusable) "cauth=" value. For instance, the "cauth" parameter for `http://10.0.1.201:9000/status.html?p0=playlist&p1=play&p2=soothing` would be completely different for the parameter for `http://10.0.1.201:9000/status.html?p0=playlist&p1=play&p2=loud-alarm` This also makes it more difficult for an attacker to trick your Squeezebox Server into doing something you don't want.
Request appears to be an AJAX/XmlHttpRequest call
  Requests bearing X-Requested-With headers indicating that they are legitimate XmlHttpRequest calls will be allowed, as Javascript/XmlHttpRequest security guidelines and Squeezebox Server username/password authentication should make JAX/XmlHttpRequest calls safe to act on.

#### Multiple Players

Finally, if more than one player is connected to the system, you can specify that player with a unique player identifier for the device being controlled. This unique identifier is generated when the player connects. This identifier may be in the form of an IP address or MAC address, depending on the kind of client that's connecting.

For example, the following pauses the player and then returns the status as an HTML page for the player at IP address 10.0.1.202:

    http://10.0.1.201:9000/status.html?p0=pause&p1=1&player=10.0.1.202

For example, the following pauses the player and then returns the status as an HTML page for the player at MAC address: 04:00:20:12:45:AB

    http://10.0.1.201:9000/status.html?p0=pause&p1=1&player=04:00:20:12:45:AB

Examples

The following plays the song "10,000 Maniacs/Blind Man's Zoo/01. Eat for Two.mp3" in the library and returns the status as an HTML page:

    http://10.0.1.204:9000/status.html?p0=playlist&p1=play&p2=%2f10,000%20Maniacs%2fBlind%20Man's%20Zoo%2f01.%20Eat%20for%20Two.mp3

The following adds every song in the directory "10,000 Maniacs/Blind Man's Zoo/" to the end of the playlist and returns the current player's playlist as an M3U file:

    http://10.0.1.204:9000/status.m3u?p0=playlist&p1=add&p2=%2f10,000%20Maniacs%2fBlind%20Man's%20Zoo

The following displays "Danger Will Robinson" on line 1 and "Hi Mom" on the second line for five seconds, and sends an empty response:

    http://10.0.1.204:9000/status?p0=display&p1=Danger%20Will%20Robinson&p2=Hi%20Mom&p3=5

The following simulates a press of the MENU button on the infrared remote and sends a response of a two line text document containing the text shown on the display:

    http://10.0.1.204:9000/status.txt?p0=button&p1=menu

Valid button codes correspond to the functions defined in the Default.map file: add", "brightness_down", "brightness_toggle", "brightness_up", "done", "down", "fire", "jump_fwd", "jump_rew", "left", "left_repeat", "menu_browse_album", "menu_browse_artist", "menu_browse_genre", "menu_browse_music", "menu_browse_playlists", "menu_plugins", "menu_home", "menu_now_playing", "menu_playlist", "menu_pop", "menu_search_album", "menu_search_artist", "menu_search_song", "menu_settings", "muting", "numberScroll_0", "numberScroll_1", "numberScroll_2", "numberScroll_3", "numberScroll_4", "numberScroll_5", "numberScroll_6", "numberScroll_7", "numberScroll_8", "numberScroll_9", "pause", "play", "play_0", "play_1", "playdisp_0", "playdisp_1", "playdisp_2", "playdisp_3", "playdisp_4", "playdisp_5", "playdisp_toggle", "power_off", "power_on", "power_toggle", "repeat_0", "repeat_1", "repeat_2", "repeat_toggle", "right", "right", "scan_end", "scan_fwd", "scan_rew", "search", "shuffle_off", "shuffle_on", "shuffle_toggle", "sleep", "slimtrisButtonHandler_add", "slimtrisButtonHandler_down", "slimtrisButtonHandler_left", "slimtrisButtonHandler_play", "slimtrisButtonHandler_right", "slimtrisButtonHandler_up", "stop", "textsize_large", "textsize_small", "textsize_medium" (on displays that support it), "textsize_toggle", "titleFormat", "up", "volume_down", & "volume_up".

Finally, static content may be served by the player by placing the content in the 'html' subdirectory within the root content directory for the HTTP server. For example:

    http://10.0.1.201:9000/html/test.html

This will return the file test.html within the 'html' subdirectory in the root content directory for the http server. Currently this resides in:

    slim/server/html/EN/html/test.html

#### Player Status

When you use the HTTP interface to control the Squeezebox Server (and player) to obtain status the server returns a response that contains:

- A header indicating a content type
- Several headers indicating the status of the player
- A response body

You can use one of five basic URL formats:

URL Format | Content Returned | "content-type:" Header Value
http://host:port/status | No content | (none)
http://host:port/status.html | Human readable HTML page indicating the status of the player | text/html
http://host:port/xml/status.xml | XML data indicating the status of the player (see The XML Skin documentation) | text/xml
http://host:port/status.m3u | M3U playlist file | audio/x-mpegurl
http://host:port/status.txt | Plain text of player's display contents | text/plain

The following is an example of an HTTP status transactions. The text in blue is sent from the client to the Squeezebox Server HTTP server. Text in red is returned by the Squeezebox Server HTTP server.

    GET /status.html?p0=pause&p1=1 HTTP/1.0

    HTTP/1.0 200 OK
    Content-Type: audio/x-mpegurl

    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/01. Excursions.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/02. Buggin' Out.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/03. Rap Promoter.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/04. Butter.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/05. Verses From The Abstrac.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/06. Show Business.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/07. Vibes And Stuff.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/08. The Infamous Date Rape.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/09. Check The Rhime.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/10. Everything Is Fair.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/11. Jazz (We've Got).mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/12. Skypager.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/13. What?.mp3
    /Volumes/10.0.1.201/A Tribe Called Quest/The Low End Theory/14. Scenario.mp3

[% PROCESS helpfooter.html %]