NAME

WWW::Grooveshark - Perl wrapper for the Grooveshark API

VERSION

This document describes WWW::Grooveshark version 0.02 (July 22, 2009).

The latest version is hosted on Google Code as part of http://elementsofpuzzle.googlecode.com/. Significant changes are also contributed to CPAN: http://search.cpan.org/dist/WWW-Grooveshark/.

SYNOPSIS

Basic use is demonstrated here. See "API METHODS" for details.

use WWW::Grooveshark;

my $gs = WWW::Grooveshark->new(https => 1, agent => "my-nice-robot/0.1");

my $r;
$r = $gs->session_start(apiKey => $secret) or die $r->fault_line;

for($gs->search_songs(query => "The Beatles", limit => 10)->songs) {
    printf("%s", $_->{songName});
    printf(" by %s", $_->{artistName});
    printf(" on %s\n", $_->{albumName});
    printf(" <%s>\n", $_->{liteUrl});
}

# session automatically ended by destructor

DESCRIPTION

Grooveshark is an internationally-available online music search, streaming, and recommendation service. WWW::Grooveshark wraps this service's API in an object-oriented Perl interface, allowing you to programmatically search for songs, artists, albums, or playlists; browse popular music; get song recommendations; manage playlists; and more.

API KEYS

...are needed to use the Grooveshark API. E-mail <developers@grooveshark.com> to get one. They'll probably also link you to the official API page, which seems to still be in beta.

CONSTRUCTOR

To use this module, you'll have to create a WWW::Grooveshark instance. The default, argumentless constructor should be adequate, but customization is possible through key-value options.

WWW::Grooveshark->new( %OPTIONS )

Prepares a new WWW::Grooveshark object with the specified options, which are passed in as key-value pairs, as in a hash. Accepted options are:

https: Whether or not to use HTTPS for API calls. Defaults to false, i.e. just use HTTP.
service: The hostname to use for the Grooveshark API service. Defaults to "api.grooveshark.com" unless staging is true, in which case it defaults to "staging.api.grooveshark.com".
path: Path (relative to the hostname) to request for API calls. Defaults to "ws".
api_version: Version of the Grooveshark API you plan on using. Defaults to 1.0.
query_string: The query string to include in API call requests. May be blank. Defaults to "json" so that the full default API root URL becomes <http://api.grooveshark.com/ws/1.0/?json>.
agent: Value to use for the User-Agent HTTP header. Defaults to "WWW::Grooveshark/### libwww-perl/###", where the "###" are substituted with the appropriate versions. This is provided for convenience: the user-agent string can also be set in the useragent_args (see below). If it's set in both places, this one takes precedence.
useragent_class: Name of the LWP::UserAgent compatible class to be used internally by the newly-created object. Defaults to LWP::UserAgent.
useragent_args: Hashref of arguments to pass to the constructor of the aforementioned useragent_class. Defaults to no arguments.

Options not listed above are ignored.

DESTRUCTOR

I like code that cleans up after itself. If a program starts by creating a session, it's only logical that it should finish by ending it. But should it be up to the programmer to manage when that happens? Anyone can be forgetful.

Enter the destructor. Continue explicitly cleaning up, but if you forget to do so, the destructor has your back. When a WWW::Grooveshark object gets garbage collected, it will destroy its session if any.

MANAGEMENT METHODS

The following methods do not issue any API calls but deal with management of the WWW::Grooveshark object itself. Ideally, you won't have to touch these methods too often. If you find yourself being insufficiently lazy, let me know how I can make this module smarter.

$gs->sessionID( ): Returns the Grooveshark API session ID, or undef if there is no active session.

API METHODS

The methods listed here directly wrap the methods of Groveshark's JSON-RPC API. As you may have noticed, there is a very complex mapping between the API's official methods and those of this interface: replace the period ('.') with an underscore ('_'). As with the constructor, pass arguments as hash-like key-value pairs, so for example, to get the 11th through 20th most popular songs, I would:

my $response = $gs->popular_getSongs(limit => 10, page => 2);

All API methods return WWW::Grooveshark::Response objects, even in case of errors, but their boolean evaluation is overloaded to give false for fault responses. Make a habit of checking that method calls were successful:

die $response->fault_line unless $response;

Access result elements by using the key as the method name. In list context, dereferencing takes place automagically, saving you a few characters:

my @songs = $response->songs;

But after this first "layer" you're stuck dealing with hashrefs, as in the "SYNOPSIS" (though perhaps this will change in the future if I'm up to it):

for(@songs) {
    printf("%s", $_->{songName});
    printf(" by %s", $_->{artistName});
    printf(" on %s\n", $_->{albumName});
    printf(" <%s>\n", $_->{liteUrl});
}

Check the official API documentation for valid keys. Alternatively, experiment!

use Data::Dumper;
print Dumper($response);

This module's interface aims to parallel the official API as much as possible. Consequently, all methods take argument names identical to the official ones. However, some methods are "overloaded." For example, session_createUserAuthToken gives you the option of passing a plaintext pass rather than a hashpass, handling hashpass generation for you.

Some methods may also have side effects. These are generally "harmless": for example, successful session_create and session_get calls store the returned session ID so that it can be passed in the header of subsequent API calls.

Alternate method arguments and any side effects are listed where applicable.

ALBUM

$gs->album_about( albumID => $ALBUM_ID ): Returns meta-information for the album with the specified $ALBUM_ID, such as album name, artist ID, and artist name.
$gs->album_getSongs( albumID => $ALBUM_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Returns all the songs on the album with the specified $ALBUM_ID, as well as song meta-information.

ARTIST

$gs->artist_about( artistID => $ARTIST_ID ): Returns information for the artist with the specified $ARTIST_ID.
$gs->artist_getAlbums( artistID => $ARTIST_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Returns the albums of the artist with the specified $ARTIST_ID, as well as album meta-information.
$gs->artist_getSimilar( artistID => $ARTIST_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Returns a list of artists similar to the one with the specified $ARTIST_ID.
$gs->artist_getSongs( artistID => $ARTIST_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Returns the songs on the albums of the artist with the specified $ARTIST_ID, as well as song meta-information.
$gs->artist_getTopRatedSongs( artistID => $ARTIST_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Returns the top rated songs of the artist with the specified $ARTIST_ID, as well as song meta-information. Use at your own risk: the existence of this method was not mentioned in the official API documentation at the time of this writing; it was discovered through the sandbox tool.

AUTOPLAY

$gs->autoplay_frown( autoplaySongID => $AUTOPLAY_SONG_ID ): "Frowns" the song with the specified $AUTOPLAY_SONG_ID in the current Autoplay session, indicating that the song is not liked and making the Autoplay session suggest fewer songs like it.
$gs->autoplay_getNextSong( ): Returns the next suggested song in the current Autoplay session, based on the seed songs and any "smiles" or "frowns."
$gs->autoplay_smile( autoplaySongID => $AUTOPLAY_SONG_ID ): "Smiles" the song with the specified $AUTOPLAY_SONG_ID in the current Autoplay session, indicating that the song is liked and making the Autoplay session suggest more songs like it.
$gs->autoplay_start( songIDs => \@SONG_IDS ): Starts an Autoplay session seeded with the specified song IDs and returns the first song suggestion.
$gs->autoplay_stop( ): Ends the active Autoplay session.

PLAYLIST

$gs->playlist_about( playlistID => $PLAYLIST_ID ): Returns information for the playlist with the specified $PLAYLIST_ID, such as its name, description, song count, creation date, etc.
$gs->playlist_addSong( playlistID => $PLAYLIST_ID , songID => $SONG_ID [, position => $POSITION ] ): Adds the song with the specified $SONG_ID to the playlist with the specified $PLAYLIST_ID at $POSITION (or at the end, if $POSITION is omitted). Valid positions start from 1: a value of zero is equivalent to not specifying any. To succeed, this method requires being authenticated as the playlist's creator.
$gs->playlist_create( name => $NAME, about => $DESCRIPTION ): Creates a playlist with the specified $NAME and $DESCRIPTION and returns the playlist ID. Requires user authentication.
$gs->playlist_delete( playlistID => $PLAYLIST_ID ): Deletes the playlist with the specified $PLAYLIST_ID. Requires being authenticated as the playlist's creator.
$gs->playlist_getSongs( playlistID => $PLAYLIST_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Returns the songs on the playlist with the specified $PLAYLIST_ID, as well as song meta-information.
$gs->playlist_moveSong( playlistID => $PLAYLIST_ID , position => $POSITION , newPosition => $NEW_POSITION ): Moves the song at $POSITION in the playlist with the specified $PLAYLIST_ID to $NEW_POSITION. Valid positions start from 1. A $NEW_POSITION of zero moves the song to the end of the playlist. To succeed, this method requires being authenticated as the playlist's creator.
$gs->playlist_removeSong( playlistID => $PLAYLIST_ID , position => $POSITION ): Removes the song at $POSITION from the playlist with the specified $PLAYLIST_ID. Valid positions start from 1. To succeed, this method requires being authenticated as the playlist's creator.
$gs->playlist_rename( playlistID => $PLAYLIST_ID , name => $NAME ): Renames the playlist with the specified $PLAYLIST_ID to $NAME. Requires being authenticated as the playlist's creator.
$gs->playlist_replace( playlistID => $PLAYLIST_ID , songIDs = \@SONG_IDS ): Replaces the contents of the playlist with the specified $PLAYLIST_ID with the songs corresponding to the given @SONG_IDS, in the specified order. To succeed, this method requires being authenticated as the playlist's creator. (But at the time of this writing, this didn't seem to work as expected, instead returning an internal server error message.)

$gs->popular_getAlbums( [ limit => $LIMIT ] [, page => $PAGE ] ): Gets a list of popular albums (and meta-information) from Grooveshark's billboard.
$gs->popular_getArtists( [ limit => $LIMIT ] [, page => $PAGE ] ): Gets a list of popular artists from Grooveshark's billboard.
$gs->popular_getSongs( [ limit => $LIMIT ] [, page => $PAGE ] ): Gets a list of popular songs (and meta-information) from Grooveshark's billboard.

SEARCH

$gs->search_albums( query => $QUERY [, limit => $LIMIT ] [, page => $PAGE ] ): Searches for albums with names that match $QUERY.
$gs->search_artists( query => $QUERY [, limit => $LIMIT ] [, page => $PAGE ] ): Searches for artists with names that match $QUERY.
$gs->search_playlists( query => $QUERY [, limit => $LIMIT ] [, page => $PAGE ] ): Searches for playlists that match $QUERY by name or by meta-information of composing songs.
$gs->search_songs( query => $QUERY [, limit => $LIMIT ] [, page => $PAGE ] ): Searches for songs that match $QUERY by name or meta-information.

SERVICE

$gs->service_getMethods( ): Gets a list of the methods supported by the service, as well as the names of their parameters. Calling this method doesn't require a session.
$gs->service_getVersion( ): Gets the version of the API supported by the service. Calling this method doesn't require a session.
$gs->service_ping( ): Checks that the service is alive. Calling this method doesn't require a session. Useful for testing (and for getting a "Hello, world" greeting in some language).

SESSION

$gs->session_createUserAuthToken( username => $USERNAME , pass => $PASS | hashpass => $HASHPASS ): Creates an authentication token for the specified $USERNAME. Authentication requires a $HASHPASS, which is a hexadecimal MD5 hash of the concatenation of $USERNAME and a hexadecimal MD5 hash of $PASS. If you're storing the password as plaintext, don't bother generating the $HASHPASS yourself: just omit the $HASHPASS and give pass => $PASS to this method. If you specify both a $HASHPASS and a $PASS, the $HASHPASS will take precedence (but don't try it). Regardless, the $PASS will be removed from the arguments that are passed during the API call.
$gs->session_destroy( ): Destroys the currently active session. As a side effect, removes the stored session ID so that subsequent sessionID calls on this WWW::Grooveshark object will return undef.
$gs->session_destroyAuthToken( token => $TOKEN ): Destroys an auth token so that subsequent attempts to use it to login will fail.
$gs->session_get( ): Gets the session ID of the currently active session. Presumably this updates every once in a while because there wouldn't be much use in this method otherwise: an active session is required to call it, and returning the same session ID would be a waste of an API call... Assuming this does update, calling this method has the side effect of updating the session ID of this WWW::Grooveshark object.
$gs->session_getUserID( ): Gets the user ID of the currently logged-in user.
$gs->session_loginViaAuthToken( token => $TOKEN ): Logs in using a $TOKEN created using session_createUserAuthToken.
$gs->session_logout( ): Logs out the logged-in user.
$gs->session_start( apiKey => $API_KEY [, mobileID => $MOBILE_ID ] ): Starts a session using the specified $API_KEY. This method must be called before using (nearly) all of the other methods. The returned session ID will be stored in this WWW::Grooveshark object, accessible via calls to sessionID, and automatically placed in the header of subsequent API calls. $MOBILE_ID isn't mentioned in the official documentation and appears only in the sandbox tool.

SONG

$gs->song_about( songID => $SONG_ID ): Returns meta-information for the song with the specified $SONG_ID, such as song name, album name, album ID, artist name, artist ID, etc.
$gs->song_favorite( songID => $SONG_ID ): Marks the song with the specified $SONG_ID as a favorite. Requires user authentication.
$gs->song_getSimilar( songID => $SONG_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Gets a list of songs similar to the one with the specified $SONG_ID, as well as their meta-information.
$gs->song_getStreamKey( songID => $SONG_ID ): Gets a streamKey for the song with the specified $SONG_ID (needed to authorize playback for some Grooveshark embeddable players).
$gs->song_getStreamUrl( songID => $SONG_ID ): Gets an URL for streaming playback of the song with the specified $SONG_ID. According to the response header, this method is deprecated and song_getStreamUrlEx should be used instead.
$gs->song_getStreamUrlEx( songID => $SONG_ID [, lowBitrate => $LOW_BITRATE ] ): The supposedly preferred alternative to song_getStreamUrlEx. Use at your own risk: the existence of this method was not mentioned in the official API documentation at the time of this writing; it was discovered through the sandbox tool as well as the deprecation message in the header of song_getStreamUrl responses.
$gs->song_getWidgetEmbedCode( songID => $SONG_ID [, theme => $THEME ] [, pxHeight => $HEIGHT ] [, pxWidth => $WIDTH ] [, ap => $AP ] ): Gets HTML code for embedding the song with the specified $SONG_ID. The code may be customized by specifying a pixel $HEIGHT and $WIDTH as well as a theme for the widget, which must be in qw(metal grass wood water). The $AP is optional and appears only in the sandbox tool and not the official documentation: its meaning is unknown.
$gs->song_getWidgetEmbedCodeFbml( songID => $SONG_ID [, theme => $THEME ] [, pxHeight => $HEIGHT ] [, pxWidth => $WIDTH ] [, ap => $AP ]: This is in fact not an API method but a wrapper for song_getWidgetEmbedCode that modifies the returned HTML code to FBML so it can be used in Facebook applications. This method is experimental: use it at your own risk.
$gs->song_unfavorite( songID => $SONG_ID ): Removes the song with the specified $SONG_ID from the logged-in user's list of favorites.

TINYSONG

$gs->tinysong_create( songID => $SONG_ID | ( query => $QUERY [, useFirstResult => $USE_FIRST_RESULT ] ) ): Creates a tiny URL that links to the song with the specified $SONG_ID. The method seems to also allow searching (if a $QUERY and whether to $USE_FIRST_RESULT are specified), but this form appears to be buggy at the time of this writing, and is discouraged.
$gs->tinysong_getExpandedUrl( tinySongUrl => $TINYSONG_URL ): Expands a TinySong URL into the full URL to which it redirects.

USER

$gs->user_about( $user_id => $USER_ID ): Returns information about the user with the specified $USER_ID, such as username, date joined, etc.
$gs->user_getFavoriteSongs( $user_id => $USER_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Returns songs (and meta-information) from the favorite list of the user with the specified $USER_ID.
$gs->user_getPlaylists( $user_id => $USER_ID [, limit => $LIMIT ] [, page => $PAGE ] ): Gets the playlists created by the user with the specified $USER_ID.

BUGS

Please report them! The preferred way to submit a bug report for this module is through CPAN's bug tracker: http://rt.cpan.org/Public/Dist/Display.html?Name=WWW-Grooveshark. You may also create an issue at http://elementsofpuzzle.googlecode.com/ or drop me an e-mail.

AUTHOR

Miorel-Lucian Palii <mlpalii@gmail.com>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available. See perlartistic.

To install WWW::Grooveshark, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WWW::Grooveshark

CPAN shell

perl -MCPAN -e shell
install WWW::Grooveshark

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

API KEYS

CONSTRUCTOR

DESTRUCTOR

MANAGEMENT METHODS

API METHODS

ALBUM

ARTIST

AUTOPLAY

PLAYLIST

POPULAR

SEARCH

SERVICE

SESSION

SONG

TINYSONG

USER

SEE ALSO

BUGS

AUTHOR

COPYRIGHT AND LICENSE

NAME

VERSION

SYNOPSIS

DESCRIPTION

API KEYS

CONSTRUCTOR

DESTRUCTOR

MANAGEMENT METHODS

API METHODS

ALBUM

ARTIST

AUTOPLAY

PLAYLIST

POPULAR

SEARCH

SERVICE

SESSION

SONG

TINYSONG

USER

SEE ALSO

BUGS

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions