NAME

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

SYNOPSIS

  # basic use

  use WWW::TinySong qw(tinysong);

  for(tinysong("we are the champions")) {
      printf("%s", $_->{song});
      printf(" by %s", $_->{artist}) if $_->{artist};
      printf(" on %s", $_->{album}) if $_->{album};
      printf(" <%s>\n", $_->{url});
  }

  # 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. (Yes, for those who are curious, the module currently works by scraping.)

FUNCTIONS

The main functionality is implemented by tinysong. It may be imported into your namespace and used as any other function. The other functions allow the customization of requests issued by this module.

tinysong( $QUERY_STRING [, $LIMIT ] )

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

Searches tinysong.com for $QUERY_STRING, 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(album artist song url). Their values will be the empty string if not given by the website. Here's a quick script to demonstrate:

  #!/usr/bin/perl

  use WWW::TinySong qw(tinysong);
  use Data::Dumper;

  print Dumper tinysong("a hard day's night", 3);

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

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

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! Submit a report at http://rt.cpan.org/Public/Dist/Display.html?Name=WWW-TinySong, create an issue at http://elementsofpuzzle.googlecode.com/, or drop me an e-mail.

AUTHOR

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

VERSION

Version 0.06 (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.