nicole/nicole.1.man

.\" Automatically generated by Pandoc 3.1.8
.\"
.TH "NICOLE" "1" "May 2024" "nicole 2.1.0" ""
.SH NAME
\f[B]N\f[R]ew-\f[B]I\f[R]ntrepid-\f[B]C\f[R]hief-\f[B]O\f[R]f-\f[B]L\f[R]yrics-\f[B]E\f[R]mbedders
(obviously)
.PP
Nicole is a program that searches for lyrics and writes them into the
mp3-tag of a file.
.SH SYNOPSIS
.PP
Directory:
.PD 0
.P
.PD
\ \ \ \f[B]nicole\f[R] [OPTION\&...]
-d DIRECTORY
.PD 0
.P
.PD
File:
.PD 0
.P
.PD
\ \ \ \f[B]nicole\f[R] [OPTION\&...]
-f FILE
.SS Files
Nicole supports FLAC and mp3 files.
Other files can not be edited (as of now).
Files that do not have a .flac or .mp3 extension are skipped
automatically.
.PP
\f[B]mp3\f[R]: lyrics are stored in \[lq]USLT\[rq] tag as
\[lq]lyrics-\[rq]
.PP
\f[B]flac\f[R]: lyrics are stored as vorbis-comment with key
\[lq]LYRICS\[rq]
.SS History
Nicole creates a history of all files that were processed in
\f[CR]\[ti]/.configs/nicole\f[R].
If a file is in the history, it will be skipped (unless \f[CR]-i\f[R] is
passed).
If the lyrics for a file can not be obtained, it is added to
\f[CR]\[ti]/.configs/nicole/failed_files\f[R].
Those files are not skipped, the file only exists so that you can see
which lyrics were not downloaded.
.PP
If you don\[cq]t want your files in the history, add the \f[CR]-n\f[R]
option.
.SS genius
Nicole searches for lyrics using the genius api with the \[lq]title\[rq]
and \[lq]artist\[rq] tags of the file.
If the title and artist names from genius are similar enough to the ones
of the file, the lyrics are scraped from the url obtained through the
api.
.SS azlyrics
Nicole creates an azlyrics.com url from the \[lq]title\[rq] and
\[lq]artist\[rq] tags of the file.
The lyrics are extracted from the html document using regex.
.PP
Unfortunately, there needs to be a 5 second delay between each request
to azlyrics.com because the site will block your ip for a while if you
send many requests.
.SH USAGE
.SS Command line options
.TP
\f[B]\[em]-directory\f[R], \f[B]-d\f[R] directory
process directory [directory]
.TP
\f[B]\[em]-file\f[R], \f[B]-f\f[R] file
process file [file]
.TP
\f[B]\[em]-recursive\f[R], \f[B]-r\f[R]
go through directories recursively
.TP
\f[B]\[em]-silent\f[R]
silent, no command-line output
.TP
\f[B]\[em]-ignore-history\f[R], \f[B]-i\f[R]
ignore history
.TP
\f[B]\[em]-no-history\f[R], \f[B]-n\f[R]
do not write to history
.TP
\f[B]\[em]-overwrite\f[R], \f[B]-o\f[R]
overwrite if the file already has lyrics
.TP
\f[B]\[em]-test\f[R], \f[B]-t\f[R]
test, do not write lyrics to file, but print to stdout
.TP
\f[B]\[em]-rm-explicit\f[R]
remove the \[lq][Explicit]\[rq] lyrics warning from the song\[cq]s title
tag
.TP
\f[B]\[em]-site\f[R], \f[B]-s\f[R] site
onlysearch [site] for lyrics (genius or azlyrics)
.PP
One of \f[CR]----file\f[R] and \f[CR]--directory\f[R] must be given at
least once.
Example: \f[CR]nicole -ior -d \[ti]/music/artist ----rm-explicit\f[R]
.SH INSTALLATION AND UPDATING
To update nicole, simply follow the installation instructions.
.SS pacman (Arch Linux)
Installing nicole using the Arch Build System also installs the man-page
and a zsh completion script, if you have zsh installed.
.IP
.EX
git clone https://github.com/MatthiasQuintern/nicole.git
cd nicole
makepkg -si
.EE
.SS pip
You can also install nicole with python-pip:
.IP
.EX
git clone https://github.com/MatthiasQuintern/nicole.git
cd nicole
python3 -m pip install .
.EE
.PP
You can also install it system-wide using
\f[CR]sudo python3 -m pip install.\f[R]
.PP
If you also want to install the man-page and the zsh completion script:
.IP
.EX
sudo cp nicole.1.man /usr/share/man/man1/nicole.1
sudo gzip /usr/share/man/man1/nicole.1
sudo cp _nicole.compdef.zsh /usr/share/zsh/site-functions/_nicole
sudo chmod +x /usr/share/zsh/site-functions/_nicole
.EE
.SS Dependencies
.IP \[bu] 2
https://github.com/quodlibet/mutagen read and write mp3-tags
.IP \[bu] 2
https://www.crummy.com/software/BeautifulSoup deal with the html from
genius
.PP
The dependencies will be automatically installed when using the either
of the two installation options.
.SH CHANGELOG
.SS 2.1.0
.IP \[bu] 2
Refactoring:
.RS 2
.IP \[bu] 2
use argparse
.IP \[bu] 2
use pyproject.toml
.RE
.IP \[bu] 2
Ignore case when matching a genius result
.SS 2.0
.IP \[bu] 2
Nicole now supports lyrics from genius!
.IP \[bu] 2
Added man-page
.IP \[bu] 2
Added zsh-completion
.SS 1.1
.IP \[bu] 2
Lyrics are now properly encoded.
.IP \[bu] 2
If a title contains parenthesis or umlaute, multiple possible urls will
be checked.
.IP \[bu] 2
Files are now processed in order
.SH COPYRIGHT
Copyright © 2024 Matthias Quintern.
License GPLv3+: GNU GPL version 3 <https://gnu.org/licenses/gpl.html>.
.PD 0
.P
.PD
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH AUTHORS
Matthias Quintern.