NAME

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

SYNOPSIS

  # basic use
  use WWW::TinySong qw(search);
  for(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". These two functions may be "import"ed and used like any other function. "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. The other public functions are either aliases for one of the above or created to allow the customization of requests issued by this module.

link( $SEARCH_TERMS )

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.

search( $SEARCH_TERMS [, $LIMIT ] )

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 qw(search);
  use Data::Dumper;
  print Dumper 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.

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("we can work it out", 3));
    

...prints something like:

  $VAR1 = {
            'artistName' => 'The Beatles',
            'tinysongLink' => 'http://tinysong.com/5Ym',
            'songName' => 'We Can Work It Out',
            'albumName' => 'The Beatles 1'
          };
  $VAR2 = {
            'artistName' => 'The Beatles',
            'tinysongLink' => 'http://tinysong.com/uLd',
            'songName' => 'We Can Work It Out',
            'albumName' => 'We Can Work It Out / Day Tripper'
          };
  $VAR3 = {
            'artistName' => 'The Beatles',
            'tinysongLink' => 'http://tinysong.com/2EaX',
            'songName' => 'We Can Work It Out',
            'albumName' => 'The Beatles 1967-70'
          };
    

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(search link);
  use LWP::RobotUA;
  my $ua = LWP::RobotUA->new('my-nice-robot/0.1', 'me@example.org');
  WWW::TinySong->ua($ua);
  # search() and link() 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 1.01 (June 26, 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.