API Logitech Squeezebox Server / Player (HTTP)

Overview

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

Logitech Media 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 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 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 Logitech Media 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, Logitech Media 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 the server via the HTTP interface. Logitech Media Server requires one of four things to be true in order to allow such control-oriented URLs to be accepted:

Referer request header matches Logitech Media Server URL
The 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 Logitech Media Server it's following a link you clicked on from a Logitech Media 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
The 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, the 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
, the 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 Logitech Media Server installation. They are based on a special "securitySecret" that is randomly assigned the first time you start the 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 server installation (so you can bookmark it or use it in your home automation system), but not work on another server setup. This unpredicatbility makes it virtually impossible for a hostile web site to trick your 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 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 the server username/password authentication should make AJAX/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 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 HTTP server. Text in red is returned by the 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

Mis à jour le : 27/06/2021 à 18:52 Auteur : Jérôme Massiaux, technicien domotique-store.fr



Les nouvelles questions sont affichées en même temps que la réponse du technicien. Nous répondons généralement en moins d'une journée ouvrée, néanmoins, certaines questions peuvent nécessiter des tests ou recherches complémentaires et augmenter ce délai. Nous nous réservons le droit de ne pas publier ni répondre aux questions de service après-vente concernant un produit n'ayant pas été acheté sur notre boutique.