Python Grooveshark

class grooveshark.Client(session=None, proxies=None)

A client for Grooveshark’s API which supports:

  • radio (songs by genre)
  • search for songs, artists and albums
  • popular songs
Parameters:
  • session – a Session object with session information
  • proxies – dictionary mapping protocol to proxy
collection(user_id)

Get the song collection of a user.

Parameters:user_id – ID of a user.
Return type:list of Song
favorites(user_id)

Get the favorite songs of a user.

Parameters:user_id – ID of a user.
Return type:list of Song
init()

Fetch Grooveshark’s token and queue id.

Return type:tuple: (init_session(), init_token(), init_queue())
init_queue()

Initiate queue. Make sure to call init_token() first.

init_token()

Fetch Grooveshark’s communication token.

playlist(playlist_id)

Get a playlist from it’s ID

Parameters:playlist_id – ID of the playlist
Return type:a Playlist object
popular(period='daily')

Get popular songs.

Parameters:period – time period
Return type:a generator generates Song objects

Time periods:

Constant Meaning
Client.DAILY Popular songs of this day
Client.MONTHLY Popular songs of this month
radio(radio)

Get songs belong to a specific genre.

Parameters:radio – genre to listen to
Return type:a Radio object

Genres:

This list is incomplete because there isn’t an English translation for some genres. Please look at the sources for all possible Tags.

Constant Genre
Radio.GENRE_RNB R and B
Radio.GENRE_JAZZ Jazz
Radio.GENRE_ROCK Rock
Radio.GENRE_CLASSICAL Classical
Radio.GENRE_DUBSTEP Dubstep
Radio.GENRE_BLUES Blues
Radio.GENRE_FOLK Folk
Radio.GENRE_ELECTRONICA Electronica
Radio.GENRE_CHRISTMAS Christmas
Radio.GENRE_OLDIES Oldies
Radio.GENRE_COUNTRY Country
Radio.GENRE_EXPERIMENTAL Experimental
Radio.GENRE_POP Pop
Radio.GENRE_INDIE Indie
Radio.GENRE_BLUEGRASS Bluegrass
Radio.GENRE_RAP Rap
Radio.GENRE_AMBIENT Ambient
Radio.GENRE_TRANCE Trance
Radio.GENRE_REGGAE Reggae
Radio.GENRE_METAL Metal
search(query, type='Songs')

Search for songs, artists and albums.

Parameters:
  • query – search string
  • type – type to search for
Return type:

a generator generates Song, Artist and Album objects

Search Types:

Constant Meaning
Client.SONGS Search for songs
Client.ARTISTS Search for artists
Client.ALBUMS Search for albums
Client.PLAYLISTS Search for playlists
class grooveshark.classes.Picture(url, connection)

Could be an album cover or a user picture. Do not use this class directly.

Parameters:url – image url
data

raw image data

type

image type for example png or jpg

class grooveshark.classes.Stream(ip, key, connection)

Get song’s raw data. Do not use this class directly.

Parameters:
  • ip – streaming server address
  • key – streaming key required to get the stream
  • connection – underlying Connection object
data

a file-like object containing song’s raw data

ip

stream server IP

key

stream key

size

size of the song’s raw data in bytes

url

stream URL

class grooveshark.classes.Album(id, name, artist_id, artist_name, cover_url, connection)

Represents an album. Do not use this class directly.

Parameters:
  • id – internal album id
  • name – name
  • artist_id – artist’s id to generate an Artist object
  • artist_name – artist’s name to generate an Artist object
  • cover_url – album’s cover to generate an Album object
  • connection – underlying Connection object
artist

Artist object of album’s artist

cover

album cover as Picture object

export()

Returns a dictionary with all album information. Use the from_export() method to recreate the Album object.

id

internal album id

name

album’s name

songs

iterator over album’s songs as Song objects

class grooveshark.classes.Artist(id, name, connection)

Represents an artist. Do not use this class directly.

Parameters:
  • id – internal artist id
  • name – name
  • connection – underlying Connection object
export()

Returns a dictionary with all artist information. Use the from_export() method to recreate the Artist object.

id

internal artist id

name

artist’s name

similar

iterator over similar artists as Artist objects

songs

iterator over artist’s songs as Song objects

class grooveshark.classes.Song(id, name, artist_id, artist_name, album_id, album_name, cover_url, track, duration, popularity, connection)

Represents a song. Do not use this class directly.

Parameters:
  • id – internal song id
  • name – name
  • artist_id – artist’s id to generate an Artist object
  • artist_name – artist’s name to generate an Artist object
  • album_id – album’s id to generate an Album object
  • album_name – album’s name to generate an Album object
  • cover_url – album’s cover to generate an Album object
  • track – track number
  • duration – estimate song duration
  • popularity – popularity
  • connection – underlying Connection object
album

album as Album object

artist

artist as Artist object

download(directory='~/Music', song_name='%a - %s - %A')

Download a song to a directory.

Parameters:
  • directory – A system file path.
  • song_name – A name that will be formatted with format().
Returns:

The formatted song name.

duration

estimate song duration

export()

Returns a dictionary with all song information. Use the from_export() method to recreate the Song object.

format(pattern)

Format the song according to certain patterns:

%a: artist title %s: song title %A: album title

id

internal song id

name

song name

popularity

popularity

safe_download()

Download a song respecting Grooveshark’s API.

Returns:The raw song data.
stream

Stream object for playing

track

track number

class grooveshark.classes.Radio(artists, radio, connection, recent_artists=[], songs_already_seen=[])

Listen to songs by specific genre. Do not use this class directly.

Parameters:
  • artists – list of artist ids
  • radio – the genre (see Client‘s radio() method)
  • connection – the underlying Connection object
export()

Returns a dictionary with all song information. Use the from_export() method to recreate the Song object.

song

Song object of next song to play