Differences

This shows you the differences between two versions of the page.

Link to this comparison view

telescope_webservice [2010/08/08 21:34]
admin
telescope_webservice [2015/08/15 15:15]
Line 1: Line 1:
-====== 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 
-      ​ 
- 
- 
-