MatthiasQuintern/nicole
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
matthias@quintern.xyz 2024-05-03 22:42:32 +02:00
parent ede2e54012
commit 269bbd1d50
2 changed files with 72 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
nicole.1.man
View File

@ -1,9 +1,7 @@
.\" Automatically generated by Pandoc 2.17.0.1 .\" Automatically generated by Pandoc 3.1.8
.\" .\"
.TH "NICOLE" "1" "April 2022" "nicole 2.0" "" .TH "NICOLE" "1" "May 2024" "nicole 2.1.0" ""
.hy
.SH NAME .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 \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) (obviously)
.PP .PP
@ -27,7 +25,6 @@ File:
\ \ \ \f[B]nicole\f[R] [OPTION\&...] \ \ \ \f[B]nicole\f[R] [OPTION\&...]
-f FILE -f FILE
.SS Files .SS Files
.PP
Nicole supports FLAC and mp3 files. Nicole supports FLAC and mp3 files.
Other files can not be edited (as of now). Other files can not be edited (as of now).
Files that do not have a .flac or .mp3 extension are skipped Files that do not have a .flac or .mp3 extension are skipped
@ -39,26 +36,24 @@ automatically.
\f[B]flac\f[R]: lyrics are stored as vorbis-comment with key \f[B]flac\f[R]: lyrics are stored as vorbis-comment with key
\[lq]LYRICS\[rq] \[lq]LYRICS\[rq]
.SS History .SS History
.PP
Nicole creates a history of all files that were processed in Nicole creates a history of all files that were processed in
\f[C]\[ti]/.configs/nicole\f[R]. \f[CR]\[ti]/.configs/nicole\f[R].
If a file is in the history, it will be skipped (unless \f[C]-i\f[R] is If a file is in the history, it will be skipped (unless \f[CR]-i\f[R] is
passed). passed).
If the lyrics for a file can not be obtained, it is added to If the lyrics for a file can not be obtained, it is added to
\f[C]\[ti]/.configs/nicole/failed_files\f[R]. \f[CR]\[ti]/.configs/nicole/failed_files\f[R].
Those files are not skipped, the file only exists so that you can see Those files are not skipped, the file only exists so that you can see
which lyrics were not downloaded. which lyrics were not downloaded.
.PP .PP
If you don\[cq]t want your files in the history, add the \f[C]-n\f[R] If you don\[cq]t want your files in the history, add the \f[CR]-n\f[R]
option. option.
.SS genius .SS genius
.PP
Nicole searches for lyrics using the genius api with the \[lq]title\[rq] Nicole searches for lyrics using the genius api with the \[lq]title\[rq]
and \[lq]artist\[rq] tags of the file. and \[lq]artist\[rq] tags of the file.
If the title and artist names from genius and the tags are similar, the If the title and artist names from genius are similar enough to the ones
lyrics are scraped from the url obtained through the api. of the file, the lyrics are scraped from the url obtained through the
api.
.SS azlyrics .SS azlyrics
.PP
Nicole creates an azlyrics.com url from the \[lq]title\[rq] and Nicole creates an azlyrics.com url from the \[lq]title\[rq] and
\[lq]artist\[rq] tags of the file. \[lq]artist\[rq] tags of the file.
The lyrics are extracted from the html document using regex. The lyrics are extracted from the html document using regex.
@ -66,92 +61,74 @@ The lyrics are extracted from the html document using regex.
Unfortunately, there needs to be a 5 second delay between each request 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 to azlyrics.com because the site will block your ip for a while if you
send many requests. 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 .SH USAGE
.SS Command line options .SS Command line options
.TP .TP
\f[B]-d\f[R] directory \f[B]\[em]-directory\f[R], \f[B]-d\f[R] directory
process directory [directory] process directory [directory]
.TP .TP
\f[B]-f\f[R] file \f[B]\[em]-file\f[R], \f[B]-f\f[R] file
process file [file] process file [file]
.TP .TP
\f[B]-r\f[R] \f[B]\[em]-recursive\f[R], \f[B]-r\f[R]
go through directories recursively go through directories recursively
.TP .TP
\f[B]-s\f[R] \f[B]\[em]-silent\f[R]
silent, no command-line output silent, no command-line output
.TP .TP
\f[B]-i\f[R] \f[B]\[em]-ignore-history\f[R], \f[B]-i\f[R]
ignore history ignore history
.TP .TP
\f[B]-n\f[R] \f[B]\[em]-no-history\f[R], \f[B]-n\f[R]
do not write to history do not write to history
.TP .TP
\f[B]-o\f[R] \f[B]\[em]-overwrite\f[R], \f[B]-o\f[R]
overwrite if the file already has lyrics overwrite if the file already has lyrics
.TP .TP
\f[B]-t\f[R] \f[B]\[em]-test\f[R], \f[B]-t\f[R]
test, do not write lyrics to file, but print to stdout test, do not write lyrics to file, but print to stdout
.TP .TP
\f[B]-h\f[R] \f[B]\[em]-rm-explicit\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 remove the \[lq][Explicit]\[rq] lyrics warning from the song\[cq]s title
tag tag
.TP .TP
\f[B]\[em]-site\f[R] site \f[B]\[em]-site\f[R], \f[B]-s\f[R] site
onlysearch [site] for lyrics (genius or azlyrics) onlysearch [site] for lyrics (genius or azlyrics)
.PP .PP
If you do not specify a directory or file, the program will ask you if One of \f[CR]----file\f[R] and \f[CR]--directory\f[R] must be given at
you want to use the current working directory. least once.
Example: \f[C]nicole -ior -d \[ti]/music/artist ----rm_explicit\f[R] Example: \f[CR]nicole -ior -d \[ti]/music/artist ----rm-explicit\f[R]
.SH INSTALLATION AND UPDATING .SH INSTALLATION AND UPDATING
.PP
To update nicole, simply follow the installation instructions. To update nicole, simply follow the installation instructions.
.SS pacman (Arch Linux) .SS pacman (Arch Linux)
.PP
Installing nicole using the Arch Build System also installs the man-page Installing nicole using the Arch Build System also installs the man-page
and a zsh completion script, if you have zsh installed. and a zsh completion script, if you have zsh installed.
.IP .IP
.nf .EX
\f[C]
git clone https://github.com/MatthiasQuintern/nicole.git git clone https://github.com/MatthiasQuintern/nicole.git
cd nicole cd nicole
makepkg -si makepkg -si
\f[R] .EE
.fi
.SS pip .SS pip
.PP
You can also install nicole with python-pip: You can also install nicole with python-pip:
.IP .IP
.nf .EX
\f[C]
git clone https://github.com/MatthiasQuintern/nicole.git git clone https://github.com/MatthiasQuintern/nicole.git
cd nicole cd nicole
python3 -m pip install . python3 -m pip install .
\f[R] .EE
.fi
.PP .PP
You can also install it system-wide using You can also install it system-wide using
\f[C]sudo python3 -m pip install.\f[R] \f[CR]sudo python3 -m pip install.\f[R]
.PP .PP
If you also want to install the man-page and the zsh completion script: If you also want to install the man-page and the zsh completion script:
.IP .IP
.nf .EX
\f[C]
sudo cp nicole.1.man /usr/share/man/man1/nicole.1 sudo cp nicole.1.man /usr/share/man/man1/nicole.1
sudo gzip /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 cp _nicole.compdef.zsh /usr/share/zsh/site-functions/_nicole
sudo chmod +x /usr/share/zsh/site-functions/_nicole sudo chmod +x /usr/share/zsh/site-functions/_nicole
\f[R] .EE
.fi
.SS Dependencies .SS Dependencies
.IP \[bu] 2 .IP \[bu] 2
https://github.com/quodlibet/mutagen read and write mp3-tags https://github.com/quodlibet/mutagen read and write mp3-tags
@ -162,9 +139,24 @@ genius
The dependencies will be automatically installed when using the either The dependencies will be automatically installed when using the either
of the two installation options. of the two installation options.
.SH CHANGELOG .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 .SS 2.0
.IP \[bu] 2 .IP \[bu] 2
Nicole now supports lyrics from genius! Nicole now supports lyrics from genius!
.IP \[bu] 2
Added man-page
.IP \[bu] 2
Added zsh-completion
.SS 1.1 .SS 1.1
.IP \[bu] 2 .IP \[bu] 2
Lyrics are now properly encoded. Lyrics are now properly encoded.
@ -174,8 +166,7 @@ be checked.
.IP \[bu] 2 .IP \[bu] 2
Files are now processed in order Files are now processed in order
.SH COPYRIGHT .SH COPYRIGHT
.PP Copyright © 2024 Matthias Quintern.
Copyright \[co] 2022 Matthias Quintern.
License GPLv3+: GNU GPL version 3 <https://gnu.org/licenses/gpl.html>. License GPLv3+: GNU GPL version 3 <https://gnu.org/licenses/gpl.html>.
.PD 0 .PD 0
.P .P

50
readme.md
View File

@ -10,7 +10,7 @@ Files that do not have a .flac or .mp3 extension are skipped automatically.
- mp3: lyrics are stored in "USLT" tag as "lyrics- " - mp3: lyrics are stored in "USLT" tag as "lyrics- "
- flac: lyrics are stored as vorbis-comment with key "LYRICS" - flac: lyrics are stored as vorbis-comment with key "LYRICS"
### History ## History
Nicole creates a history of all files that were processed in `~/.configs/nicole`. 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 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`. If the lyrics for a file can not be obtained, it is added to `~/.configs/nicole/failed_files`.
@ -18,37 +18,35 @@ Those files are not skipped, the file only exists so that you can see which lyri
If you don't want your files in the history, add the `-n` option. If you don't want your files in the history, add the `-n` option.
### genius ## genius
Nicole searches for lyrics using the genius api with the "title" and "artist" tags of the file. Nicole searches for lyrics using the genius api with 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. 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.
### azlyrics ## azlyrics
Nicole creates an azlyrics.com url from the "title" and "artist" tags of the file. 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. 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. 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 ## Usage
### Command line options ### Command line options
- `-d [directory]` process directory [directory] - `--directory DIRECTORY, -d DIRECTORY`
- `-f [file]` process file [file] process directory [directory]
- `-r` go through directories recursively - `--file FILE, -f FILE` process file [file]
- `-s` silent, no command-line output - `--recursive, -r` go through directories recursively
- `-i` ignore history - `--silent` silent, no command-line output
- `-n` do not write to history - `--ignore-history, -i` ignore history
- `-o` overwrite if the file already has lyrics - `--no-history, -n` do not write to history
- `-t` test, do not write lyrics to file, but print to stdout - `--overwrite, -o` overwrite if the file already has lyrics
- `-h` show this - `--dry-run, -t` test, do not write lyrics to file, but print to console
- `--rm_explicit` remove the "[Explicit]" lyrics warning from the song's title tag - `--rm-explicit` remove the "[Explicit]" lyrics warning from the songs title tag
- `--site [site]` only search [site] for lyrics (genius or azlyrics) - `--site SITE, -s SITE` use only [site]: azlyrics or genius
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` Example: `nicole -ior -d ~/music/artist --rm-explicit`
## Installation and Updating ## Installation and Updating
To update nicole, simply follow the installation instructions. To update nicole, simply follow the installation instructions.
@ -85,6 +83,12 @@ sudo chmod +x /usr/share/zsh/site-functions/_nicole
The dependencies will be automatically installed when using the either of the two installation options. The dependencies will be automatically installed when using the either of the two installation options.
## Changelog ## Changelog
## 2.1.0
- Refactoring:
- use argparse
- use pyproject.toml
- Ignore case when matching a genius result
### 2.0 ### 2.0
- Nicole now supports lyrics from genius! - Nicole now supports lyrics from genius!
- Added man-page - Added man-page
@ -96,5 +100,5 @@ The dependencies will be automatically installed when using the either of the tw
- Files are now processed in order - Files are now processed in order
# Copyright # Copyright
Copyright © 2022 Matthias Quintern. License GPLv3+: GNU GPL version 3 <https://gnu.org/licenses/gpl.html>.\ Copyright © 2024 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. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.