File Coverage

blib/lib/WWW/Grooveshark.pm

Criterion	Covered	Total	%
statement	52	227	22.9
branch	7	26	26.9
condition	8	24	33.3
subroutine	13	65	20.0
pod	55	55	100.0
total	135	397	34.0

package WWW::Grooveshark;

use 5.006;
use strict;
use warnings;

=head1 NAME

WWW::Grooveshark - Perl wrapper for the Grooveshark API

=head1 VERSION

This document describes C version 0.02 (July 22, 2009).

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

=cut

our $VERSION = '0.02';
$VERSION = eval $VERSION;

=head1 SYNOPSIS

Basic use is demonstrated here.  See L 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

=head1 DESCRIPTION

Grooveshark is an internationally-available online music search, streaming,
and recommendation service.  C 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.

=head1 API KEYS

...are needed to use the Grooveshark API.  E-mail
[e-mail] to get one.  They'll probably also link
you to the official API page, which seems to still be in beta.

=cut

use Carp;
use Digest::MD5 qw(md5_hex);
use JSON::Any;
use URI::Escape;

use WWW::Grooveshark::Response qw(:fault);

our @ISA = ();

=head1 CONSTRUCTOR

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

=over 4

=item WWW::Grooveshark->new( %OPTIONS )

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

=over 4

=item I

Whether or not to use HTTPS for API calls.  Defaults to false, i.e. just use
HTTP.

=item I

The hostname to use for the Grooveshark API service.  Defaults to
"api.grooveshark.com" unless C is true, in which case it defaults to
"staging.api.grooveshark.com".

=item I

Path (relative to the hostname) to request for API calls.  Defaults to "ws".

=item I

Version of the Grooveshark API you plan on using.  Defaults to 1.0.

=item I

The query string to include in API call requests.  May be blank.  Defaults to
"json" so that the full default API root URL becomes
Ehttp://api.grooveshark.com/ws/1.0/?jsonE.

=item I

Value to use for the C 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 C (see below).  If it's set in
both places, this one takes precedence.

=item I

Name of the L compatible class to be used internally by the
newly-created object.  Defaults to L.

=item I

Hashref of arguments to pass to the constructor of the aforementioned
C.  Defaults to no arguments.

=back

Options not listed above are ignored.

=cut

sub new {
	my($pkg, %opts) = @_;

	# user-agent constructor args
	my $ua_args = $opts{useragent_args} || {};

	# user-agent string
	$ua_args->{agent} = $opts{agent} if defined $opts{agent};
	$ua_args->{agent} ||= __PACKAGE__  . "/$VERSION ";

	# prepare user-agent object
	my $ua_class = $opts{useragent_class} || 'LWP::UserAgent';
	eval "require $ua_class";
	croak $@ if $@;
	my $ua = $ua_class->new(%$ua_args);

	my $default_service = $opts{staging} ?
	                      'staging.api.grooveshark.com' :
		                  'api.grooveshark.com';

	return bless({
		_ua           => $ua,
		_service      => $opts{service}      || $default_service,
		_path         => $opts{path}         || 'ws',
		_api_version  => $opts{api_version}  || '1.0',
		_query_string => $opts{query_string} || 'json',
		_https        => $opts{https}        || 0,
		_session_id   => undef,
		_json         => new JSON::Any,
	}, $pkg);
}

=back

=head1 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 C object gets
garbage collected, it will destroy its session if any.

=cut

sub DESTROY {
	my $self = shift;
	$self->session_destroy if $self->sessionID;
}

=head1 MANAGEMENT METHODS

The following methods do not issue any API calls but deal with management of
the C 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.

=over 4

=item $gs->sessionID( )

Returns the Grooveshark API session ID, or C if there is no active
session.

=back

=cut

sub sessionID {
	return shift->{_session_id};
}

=head1 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 L objects, even in case of
errors, but their boolean evaluation is Led 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
L (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,
C gives you the option of passing a plaintext
C rather than a C, handling C generation for you.

Some methods may also have side effects.  These are generally "harmless": for
example, successful C and C 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.

=head2 ALBUM

=over 4

=item $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.

=cut

sub album_about {
	my($self, %args) = @_;
	my $ret = $self->_call('album.about', %args);
	return $ret;
}

=item $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.

=cut

sub album_getSongs {
	my($self, %args) = @_;
	my $ret = $self->_call('album.getSongs', %args);
	return $ret;
}

=back

=head2 ARTIST

=over 4

=item $gs->artist_about( artistID => $ARTIST_ID )

Returns information for the artist with the specified $ARTIST_ID.

=cut

sub artist_about {
	my($self, %args) = @_;
	my $ret = $self->_call('artist.about', %args);
	return $ret;
}

=item $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.

=cut

sub artist_getAlbums {
	my($self, %args) = @_;
	my $ret = $self->_call('artist.getAlbums', %args);
	return $ret;
}

=item $gs->artist_getSimilar( artistID => $ARTIST_ID [, limit => $LIMIT ] [, page => $PAGE ] )

Returns a list of artists similar to the one with the specified $ARTIST_ID.

=cut

sub artist_getSimilar {
	my($self, %args) = @_;
	my $ret = $self->_call('artist.getSimilar', %args);
	return $ret;
}

=item $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.

=cut

sub artist_getSongs {
	my($self, %args) = @_;
	my $ret = $self->_call('artist.getSongs', %args);
	return $ret;
}

=item $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.

=cut

sub artist_getTopRatedSongs {
	my($self, %args) = @_;
	my $ret = $self->_call('artist.getTopRatedSongs', %args);
	return $ret;
}

=back

=head2 AUTOPLAY

=over 4

=item $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.

=cut

sub autoplay_frown {
	my($self, %args) = @_;
	my $ret = $self->_call('autoplay.frown', %args);
	return $ret;
}

=item $gs->autoplay_getNextSong( )

Returns the next suggested song in the current Autoplay session, based on the
seed songs and any "smiles" or "frowns."

=cut

sub autoplay_getNextSong {
	my($self, %args) = @_;
	my $ret = $self->_call('autoplay.getNextSong', %args);
	return $ret;
}

=item $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.

=cut

sub autoplay_smile {
	my($self, %args) = @_;
	my $ret = $self->_call('autoplay.smile', %args);
	return $ret;
}

=item $gs->autoplay_start( songIDs => \@SONG_IDS )

Starts an Autoplay session seeded with the specified song IDs and returns the
first song suggestion.

=cut

sub autoplay_start {
	my($self, %args) = @_;
	my $ret = $self->_call('autoplay.start', %args);
	return $ret;
}

=item $gs->autoplay_stop( )

Ends the active Autoplay session.

=cut

sub autoplay_stop {
	my($self, %args) = @_;
	my $ret = $self->_call('autoplay.stop', %args);
	return $ret;
}

=back

=head2 PLAYLIST

=over 4

=item $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.

=cut

sub playlist_about {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.about', %args);
	return $ret;
}

=item $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.

=cut

sub playlist_addSong {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.addSong', %args);
	return $ret;
}

=item $gs->playlist_create( name => $NAME, about => $DESCRIPTION )

Creates a playlist with the specified $NAME and $DESCRIPTION and returns the
playlist ID.  Requires user authentication.

=cut

sub playlist_create {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.create', %args);
	return $ret;
}

=item $gs->playlist_delete( playlistID => $PLAYLIST_ID )

Deletes the playlist with the specified $PLAYLIST_ID.  Requires being
authenticated as the playlist's creator.

=cut

sub playlist_delete {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.delete', %args);
	return $ret;
}

=item $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.

=cut

sub playlist_getSongs {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.getSongs', %args);
	return $ret;
}

=item $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.

=cut

sub playlist_moveSong {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.moveSong', %args);
	return $ret;
}

=item $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.

=cut

sub playlist_removeSong {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.removeSong', %args);
	return $ret;
}

=item $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.

=cut

sub playlist_rename {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.rename', %args);
	return $ret;
}

=item $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.)

=cut

sub playlist_replace {
	my($self, %args) = @_;
	my $ret = $self->_call('playlist.replace', %args);
	return $ret;
}

=back

=head2 POPULAR

=over 4

=item $gs->popular_getAlbums( [ limit => $LIMIT ] [, page => $PAGE ] )

Gets a list of popular albums (and meta-information) from Grooveshark's
billboard.

=cut

sub popular_getAlbums {
	my($self, %args) = @_;
	my $ret = $self->_call('popular.getAlbums', %args);
	return $ret;
}

=item $gs->popular_getArtists( [ limit => $LIMIT ] [, page => $PAGE ] )

Gets a list of popular artists from Grooveshark's billboard.

=cut

sub popular_getArtists {
	my($self, %args) = @_;
	my $ret = $self->_call('popular.getArtists', %args);
	return $ret;
}

=item $gs->popular_getSongs( [ limit => $LIMIT ] [, page => $PAGE ] )

Gets a list of popular songs (and meta-information) from Grooveshark's
billboard.

=cut

sub popular_getSongs {
	my($self, %args) = @_;
	my $ret = $self->_call('popular.getSongs', %args);
	return $ret;
}

=back

=head2 SEARCH

=over 4

=item $gs->search_albums( query => $QUERY [, limit => $LIMIT ] [, page => $PAGE ] )

Searches for albums with names that match $QUERY.

=cut

sub search_albums {
	my($self, %args) = @_;
	my $ret = $self->_call('search.albums', %args);
	return $ret;
}

=item $gs->search_artists( query => $QUERY [, limit => $LIMIT ] [, page => $PAGE ] )

Searches for artists with names that match $QUERY.

=cut

sub search_artists {
	my($self, %args) = @_;
	my $ret = $self->_call('search.artists', %args);
	return $ret;
}

=item $gs->search_playlists( query => $QUERY [, limit => $LIMIT ] [, page => $PAGE ] )

Searches for playlists that match $QUERY by name or by meta-information
of composing songs.

=cut

sub search_playlists {
	my($self, %args) = @_;
	my $ret = $self->_call('search.playlists', %args);
	return $ret;
}

=item $gs->search_songs( query => $QUERY [, limit => $LIMIT ] [, page => $PAGE ] )

Searches for songs that match $QUERY by name or meta-information.

=cut

sub search_songs {
	my($self, %args) = @_;
	my $ret = $self->_call('search.songs', %args);
	return $ret;
}

=back

=head2 SERVICE

=over 4

=item $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.

=cut

sub service_getMethods {
	my($self, %args) = @_;
	my $ret = $self->_call('service.getMethods', %args);
	return $ret;
}

=item $gs->service_getVersion( )

Gets the version of the API supported by the service.  Calling this method
doesn't require a session.

=cut

sub service_getVersion {
	my($self, %args) = @_;
	my $ret = $self->_call('service.getVersion', %args);
	return $ret;
}

=item $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).

=cut

sub service_ping {
	my($self, %args) = @_;
	my $ret = $self->_call('service.ping', %args);
	return $ret;
}

=back

=head2 SESSION

=over 4

=item $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 C $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.

=cut

sub session_createUserAuthToken {
	my($self, %args) = @_;

	# make hashpass, unless it already exists
	if(exists($args{hashpass})) {
		delete $args{pass};
	}
	else {
		if(exists($args{username}) && exists($args{pass})) {
			$args{hashpass} = md5_hex($args{username}, md5_hex($args{pass}));
		}
		else {
			carp 'Need username and pass to create authentication token';
		}
		delete $args{pass};
	}

	my $ret = $self->_call('session.createUserAuthToken', %args);
	return $ret;
}

=item $gs->session_destroy( )

Destroys the currently active session.  As a side effect, removes the stored
session ID so that subsequent C calls on this C
object will return C.

=cut

sub session_destroy {
	my($self, %args) = @_;
	my $ret = $self->_call('session.destroy', %args);

	# kill the stored session ID if destroying was successful
	$self->{_session_id} = undef if $ret;

	return $ret;
}

=item $gs->session_destroyAuthToken( token => $TOKEN )

Destroys an auth token so that subsequent attempts to use it to login will
fail.

=cut

sub session_destroyAuthToken {
	my($self, %args) = @_;
	my $ret = $self->_call('session.destroyAuthToken', %args);
	return $ret;
}

=item $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
C object.

=cut

sub session_get {
	my($self, %args) = @_;
	my $ret = $self->_call('session.get', %args);

	# save the session ID given in the response
	$self->{_session_id} = $ret->sessionID if $ret;

	return $ret;
}

=item $gs->session_getUserID( )

Gets the user ID of the currently logged-in user.

=cut

sub session_getUserID {
	my($self, %args) = @_;
	my $ret = $self->_call('session.getUserID', %args);
	return $ret;
}

=item $gs->session_loginViaAuthToken( token => $TOKEN )

Logs in using a $TOKEN created using C.

=cut

sub session_loginViaAuthToken {
	my($self, %args) = @_;
	my $ret = $self->_call('session.loginViaAuthToken', %args);
	return $ret;
}

=item $gs->session_logout( )

Logs out the logged-in user.

=cut

sub session_logout {
	my($self, %args) = @_;
	my $ret = $self->_call('session.logout', %args);
	return $ret;
}

=item $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 C object, accessible via calls to
C, 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.

=cut

sub session_start {
	my($self, %args) = @_;

	# remove a prior session ID, but store this value
	my $old_session_id = $self->{_session_id};
	$self->{_session_id} = undef;

	my $ret = $self->_call('session.start', %args);

	if($ret) {
		# save the session ID given in the response
		$self->{_session_id} = $ret->sessionID;
	}
	else {
		# restore old session ID
		$self->{_session_id} = $old_session_id;
	}

	return $ret;
}

=back

=head2 SONG

=over 4

=item $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.

=cut

sub song_about {
	my($self, %args) = @_;
	my $ret = $self->_call('song.about', %args);
	return $ret;
}

=item $gs->song_favorite( songID => $SONG_ID )

Marks the song with the specified $SONG_ID as a favorite.  Requires user
authentication.

=cut

sub song_favorite {
	my($self, %args) = @_;
	my $ret = $self->_call('song.favorite', %args);
	return $ret;
}

=item $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.

=cut

sub song_getSimilar {
	my($self, %args) = @_;
	my $ret = $self->_call('song.getSimilar', %args);
	return $ret;
}

=item $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).

=cut

sub song_getStreamKey {
	my($self, %args) = @_;
	my $ret = $self->_call('song.getStreamKey', %args);
	return $ret;
}

=item $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
C should be used instead.

=cut

sub song_getStreamUrl {
	my($self, %args) = @_;
	my $ret = $self->_call('song.getStreamUrl', %args);
	return $ret;
}

=item $gs->song_getStreamUrlEx( songID => $SONG_ID [, lowBitrate => $LOW_BITRATE ] )

The supposedly preferred alternative to C.  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
C responses.

=cut

sub song_getStreamUrlEx {
	my($self, %args) = @_;
	my $ret = $self->_call('song.getStreamUrlEx', %args);
	return $ret;
}

=item $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 C.  The $AP is
optional and appears only in the sandbox tool and not the official
documentation: its meaning is unknown.

=cut

sub song_getWidgetEmbedCode {
	my($self, %args) = @_;
	my $ret = $self->_call('song.getWidgetEmbedCode', %args);
	return $ret;
}

=item $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 C
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.

=cut

sub song_getWidgetEmbedCodeFbml {
	my $ret = shift->song_getWidgetEmbedCode(@_);

	if($ret) {
		my $code = $ret->{result}->{embed};
		$code =~ /\s*<\/embed>/;
		$code = "";
		$ret->{result}->{embed} = $code;
	}

	return $ret;
}

=item $gs->song_unfavorite( songID => $SONG_ID )

Removes the song with the specified $SONG_ID from the logged-in user's list
of favorites.

=cut

sub song_unfavorite {
	my($self, %args) = @_;
	my $ret = $self->_call('song.unfavorite', %args);
	return $ret;
}

=back

=head2 TINYSONG

=over 4

=item $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.

=cut

sub tinysong_create {
	my($self, %args) = @_;
	my $ret = $self->_call('tinysong.create', %args);
	return $ret;
}

=item $gs->tinysong_getExpandedUrl( tinySongUrl => $TINYSONG_URL )

Expands a TinySong URL into the full URL to which it redirects.

=cut

sub tinysong_getExpandedUrl {
	my($self, %args) = @_;
	my $ret = $self->_call('tinysong.getExpandedUrl', %args);
	return $ret;
}

=back

=head2 USER

=over 4

=item $gs->user_about( $user_id => $USER_ID )

Returns information about the user with the specified $USER_ID, such as
username, date joined, etc.

=cut

sub user_about {
	my($self, %args) = @_;
	my $ret = $self->_call('user.about', %args);
	return $ret;
}

=item $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.

=cut

sub user_getFavoriteSongs {
	my($self, %args) = @_;
	my $ret = $self->_call('user.getFavoriteSongs', %args);
	return $ret;
}

=item $gs->user_getPlaylists( $user_id => $USER_ID [, limit => $LIMIT ] [, page => $PAGE ] )

Gets the playlists created by the user with the specified $USER_ID.

=cut

sub user_getPlaylists {
	my($self, %args) = @_;
	my $ret = $self->_call('user.getPlaylists', %args);
	return $ret;
}

=back

=cut

################################################################################

sub _call {
	my($self, $method, %param) = @_;

#	print STDERR "Called $method\n";

	my $req = {
		header     => {sessionID => $self->sessionID},
		method     => $method,
		parameters => \%param,
	};

#	use Data::Dumper; print STDERR Dumper($req);

	my $json = $self->{_json}->encode($req);
	my $url = sprintf('%s://%s/%s/%s/', ($self->{_https} ? 'https' : 'http'),
		map($self->{$_}, qw(_service _path _api_version)));
	if(my $q = $self->{_query_string}) {
		$q = uri_escape($q);
		$url .= '?' . $q;
	}
	my $response = $self->{_ua}->post($url,
		'Content-Type' => 'text/json',
		'Content'      => $json,
	);

   	my $ret;
	if($response->is_success) {
		my $content = $response->decoded_content || $response->content;
		$ret = $self->{_json}->decode($content);
	}
	else {
    	$ret = {
    		header => {sessionID => $self->sessionID},
    		fault  => {
    			code    => INTERNAL_FAULT,
	    		message => $response->status_line,
	    	},
    	};
	}

#	use Data::Dumper; print STDERR Dumper($ret);

	return WWW::Grooveshark::Response->new($ret);
}

1;

__END__