From 269bbd1d50b4c286fb596641bbc570c9640cb94f Mon Sep 17 00:00:00 2001 From: "matthias@quintern.xyz" Date: Fri, 3 May 2024 22:42:32 +0200 Subject: [PATCH] update readme --- nicole.1.man | 99 ++++++++++++++++++++++++---------------------------- readme.md | 50 ++++++++++++++------------ 2 files changed, 72 insertions(+), 77 deletions(-) diff --git a/nicole.1.man b/nicole.1.man index c31e739..c80a8b0 100644 --- a/nicole.1.man +++ b/nicole.1.man @@ -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" "" -.hy +.TH "NICOLE" "1" "May 2024" "nicole 2.1.0" "" .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 @@ -27,7 +25,6 @@ File: \ \ \ \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 @@ -39,26 +36,24 @@ automatically. \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 +\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[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 which lyrics were not downloaded. .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. .SS genius -.PP 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 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. .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. @@ -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 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 +\f[B]\[em]-directory\f[R], \f[B]-d\f[R] directory process directory [directory] .TP -\f[B]-f\f[R] file +\f[B]\[em]-file\f[R], \f[B]-f\f[R] file process file [file] .TP -\f[B]-r\f[R] +\f[B]\[em]-recursive\f[R], \f[B]-r\f[R] go through directories recursively .TP -\f[B]-s\f[R] +\f[B]\[em]-silent\f[R] silent, no command-line output .TP -\f[B]-i\f[R] +\f[B]\[em]-ignore-history\f[R], \f[B]-i\f[R] ignore history .TP -\f[B]-n\f[R] +\f[B]\[em]-no-history\f[R], \f[B]-n\f[R] do not write to history .TP -\f[B]-o\f[R] +\f[B]\[em]-overwrite\f[R], \f[B]-o\f[R] overwrite if the file already has lyrics .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 .TP -\f[B]-h\f[R] -show this -.TP -\f[B]\[em]-rm_explicit\f[R] +\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 +\f[B]\[em]-site\f[R], \f[B]-s\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] +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 -.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 have zsh installed. .IP -.nf -\f[C] +.EX git clone https://github.com/MatthiasQuintern/nicole.git cd nicole makepkg -si -\f[R] -.fi +.EE .SS pip -.PP You can also install nicole with python-pip: .IP -.nf -\f[C] +.EX git clone https://github.com/MatthiasQuintern/nicole.git cd nicole python3 -m pip install . -\f[R] -.fi +.EE .PP 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 If you also want to install the man-page and the zsh completion script: .IP -.nf -\f[C] +.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 -\f[R] -.fi +.EE .SS Dependencies .IP \[bu] 2 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 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. @@ -174,8 +166,7 @@ be checked. .IP \[bu] 2 Files are now processed in order .SH COPYRIGHT -.PP -Copyright \[co] 2022 Matthias Quintern. +Copyright © 2024 Matthias Quintern. License GPLv3+: GNU GPL version 3 . .PD 0 .P diff --git a/readme.md b/readme.md index 2de4792..e8eae52 100644 --- a/readme.md +++ b/readme.md @@ -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- " - 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`. 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`. @@ -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. -### genius +## genius 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. 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. +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. ## 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]` only search [site] for lyrics (genius or azlyrics) +- `--directory DIRECTORY, -d DIRECTORY` + process directory [directory] +- `--file FILE, -f FILE` process file [file] +- `--recursive, -r` go through directories recursively +- `--silent` silent, no command-line output +- `--ignore-history, -i` ignore history +- `--no-history, -n` do not write to history +- `--overwrite, -o` overwrite if the file already has lyrics +- `--dry-run, -t` test, do not write lyrics to file, but print to console +- `--rm-explicit` remove the "[Explicit]" lyrics warning from the songs title tag +- `--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 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. ## Changelog +## 2.1.0 +- Refactoring: + - use argparse + - use pyproject.toml +- Ignore case when matching a genius result + ### 2.0 - Nicole now supports lyrics from genius! - 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 # Copyright -Copyright © 2022 Matthias Quintern. License GPLv3+: GNU GPL version 3 .\ +Copyright © 2024 Matthias Quintern. License GPLv3+: GNU GPL version 3 .\ This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.