view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        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";
        }

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:
    LyricFinder::ApiLyricsOvh (for searching api.lyrics.ovh),
    LyricFinder::AZLyrics (www.azlyrics.com), LyricFinder::ChartLyrics
    (api.chartlyrics.com), LyricFinder::Genius (genius.com),
    LyricFinder::Letras (www.letras.mus.br), LyricFinder::Lrclib
    (lrclib.net), and LyricFinder::Musixmatch (www.musixmatch.com). There is
    a special module for storing and / or fetching lyrics (.lrc) files
    already stored locally, called LyricFinder::Cache.

    This module is derived from the (older) 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 *-omit* argument with a
    reference to a list of module names to skip, ie. *-omit =*>
    *'AZLyrics,Genius'* in the *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 the site
    module name, ie. "Musixmatch", or reference to an array of site module
    names, ie. [Genius, AZLyrics]. 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::*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)!

INSTALLATION
            To install this module, run the following commands:

            perl Makefile.PL

            make

            make test

            make install

SUBROUTINES/METHODS
    new *LyricFinder*([ *options* ])
        Creates a new finder object for fetching lyrics. The same finder
        object can be used for multiple fetches from multiple sites, so this
        normally only needs to be called once.