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
Getting Media Lists
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
Getting Track Data
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?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 resource
/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