Added manpage
This commit is contained in:
matthias@arch
parent
b4bd1ed448
commit
cbb5029555
185
nicole.1.man
Normal file
185
nicole.1.man
Normal file
@ -0,0 +1,185 @@
|
||||
.\" Automatically generated by Pandoc 2.17.0.1
|
||||
.\"
|
||||
.TH "NICOLE" "1" "April 2022" "nicole 2.0" ""
|
||||
.hy
|
||||
.SH NAME
|
||||
.PP
|
||||
\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
|
||||
.PP
|
||||
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
|
||||
.PP
|
||||
Nicole creates a history of all files that were processed in
|
||||
\f[C]\[ti]/.configs/nicole\f[R].
|
||||
If a file is in the history, it will be skipped (unless \f[C]-i\f[R] is
|
||||
passed).
|
||||
If the lyrics for a file can not be obtained, it is added to
|
||||
\f[C]\[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[C]-n\f[R]
|
||||
option.
|
||||
.SS genius
|
||||
.PP
|
||||
Nicole searches for lyrics using the genius api using the
|
||||
\[lq]title\[rq] and \[lq]artist\[rq] tags of the file.
|
||||
If the title and artist names from genius and the tags are similar, the
|
||||
lyrics are scraped from the url obtained through the api.
|
||||
.SS azlyrics
|
||||
.PP
|
||||
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.
|
||||
.SS Important Note
|
||||
.PP
|
||||
Since the lyrics are extracted from html pages and not from an api, the
|
||||
lyrics sites might temporarily block your ip address if you send too
|
||||
many requests.
|
||||
If that is the case, wait a few hours and try again.
|
||||
.SH USAGE
|
||||
.SS Command line options
|
||||
.TP
|
||||
\f[B]-d\f[R] directory
|
||||
process directory [directory]
|
||||
.TP
|
||||
\f[B]-f\f[R] file
|
||||
process file [file]
|
||||
.TP
|
||||
\f[B]-r\f[R]
|
||||
go through directories recursively
|
||||
.TP
|
||||
\f[B]-s\f[R]
|
||||
silent, no command-line output
|
||||
.TP
|
||||
\f[B]-i\f[R]
|
||||
ignore history
|
||||
.TP
|
||||
\f[B]-n\f[R]
|
||||
do not write to history
|
||||
.TP
|
||||
\f[B]-o\f[R]
|
||||
overwrite if the file already has lyrics
|
||||
.TP
|
||||
\f[B]-t\f[R]
|
||||
test, do not write lyrics to file, but print to stdout
|
||||
.TP
|
||||
\f[B]-h\f[R]
|
||||
show this
|
||||
.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] site
|
||||
onlysearch [site] for lyrics (genius or azlyrics)
|
||||
.PP
|
||||
If you do not specify a directory or file, the program will ask you if
|
||||
you want to use the current working directory.
|
||||
Example: \f[C]nicole -ior -d \[ti]/music/artist ----rm_explicit\f[R]
|
||||
.SH INSTALLATION AND UPDATING
|
||||
.PP
|
||||
To update nicole, simply follow the installation instructions.
|
||||
.SS pacman (Arch Linux)
|
||||
.PP
|
||||
Installing nicole using the Arch Build System also installs the man-page
|
||||
and a zsh completion script if you are using zsh as default shell.
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
git clone https://github.com/MatthiasQuintern/nicole.git
|
||||
cd nicole
|
||||
makepkg -si
|
||||
\f[R]
|
||||
.fi
|
||||
.SS pip
|
||||
.PP
|
||||
Clone this repository and install it using python-pip.
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
git clone https://github.com/MatthiasQuintern/nicole.git
|
||||
cd nicole
|
||||
python3 -m pip install .
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
You can also install it system-wide using
|
||||
\f[C]sudo python3 -m pip install.\f[R]
|
||||
.PP
|
||||
If you also want to install the man-page and the zsh completion script:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
sudo cp nicole.1.man /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
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Dependencies
|
||||
.IP \[bu] 2
|
||||
https://github.com/seebye/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.0
|
||||
.IP \[bu] 2
|
||||
Nicole now supports lyrics from genius!
|
||||
.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
|
||||
.PP
|
||||
Copyright \[co] 2022 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.
|
||||
129
nicole.1.md
Normal file
129
nicole.1.md
Normal file
@ -0,0 +1,129 @@
|
||||
% NICOLE(1) nicole 2.0
|
||||
% Matthias Quintern
|
||||
% April 2022
|
||||
|
||||
# NAME
|
||||
**N**ew-**I**ntrepid-**C**hief-**O**f-**L**yrics-**E**mbedders (obviously)
|
||||
|
||||
Nicole is a program that searches for lyrics and writes them into the mp3-tag of a file.
|
||||
|
||||
# SYNOPSIS
|
||||
| Directory:
|
||||
| **nicole** [OPTION...] -d DIRECTORY
|
||||
| File:
|
||||
| **nicole** [OPTION...] -f FILE
|
||||
|
||||
## 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.
|
||||
|
||||
**mp3**: lyrics are stored in "USLT" tag as "lyrics- "
|
||||
|
||||
**flac**: lyrics are stored as vorbis-comment with key "LYRICS"
|
||||
|
||||
## History
|
||||
Nicole creates a history of all files that were processed in `~/.configs/nicole`.
|
||||
If a file is in the history, it will be skipped (unless `-i` is passed).
|
||||
If the lyrics for a file can not be obtained, it is added to `~/.configs/nicole/failed_files`.
|
||||
Those files are not skipped, the file only exists so that you can see which lyrics were not downloaded.
|
||||
|
||||
If you don't want your files in the history, add the `-n` option.
|
||||
|
||||
## genius
|
||||
Nicole searches for lyrics using the genius api using the "title" and "artist" tags of the file.
|
||||
If the title and artist names from genius and the tags are similar, the lyrics are scraped from the url obtained through the api.
|
||||
|
||||
## azlyrics
|
||||
Nicole creates an azlyrics.com url from the "title" and "artist" tags of the file.
|
||||
The lyrics are extracted from the html document using regex.
|
||||
|
||||
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.
|
||||
|
||||
## Important Note
|
||||
Since the lyrics are extracted from html pages and not from an api, the lyrics sites might temporarily block your ip address if you send too many requests.
|
||||
If that is the case, wait a few hours and try again.
|
||||
|
||||
# USAGE
|
||||
|
||||
## Command line options
|
||||
**-d** directory
|
||||
: process directory [directory]
|
||||
|
||||
**-f** file
|
||||
: process file [file]
|
||||
|
||||
**-r**
|
||||
: go through directories recursively
|
||||
|
||||
**-s**
|
||||
: silent, no command-line output
|
||||
|
||||
**-i**
|
||||
: ignore history
|
||||
|
||||
**-n**
|
||||
: do not write to history
|
||||
|
||||
**-o**
|
||||
: overwrite if the file already has lyrics
|
||||
|
||||
**-t**
|
||||
: test, do not write lyrics to file, but print to stdout
|
||||
|
||||
**-h**
|
||||
: show this
|
||||
|
||||
**--rm_explicit**
|
||||
: remove the "[Explicit]" lyrics warning from the song's title tag
|
||||
|
||||
**--site** site
|
||||
: onlysearch [site] for lyrics (genius or azlyrics)
|
||||
|
||||
If you do not specify a directory or file, the program will ask you if you want to use the current working directory.
|
||||
Example: `nicole -ior -d ~/music/artist --rm_explicit`
|
||||
|
||||
# INSTALLATION AND UPDATING
|
||||
To update nicole, simply follow the installation instructions.
|
||||
|
||||
## pacman (Arch Linux)
|
||||
Installing nicole using the Arch Build System also installs the man-page and a zsh completion script if you are using zsh as default shell.
|
||||
```shell
|
||||
git clone https://github.com/MatthiasQuintern/nicole.git
|
||||
cd nicole
|
||||
makepkg -si
|
||||
```
|
||||
|
||||
## pip
|
||||
Clone this repository and install it using python-pip.
|
||||
```shell
|
||||
git clone https://github.com/MatthiasQuintern/nicole.git
|
||||
cd nicole
|
||||
python3 -m pip install .
|
||||
```
|
||||
You can also install it system-wide using `sudo python3 -m pip install.`
|
||||
|
||||
If you also want to install the man-page and the zsh completion script:
|
||||
```shell
|
||||
sudo cp nicole.1.man /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
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
- https://github.com/seebye/mutagen: read and write mp3-tags
|
||||
- https://www.crummy.com/software/BeautifulSoup/: deal with the html from genius
|
||||
|
||||
The dependencies will be automatically installed when using the either of the two installation options.
|
||||
|
||||
# CHANGELOG
|
||||
## 2.0
|
||||
- Nicole now supports lyrics from genius!
|
||||
|
||||
## 1.1
|
||||
- Lyrics are now properly encoded.
|
||||
- If a title contains parenthesis or umlaute, multiple possible urls will be checked.
|
||||
- Files are now processed in order
|
||||
|
||||
# COPYRIGHT
|
||||
Copyright © 2022 Matthias Quintern. License GPLv3+: GNU GPL version 3 <https://gnu.org/licenses/gpl.html>.\
|
||||
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
|
||||
Loading…
Reference in New Issue
Block a user