[% pageicon = 'help' %] [% pagetitle = 'SlimServer Web Interface' %] [% techinfo = '1' %] [% PROCESS helpheader.html %]

#### Overview

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

The SlimServer 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 SlimServer 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 SlimServer 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 SlimServer 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.

#### 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 identifyer 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 SlimServer (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

For each of these formats additional headers are returned:

x-playerindex: | <currentitem> | Index of the currently played item. 1 is the first item
x-playervolume: | <currentvolume> | The current volume of the player, range 0-99
x-playertracks: | <trackcount> | Total number of tracks in the playlist
x-playershuffle: | <0|1> | Playlist shuffle state: 0=no, 1=yes
x-playerrepeat: | <0|1|2> | Playlist repeat state: 0=stop at end, 1=repeat current song, 2=repeat all songs
x-playermode: | <play|pause|stop|off> | Current player state: play, pause, stop, powered off
x-playertime: | <seconds> | Number of seconds of the song that have been played. Floating point value.
x-playerduration: | <seconds | Duration of current song in seconds. Floating point value.
x-playerartist: | <artistname> | Name of the artist associated with the currently playing song.
x-playeralbum: | <albumname> | Name of the album associated with the currently playing song.
x-playertitle: | <songtitle> | Title of the song currently playing.
x-playertrack: | <tracknumber> | Track number associated with the song currently playing.
x-playergenre: | <genrename> | Genre associated with the currently playing song.
x-player | <playerid> | The identifier for the given player
x-playername | <playername> | The human readable name assigned to the player
x-p0 | <p0> | The value of p0 after the command has been executed
x-p1 | <p1> | The value of p0 after the command has been executed
x-p2 | <p2> | The value of p0 after the command has been executed
x-p3 | <p3> | The value of p0 after the command has been executed
x-p4 | <p4> | The value of p0 after the command has been executed

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

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

    HTTP/1.0 200 OK
    Content-Type: audio/x-mpegurl
    x-playerindex: 11
    x-playervolume: 71.5
    x-playertracks: 14
    x-playershuffle: 0
    x-playerrepeat: 2
    x-playermode: play
    x-playertime: 23.245
    x-playerduration: 234.33
    x-playerartist: A Tribe Called Quest
    x-playeralbum: The Low End Theory
    x-playertitle: Jazz (We've Got)
    x-playertrack: 11
    x-playergenre: HipHop
    x-player: 10.0.1.204:69
    x-playername: Living room
    x-p0: pause
    x-p1: 1

    /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 %]