[[[ SYNOPSIS ]]]

lyrfetch [options] <file>|<directory>|-s <query> ...

[[[ DESCRIPTION ]]]

 This is lyrfetch v0.4.1, a PHP script for the command line interpreters of
unix-like operating systems that can search for and retrieve from genius.com
any number of lyrics, and output them to the terminal, or save each of them
into a corresponding file in Cantata¹ lyrics cache.
 It builds the queries for lyrics to be searched for from the «title» and
«artist» tags that it can retrieve with ffmpeg’s ffprobe utility from each
supported file you pass as argument to it, and from each supported file it may
find by recursively searching inside each directory you pass as argument to
it. You can also pass explicit queries to it using its «-s»/«--search» option
(see section «OPTIONS» below).
 In order for search to work, lyrfetch needs a genius.com API token², so it
comes with an “hardcoded” one, and it uses that unless it finds another one on
the first line of a file named «token» inside lyrfetch’s configuration
directory (usually «.config/lyrfetch/» under your home directory, but look at
your «XDG_CONFIG_HOME» environment variable to check if it’s set to a
non-standard value), and unless you explicitly set it with the «-t»/«--token»
or the «-T/--token-file» options (see section «OPTIONS» below).

¹ Cantata is a client for mpd, the Music Player Daemon; it can search,
retrieve and show lyrics by itself, but only one song at a time, and, since
it’s no longer maintained, this feature currently fails most of the times;
that’s the main reason why lyrfetch was born.

² To get a genius.com API token, create an account on https://genius.com, if
you don’t already have one; log into it, open https://genius.com/api-clients,
create a new API client and then click on the «Generate Access Token» link.

[[[ OPTIONS ]]]

-h / --help
  Shows this help text and exit.
-o / --output <«terminal»|«cantata»>
  Sets the output type: «terminal» (the default) to output found lyrics to the
 terminal; «cantata» to output them to current user’s Cantata lyrics cache.
  Note that, in order to avoid adding useless files to Cantata lyrics cache,
 each lyrics that may be found searching for queries passed to lyrfetch with
 its «-s»/«--search» option (see below) will always be output to the terminal,
 regardless of this option.
-s / --search <query>
  Sets a query to be searched for (note that genius.com seems to give more
 reliable results when the query mentions the title first, and then the
 artist). This option can be used multiple times, to search for more than one
 lyrics, and can be mixed with files and directories specifications, but note
 that lyrics matching queries that were passed to lyrfetch with this option
 will always be output to the terminal, regardless of the specified output
 type (see previous option description), and always before those that may be
 found searching for «title» and «artist» tags that were retrieved from files.
-O / --overwrite
  When using «cantata» output type (see above), and when a lyrics file that
 lyrfetch would write to already exists in Cantata cache directory, this
 option makes lyrfetch overwrite it.
  This option has no effect in «terminal» mode.
-e / --extensions <extension[,extension,...]>
  Sets the file extensions lyrfetch will consider when recursively browsing
 the directories that are passed to it as arguments. Extensions must be
 written without the preceeding dots, and must be separated by a comma.
  By default, lyrfetch considers files with flac, mp3, ogg, mpc, ape, m4a and
 aac extensions.
-t / --token <token>
  Sets the token to be used to authenticate with genius.com API to the one
 that you must pass as parameter. This will superseed any other token.
-T / --token-file <token file>
  Sets the token to be used to authenticate with genius.com API from the first
 line in the specified file. This will superseed any other token.
-q / --quietness <«0»|«1»|«2»|«3»>
  Sets the “quietness” level of lyrfetch while it’s processing files and
 queries (this is completely independent from the log feature described
 below). With «3» (the default when only one file or query is passed),
 lyrfetch won’t output anything except fatal error messages (on STDERR); with
 «2» it will also output non-fatal error messages (also on STDERR); with «1»
 it will also output warning messages (also on STDERR); with «0» (the default
 when more than one file and-or query is passed) it will also output
 informational messages (on STDOUT).
-L / --no-log
  By default, lyrfetch will log warning and non-fatal error messages in an
 internal array and, if there are any, it will output them on STDERR soon
 before exiting; with this option, it won’t.
  This is completely independent from the “quietness” that can be set with the
 option described above.
--
  This tells lyrfetch to consider all the subsequent arguments as files or
 directories, in case you have, e.g., a file named «--search» ;-)

[[[ EXIT CODES ]]]

0: regular run
10: some warnings occurred
20: some non-fatal errors occurred
30: a fatal error occurred

 When terminated with SIGTERM, SIGHUP or SIGINT, lyrfetch’s exit codes are the
same as above, +100.

[[[ DISCLAIMER AND LICENSE ]]]

 This program comes with ABSOLUTELY NO WARRANTY; for details see the source.
 This is free software, and you are welcome to redistribute it under certain
conditions; see <http://www.gnu.org/licenses/> for details.