From dc27d4493ce8e7769474b0f33d9d98abbf07f143 Mon Sep 17 00:00:00 2001
From: Levon Gevorgyan <lgevorgyan03@gmail.com>
Date: Wed, 6 May 2026 16:16:27 -0500
Subject: [PATCH] init readme

---
 README.md                 | 35 +++++++++++++++++++++++++++++++++++
 lib/0-utils.sh            | 25 +++++++++++++++++++------
 test-add-synced-lyrics.sh | 15 ++-------------
 3 files changed, 56 insertions(+), 19 deletions(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c024d6a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,35 @@
+# add-synced-lyrics
+A script that automates adding lyrics to your songs.
+```
+add-synced-lyrics.sh [options]
+
+OPTIONS:
+  -d, --dir       process files in directory
+  -r, --recurse   recursively process directory
+  -f, --file      process one file
+  -e, --embed     embed lyrics directly into the song file
+  -n, --dry-run   do not add synced lyrics,
+                  just show the files that would be processed
+  -i, --ignore    ignore errors, and continue attempting to find lyrics
+                  even in the case of errors
+  -h, --help      show this output
+  --debug         extra information useful for debugging
+  --eval          output bash functions that can be directly processed
+                  by eval for use with testing this script.
+```
+
+# Requirements
+- CLI tools:
+    - coreutils: `mktemp cat sort base64 readlink`
+    - `ffmpeg ffprobe` 
+    - `jq`
+    - `node` (any version)
+    - [`librelyrics`](https://github.com/libre-lyrics/librelyrics):
+        - uses the [deezer](https://github.com/libre-lyrics/librelyrics-deezer) and [spotify](https://github.com/libre-lyrics/librelyrics-spotify) plugins
+    - [`spotify`](https://github.com/ledesmablt/spotify-cli) most easily installed with `uv tool install --python 3.8 spotify-cli`
+- Music that has the appropriate ISRC tag.
+
+## Features
+- Uses the ISRC tag to search for synced lyrics across the download providers: lrclib, spotify, and deezer (in that order).
+- Caches all networked-calls to the download providers.
+- Supports separate (dedicated .lrc file) or adding the lyrics directly to the song file with the LYRICS tag.
\ No newline at end of file
diff --git a/lib/0-utils.sh b/lib/0-utils.sh
index 4a85a23..4531d73 100644
--- a/lib/0-utils.sh
+++ b/lib/0-utils.sh
@@ -89,17 +89,29 @@ dry() {
 # check required utilities for this project
 check_required_utils() {
     local utils=(
-        mktemp
+        # coreutils
+        bash
+        cat
         sort
         base64
-        cat
-        ffprobe
+        mktemp
+        readlink
+
         jq
-        librelyrics
-        spotify # uv tool install --python 3.8 spotify-cli
-        docker
         node
+        docker
+        ffmpeg
+        ffprobe
+
+        librelyrics
+        spotify
     )
+
+    if [[ "${1:-}" == '--print-required' ]]; then
+        echo "utils='${utils[*]}'"
+        return
+    fi
+
     local missing=false
     for util in "${utils[@]}"; do
         if ! have_cmd "${util}"; then
@@ -252,6 +264,7 @@ output_eval_functions() {
             "${function}" == set_default_options ]] || continue
         ${line}
     done <<<"$(declare -F)"
+    check_required_utils --print-required
 }
 
 get_file_isrc() {
diff --git a/test-add-synced-lyrics.sh b/test-add-synced-lyrics.sh
index f8083d2..8b5cf70 100755
--- a/test-add-synced-lyrics.sh
+++ b/test-add-synced-lyrics.sh
@@ -89,7 +89,6 @@ run_test_cmd() {
     else
         return 0
     fi
-
 }
 
 test_help_option() {
@@ -163,21 +162,11 @@ test_determine_inputs_recurse() {
 }
 
 test_determine_inputs_bash() {
+    eval "$(add-synced-lyrics --eval)"
     # TEST_ADD_BIN guaranteed to be single word
     # shellcheck disable=SC2206
     local utils=(
-        mktemp
-        sort
-        base64
-        cat
-        ffprobe
-        jq
-        librelyrics
-        spotify
-        docker
-        node
-        readlink
-        bash
+        ${utils}
         ${TEST_ADD_BIN:-}
     )