API server

intarstudents edited this page Oct 22, 2012 · 15 revisions

Getting Started

What, what?

keySharky API server ( internally known as gsAPI ) listens to HTTP 1.1 requests ( to specified port, with default tunned to 8800 ), those can be used to remotely control Grooveshark player interface, who is siting inside Firefox or Prism.

It has been internally blended into keyShark starting from version 1.4

Configure API server in keySharky

Be sure that you know what is Firewall and what evil it can do, when configuring desired port number;

  • In Firefox main window go to Tools > Add-ons > (in list find keySharky and press Preferences);
  • If server is running, press Stop;
  • Now in Port input box, select your desired port number;
  • Check Start with ... checkbox, if you want to start API server, when you open Firefox or Prism;
  • Press Start to run server;

FYI

Replace PORT in this wiki, with port number that you have chosen in keySharky or with default one – 8800.

Sample usage (with wget in Ubuntu)

If you’re lazy terminal guy, you could write this wget command to play/pause current song, never leaving terminal window!

$ wget http://localhost:PORT/play --spider --no-cache

Simple and fast, isn’t it? Just remember that “With great power comes great responsibility.” ;)

Methods

API server has access to every keyboard shortcut toggle in keySharky, so you can play, stop, select next song etc. easily with one of these methods.

List of them

Play/Pause current song

http://localhost:PORT/play

Stop playing current song

http://localhost:PORT/stop

Select previous song in playlist

http://localhost:PORT/previous

Select next song in playlist

http://localhost:PORT/next

Favorite current song

http://localhost:PORT/favorite

Remove current song from queue (>= 1.6)

http://localhost:PORT/remove

Vote up current song

http://localhost:PORT/voteup

Vote down current song

http://localhost:PORT/votedown

Clear vote of current song

http://localhost:PORT/voteclear

Toggle mute (>= 1.5.2)

http://localhost:PORT/mute

Decrease volume (>= 1.5.2)

http://localhost:PORT/voldown

Increase volume (>= 1.5.2)

http://localhost:PORT/volup

Retrieve current song status

http://localhost:PORT/currentSong

This, if successful, will return something like this (in plain text):

status: playing
artistID: 2267
songID: 25363319
songName: Hero feat. Keri hilson
artURL: 
trackNum: 0
estimateDuration: 244453.8775510204
artistName: Nas
albumID: 4343114
albumName: Hero - Single

Retrieve previous song status (>= 1.5)

http://localhost:PORT/previousSong

This, if successful, will return something like this (in plain text):

estimateDuration: 180924.08163265305
albumName: Hands All Over
artURL: http://beta.grooveshark.com/static/amazonart/m4599155.jpg
artistName: Maroon 5
trackNum: 0
songID: 26770042
albumID: 4599155
artistID: 193
songName: Give A Little More
vote: 0

Retrieve next song status (>= 1.5)

http://localhost:PORT/nextSong

This, if successful, will return something like this (in plain text):

estimateDuration: 268000
albumName: Ready For The Weekend
artURL: 
artistName: Calvin Harris
trackNum: 3
songID: 23230835
albumID: 3427707
artistID: 7612
songName: Stars Come Out
vote: 0

Retrieve volume (>= 1.5.2)

http://localhost:PORT/volume

This, if successful, will return something like this (in plain text):

volume: 79

Set volume (>= 1.5.2)

http://localhost:PORT/setVolume?[0-100]

If you will try something like this " http://localhost:PORT/setVolume?50 ", it will set volume to 50 and return something like this (in plain text):

VOLUME SET TO 50

Check if muted (>= 1.5.2)

http://localhost:PORT/muted

This, if successful, will return something like this (in plain text):

muted: false

Retrieve Grooveshark version (>= 1.5.2)

http://localhost:PORT/gs-version

This, if successful, will return something like this (in plain text):

20100831

Retrieve GroovesharkAPI version (>= 1.5.2)

http://localhost:PORT/gs-api-version

This, if successful, will return something like this (in plain text):

1.3

Responses and Errors

In world, nothing is perfect, so same applies to this API. But luckily, if you really care what has gone wrong, you can see it.

200 – Method executed fine

If answer header to one of these methods has status code 200, you should be fine and method executed as supposed.

TOGGLING (play) OK

500 – Problems while executing method

If answer header to one of these methods has status code 500, you may experiencing little turbulence:

  • keySharky couldn’t find Grooveshark player;
  • gsliteswf object has been modified and doesn’t provide that method anymore;
TOGGLING (play) FAILED

501 – Not implemented

If answer header to one of these methods has status code 501, you have requested method that doesn’t exist in API.