From cbb5029555072bfa3e31626de0bf448bc462b3ed Mon Sep 17 00:00:00 2001 From: "matthias@arch" Date: Mon, 4 Apr 2022 05:55:34 +0200 Subject: [PATCH] Added manpage --- nicole.1.man | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++ nicole.1.md | 129 +++++++++++++++++++++++++++++++++++ 2 files changed, 314 insertions(+) create mode 100644 nicole.1.man create mode 100644 nicole.1.md diff --git a/nicole.1.man b/nicole.1.man new file mode 100644 index 0000000..c9ad13a --- /dev/null +++ b/nicole.1.man @@ -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 . +.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. diff --git a/nicole.1.md b/nicole.1.md new file mode 100644 index 0000000..ea2c3a5 --- /dev/null +++ b/nicole.1.md @@ -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 .\ +This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.