view release on metacpan or  search on metacpan

lib/LyricFinder.pm  view on Meta::CPAN

    # or you can pass an arrayref of sites you want used in order:
    print $finder->fetch('Oasis', 'Whatever', [qw(Genius AZLyrics)]);

    # To find out which site modules are available:
    my @fetchers = $finder->sources();

    # To fetch the source (site) name and base url:
    print "(Lyrics courtesy: ".$finder->source().")\n";
    print "site url:  ".$finder->site().")\n";

    # To show what sites we had to search for these lyrics:
    print "..Tried sites:  ".$finder->tried().".\n";

    # To do caching:
    $finder->cache('/tmp/lyrics');
    #-or-
    my $localfinder = new LyricFinder(-cache => '/tmp/lyrics');

    #-or- to only fetch lyrics from our cache:
    my $local_lyrics = $localfinder->fetch('Oasis', 'Cast No Shadow', 'Cache');
    if ($local_lyrics) {
        print "..Lyrics from disk:\n\n$local_lyrics\n";
    } else {
        print "..No local lyrics found for 'Cast No Shadow', by Oasis.\n";
    }


=head1 DESCRIPTION

LyricFinder accepts an artist name and song title, searches supported 
lyrics sites for song lyrics, and, if found, returns them as a string.

The supported and currently-installed modules are:  
L<LyricFinder::ApiLyricsOvh> (for searching api.lyrics.ovh), 
L<LyricFinder::AZLyrics> (www.azlyrics.com), L<LyricFinder::Genius> 
(genius.com), L<LyricFinder::Letras> (www.letras.mus.br), 
L<LyricFinder::Lrclib> (lrclib.net), and L<LyricFinder::Musixmatch> 
(www.musixmatch.com).  There is a special module for storing and / or fetching 
lyrics (.lrc) files already stored locally, called L<LyricFinder::Cache>.

This module is derived from the (older) L<Lyrics::Fetcher> collection of 
modules by (c) 2007-2020 David Precious, but currently supports 
more lyric sites (7) and bundles all the supported site modules together here 
(simply install this one module).  We have reworked the "Cache" module to 
cache lyrics files by artist and song title on disk in the user's desired 
location.  LyricFinder is also truly object-oriented making interaction with 
the user-facing methods and data easier and more streamlined.

NOTE:  This module is used completely independent of any of those modules, 
but some of the code is derived from them, as allowed by and the license and 
credits are included here, as required by their open-source license.  It is 
capable of being used as a drop-in replacement, but some function names and 
other code changes will be needed.

We've also added methods to easily change the "user-agent" passed to the 
lyrics sites, as needed/desired by the user programatically.

We've also changed the default to search the supported sites randomly, instead 
of in the same fixed alphabetical order by module name ("load-balancing" the 
searches to all the sites).  This is helpful when using LyricFinder as a 
plugin for streaming media players, such as the author's very own "Fauxdacious 
Media Player" that frequently stream internet radio stations, which can 
impose a "hit" on the lyrics sites each time the song title changes.  This 
reduces the odds of a user's IP-address possibly being banned by a lyrics site 
for "too-frequent scraping / usage"!  NOTE:  If you want to prevent the usage 
of one or more of the specific sites, simply specify the I<-omit> argument with 
a reference to a list of module names to skip, 
ie. I<-omit =>> I<'AZLyrics,Genius'> in the I<new LyricFinder()> function.  
If you want to use one or more specific sites, or enforce 
a specific search order, you can call the fetch() method with a third 
argument consisting of either a string consisting of one, or more site module-
names separated by commas - ie. "Musixmatch", or a reference to an array of 
site module names, ie. [qw(Genius, AZLyrics)].  The lyric sites will be 
searched in the order specified until either lyrics are found, or all site(s) 
specified have been searched.  To search all the sites instead in random order, 
specify the special value I<"random">.  If you specify "Cache" as the 
single module name (and provide a "-cache" directory containing lyrics files 
on your hard drive), LyricFinder will only search that directory for lyrics, 
and not the internet.  Otherwise, specifying a "-cache" directory will cause 
LyricFinder to first look in your cache directory for matching lyrics first, 
and only search any of the lyrics sites if not found, then will cache the 
lyrics found on the internet to a new lyric file in your lyrics directory 
eleminating re-searching the web when you play the same song again later and 
reducing internet bandwidth usage!

In case of problems with fetching lyrics, the error string will be returned by 
$finder->message().  If all goes well, it will have 'Ok' in it.

The site selection is made by the "method" parameter passed to the fetch() 
of this module.  You can also omit this parameter, in which case all available
fetchers will be tried in random order, or you can supply an arrayref of sites 
you'd like to try in the order you specify.

The value of the "method" parameter (if specified) must be either the "*" part 
of one of the installed LyricFinder::* fetcher package name, "all", or 
"random".

If you have another lyrics site that is not supported, please file a feature 
request via email or the CPAN bug system, or (for faster service), provide a 
Perl patch module / program source that can extract lyrics from that site and 
I'll consider it!  The easiest way to do this is to take one of the existing 
submodules, copy it to "LyricFinder::I<YOURSITE>.pm and modify it (and the POD 
docs) to your specific site's needs, test it with several Artist / Title 
combinations (see the "SYNOPSIS" code above), and send it to me 
(That's what I do for new sites)!

=head1 INSTALLATION

	To install this module, run the following commands:

	perl Makefile.PL

	make

	make test

	make install

=head1 SUBROUTINES/METHODS

=over 4