/ 
WWW-TinySong-0.50
River stage zero No dependents
/ WWW::TinySong

NAME

WWW::TinySong - Get free music links from tinysong.com

WARNING

This version of the module is only provided to serve as a transitional step between the 0.0x series (which worked by scraping because it was born before Tinysong had released an API) and the 1.0+ series, which will break backward compatibility by exclusively using field and method names parallel to the official documentation at http://apidocs.tinysong.com/.

If you are just getting started with this module, please look for a newer version instead, so that you aren't tempted to use deprecated functions. If you already have code depending on the older interface, this version should work as a transparent drop-in replacement, but please consider updating: it should be a fairly straightforward refactoring.

SYNOPSIS

# basic use

use WWW::TinySong;

for(WWW::TinySong->search("we are the champions")) {
    printf("%s", $_->{songName});
    printf(" by %s", $_->{artistName});
    printf(" on %s", $_->{albumName}) if $_->{albumName};
    printf(" <%s>\n", $_->{tinysongLink});
}

# customize the user agent

use LWP::UserAgent;

my $ua = new LWP::UserAgent;
$ua->timeout(10);
$ua->env_proxy;

WWW::TinySong->ua($ua);

# customize the service

WWW::TinySong->service('http://tinysong.com/');

# tolerate some server errors

WWW::TinySong->retries(5);

DESCRIPTION

tinysong.com is a web app that can be queried for a song and returns a tiny URL, allowing you to listen to the song for free online and share it with friends. WWW::TinySong is a Perl interface to this service, allowing you to programmatically search its underlying database.

FUNCTIONS

The do-it-all function is search. If you just want a tiny URL, use link. call and parse are provided so that you can (hopefully) continue to use this module if the tinysong.com API is extended and I'm too lazy or busy to update, but you will probably not need to use them otherwise. tinysong is included for backward compatibility but is deprecated. The other public functions are either aliases for one of the above or created to allow the customization of requests issued by this module.

WWW::TinySong->link( $SEARCH_TERMS )
WWW::TinySong->a( $SEARCH_TERMS )

Returns the short URL corresponding to the top result of searching with the specified song and artist name terms or undef if no song was found.

WWW::TinySong->search( $SEARCH_TERMS [, $LIMIT ] )
WWW::TinySong->s( $SEARCH_TERMS [, $LIMIT ] )

Searches for the specified song and artist name terms, giving up to $LIMIT results. $LIMIT defaults to 10 if not defined. Returns an array in list context or the top result in scalar context. Return elements are hashrefs with keys qw(tinysongLink songID songName artistID artistName albumID albumName groovesharkLink) as given by parse. Here's a quick script to demonstrate:

#!/usr/bin/perl

use WWW::TinySong;
use Data::Dumper;

print Dumper(WWW::TinySong->search("three little birds", 3));

...and its output on my system at the time of this writing:

$VAR1 = {
          'artistName' => 'Bob Marley',
          'albumName' => 'Legend',
          'songName' => 'Three Little Birds',
          'artistID' => '139',
          'tinysongLink' => 'http://tinysong.com/eg9',
          'songID' => '1302',
          'albumID' => '97291',
          'groovesharkLink' => 'http://listen.grooveshark.com/song/Three_Little_Birds/1302'
        };
$VAR2 = {
          'artistName' => 'Bob Marley',
          'albumName' => 'One Love: The Very Best Of Bob Marley & The Wailers',
          'songName' => 'Three Little Birds',
          'artistID' => '139',
          'tinysongLink' => 'http://tinysong.com/lf2',
          'songID' => '3928811',
          'albumID' => '221021',
          'groovesharkLink' => 'http://listen.grooveshark.com/song/Three_Little_Birds/3928811'
        };
$VAR3 = {
          'artistName' => 'Bob Marley & The Wailers',
          'albumName' => 'Exodus',
          'songName' => 'Three Little Birds',
          'artistID' => '848',
          'tinysongLink' => 'http://tinysong.com/egc',
          'songID' => '3700',
          'albumID' => '2397306',
          'groovesharkLink' => 'http://listen.grooveshark.com/song/Three_Little_Birds/3700'
        };
WWW::TinySong->b( $SEARCH_TERMS )

Searches for the specified song and artist name terms, giving the top result. I'm not really sure why this is part of the API because the same result can be obtained by limiting a search to one result, but it's included here for completeness.

tinysong( $QUERY_STRING [, $LIMIT ] )
WWW::TinySong->tinysong( $QUERY_STRING [, $LIMIT ] )

Deprecated legacy method that searches for $QUERY_STRING, giving up to $LIMIT results. Currently just a wrapper for search that does a bit of surgery to the results so that hashref keys are qw(album artist song url), like previous module versions. The scraping implementation has been renamed to scrape and uses the same hashref keys as the API. This function will be removed in the next version.

WWW::TinySong->call( $METHOD , $SEARCH_TERMS [, \%EXTRA_PARAMS ] )

Calls API "method" $METHOD using the specified $SEARCH_TERMS and optional hashref of extra parameters. Whitespace sequences in $SEARCH_TERMS will be converted to pluses. Returns the entire response as a string. Unless you're just grabbing a link, you will probably want to pass the result through parse.

WWW::TinySong->parse( [ @RESULTS ] )

Parses all the lines in the given list of results according to the specs, building and returning a (possibly empty) list of hashrefs with the keys qw(tinysongLink songID songName artistID artistName albumID albumName groovesharkLink), whose meanings are hopefully self-explanatory.

WWW::TinySong->scrape( $QUERY_STRING [, $LIMIT ] )

Searches for $QUERY_STRING by scraping, giving up to $LIMIT results. $LIMIT defaults to 10 if not defined. Returns an array in list context or the top result in scalar context. Return elements are hashrefs with keys qw(albumName artistName songName tinysongLink). Their values will be the empty string if not given by the website. As an example, executing:

#!/usr/bin/perl

use WWW::TinySong;
use Data::Dumper;

print Dumper(WWW::TinySong->scrape("a hard day's night", 3));

...prints something like:

$VAR1 = {
          'artistName' => 'Beatles',
          'tinysongLink' => 'http://tinysong.com/2gxh',
          'songName' => 'Hard Day\'s Night',
          'albumName' => 'Beatles'
        };
$VAR2 = {
          'artistName' => 'The Beatles',
          'tinysongLink' => 'http://tinysong.com/2BI5',
          'songName' => 'A Hard Day\'s Night',
          'albumName' => '1'
        };
$VAR3 = {
          'artistName' => 'The Beatles',
          'tinysongLink' => 'http://tinysong.com/2i03',
          'songName' => 'And I Love Her',
          'albumName' => 'A Hard Day\'s Night'
        };

This function is how the primary functionality of the module was implemented in the 0.0x series. It remains here as a tribute to the past, but should be avoided because scraping depends on the details of the response HTML, which may change at any time (and in fact did at some point between versions 0.05 and 0.06). Interestingly, this function does currently have one advantage over the robust alternative: whereas search is limited to a maximum of 32 results by the web service, scraping doesn't seem to be subjected to this requirement.

WWW::TinySong->ua( [ $USER_AGENT ] )

Returns the user agent object used by this module for web retrievals, first setting it to $USER_AGENT if it's specified. Defaults to a new LWP::UserAgent. If you explicitly set this, you don't have to use a LWP::UserAgent, it may be anything that can get a URL and return a response object.

WWW::TinySong->service( [ $URL ] )

Returns the web address of the service used by this module, first setting it to $URL if it's specified. Defaults to <http://tinysong.com/>.

WWW::TinySong->retries( [ $COUNT ] )

Returns the number of consecutive internal server errors the module will ignore before failing, first setting it to $COUNT if it's specified. Defaults to 0 (croak, do not retry in case of internal server error). This was created because read timeouts seem to be a common problem with the web service. The module now provides the option of doing something more useful than immediately failing.

BE NICE TO THE SERVERS

Please don't abuse the tinysong.com web service. If you anticipate making a large number of requests, don't make them too frequently. There are several CPAN modules that can help you make sure your code is nice. Try, for example, LWP::RobotUA as the user agent:

use WWW::TinySong qw(tinysong);
use LWP::RobotUA;

my $ua = LWP::RobotUA->new('my-nice-robot/0.1', 'me@example.org');

WWW::TinySong->ua($ua);

# tinysong() should now be well-behaved

SEE ALSO

http://tinysong.com/, LWP::UserAgent, LWP::RobotUA

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-TinySong. You may also create an issue at http://elementsofpuzzle.googlecode.com/ or drop me an e-mail.

AUTHOR

Miorel-Lucian Palii, <mlpalii@gmail.com>

VERSION

Version 0.50 (June 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-TinySong/.

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Miorel-Lucian Palii

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.