Clients

Although not heavily commented, we hope the source code itself should provide some insight into how things work.

The simple client

The simple client is our console based multi-OS proof of concept client.

Available commands:

list [num]              List stored playlists
rename [num] [string]   Rename playlist
collab [num]            Toggle playlist collaboration

search [string]         Search for [string] or get next 100 results
artist [num]            Show information about artist for track [num]
album [num]             List album for track [num]
uri [string]            Display info about Spotify URI
portrait [num]          Save artist portrait to portrait.jpg

play [num]              Play track [num] in the last viewed list
playalbum [num]         Play album for track [num]
stop, pause, resume     Control playback

info                    Details about your account and current connection
help                    This text
quit                    Quit

> list
 1: I <3 techno in the morning                58   christ0ph
 2: Electrogirls                              13   nshearing
 3: Binary Beats                              36   vengo

> list 2
  1: Crimewave (Crystal Castles vs. Health)    4:18 Crystal Castles
  2: Paris Is Burning                          3:47 Ladyhawke
  3: Stuck On Repeat                           3:19 Little Boots
  4: Little Bit                                4:33 Lykke Li
 [ .. snip .. ]

> search foo

Artists found (9):
 Foo Fighters
 Kung Foo
 [ .. snip .. ]

Albums found (4):
 Foo Foo
 Foo Fighters
 [ .. snip .. ]

Tracks found (100/195):
  1: This Is a Call                            3:53 Foo Fighters
  2: Big Me                                    2:12 Foo Fighters
 [ .. snip .. ]

Supported commands

  • list [number]
    List all playlists or select playlist with number [number]
  • rename [number] [string]
    Rename playlist [number] to [string]
  • collab [number]
    Toggle collaborative flag on playlist [number]
  • search [string]
    Search for [string] or get next 100 results
  • artist [num]
    Show information about artist for track [num]
  • album [num]
    List album for track [num]
  • uri [string]
    Display info about Spotify URI
  • portrait [num]
    Save artist portrait to portrait.jpg
  • play [num]
    Play track [num] in the last viewed list
  • playalbum [num]
    Play album for track [num]
  • stop, pause, resume
    Control playback
  • info
    Details about your account and current connection
  • help
    List of commands
  • quit
    Quit the client

The ncurses client

Despotify curses client (splash screen)Despotify curses client (search window)

The despotify Gateway

The gateway was implemented to support a HTTP REST API. The idea is to have the gateway running in the background and keep logged in sessions to Spotify alive. The frontend (HTTP) part can easily be implemented by making your favorite web scripting language talk to the backend over a socket.

Supported commands

  • login username password
    Start a new session by logging in as username to Spotify
  • session sessionid
    Reconnect to an established session using a session ID reported by the id command.
  • id
    Report the session ID of a logged in session.
  • country
    Report the assigned country code for the logged in user.
  • search search-text
    Dump search result as XML. Use tag:new as search text to find out what’s new.
  • playlist playlist-id
    Dump the playlist as XML. Playlist IDs are 34 characters (hex representation of 17 byte IDs). Use 34 zeroes to get a list of all playlists for the logged in user.
  • browsetrack track-id
    Dump the track metadata as XML. Track IDs are 32 characters (hex representation of 16 byte IDs). Use the 32 first characters from the playlist XML dump
  • browseartist artist-id
    Dump the artist metadata as XML. Artist IDs are 32 characters (hex representation of 16 byte IDs). Artist IDs are found in browsetrack or search replies.
  • logout
    Drop the established session.
  • quit
    Shutdown the connection to the gateway. This does not kill an eventual session to Spotify.

Interaction with the gateway

The gateway uses a text-based protocol to ease testing and integration with other software.

The output format looks like this:
<HTTP-style error code> <payload length> <OK/WARN/ERROR> <description>\n
[eventual payload data, as long as "payload length" says]

Here’s an example.

this is going to fail
501 0 WARN Invalid command 'this is going to fail'
login foouser barpassword
200 0 OK Login successful
country
200 2 OK Assigned country below
SE