Telescope HTTP JSON interface

NOTE: This is all proposed, as this isn't even at alpha yet!
this interface is based on HTTP, I honestly don't know how 1.0/1.1 would affect it, but we'll say 1.1

Requests may be made with no extension, in which case JSON format will be assumed. e.g. /playlists is equivalent to /playlists.json

Media lists requests are a cascading list of filters, starting with the library, then the playlist, then applying different filters. Finally the type of information is set.
Examples
/library/LIBRARY_GUID/playlists
/library/LIBRARY_GUID/playlist/PLAYLIST_GUID
/playlist/PLAYLIST_GUID/artist/The Verve/albums

The first parameter specifies the library, and is optional, if it is not used the main songbird library is assumed.
/library/LIBRARY_GUID
or
/
These return a MediaListInfo object structure, and MediaListInfo data can be requested Next we can look for media lists contained within the current media list, like so:
/library/LIBRARY_GUID/playlist/PLAYLIST_GUID
or just
/playlist/PLAYLIST_GUID
These act the same as the Library, in that they return a MediaListInfo object structure.

To find out what sub media lists are contained within a media list (e.g. the library), append playlists
/library/LIBRARY_GUID/playlists
/playlists

With the media list chosen, optional filters can be applied, these are: artist, album, genre, year. These can be chained together
…./playlist/PLAYLIST_GUID/artist/ARTIST_FILTER/
…./playlist/PLAYLIST_GUID/artist/The Verve/album/Urban Hymns

Once you have a media list, you can choose various data sets from it. The default data set is returned if nothing is appended: (NOTE: this default result only includes tracks in the list, and not playlists, playlists must be returned using the /playlist data set)
/playlist/PLAYLIST_GUID/artist/ARTIST_FILTER/
returns

{ 
  guid: 'string'                   The guid of the media list
  name : 'string'                  The name of the media list
  listtype: 'string'               The type of the media list, or -1 if the list is filtered
  tracks : [ mediaItem ]           An array of media items in this list
 }

A media item is an object of the form:

{ guid: 'string'                    The GUID of this media item
  name: 'string'                    The name
  artist: 'string'
  album: 'string'
  genre: 'string'
  duration: integer                 The length of this track in ms
}

The following options can be used to get a list of unique properties for the items in the current list: artists, albums, genres, tracks. These return a list of each unique property value along with a count of how many items have that property.
Examples:
/playlist/PLAYLIST_GUID/artists
/albums
returns

[                                 An Array of all property values
  { name: 'string'                A property value
    count: integer                The number of items with this property value
  }
]

Assuming a base URI of http://server_addr:3689/service the path structure would look like this /items.json - a list of all items (songs, radio files etc) in the database, basically anything that can be played.
/playlists.json - a list of all playlists in songbird, including smart playlists
/item/id - the songbird file (e.g. the mp3 file), or the URL of the item, may return 502 Bad Gateway if it cannot return the resource. No file format should be specified for this. may support partial requests
/playlist/id.json - a list of all items in the playlist, same format as /items.json
/player - the player resource, standard GET returns details of currently playing stuff. POST used to modify. See below for details

Data on individual tracks is found by using /track instead of /playlist Examples /track/TRACK_GUID /library/LIBRARY_GUID/track/TRACK_GUID

by default this returns the track file in it's entirity, with the content-type set. (so an mp3 returns the mp3 file with the audio/mpeg content type) Other specifiers are:
/track/TRACK_GUID/info
Returns a media item object as above for this track
/track/TRACK_GUID/art
Returns the primary art associated with this track (usually album art). An extension should not be specified, return format depends on the format of the album art itself (Content-Type is set)

/search?search=«searchterm» You can perform a full search using this resource. This searches for artists, albums and tracks at once. Artists and Albums must match their fields, but Tracks can match any metadata (so a search for 'Kings' would list all tracks by Kings of Leon for example.

{
 artists[]:
    name:   'string'      Artist Name
 albums[]:
    name:   'string'      Album Name
 tracks[]:                Media Item Object 
} 

/player this is used to see and control what is playing. It can also be controlled via POST messages GET: returns a JSON array of the currently playing item and the player status

{
  curItemIndex: integer       The index of the curent item in the currently playing view
                              NOTE: an index of -1 signifies no view loaded
  curItem : {mediaItem}       A media Item object of the currently playing item
  status: integer             The status of the player
                              0 = Unknown
                              1 = Playing
                              2 = Paused
                              4 = Stopped
                              8 = Buffering
  position: integer            The current time position in the track in ms
  duration: integer            The duration of the track in ms
  volume: float                The output volume: between 0 and 1
  mute: boolean                Whether volume is muted or not
}

/player/art Returns the album artwork of the currently playing track

/player/playlist

[ mediaItem]      Returns an array of media items that comprise the current playlist

The player can be controlled using a url parameter encoded POST message. The primary field is 'action'. Different actions may require other parameters
Action (string value)

playMediaList               Plays the specified media list
     guid: string           The guid of the list to play
     library: string        **OPTIONAL** the library that contains the media list

playCustomList              Plays a custom list of media items
     guidList: string,string A comma-separated list of guids that make up the playlist
     startIndex: integer    **OPTIONAL** the index to start playing at
     library: string        **OPTIONAL** The library that contains the media list

play                        Resumes playing the current track (If nothing paused then Non-op)
pause                       Pauses current playback
next                        Skips to next track in playlist
previous                    Skips to previous track in playlist
playIndex                   Skips to a given index in the playlist
    index: integer          The index of the track to skip to

mode                        Sets whether shuffle is on or not
     mode: integer          0 = forward, 1 = reverse, 2 = shuffle
repeatMode                  Sets the repeat mode
    mode: integer           0 = no repeat, 1 = Repeat one, 2 = Repeat All

seek                        Jumps to a time in the current track
    position: integer       The time in ms to jump to

volume                      Changes the output volume
    volume: float           The new volume, between 0 and 1
    muted: boolean          Whether the volume is muted