The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
LyricFinder-1.21
River stage zero No dependents
1 ++
/ LyricFinder::Musixmatch

NAME

LyricFinder::Musixmatch - Fetch song lyrics from www.musixmatch.com.

AUTHOR

This module is Copyright (c) 2020 by

Jim Turner, <turnerjw784 at yahoo.com>

All rights reserved.

This library is free software; you can redistribute it and/or modify it under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

NOTE: This is a "derived work" of Lyrics::Fetcher family of modules, by (c) David Precious (davidp at preshweb.co.uk) (CPAN Id: BIGPRESH), as fair use legal under the terms of, subject to, and licensed in terms compatable and compliant with those modules. Many thanks to David for laying the groundwork for this module!

SYNOPSIS

    #!/usr/bin/perl

    use LyricFinder::Musixmatch;

    # create a new finder object:
    my $finder = new LyricFinder::Musixmatch();

    # fetch lyrics for a song from https://www.musixmatch.com:
    print $finder->fetch('Pink Floyd','Echoes');

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

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

DESCRIPTION

LyricFinder::Musixmatch accepts an artist name and song title, searches https://www.musixmatch.com for song lyrics, and, if found, returns them as a string. It's designed to be called by LyricFinder, but can be used directly as well. In LyricFinder, it is invoked by specifying "Musixmatch" as the third argument of the fetch() method.

NOTE: Musixmatch flags lyrics with a status of either "ok", "warning", or "error". "warning" seems to mean "pending review", and when flagged "error", their site says "We detected some issues". I don't know if this means someone's complained about correctness, profanity, etc. Therefore, we append: (Musixmatch status: status) to the end of the returned lyrics.

This status msg. can be suppressed by passing the option "-noextra" => 1. There are some rare cases where no lyrics are found the normal way and we have to try a backup method to extract them. In those cases, we set the status to "error!".

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.

INSTALLATION

This module is installed automatically with LyricFinder installation.

SUBROUTINES/METHODS

new LyricFinder::Musixmatch([ options ])

Creates a new finder object for fetching lyrics. The same finder object can be used for multiple fetches, so this normally only needs to be called once.

options is a hash of option/value pairs (ie. "-option" => "value"). If an "-option" is specified with no "value" given, the default value will be 1 ("true"). The currently-supported options are:

-agent => "user-agent string"

Specifies an alternate "user-agent" string sent to www.musixmatch.com when attempting to fetch lyrics. Set the desired user-agent (ie. browser name) to pass to www.musixmatch.com. Some sites are pickey about receiving a user-agent string that corresponds to a valid / supported web-browser to prevent their sites from being "scraped" by programs, such as this.

Default: "Mozilla/5.0 (X11; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0".

NOTE: This value will be overridden if $founder->agent("agent") is called!

-cache => "directory", and -debug => integer.

Specifies a directory (ie. "/home/user/Music/Lyricsfiles") to be used for disk caching. If specified, this directory will be searched for a matching lyrics (.lrc) file (in this example, "/home/user/Music/LyricsFiles/artist/title.lrc"). If no matching lyrics file is found (and the search module list is not specifically set to "Cache" (and lyrics are found on the internet), then the lyrics will be saved to the directory under "artist/title.lrc".

Default: none (no caching)

An optional dirctional indicator ("<" or ">") can be prepended to the directory to limit caching activity. "<" allows fetching lyrics from the cache directory, but will not cache (write) new lyrics found on the web to the directory. ">" (the opposite) will cache new lyrics but will never attempt to fetch (read) lyrics from the cache directory. These options may be useful if one either simply wants to build a lyrics database but always fetch the latest, or perhaps limit lyrics to a fixed cache but not add to it, or perhaps is using a readonly directory. The default is no indicator which allows both reading and writing.

Directory must be a valid directory, but may be specified as either a path (ie. "/home/user/lyrics") or a URI (ie. "file:///home/user/lyrics") or with a limiting directional indicator, ie. "</home/user/lyrics". It may or may not have a trailing "/" (ie. "/home/user/lyrics/").

NOTE: This value will be overridden if $founder->cache("directory") is called!

-debug => number

Specifies whether debug information will be displayed (0: no, >0: yes). Default 0 (no). 1 will display debug info. There is currently only one level of debug verbosity.

-noextra => 0 | 1 (false or true)

Musixmatch returns a (useful to some) "status" reflecting the quality or "status" of the lyrics for each song on their site. This message is appended to the bottom of the lyrics returned. If specified or given a true value, the message containing the Musixmatch "status" will NOT be appended below the lyrics text and only the actual lyrics will be returned. Default 0 (false) (append the message).

[ $current-agent string = ] $finder->agent( [ user-agent string ] )

Set / get the desired user-agent (ie. browser name) to pass to www.musixmatch.com. Some sites are pickey about receiving a user-agent string that corresponds to a valid / supported web-browser to prevent their sites from being "scraped" by programs, such as this.

Default: "Mozilla/5.0 (X11; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0"

If no argument is passed, it returns the current GENERAL user-agent string in effect (but a different agent option is specified for a specific module may have been specified and used by THAT module - see new() options above).

NOTE: This will override any -agent option value specified in new()!

[ $current-directory = ] $finder->cache( [ $directory ] )

Specifies a directory (ie. "/home/user/Music/Lyricsfiles") to be used for disk caching. If specified, this directory will be searched for a matching lyrics (.lrc) file (in this example, "/home/user/Music/LyricsFiles/artist/title.lrc"). If no matching lyrics file is found (and the search module list is not specifically set to "Cache" (and lyrics are found on the internet), then the lyrics will be saved to the directory under "artist/title.lrc".

An optional dirctional indicator ("<" or ">") can be prepended to the directory to limit caching activity. "<" allows fetching lyrics from the cache directory, but will not cache (write) new lyrics found on the web to the directory. ">" (the opposite) will cache new lyrics but will never attempt to fetch (read) lyrics from the cache directory. These options may be useful if one either simply wants to build a lyrics database but always fetch the latest, or perhaps limit lyrics to a fixed cache but not add to it, or perhaps is using a readonly directory. The default is no indicator which allows both reading and writing.

Directory must be a valid directory, but may be specified as either a path (ie. "/home/user/lyrics") or a URI (ie. "file:///home/user/lyrics") or with a limiting directional indicator, ie. "</home/user/lyrics". It may or may not have a trailing "/" (ie. "/home/user/lyrics/").

If no argument is passed, it returns the current GENERAL cache directory string in effect (but a different directory option is specified for a specific module may have been specified and used by THAT module - see new() options above).

NOTE: This will override any -cache option value specified in new()!

[ $scalar | @array ] = $finder->credits()

Returns either a comma-separated list or an array of names credited by the site with posting the lyrics on the site (if any) or an empty string, if none found. NOTE: This site currently does not provide "credits", so an empty string or array will always be returned.

$string = $finder->fetch($artist, $title)

Attempt to fetch the lyrics for the given artist and title. This is the primary method call, and the only one required to be called (besides new()) to obtain lyrics.

Returns lyrics as a string (includes line-breaks appropriate for the user's operating system), or an empty string, if no lyrics found.

$scalar = $finder->image_url()

Returns a URL for a cover-art image, if one found on the lyrics page. If no image is found, an empty string will be returned if this method is called.

$scalar = $finder->message()

Returns the last error string generated, or "Ok" if all's well.

[ $scalar | @array ] = $finder->order()

LyricFinder method, included here for compatibility only that isn't particularly useful here.

Returns either a comma-separated list or an array of the site modules tried by the last fetch. This is useful to see what sites are being tried and in what order if random order is being used. Similar to tried(), except all sites being considered are shown.

In the case of site submodules, such as this, it simply returns the source (this module's) name, either as "Musixmatch" or ("Musixmatch").

$scalar = $finder->site()

Returns the actual base URL of the site that successfully fetched the lyrics in the last successful fetch (or an empty string if the fetch failed). This site's base URL on success is always: "https://www.musixmatch.com".

NOTE: If caching is being used and lyrics are found and fetched from the cache directory, site() will return the cache directory in URI format, ie. "file:///home/user/Music/LyricsFiles"!

$scalar = $finder->source()

Returns the name of the module that successfully fetched the lyrics in the last successful fetch (or "none" if the fetch failed). This site's module name on success is always: "Musixmatch".

NOTE: If caching is being used and lyrics are found and fetched from the cache directory, source() will return "Cache"!

[ $scalar | @array ] = $finder->tried()

LyricFinder method, included here for compatibility only that isn't particularly useful here.

Returns either a comma-separated list or an array of the site modules actually tried when fetching lyrics. This is useful to see what sites were actually hit and in what order if random order is being used. Similar to order(), except only sites actually hit are shown (the last one is the one that successfully fetched the lyrics.

In the case of site submodules, such as this, it simply returns the source (this module's) name, either as "Musixmatch" or ("Musixmatch").

$scalar = $finder->url()

Returns the actual URL used to fetch the lyrics from the site (includes the actual formatted search arguments passed to the site). This can be helpful in debugging, etc.

NOTE: If caching is being used and lyrics are found and fetched from the cache directory, site() will return the full filename of the cache file fetched.

DEPENDENCIES

HTML::Strip, HTTP::Request, LWP::UserAgent, URI::Escape

BUGS

Please report any bugs or feature requests to bug-lyricFinder-musixmatch at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LyricFinder-Musixmatch. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc LyricFinder::Musixmatch

SEE ALSO

LyricFinder - (LyricFinder)

LICENSE AND COPYRIGHT

Copyright (c) 2020 Jim Turner.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.